Skip to content

ADR-0003: Enterprise Password Manager Selection

  • Status: ✅ Accepted
  • Date: 2026-01-28
  • Amended: 2026-06-08
  • Owners: @team/devops, @osmank, @berk

Context

Appcircle requires a centralized, secure, and auditable password management solution for storing and sharing credentials across teams. As our infrastructure grows, managing secrets (API keys, service accounts, shared credentials, SSH keys, certificates) in a secure, controlled, and traceable manner becomes critical.

Requirements / Constraints

We need:

  1. Zero-Knowledge Architecture
  2. Client-side encryption where the provider cannot access plaintext secrets.
  3. Strong Encryption Standards
  4. AES-256 or equivalent, with modern key derivation functions (Argon2, PBKDF2).
  5. Multi-Factor Authentication (MFA) Enforcement
  6. Ability to enforce MFA at the organizational level via policy.
  7. Team-Based Sharing Model
  8. Secure sharing with RBAC (Role-Based Access Control), vaults, and collections.
  9. SSO Integration
  10. SAML, OIDC, LDAP, or SCIM support for centralized identity management.
  11. Self-Host Capability
  12. Option to host on our own infrastructure for data sovereignty and compliance.
  13. Audit & Logging
  14. Comprehensive audit trails, event logs, and SIEM integration for compliance.
  15. Enterprise Support
  16. Reliable vendor support, SLA guarantees, and security certifications.
  17. CLI Tools & API Access
  18. Command-line interface for server-side automation and scripting.
  19. Support for automated credential rotation (passwords, SSH keys, API tokens).
  20. Headless/non-interactive authentication for service accounts.

Decision

We will adopt Vaultwarden (Self-Hosted) as the standard password manager for Appcircle.

The initial proposal evaluated Passbolt. After further review, Vaultwarden was selected because SSO via OIDC became available in Vaultwarden, removing the primary concern that had previously ruled it out. Combined with zero licensing cost and native compatibility with the Bitwarden client ecosystem, Vaultwarden became the better fit.

Key points:

  • Vaultwarden is deployed on Appcircle infrastructure and accessible at https://pass.appcircle.io.
  • AES-256-GCM encryption with Argon2id key derivation — same cryptographic model as Bitwarden.
  • All official Bitwarden clients (browser extensions, desktop and mobile apps) are used as the front-end; no custom client is required.
  • Credentials are organized using organizations, collections, and RBAC — one organization per company, collections per team.
  • SSO is configured via Microsoft Entra ID (OIDC), enabling users to authenticate with their @appcircle.io account.
  • Full data sovereignty — all credentials remain on Appcircle-controlled infrastructure.
  • Zero licensing cost — Vaultwarden is free and open-source.

Options Considered

Comparison Matrix

Product Encryption Model Key Derivation / KDF Zero-Knowledge MFA Enforcement Sharing Model SSO Support Self-Host Audit / Logging Licensing / Cost Security Notes
Bitwarden Enterprise AES-256-GCM Argon2id (configurable) Yes Yes (policy-enforced) Org vaults, collections, RBAC Yes (OIDC, SAML) Yes (Docker/K8s) Advanced audit logs, SIEM integration Per-user pricing (Teams/Enterprise plans) Mature and supported for enterprise use.
Vaultwarden ✅ AES-256-GCM Argon2id (configurable) Yes (same encryption as Bitwarden, not officially audited) Available but limited enforcement Collection and vault logic compatible Yes (OIDC added; SSO now available) Yes (Docker, low resource) Basic level, requires custom improvements Free (community), no official support SSO availability resolved the original blocker; selected for zero cost and Bitwarden client compatibility.
1Password Business AES-256 PBKDF2 + Secret Key (SRP-based) Yes (very strong model) Yes Team vaults, access policies Yes (SCIM + SAML/Entra) No (SaaS only, region selectable) Advanced access and event reports Per-user licensing Strong security model but SaaS dependency.
Passbolt OpenPGP (user key pairs) User GPG key generation Yes (client-side decryption) Yes Groups and access permissions Yes (SAML, LDAP) Yes (Docker/K8s) Advanced audit logs Community + Enterprise options Excellent for self-host and secure sharing.
KeePassXC AES-256 / ChaCha20 (configurable) Argon2 Yes (local storage) No (no central MFA enforcement) Manual file sharing (NOT suitable for secure team sharing) No Yes (file-based) No (no central logging) Free Not suitable for team use or auditability.
Keeper AES-256 PBKDF2 (configurable) Yes Yes Vault sharing, folder-based access control Yes (SAML/LDAP/OIDC) Yes (privately hosted enterprise options) Advanced reporting and alerting Per-user licensing Strong enterprise management and SSO integrations.

Consequences

Positive

  • Full data sovereignty — all credentials remain on Appcircle-controlled infrastructure.
  • Zero licensing cost — Vaultwarden is free and open-source; no per-user fees.
  • Bitwarden client ecosystem — users get a polished, widely supported client on all platforms without any custom tooling.
  • SSO via Microsoft Entra ID (OIDC) centralizes authentication and simplifies user lifecycle management.
  • Collection-based RBAC enables fine-grained per-team and per-role access control.
  • Bitwarden Send provides a secure, expiring channel for sharing secrets without using Slack or email.
  • Low resource footprint; runs on a single Docker container.

Negative / Trade-offs

  • No official vendor support — Vaultwarden is community-maintained; security patches depend on the upstream project.
  • Not officially audited — cryptographic implementation mirrors Bitwarden but has not undergone independent third-party audit.
  • Operational overhead — backups, upgrades, and monitoring are entirely self-managed.
  • MFA policy enforcement is limited compared to the official Bitwarden Enterprise offering.

Follow-ups / Migrations

  1. ~~Infrastructure Setup: Deploy on Docker~~ — done; running at https://pass.appcircle.io.
  2. ~~SSO Integration: Configure Microsoft Entra ID (OIDC)~~ — done.
  3. Organization invite workflow: Document and socialize the manual invite process (no SCIM auto-provisioning).
  4. Collection structure: Finalize <Team> / <Team>/Privileged collection hierarchy for all teams.
  5. Offboarding: Add Vaultwarden account removal to the offboarding checklist.
  6. Backup verification: Confirm automated backup and restore procedure is tested.