Passbolt Security: Self-Hosted Hardening, Keys and Roles

A self-hosted Passbolt server holds the encrypted credentials of an entire team, so the security of the host, the OpenPGP keys and the admin settings around it is the customer's job from day one. This guide explains how to run Passbolt securely, using Passbolt's own documentation and admin guidance as the source for every product detail. It covers the OpenPGP key model, the server key and organisation recovery key, administrator rights and role-based access control, SSO, the MFA policy, API authentication for scripts, directory sync, the audit log and a hardening baseline for the host, database and network. It is written for system administrators, platform engineers and security teams running Passbolt Community Edition, Pro or Cloud. For the wider discipline see the Secrets Management Guide.

This is an independent guide from NHI Mgmt Group, based on Passbolt's public documentation as of November 2026. It is not sponsored or reviewed by Passbolt. Product features change, so confirm settings against Passbolt's current documentation.

Key takeaways

• Three keys need a custodian. Each user's private key and passphrase, the server's OpenPGP key and, when account recovery is on, the organisation recovery key (ORK) each need a named owner, a backup and a documented recovery procedure.
• The ORK is break-glass material. Passbolt's most secure option is to generate the ORK offline, keep it offline and rotate it after each use.
• Some settings shape the interface, others the API. RBAC denials and the MFA "Prompt" policy apply in the interface; since v5.8.0 account recovery management, group creation and Offline mode denials are also enforced at the API, and MFA enforcement for scripts is set at the provider level.
• Self-hosting makes the stack yours. TLS, HSTS, OS patching, database permissions, backups and log shipping sit with the operator, and passbolt healthcheck is the first check after every change.
• The audit log is written in every edition. Pro and Cloud add the Activity tab and /actionlog API; every edition can forward to a SIEM, and rows grow until you purge them with action_logs_purge.

How identity and access work in Passbolt

Passbolt is built on OpenPGP. Each user has a key pair; secrets are encrypted to the public keys of everyone they are shared with, and the user's private key, protected by their passphrase, decrypts them in the browser extension. The server has its own OpenPGP key pair, which the login protocol uses so that client and server can each prove their identity.

Authentication protocols

Passbolt's developer documentation describes two challenge-based login methods:

• JWT authentication (preferred): the client signs a UUID challenge with its private key and encrypts it to the server's public key from /auth/verify.json. The server returns an access token (a JWT) and a refresh token encrypted to the user's key, and the client checks the returned verify token to confirm the server. Refresh tokens are single use: each refresh returns a new access token and a new refresh token.
• GPGAuth (legacy): a staged challenge exchange that sets a passbolt_session cookie and a CSRF token. Passbolt states that it will eventually be dropped in favour of JWT, and recommends the optional stage 0 server check where it is still used.

When MFA is on, the API answers with HTTP 403 and the list of providers; the client posts the code to /mfa/verify/<provider>.json and receives a passbolt_mfa cookie.

Single sign-on

Pro and Cloud support SSO with Microsoft Entra ID (since 3.9), AD FS, Google, Keycloak, Okta and PingOne. Passbolt's Entra ID page explains that SSO sits on top of the existing challenge login: signing in with the identity provider unlocks a server-side key that decrypts the user's passphrase, which is stored encrypted with a non-extractable symmetric key in the browser extension's local storage. Users sign in once with their passphrase after SSO is enabled before SSO is offered to them.

• Identity mapping: accounts are correlated by email. Passbolt's default uses the verified email claim and warns against mapping on attributes users can change without verification.
• Client secret lifecycle: Entra client secrets last 6, 12 or 24 months; Passbolt alerts administrators 10 days before expiry, and administrators can still sign in with their passphrase at /auth/login to replace an expired secret.
• Prompt setting: "Login" asks for Entra credentials each time; "None" reuses the active Entra session. Choose "Login" where shared or kiosk devices exist.

See the Identity Provider and SSO Security Guide for IdP-side controls.

Metadata encryption

Passbolt's own security check-up explains that v5 offers more than one metadata encryption mode, and that the default mode lets the server access the shared metadata key, which makes onboarding easier. Choose the mode that fits your threat model against your threat model, and if you use shared metadata encryption, rotate the metadata key periodically (Passbolt suggests yearly, or more often with high staff turnover).

Admin roles and privileged access

Passbolt separates administrators, who manage the organisation settings, from users, who manage only the resources shared with them. Since v5.8, custom roles can be granted narrower administrative tasks; Passbolt's account recovery documentation cites the example of letting non-administrators view, index and review recovery requests.

Role-based access control

RBAC (Organisation settings > Role-Based Access Control, v4.1.0 and later, all editions) lets administrators allow or deny individual features for users. Every feature is allowed by default. Since v5.8.0, denials for account recovery management, group creation and Offline mode actions are also enforced at the API; other denials shape the interface. Use RBAC to simplify what users see, and use resource permissions to decide what they can decrypt.

Account recovery and the organisation recovery key

Account recovery (Pro 3.6.0 and later, or Cloud) lets users deposit an encrypted backup of their private key that only holders of the ORK can unlock. It is disabled by default. The policies, from Passbolt's configuration page:

An imported ORK must be an RSA 4096-bit public GPG key with a passphrase, or Passbolt can generate one. Changing or disabling the policy requires the current ORK, which stops someone from re-enabling recovery with their own key. Passbolt offers two custody models:

• Most secure (Passbolt's recommendation): generate the ORK offline, store it offline (for example in a physical safe) and rotate it after each use.
• Most convenient: store the ORK in Passbolt and share it with a small group, with strict access, regular reviews and rotation when a holder leaves.

Two operational notes from the same page: changing the Passbolt domain name stops account recovery from working, and disabling the policy deletes the escrowed data, so users must enrol again. See the Break-Glass Account Guide for custody patterns.

Privileged access recommendations

• Few administrators: two or three named people, each with MFA and SSO where available. Use custom roles for recovery review rather than full admin rights.
• Directory sync accounts: the "Default Admin" that performs sync actions and the "Default Group Admin" for synced groups should be named service owners, reviewed like any administrator.
• Server access is admin access: anyone with shell access to the host can run Passbolt commands, read the configuration and reach the server key. Restrict SSH to an admin network and log every session.

Integrations, API tokens and service accounts

Scripts, the Passbolt CLI and integrations authenticate as Passbolt users with their own OpenPGP key. That makes each automation identity a full user, and the controls follow from it.

The MFA policy page states that the Prompt policy does not apply to API clients such as scripts or the CLI, and that MFA enforcement for authentication is configured at the provider level. Plan your automation users with that in mind: give them minimal shares, monitor their activity separately and rotate their keys when their owner changes. See the Secrets Management Guide.

Directory sync runs from cron as the web server user (for example www-data), never as root. Run "Simulate Synchronise" before the first real run, because a real sync sends invitations. Deleting a user in the directory removes them from Passbolt on the next sync, which is the leaver control; only direct group memberships are synced. See the Joiner-Mover-Leaver Guide.

Logging and detection

Passbolt writes one audit row per authenticated API call, apart from calls on a denylist that operators can extend. Entries cover resource and folder creation and updates, secret reads and updates, permission changes and user account changes. Passbolt documents the scope clearly: permission changes list the users, groups and levels involved, other updates are recorded as an item or secret update, and resource exports are outside the log, so pair it with endpoint and browser controls if you need to track exports.

What to alert on

• Bulk secret reads by one user or automation identity: possible harvesting (ATT&CK T1555.005 Password Managers).
• Permission changes on sensitive folders: shares granted to new users or groups.
• User created, role changed or deleted: account manipulation (T1098).
• Repeated authentication failures and MFA failures: from server and proxy logs, which Passbolt's check-up asks you to ship off the host.
• Unexpected outbound connections from the server: anything beyond SMTP, LDAP, the IdP and other configured integrations.

Metrics that show the baseline is working

• Healthcheck status: passbolt healthcheck clean after every upgrade and configuration change.
• MFA coverage: share of human users with an MFA provider configured (target: 100%).
• Leaver lag: hours from directory deletion to Passbolt removal, set by your sync interval.
• Secrets rotated after departures: share of secrets a leaver could decrypt that were rotated within your target window.
• Restore test age: days since the last timed restore of database and server key (Passbolt suggests at least yearly).
• Certificate lifetime: TLS certificate validity, aiming for 90 days and never above 366 as Passbolt advises.

Hardening baseline

Passbolt published an administrator security check-up that covers infrastructure, backups, configuration and clients. The table below condenses it; where a value is ours it is marked.

Phased rollout

1. Run the healthcheck: ./bin/cake passbolt healthcheck (path depends on install method) and fix every failure first.
2. Secure custody: back up the server key, decide the account recovery policy and ORK custody model, and document both outside any one person's head.
3. Harden the stack: TLS and HSTS, host patching, network limits and database permissions, using a staging server first where you have one.
4. Turn on MFA and SSO: configure providers, set the MFA policy, then enable SSO for a pilot group whose emails match exactly.
5. Connect the directory: simulate, then schedule sync as the web server user.
6. Ship logs: enable SIEM forwarding, set a purge window that meets retention requirements, and build the alerts above.
7. Roll back safely: take a database and key backup before every upgrade or configuration change so you can restore the prior state.
8. Review quarterly: active users, groups, resource owners, administrators, ORK holders and secrets that leavers could read.

Small teams on Community Edition can meet most of this with host hardening, TOTP, offline backups and SIEM forwarding. Larger organisations benefit from Pro features (directory sync, SSO, account recovery and the /actionlog API) because they move joiner and leaver handling and recovery into reviewed processes.

Framework mapping

Common misconfigurations

• Server key missing from backups: a database backup without the server OpenPGP key cannot restore a working server. Back up both and test the restore.
• ORK stored online with many holders: convenient, but every holder becomes a path to every escrowed key. Keep it offline or limit holders and rotate on change.
• Relying on RBAC to block API calls: outside the three API-enforced features, RBAC shapes the interface. Control access through resource permissions.
• Assuming the Prompt policy enforces MFA: Passbolt documents Prompt as an interface reminder. To require MFA at sign-in, configure it at the provider level, as Passbolt advises, and track coverage.
• Directory sync run as root, or with a privileged bind account: run it as the web server user with a read-only bind account.
• Revoking access without rotating secrets: a leaver may have copied what they could decrypt. Rotate secrets they had access to, using password expiry to flag them.

Practitioner checklist

• Run passbolt healthcheck after every upgrade and change.
• Back up the server OpenPGP key and the database off-host, and time a restore at least yearly.
• Choose an account recovery policy and keep the ORK offline, rotating it after each use.
• Enforce HTTPS with HSTS, TLS 1.3 where possible and inbound 443 only.
• Give the Passbolt database user least privilege and restrict SSH to an admin network.
• Configure MFA providers, set the MFA policy and review "Remember this device for a month".
• Map SSO users on verified email and rotate IdP client secrets before expiry.
• Use one dedicated Passbolt user per automation workload, shared only what it needs.
• Forward the audit log to a SIEM and alert on bulk reads, permission and user changes.
• Rotate secrets that departing users could decrypt.

Standards and references

• Passbolt: You're the admin now, a security check-up
• Passbolt: Account recovery configuration
• Passbolt: Role-based access control
• Passbolt: MFA policy
• Passbolt: API authentication
• Passbolt: SSO with Microsoft Entra ID
• Passbolt: Users directory
• Passbolt: Audit log

Related NHI Mgmt Group resources: Break-Glass Account Guide · Identity Provider and SSO Security Guide · SIEM Log Source Onboarding Checklist · OpenPGP and S/MIME Email Encryption Guide