Organizations, members, groups, policies, providers

Active contributors: admin console team.

Purpose

Organizations are the multi-tenant boundary in Bitwarden. An Organization row owns members (OrganizationUser), groups, collections, policies, an SSO config, a SCIM config, an installation key (for the public API), and a billing relationship. Providers add another level of multi-tenancy: a managed-services provider tenant owns multiple client organizations.

Where the code lives

Concern	Path
Domain	src/Core/AdminConsole/
API	src/Api/AdminConsole/Controllers/, src/Api/AdminConsole/Public/Controllers/
Schema	src/Sql/dbo/Tables/Organization*.sql, Group*.sql, Policy.sql, Provider*.sql, Collection*.sql
Authorization	src/Core/AdminConsole/Authorization/, src/Api/AdminConsole/Authorization/
Per-feature folders	src/Core/AdminConsole/OrganizationFeatures/{Organizations, OrganizationUsers, Groups, Policies, OrganizationApiKeys, OrganizationConnections, OrganizationDomains, OrganizationAbility, AccountRecovery, Collections, Import, Shared}/

Key abstractions

Type	Path	Description
Organization	src/Core/AdminConsole/Entities/Organization.cs	Plan info, seat counts, feature flags, billing pointers, public-API installation key.
OrganizationUser	src/Core/AdminConsole/Entities/OrganizationUser.cs	Membership row: User ↔ Org with role + status (Invited, Confirmed, Revoked).
Group	src/Core/AdminConsole/Entities/Group.cs	Bulk-permission grouping.
Collection	src/Core/AdminConsole/Entities/Collection.cs	Cipher container scoped to an org.
Policy	src/Core/AdminConsole/Entities/Policy.cs	Org-wide rule (PolicyType enum: TwoFactorAuthentication, MasterPassword, PasswordGenerator, SingleOrg, RequireSso, ResetPassword, MaximumVaultTimeout, RemoveUnlockWithPin, FreeFamiliesSponsorshipPolicy, ...).
Provider / ProviderUser / ProviderOrganization	src/Core/AdminConsole/Providers/	MSP tenant + its members + the orgs it manages.
IOrganizationService / OrganizationService	src/Core/AdminConsole/Services/{IOrganizationService.cs, Implementations/OrganizationService.cs}	The classic 1,219-line "fat service" — being incrementally split into commands.
IOrganizationUserCommands / Queries (per feature folder)	src/Core/AdminConsole/OrganizationFeatures/OrganizationUsers/	Newer narrower interfaces.
OrganizationDomain	src/Core/Entities/OrganizationDomain.cs	Verified email domains used to claim an org. Verified via DNS TXT record.
BulkCollectionAuthorizationHandler etc.	src/Core/Vault/AuthorizationHandlers/, src/Core/AdminConsole/Authorization/	The resource-based auth handlers that decide who can act on what.

How permissions work

graph TD
    User --> OU[OrganizationUser<br/>Role: Owner/Admin/Manager/User/Custom]
    User --> GroupMember
    GroupMember --> Group
    OU --> CollectionAccess[CollectionUser<br/>readOnly / hidePasswords / manage]
    Group --> CollectionAccess[CollectionGroup]
    CollectionAccess --> Collection
    Collection --> CollectionCipher --> Cipher

• An OrganizationUser is one of Owner, Admin, Manager, User, or Custom. Custom roles use a JSON permissions blob stored on the OrganizationUser row.
• Access to ciphers flows through Collection membership — either directly (CollectionUser) or via Group (CollectionGroup).
• BulkCollectionAuthorizationHandler materialises this graph and answers "can this caller view / edit / manage these collections?".

Major in-flight features (2025-2026)

• Invite Links — PR #7407 "Add entities, repository and database migrations for Organization Invite Link feature" (2026-04-09). Extends invitation to a shareable link instead of email-only.
• Bulk Auto-Confirm on Login — PR #7530 + flag BulkAutoConfirmOnLogin. Auto-confirms invited users at first login when policy permits.
• Master Password policy uplift — PR #7537, "Implement master password policy requirement". Stronger gating for admin enforcement.
• Group Revision Date bump — PR #7467. Ensures the Group.RevisionDate advances when access changes so client caches sync.

Policies

Policy rows are the org-wide rule set. The full enum lives in src/Core/AdminConsole/Enums/PolicyType.cs. Policy enforcement is split across:

• IPolicyService (src/Core/AdminConsole/Services/IPolicyService.cs) — read / save / publish.
• Per-policy enforcement under src/Core/AdminConsole/OrganizationFeatures/Policies/PolicyValidators/ — each validator decides whether a given user / action is allowed under the active policies.
• BaseRequestValidator invokes the relevant policy enforcement at login time (e.g. RequireTwoFactorAuthenticationPolicy).

Public API (org-level)

src/Api/AdminConsole/Public/ is the documented org-level v1 API used by integrations. It reuses the same domain commands but exposes a curated, versioned surface (Members, Groups, Collections, Policies, Events).

Integration points

• Audit events — every membership / group / policy mutation logs an OrganizationUser_* / Group_* / Policy_* event.
• Mail — invitations, accept / confirm / revoke notifications go through IMailService.
• Application cache — OrganizationAbility is updated on every plan / seat / feature toggle.
• Push — org changes push SyncOrgKeys events so clients refetch.

Entry points for modification

• New policy → add to PolicyType, write a validator under src/Core/AdminConsole/OrganizationFeatures/Policies/PolicyValidators/, surface in the Web Vault UI via Api/AdminConsole/Controllers/PoliciesController.cs.
• New OrganizationUser status → extend OrganizationUserStatusType, update OrganizationService and the auth filters that gate by status.
• New group → straightforward; add to the relevant OrganizationFeatures/Groups/ commands. Be sure to bump Group.RevisionDate (PR #7467 made this consistent).
• Public API addition → controller under src/Api/AdminConsole/Public/Controllers/ with the Public API group convention.