You need the Admin or Owner tenant role, or be the tenant’s primary owner. See Organizations and roles. At least one of your email domains must be verified with DNS: single sign-on admits only addresses at your verified domains, so your identity provider can vouch for your people and nobody else’s. See Domains. Your identity provider must support SAML 2.0 and be able to send each person’s email address as the NameID. A tenant has one identity provider connection.
Set up single sign-on
Open the Recursion console, open Settings, and choose Enterprise SSO. The page walks through four steps.1
Create a SAML app at your identity provider
The first card, Create a SAML app at your identity provider, shows the values your provider needs: Single sign-on URL (ACS), Audience URI (SP entity ID), and SP metadata URL. Copy them from the console into a new SAML app at your provider. Provider-specific steps are below.
2
Check your verified domains
The second card lists your tenant’s DNS-verified domains. If none are listed, click Manage domains and verify one. You can save and test the connection before then, but you can’t turn it on.
3
Connect your identity provider
In Connect your identity provider, choose where the settings come from:
- Metadata URL: paste your provider’s metadata URL into IdP metadata URL. Recursion reads the sign-in URL and signing certificate from it, and can refresh them later.
- Entered by hand: paste the IdP single sign-on URL and the Signing certificate in PEM form, starting with
-----BEGIN CERTIFICATE-----. The certificate is public; no key is stored.
4
Test it
Test it shows a Test sign-in link. Open it in a private window and sign in at your identity provider. The link works whether single sign-on is on or off. While it’s off, it signs in existing members only, so test with your own account or a test account that’s already a member.
Identity provider setup
Use the values from the console’s first card. Each provider must send the person’s email address as the NameID.- Okta
- Microsoft Entra ID
- Google Workspace
- In the Okta Admin Console, go to Applications › Applications, click Create App Integration, and choose SAML 2.0.
- Set Single sign-on URL to the console’s Single sign-on URL (ACS), and Audience URI (SP Entity ID) to its Audience URI (SP entity ID).
- Set Name ID format to EmailAddress and Application username to Email.
- Finish creating the app, then assign the people or groups who should sign in on its Assignments tab.
- On the Sign On tab, copy the Metadata URL and paste it into IdP metadata URL in the console.
Require single sign-on
Check Require single sign-on for your verified domains under Require it, and click Save changes. The connection must be on first. While it’s required, people at your verified domains can sign in only through your identity provider. Email, Google, and other sign-ins are refused for those addresses, current members included. The sign-in screen tells them to enter their work email and continue through your provider.Keep the certificate current
Identity providers rotate their signing certificates. Enterprise SSO shows the current certificate’s expiry and warns you before it expires.- Metadata URL: after your provider publishes the new certificate, click Refresh from metadata.
- Entered by hand: paste the new certificate into Signing certificate and click Save changes. Leave the field empty to keep the current one.
Turn off or remove single sign-on
- Turn off: uncheck Offer single sign-on at sign-in and click Save changes. The connection’s settings are kept, and the test link still works for existing members. Sign-in from your identity provider’s app catalog also keeps working if you allowed it; uncheck that too to stop it.
- Remove: click Remove, then Remove single sign-on. Members who joined through it stay, and can sign in another way.
How people sign in
- From the sign-in screen. A person enters their work email and clicks Continue. An address at one of your verified domains goes to your identity provider.
- From your identity provider, if you allow it. This stays off until an admin checks Allow sign-in from your identity provider’s app catalog under App catalog and confirms the warning. People can then open Recursion from your provider’s app catalog, such as the Okta dashboard, Microsoft My Apps, or the Google app launcher. The warning is there because a sign-in that starts at the identity provider cannot be checked as one the person asked for, so someone can be tricked into a session that belongs to an attacker.
- New people join automatically. The first time someone signs in through your provider, they join your tenant at the domain’s Default role, set on the Domains card. They don’t get a separate tenant of their own.
- Existing accounts are kept. If someone already signs in with Google or email at the same address, their first single sign-on asks them to confirm that account once. The two sign-in methods then share one account.
- Removed members stay removed. Someone you removed from the tenant can’t rejoin through single sign-on.
- Only verified domains. Your provider can’t sign in an address at a domain your tenant hasn’t verified, whatever it asserts.
What can go wrong
The most common problems:- The sign-in screen says your organization’s single sign-on could not sign you in. Your identity provider’s app settings don’t match the console, most often the audience or entity ID. Compare the app’s ACS URL and entity ID with the console’s first card, then try the test link again.
- Sign-in fails even though the ACS URL and entity ID match. Your provider doesn’t send the person’s email address as the NameID. Set it as in Identity provider setup.
- Your provider refuses the person before they reach Recursion. The person isn’t assigned to the SAML app at your provider. Assign them, or their group, to the app.
Every single sign-on problem
Every single sign-on problem
Next steps
Domains
Claim and verify the domains single sign-on admits.
Organizations and roles
See what each role can do.