Single sign-on and SCIM

Single sign-on proves who someone is. It does not decrypt anything. Your vault stays end-to-end encrypted:

• Normally, single sign-on is an extra step. Members sign in at the identity provider and then enter their master password, plus their Secret Key on a new device.
• On trusted devices, signing in at the identity provider can open the vault without a master password. You must allow this for the organization explicitly (see below).

Passbox supports OpenID Connect. SAML is not supported. Most providers offer both.

You need the owner or admin role.

1. Open Family & team, your organization, then Settings → Single sign-on → Set up.
2. Choose the provider and enter a name for the sign-in button.
3. Copy the redirect URI and add it at your identity provider (guides below).
4. Enter the issuer URL, client ID and client secret. Passbox stores the secret encrypted and never shows it again.
5. Enter your company's email domains, one per line.
6. Choose Check connection. Passbox reads the provider's settings.
7. Turn on Single sign-on is on and save.
8. Test sign-in opens the provider in a window and shows what it sends to Passbox and whether a real sign-in would work. Nobody is signed in.

On a server, each email domain can belong to only one organization.

• Require single sign-on: Members must sign in through the provider. Owners and admins can always use their master password too, so a broken provider cannot lock anyone out. How long a device is remembered after a sign-in is set under Advanced: claims and token request (default: 12 hours).
• Allow unlocking with single sign-on: Members can trust devices and then unlock without a master password. Read the section "Trusted devices" first.
• Require a verified email (under Advanced: claims and token request, on by default): Passbox accepts only addresses the provider reports as verified.

After a sign-in through single sign-on, Passbox does not also ask for its own two-factor sign-in. So require multi-factor authentication at your identity provider.

Microsoft Entra ID

1. Entra admin center → App registrations → New registration: name "Passbox", single tenant, redirect URI of type Web with the redirect URI from Passbox.
2. Certificates & secrets → New client secret. Copy the value, not the ID.
3. Token configuration → Add optional claim → ID token → email.
4. In Passbox: issuer https://login.microsoftonline.com/<tenant-id>/v2.0, client ID is the application ID. Under Advanced: claims and token request, turn off "Require a verified email", because Entra ID does not send this claim.

Google Workspace

1. Google Cloud console → APIs & Services → OAuth consent screen: Internal. Then Credentials → OAuth client ID → Web application, with the redirect URI from Passbox.
2. In Passbox: issuer https://accounts.google.com, plus the client ID and secret.

Okta

1. Applications → Create App Integration → OIDC, Web Application. The sign-in redirect URI is the redirect URI from Passbox. Assign people or groups.
2. In Passbox: issuer https://<your-org>.okta.com or https://<your-org>.okta.com/oauth2/default, plus the client ID and secret.

Keycloak

1. Realm → Clients → Create client: OpenID Connect, client ID "passbox", client authentication on, standard flow on, valid redirect URI from Passbox. Under Advanced set PKCE to S256.
2. In Passbox: issuer https://<host>/realms/<realm>, secret from the Credentials tab.

authentik

1. Providers → Create → OAuth2/OpenID Provider, confidential client, redirect URI from Passbox, signing with your certificate. Then an application with the slug "passbox".
2. In Passbox: issuer https://<host>/application/o/passbox/ with the trailing slash.

ZITADEL

1. Project → New application → Web, method Code, redirect URI from Passbox.
2. In Passbox: issuer https://<instance>.zitadel.cloud or your own domain, client ID and secret.

On the sign-in page, members choose Use single sign-on (SSO) or type their company email address, and the option appears by itself. After signing in at the provider, they enter their master password as usual.

Single sign-on works in the web app in the browser. In the desktop app, the browser extension, the phone apps and on the command line, members sign in with their master password.

Anyone without a Passbox account creates one first. Passbox does not create accounts automatically on the first sign-in, because the master password and Secret Key must be created on the person's device.

With Allow unlocking with single sign-on on, members can trust a device under Settings → Trusted devices with Trust this browser. Signing in at the provider then opens the vault on that device without a master password.

An already trusted device approves another one: both show a code, the member compares it and chooses Approve.

You remove a device under Trusted devices → Remove. It then needs the master password again.

With SCIM 2.0, your directory sends people and groups to Passbox.

1. In the single sign-on settings, open Provisioning (SCIM). It shows the SCIM base URL.
2. Choose Create token, enter a name and a validity of 1 to 730 days. The token is shown only once.
3. Enter the base URL and token at your provider, for example in Entra ID under Enterprise applications → Provisioning → Automatic, or in Okta under Provisioning. Keycloak, authentik, ZITADEL, JumpCloud and OneLogin work through their SCIM 2.0 connector.

What happens then:

• New people get an invitation by email or join on their first sign-in through single sign-on. They then wait for confirmation. Confirm them under Provisioned people. Only an admin can do this, because only an admin's device can give them the organization's keys.
• Deactivated people lose access at once. Passbox signs them out on all devices and removes their trusted devices. Reactivating restores access.
• Directory groups are shown. Adding people to Passbox groups is up to you, because groups have their own keys.

Create a new token before one expires and revoke the old one. Passbox marks tokens that expire within the next 14 days.

• SAML is not supported.
• Single sign-on works in the web app in the browser, not yet in the desktop app, the extension, the phone apps or on the command line.
• Passbox does not verify that an email domain really belongs to an organization. On a shared server, a domain belongs to the organization that adds it first. The domain only decides which sign-in is offered. It never signs in anyone who is not a member.
• Accounts are not created automatically on the first sign-in, and directory groups do not become Passbox groups automatically.

If you run Passbox yourself, set your server's address first, see Server configuration.