Set up single sign-on

Prove your company's email domain, connect your identity provider and, when you are ready, require it of everyone at that domain.

In short

Single sign-on lets people at your company's email domains sign in through your own identity provider instead of a {{brand}} password. The provider can be Microsoft Entra ID, Okta, Google Workspace, AD FS or any other that speaks OpenID Connect or SAML 2.0, and an organization can connect several. You prove the domain, connect the provider, try it, and only then require it. It comes with the Enterprise plan.

Before you start

• Who: "Change organization settings". Name a break-glass administrator before you require single sign-on.
• Plan: single sign-on comes with the Enterprise plan.
• First: access to the company's DNS to add a TXT record, and an application at your identity provider that uses OpenID Connect or SAML 2.0.

Steps

1. Open Settings › Single sign-on and add the part after the @ of your work addresses.
2. Copy the TXT record the page shows and add it at the company that runs DNS for the domain.
3. Choose "Check now". A new record can take a few minutes to show, sometimes longer.

1. At your provider, create an application for {{brand}}. For OpenID Connect, use the authorization code flow and give it the redirect address the page shows. For SAML, give it the entity ID and the answer address the page shows.
2. Fill in the issuer address, the client ID and the client secret the provider gives you - or, for SAML, paste its metadata or its metadata address - and save.
3. With more than one proved domain, tick the domains this provider signs in. With none ticked it signs in every proved domain no other provider names.
4. Choose "Test connection" to check that the provider's settings can be read.

1. Choose "Sign in through the provider". You are taken to your provider and brought back signed in.
2. The page then shows the day it worked. It is the only proof that the client secret is right.

Result: people at your proved domains can choose "Continue with single sign-on" on the sign-in form.

Good to know

• It is set up by someone who manages the organization's settings.
• Your provider is believed only for an address it says it verified, at a domain your organization has proved. It can never sign in anyone at another company's domain.
• Someone who signs in through it for the first time gets an account and joins the organization with your default role for newcomers.
• An existing account with that address is connected to it. An account with its own two-step sign-in is connected only after its owner signs in with the password once more, and still asks for its authenticator code afterwards.
• One organization holds a domain at a time. Leave the TXT record in place: it is read every day. If it goes missing, administrators are told and have 7 days to put it back before the domain stops counting.
• Allowed email domains under Joining is a different thing: it filters who may join and proves nothing.
• The provider must send the person's email address and say it is verified. Okta and Google Workspace do so with the email scope. Microsoft Entra ID needs the optional claims email and xms_edov added to the ID token.
• The client secret is kept encrypted and never shown again. The issuer must be an https address on the public internet.
• A different issuer or client ID is a new connection. Everyone is connected again on their next sign-in, and requiring single sign-on is switched off until a sign-in through it has worked.
• Several providers: choose "Add a provider" above the form. Each one signs in the domains ticked for it, a domain belongs to one provider at a time, and one provider at most signs in all the rest. Steps 3 and 5 are about the provider chosen above the form.
• Sign-in from the provider and sign-out, under each provider: "Let people start from the provider" lets people open {{brand}} from the provider's app tile - give the provider the initiate login address shown. What the tile sends always becomes a fresh sign-in that starts here.
• "Sign out at the provider too" sends someone who signs out on to the provider, so its session ends as well. A SAML provider needs its sign-out address; for OpenID Connect the address the provider publishes is used unless you give one.

Roles from groups (optional)

• Map a group your provider sends to a role. Lines are read from the top and the first match wins; someone in none of the groups gets the default role for newcomers.
• Roles follow the provider at every sign-in. The owner's role never changes, and the last administrator is never moved down.
• You can map groups only to roles you could give someone yourself.
• When a new role would add a paid seat that has to be confirmed, the person keeps the role they have and the administrators are asked.
• A sign-in that carries no groups at all changes nobody's role.

Teams from groups and trying a sign-in (optional)

• Under the provider's steps, Teams from groups leads the people of a group into a team. A group can lead to several teams, and a team can take several groups.
• At every sign-in the person gets a place in each team their groups lead to - at once if the organization places people in teams directly (Policies), otherwise as an invitation they accept or decline. A declined invitation stays their answer.
• Once the person's groups no longer lead to a team, the place the provider made goes again. A place someone arranged by hand is never touched, and the team's own lead or deputy is never taken out.
• You can lead groups only to teams you arrange: any team if you manage teams, otherwise a team in the branch you lead. A line counts while the person who saved it still arranges its team; a skipped line places and removes nobody until someone who arranges the team saves it again.
• Try a sign-in: type the groups the provider would send, choose someone new or a member, and see the role and every team the sign-in would give, with your unsaved team lines if you have any. Nothing changes.

Require single sign-on (optional)

When single sign-on is required, addresses at your proved domains cannot sign in with a password or a passkey, reset a password or create an account by hand. They sign in through your provider.

• Name one break-glass administrator first: a person who manages the organization's settings and keeps their own sign-in for the day the provider is down. They need a password or a passkey.
• It can be turned on only after a sign-in through the provider has worked.
• Accounts with their own two-step sign-in keep their password until they are connected.
• Someone removed at your provider cannot sign in again, but a session already running lasts until it ends - by default at most 12 hours. To stop someone at once, remove them from the organization too.

What it does not do

• Your provider does not create accounts ahead of a first sign-in on its own. To add and remove people from the provider, set up SCIM provisioning (see Related).
• Removing someone at your provider does not delete their {{brand}} account or take them out of the organization. It stops them signing in.
• A person's email address here does not follow a change of address at the provider. Change it in their account, or ask them to.

If something goes wrong

• The domain is not proved yet: DNS can take a while. Check the record's name and value, then "Check now" again.
• A public mail domain such as gmail.com cannot be proved.
• "Test connection" fails: check the issuer address is https and public, and the client ID.
• Sign-in through the provider fails: check the redirect address at the provider, the client secret, and that the provider sends a verified email.
• Your own address is not at a proved domain: ask a colleague at that domain to choose "Continue with single sign-on" on the sign-in form.

Related

• /help/settings/sign-in-with-single-sign-on
• /help/organizations/joining-rules
• /help/organizations/organization-policies