Single Sign-On
Last updated on May 21, 2026
Your identity provider (Okta, Microsoft Entra, Azure AD, Auth0, OneLogin, Google Workspace) decides who can sign in. Anyone whose email matches your domain is redirected to your provider on every login, so credentials never live on TofuPilot.
SSO covers authentication only. For directory-driven membership and role assignment, add SCIM provisioning.
SSO is available on Enterprise plans. Contact sales.
Protocols
TofuPilot supports the two protocols you are likely to encounter when you wire in an identity provider.
| Protocol | Notes |
|---|---|
| OIDC | JSON-based. Default for Okta, Auth0, Microsoft Entra, OneLogin. |
| SAML 2.0 | XML-based. Used in legacy and government environments. |
Configure OIDC
OIDC requires four values: issuer URL, client ID, client secret, and redirect URI. You collect them from your IdP and paste them into TofuPilot.
In your IdP, create an OIDC application for TofuPilot with application type Web, then grant access to the users or groups you want signing in.
In TofuPilot, open Settings > Organization > Single Sign-On and pick the OIDC tab.
Fill in the form:
- Email Domain: your domain, e.g.
acme.com. - Issuer URL: from your IdP application.
- Client ID and Client Secret: from your IdP application.
Copy the Callback URL shown in the form, then paste it into your IdP application's allowed redirect URIs.
Save. TofuPilot validates the connection by fetching your IdP's discovery document.
Required OIDC scopes
Your OIDC application has to grant these scopes so TofuPilot can read the identity claims it needs:
openidprofileemail
Configure SAML 2.0
SAML uses an XML metadata exchange between TofuPilot (the service provider) and your IdP, so the setup is a two-way swap of identifiers and certificates.
In your IdP, create a SAML application for TofuPilot.
In TofuPilot, open Settings > Organization > Single Sign-On and pick the SAML 2.0 tab.
Fill in the form:
- Email Domain: your domain.
- IdP SSO URL: your provider's SSO endpoint.
- IdP Certificate: X.509 signing certificate in PEM format.
Copy the SP Metadata URL and import it into your IdP, or configure manually with the ACS URL and Entity ID shown.
Save.
Required SAML attribute mappings
Your SAML assertion has to include at least the email attribute, and a display name is recommended.
| TofuPilot attribute | Required | Source |
|---|---|---|
email | Yes | Primary email address |
name or displayName | No | Full display name |
Sessions
A successful SSO sign-in creates a 24-hour session. After expiry, you are redirected to your IdP again, because there is no TofuPilot password to fall back on.
Break-glass account
Keep one Owner account that signs in with email, not SSO. You use it if the IdP goes down or SSO breaks.
Verify the break-glass account before enabling SSO enforcement.
Enforce SSO
Once SSO works for your users, you can require it for everyone.
- Open Settings > Organization > Single Sign-On.
- Toggle Require SSO for all members.
Members who try email/password are bounced to the IdP. The break-glass account is exempt.
Troubleshooting
If sign-in fails, the table below covers the most common causes.
| Symptom | Cause |
|---|---|
| Users not redirected to IdP | Email domain mismatch (subdomains count). Configuration not saved. |
| IdP login succeeds but TofuPilot errors | Callback URL wrong, required scopes missing, email attribute not mapped. |
| IdP group changes do not affect TofuPilot roles | SSO does not push groups. Use SCIM. |
How is this guide?