Per-organisation SSO

Bring your own identity provider. Available on Team and above.

What you supply

Who can do what

New after v0.2.1. Saving the provider and adding or verifying a domain become owner-only in the first garboard release after v0.2.1. In v0.2.1, an admin can also do them.

Choosing the provider and its domains is owner-only because, at a verified domain, the provider signs in as every account there — owners included. Whoever chooses it chooses who can sign in as an owner, so it is held to the same rule as granting ownership. An admin is refused with owner role required. Members and viewers cannot read the configuration at all: they are the people an SSO requirement is imposed on.

Every change, and every connection test, 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, no one can save an identity provider at all — not even an owner — 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. An owner adds the domain, publishes the TXT record we give, then verifies.

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, everyone but an owner — admins included — 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:

EVERYONE ELSE  must use the IdP, admins included
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 sanctioned escape hatch gets ripped out during the first incident.

Three guards worth knowing:

• It refuses to turn on unless a full configuration is stored, at least one domain is verified, the provider’s discovery document fetches at that moment, and this instance’s sign-in page can send members to that provider — today, that means the instance-level GARBOARD_OIDC_ISSUER names the same provider. The refusal names the one that is missing. A typo cannot lock your members out.
• Turning it off has no preconditions. The off switch cannot be held hostage by the thing it switches off: if the provider breaks, an owner signs in with a password and turns it off.
• Changing the issuer turns it off. The new provider has passed none of the checks above, so requiring it again is a deliberate act.

A personal access token is not a sign-in, so it never satisfies the requirement and never gets the break-glass — an owner’s included. Under enforcement every token in the organisation is refused: a credential that is not a sign-in does not get a door that nothing records. An admin’s, member’s or viewer’s password session stops working the moment enforcement is switched on. An owner’s password session minted before then 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 refused SSO sign-in names a coarse class of failure and never what your provider returned: for example SSO sign-in failed when the exchange with your provider fails, invalid SSO state for a stale or replayed sign-in, or a one-line reason when the provider has not verified the email or is not authorised for that email’s domain. The detail is in the server log. That is not politeness — a detailed error tells an attacker which half of their guess was right.