Secrets Manager

Active contributors: tools / secrets manager team.

Purpose

Bitwarden Secrets Manager is a developer-secrets product: encrypted secrets organised into projects, accessed via short-lived tokens minted from service accounts, with a CLI / SDK clients can use during build pipelines. The feature shipped in 2023 (PR #2164 on 2023-01-13) and continues to grow.

The OSS distribution does not include Secrets Manager — it is part of the commercial license. The shared interfaces and core domain types live under src/Core/SecretsManager/ so the OSS build still compiles the surrounding code; the actual implementations live under bitwarden_license/src/Commercial.Core/SecretsManager/ and bitwarden_license/src/Commercial.Infrastructure.EntityFramework/SecretsManager/.

Where the code lives

Concern	Path
Domain interfaces & entities	src/Core/SecretsManager/
Commercial implementations	bitwarden_license/src/Commercial.Core/SecretsManager/
Commercial EF mappings	bitwarden_license/src/Commercial.Infrastructure.EntityFramework/SecretsManager/
API surface	src/Api/SecretsManager/Controllers/
Schema	src/Sql/dbo/Tables/Project*.sql, Secret*.sql, ServiceAccount*.sql, AccessPolicy*.sql

Key abstractions

Type	Path	Description
Project	src/Core/SecretsManager/Entities/Project.cs	A bucket of secrets, scoped to an organization.
Secret	src/Core/SecretsManager/Entities/Secret.cs	Encrypted secret with name + value + note (all client-encrypted).
ServiceAccount	src/Core/SecretsManager/Entities/ServiceAccount.cs	Non-human identity that obtains short-lived API tokens to read secrets at build/runtime.
AccessPolicy (and its concrete subclasses)	src/Core/SecretsManager/Entities/	Per-project / per-secret / per-service-account access grants.
IAccessPolicyAuthorizationHandler	src/Core/SecretsManager/AuthorizationRequirements/	Resource-based authz that checks the caller's access via the policy graph.
Commands & Queries	src/Core/SecretsManager/Commands/, Queries/	Narrow interfaces (e.g. ICreateSecretCommand, IRevokeAccessTokenCommand); commercial implementations in bitwarden_license/src/Commercial.Core/SecretsManager/.
Trash (soft-deleted secrets)	Implemented in PR SM-281 on 2023-02-20	Restorable for 30 days.

API surface

src/Api/SecretsManager/Controllers/:

• ProjectsController — CRUD on projects.
• SecretsController — CRUD + bulk on secrets.
• ServiceAccountsController — CRUD service accounts and rotate API tokens.
• AccessPoliciesController — manage who can read / write / manage what.
• TrashController — list / restore / permanently delete.

Authentication uses the Policies.Secrets JWT scope (which accepts either the standard api scope or the bespoke api.secrets scope minted for service accounts).

How it works

graph TD
    User[Web Vault user] --> ApiSec["Api / SecretsManager controllers"]
    ApiSec --> Authz[IAccessPolicyAuthorizationHandler]
    ApiSec --> CmdQ[Commands / Queries]
    CmdQ --> Repo[(Repositories)]

    SA[Service Account] --> Identity[(Identity host)]
    Identity --> Token[api.secrets JWT]
    Token --> ApiSec

The web vault speaks the same API as service accounts; only the JWT scope differs. Service-account tokens are short-lived (default ~30 minutes) and rotate via IRotateAccessTokenCommand.

Integration points

• Identity — service-account tokens are minted by the same Identity host. The token issuance flow lives in src/Core/Auth/IdentityServer/RequestValidators/ and src/Core/SecretsManager/AccessTokens/.
• Database — the SecretsManager EF repositories are commercial-only; OSS uses Noop implementations (e.g. NoopServiceAccountRepository) so the DI graph still resolves.
• Audit events — secret reads are logged via IEventService for compliance.

OSS-vs-licensed split

src/Api/Startup.cs registers Secrets Manager only on non-OSS builds:

#if !OSS
        services.AddCommercialSecretsManagerServices();
        services.AddSecretsManagerEfRepositories();
        Jobs.JobsHostedService.AddCommercialSecretsManagerJobServices(services);
#endif

OSS builds register NoopServiceAccountRepository etc. (src/Identity/Startup.cs registers it explicitly to satisfy DI even for non-OSS builds during a transition window).

Entry points for modification

• New API endpoint → controller in src/Api/SecretsManager/Controllers/ + command/query interface in src/Core/SecretsManager/ + commercial implementation in bitwarden_license/src/Commercial.Core/SecretsManager/.
• New access-policy type → entity + EF mapping + a handler in IAccessPolicyAuthorizationHandler.
• New service-account scope → extend ApiScopes (src/Core/Auth/IdentityServer/Constants/) + the matching grant validator.

The Secrets Manager team also owns the corresponding clients in the bitwarden/sdk-secrets repo and the bws CLI; this server-side code is the source of truth for the API contract.