Single Sign-On
Last updated on November 20, 2026
Single sign-on (SSO) delegates authentication to your identity provider, such as Okta, Microsoft Entra ID or Google Workspace. Members who sign in through SSO authenticate with your provider, and its policies, MFA included, apply to that sign-in.
SSO covers authentication. A user of your SSO domain who signs in through SSO for the first time joins the organization as a Viewer, with the organization's access for new members, which is no access by default. For directory-driven membership, add SCIM provisioning. Configuring SSO requires the Owner role.
Rolling out SSO takes three stages: configure your identity provider, verify your email domain, then require SSO once you have tested it.
SSO is available on Enterprise plans. Contact sales.
Protocols
| 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 > SSO 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. The issuer has to match the issuer in that document exactly, trailing slash included, and the IdP has to be reachable over the public internet. On a self-hosted instance, an IdP on your private network is allowed once its origin is trusted (see Identity provider on a private network).
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 > SSO and pick the SAML 2.0 tab.
Fill in the form:
- Email Domain: your domain.
- IdP Entity ID (Issuer): your provider's own identifier. Okta calls it Identity Provider Issuer, Microsoft Entra calls it Microsoft Entra Identifier, Google calls it Entity ID.
- 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 |
Verify your domain
Nobody can sign in with SSO until your email domain is verified. Verification proves that your organization controls the domain: once it is verified, no other organization can register or verify it.
After saving the configuration, the SSO dialog shows a TXT record: a Name and a Value.
Add that TXT record at your DNS provider. Most providers append your DNS zone (such as acme.com) to the name automatically, so the name field may only need the part before the zone. For a subdomain such as eng.acme.com in the acme.com zone, that part ends with eng.
Back in Settings > SSO, open Manage and click Verify domain. A new record can take up to an hour to appear.
Once the domain is verified, people whose email is on that domain or one of its subdomains see your identity provider when they enter their email on the sign-in page. They can still choose to sign in with a code. Use this stage to test the configuration with a few people.
Require SSO
Require SSO makes your identity provider the only way to sign in for your domain. Sign-in codes, passkeys and social accounts (Google, Microsoft, GitHub, GitLab, Atlassian) stop working for people on that domain, so your identity provider's MFA and offboarding apply to every sign-in.
To turn it on:
Sign out, then sign back in with SSO. Only an owner with an address on your domain, whose current session was opened with SSO, can turn it on. This proves the configuration works before anyone depends on it.
Open Settings > SSO and turn on Require SSO.
Choose whether to sign out the sessions on your domain that were not opened with SSO. If you do, the rule applies right away. Otherwise each of those sessions ends at its current expiry, within 7 days, and is no longer extended.
Everyone on your domain with a TofuPilot account receives an email telling them to sign in with your identity provider from now on.
- Owners keep a sign-in code, so a misconfigured identity provider cannot lock your organization out. Use it to fix the configuration. Their social accounts and passkeys stop working like everyone else's.
- On a self-hosted instance, Require SSO needs email, because the owners' code is sent by email. Without email, people still reach your identity provider by entering their email on the sign-in page, but Require SSO cannot be turned on.
- People outside your domain, such as contractors and suppliers you invite, keep their usual sign-in methods.
- Changing the SSO configuration or removing the provider turns Require SSO off. A changed configuration has to be tested again before it is required. The SSO dialog warns you before you save, Settings > SSO shows a banner until an owner turns it back on (or dismisses it, once the provider is removed), and every owner receives an email.
Sessions
A session opened with SSO never lasts longer than a fixed time, whatever its use, and also ends after 7 days without use. When it ends, the member signs in again through your identity provider, so someone removed from your identity provider loses access to the TofuPilot web app within that time.
API keys and MCP connections are not tied to the SSO session: they keep working until the person is removed from the organization. To remove people automatically when they leave your directory, add SCIM provisioning.
Set the length in Settings > SSO under SSO session length, from 1 hour to 30 days. The default is 24 hours. Sessions that are already open pick up a shorter length within a day.
Troubleshooting
| Symptom | Cause |
|---|---|
| Entering an email does not lead to your identity provider | Domain not verified yet. Email domain does not match (subdomains count). Configuration not saved. |
| IdP login succeeds but TofuPilot errors | Callback URL or ACS URL wrong, required scopes missing, email attribute not mapped. |
| IdP login succeeds but TofuPilot says the email is outside your SSO domain | Your identity provider sent an email address that is not on your verified domain or one of its subdomains. TofuPilot only accepts addresses on that domain. |
| Require SSO cannot be turned on | Your current session was not opened with SSO: sign out and sign back in with SSO. If your own email is not on the SSO domain, an owner with an address on the domain has to turn it on. The domain must also be verified. |
| People on your domain can sign in with a code again | Require SSO was turned off by a configuration change. Check the banner in Settings > SSO. |
| IdP group changes do not affect TofuPilot roles | Neither SSO nor SCIM sets roles. Change roles in Settings > Members. |
How is this guide?
Managing Members
Learn how to invite users, change roles, and remove members from your TofuPilot organization while keeping their test data traceable.
SCIM Provisioning
Learn how to sync members and groups from your identity provider to TofuPilot with SCIM, so account lifecycle stays in your directory.