Single sign-on
Configure SAML sign-in, provisioning, group mapping, and recovery access.
Single sign-on connects an organization to a Security Assertion Markup Language (SAML) identity provider. Sign-in establishes user identity; role bindings determine infrastructure access.
Configure the connection
You have the Organization Owner role. Open Organization settings → Authentication → SAML. Copy the service-provider entity ID and assertion-consumer URL into the identity provider. Import the provider's metadata or configure its issuer, sign-in URL, and signing certificate.
The public console URL must match the externally reachable origin. A self-hosted reverse proxy must preserve that origin and terminate TLS with a trusted certificate. See Configuration.
Identity mapping
Use a stable unique subject to bind the provider identity to a member. Email is required for contact and approved enrollment matching; display name is optional. A display name must not become the member's identity key.
Optional group attributes can map the provider's groups to configured Infra teams. Those mappings grant the teams' existing role bindings rather than creating permissions from arbitrary assertion text. Use SCIM when membership and deactivation must synchronize independently of the next sign-in.
Changing a provider subject can create a new identity or require an administrator-approved account link. A changed email does not automatically transfer ownership between identities.
Test before enforcement
Create a test connection, sign in as a non-owner account, and verify project access, team mapping, session renewal, and logout. Keep an active recovery-owner session until the test succeeds.
Enable enforcement only after all required users have a verified provider identity. Enforcement restricts normal organization sign-in to the configured provider; designated recovery access follows the explicit recovery policy.
Provisioning and groups
SCIM provisioning synchronizes directory membership independently of interactive sign-in. Just-in-time provisioning can create a member after a valid assertion when organization policy permits it. The default project access is none. Grant access through group-to-team mappings or explicit role bindings.
Group mappings apply only to configured teams. An unrecognized provider group does not create an administrator role. Review mappings that grant organization-wide permissions more carefully than mappings for a single project.
Removing a group claim affects the next access synchronization. For immediate removal, disable the member and revoke sessions and API keys as required by the access removal procedure.
Certificates and failure
Rotate signing certificates before expiry. Configure overlapping trusted certificates during the provider's transition when supported. A signature, audience, issuer, or time validation failure rejects the assertion and leaves the user unauthenticated.
An identity-provider outage does not stop running droplets. It can prevent new operator sessions. Use the tested recovery account to repair configuration; do not disable organization authentication through unreviewed database edits.
Audit and session policy
Sign-in events, connection changes, enforcement changes, and recovery use are audited. Session lifetime and reauthentication controls are configured separately from API-key expiry. See API authentication for machine access.