Administration
Per-organisation SSO
Bring your own identity provider. Available on Team and above.
What you supply
| Field | Notes |
|---|---|
| Issuer | A plain https URL with a host and no username, password, query string or fragment. http://, file://, a bare hostname or https://user:pw@host are refused. |
| Client ID | From your identity provider application. |
| Client secret | Stored envelope-encrypted, sealed against your organisation’s id. |
| Verified domains | The email domains your provider may assert. Each must be proven by DNS first. |
| Require SSO | Enforcement, with an owner break-glass. See below. |
Writing the configuration requires admin or owner, and is audited.
The client secret has no read path
It is sealed against your organisation id, and there is no path that returns it. Rotating means entering a new one, never viewing the old one. A support engineer cannot read it, because the software cannot.
This depends on GARBOARD_SECRET_KEY: on an instance with no envelope root key, an admin cannot save an identity provider at all, because there is nothing to seal the secret with. See install.
Domains must be proven
A domain routes nothing until it is verified by DNS. Add the TXT record we give you, then verify.
Without this, an organisation could claim a domain it does not own and thereby capture sign-ins for it. Domain verification is not paperwork; it is the control that makes discovery safe.
Enforced SSO, and why owners keep a password
With Require SSO on, members must sign in through your identity provider. Owners keep the password door, and every sign-in through it is recorded as the session is minted.
The design is deliberately not absolute:
members must use the IdP
OWNERS keep the password door, and every SIGN-IN through it is recorded
An identity provider that breaks, or a configuration that was wrong, would otherwise lock everybody out — and the fix would be a database edit during an outage. This mirrors the gate’s own break-glass: a blocking control with no governed escape hatch gets ripped out during the first incident.
Two guards worth knowing:
- It refuses to turn on until the admin enabling it has themselves signed in through the configured provider. You cannot lock yourself out with a typo.
- Turning it off is never gated by SSO. The off switch cannot be held hostage by the thing it switches off.
A personal access token is not a sign-in, so it never receives a break-glass entry — a credential that is not a sign-in does not get one that nothing records. And a password session minted before enforcement was switched on keeps working until it expires, with no entry, because there was nothing to record when it was minted.
Failures are deliberately vague to the browser
A failed SSO sign-in says SSO sign-in failed. The detail is in the server log. That is not politeness — a detailed error tells an attacker which half of their guess was right.