Single sign-on (OIDC)

How it works

MangoSSH signs in to your IdP directly, in the user's own browser, as a public client using the authorization code flow with PKCE. It sends the resulting ID token to your vault server, which checks the signature against the IdP's published keys, the issuer, the client ID, the expiry, and a one-time nonce tied to that device. It then maps the user's groups to a vault role.

An existing member simply gets an SSO session and their role updated. A new device is different, because vault membership is end-to-end encrypted: only a device that already holds the vault key can let another one in. So the server files an SSO-vouched join request, and an admin's MangoSSH completes it automatically after checking the IdP's token itself.

What you need

• A Cloud Vault or Self Hosting Vault, and a MangoSSH device that is an admin of it.
• An OIDC identity provider whose discovery document (/.well-known/openid-configuration) your vault server and your users' devices can reach.
• Rights to register an application at that IdP.

Step 1 — Register MangoSSH at your IdP

Whatever the IdP, the application must be:

• a public client: no client secret. MangoSSH does not send one;
• allowed to use the authorization code flow with PKCE (S256);
• registered with exactly this redirect URI: http://localhost:8251/callback;
• set up to put the user's groups in the ID token, if you want groups to decide roles. MangoSSH asks for the scopes openid email profile and reads groups from the ID token only.

Note the issuer URL and the client ID. The issuer must be the exact value your IdP's discovery document lists as issuer (a trailing slash does not matter).

Menu names at each IdP change over time; the requirements in the list above are what matter.

Step 2 — Turn on SSO in MangoSSH

1. On an admin device, open Dashboard → PAM Dashboard, then Single sign-on under Access.

2. Fill in the settings (table below). Use Add Mapping for each IdP group that should grant a role. The redirect URI to register is shown there too, with a Copy link.

3. Tick Enable single sign-on. Tick Require it for access to targets only once people can sign in (see “What SSO gates”).

4. Click Save SSO Settings. The server fetches your IdP's discovery document and keys straight away, so a wrong issuer fails here rather than at everyone's next sign-in.

Step 3 — Teammates join with SSO

1. Send each teammate the Server URL and the Vault ID.

2. They open Settings → Self Hosting Vault (or Cloud Vault), fill in the join form with an optional device label, and click Join with SSO.

3. Their browser opens at your IdP. After they sign in, the browser says “Signed in. You can close this window and return to MangoSSH.”, and the app says which role their groups grant.

4. An eligible admin device (see below) checks for SSO requests about every 30 seconds. Once it admits the request, the new device receives the vault key and starts syncing. Nobody has to click Approve.

A sign-in that maps to Admin is never admitted automatically. It waits under Pending join requests for an admin to approve it by hand.

Auto-approval and the pinned trust anchor

An admin device completes SSO joins only when all of these hold:

• MangoSSH is running on it and the vault is unlocked;
• it is an admin of the vault;
• its admin has clicked Save SSO Settings on that device. Saving pins the issuer and client ID locally, and the Single sign-on panel shows what the device trusts.

Before sealing the vault key, the admin's app re-checks the ID token itself: the signature against the pinned IdP's keys, the pinned issuer and client ID, a nonce proving the token was issued for exactly that device and its encryption key, and a sign-in no more than 7 days old. It uses its own pinned settings, not the server's copy, so a compromised vault server cannot get a device admitted that your IdP never vouched for.

If a check fails, the device writes the refusal to its audit log once and leaves the request under Pending join requests. If you change the issuer or client ID, save the settings on each admin device that should auto-approve.

Signing in as a member

The Single sign-on panel shows this device's session, for example “signed in as ann@corp.example (editor) · session ends in 9 hours”. To start or renew one, click Sign in with SSO. If your IdP session is still active, the browser step is usually instant.

What SSO gates

With Require it for access to targets ticked, the vault server issues these only to a device with a current SSO session:

• PAM Broker tickets;
• browser share links;
• SSH certificates from the MangoSSH CA.

Vault sync is deliberately not gated: people keep their shared hosts and can still connect directly to hosts whose credentials they hold. Admins are not exempt from the gate, but they cannot lock themselves out, because changing the SSO settings needs only the admin role. The server refuses saving “required” with no group mapping and no default role, since that would refuse everyone.

Offboarding

Disable or remove the user in your IdP. They cannot sign in again, so their SSO session runs out within Session length, and from then on the gated credentials are refused. A user whose groups no longer map to any role, with no default role, is refused at sign-in in the same way.

Limits in this version

• No immediate revocation: access ends when the SSO session expires, not the moment the IdP disables the user.
• No SCIM provisioning. Members whose groups stop mapping are refused at sign-in but are not removed from the vault.
• Users who only open browser share links do not sign in with SSO. The gate applies to the device that creates the link.

Troubleshooting