Skip to content

Single sign-on: sign in with your identity provider

Single sign-on lets the people in your account sign in with your organisation’s identity provider instead of an emailed link. It speaks OpenID Connect, and the setup page has instructions in the words of Okta, Microsoft Entra ID and Google Workspace, and for any other OpenID Connect provider. (SAML is planned.)

Only owners set it up (Settings → Single sign-on). Everyone else sees one line: whether single sign-on is off, allowed or required in the account.

The page walks through the steps; each can be revisited later.

  1. Choose your identity provider. This creates the account’s connection, off, with nothing in it yet.

  2. Create an app in your provider. The page shows what to paste into it, labelled with your provider’s own field names, each with a Copy button:

    • Okta: an app integration with sign-in method OIDC - OpenID Connect and application type Web Application. Paste the redirect URI into Sign-in redirect URIs, and the sign-in link into Initiate login URI with Login initiated by set to Either Okta or App, so the app’s tile opens it. Assign the people or groups who should sign in.
    • Microsoft Entra ID: an app registration for accounts in your directory only, with a Web redirect URI. Create a client secret under Certificates & secrets, and under Token configuration add the optional ID token claims email and xms_edov: we accept only an address Entra says is verified, which needs your domain verified in your Entra tenant. The issuer is https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0.
    • Google Workspace: in the Google Cloud console, under Google Auth Platform, set the audience to Internal, then create an OAuth client of type Web application and paste the redirect URI into Authorized redirect URIs. The issuer is https://accounts.google.com.
    • Another provider: an OpenID Connect web application using the authorization code flow, signing ID tokens with RS256, and sending email_verified as true.

    The scopes are openid email profile.

  3. Tell us about your identity provider: the issuer URL (exactly as your provider writes it, a trailing / included), the client ID and the client secret, and, if your provider shows one, the day the secret expires. We read the rest from your provider’s discovery document when you save, and refuse an address that is not https, that points at our own site, or a provider that does not sign with RS256. The client secret is never shown again: the page shows its last four characters.

  4. Verify your domains (the Domains pane). For each domain your people’s addresses are at, publish the TXT record the page shows and press Check. A domain stays verified while its record is there. If the daily check stops finding it, every owner is told, and the page shows the record again with the day it went missing and Check; one missing for 14 days in a row lapses. Members who already sign in with single sign-on keep doing so through your sign-in link after a lapse, but typing an address at that domain no longer finds single sign-on. Your verified domains are what the sign-in pages show people, so they know a sign-in link is really yours, and what lets people find single sign-on by typing their address.

  5. Test sign-in. This opens your provider in the same tab and comes back to the page with the result: the address and the permanent id your provider sent, or one sentence naming what to fix. A test signs nobody in.

  6. Apply, once the test has passed. Until then nothing you saved affects anyone.

  7. Turn it on (the Who signs in pane): Allowed (people may use single sign-on or an email link) or Required (people must use single sign-on). You can also let people at your verified domains join as members on their first sign-in.

Saving your provider’s details writes a draft. The live version keeps signing people in until you test the draft and apply it, so a mistyped issuer or secret is a failed test, never an outage. Discard draft throws a draft away. When a draft changes the issuer (a move to a new identity provider), the page says how many people are linked to the current one: after you apply, each links again at their next sign-in. Applying a new issuer also signs out everyone who signed in through the old one (you too, if you did: the page says so before you press Apply, and how many sessions ended after), and a sign-in the old provider answered but that was not finished yet is refused (the person starts again): nothing the old provider vouched for outlasts the change. A single sign-on session counts only while the provider it came through is the live one, checked on every request, so even a sign-in that was finishing at the very moment you pressed Apply is signed out at its first request.

Requiring single sign-on, and recovery owners

Section titled “Requiring single sign-on, and recovery owners”

To require single sign-on you need a live version (one you applied after its test passed: a later test of the live version, passed or refused, is a report and changes nothing), at least one verified domain, and at least one recovery owner: an owner who can still sign in with an email link while single sign-on is required, so someone can fix it if it stops working. When you turn Required on, everyone signed in with an email link is signed out, except the recovery owners, and every owner is told how many people that was. While single sign-on is required, the last recovery owner who is an owner cannot be removed, demoted or leave: name another owner a recovery owner first.

If your email runs on the same provider as your sign-in (Google Workspace or Microsoft 365), an outage of that provider also stops the sign-in email. Make at least one recovery owner someone whose mailbox is elsewhere.

  • From the sign-in page: type your work address and press Continue. If your domain uses single sign-on, you go to your identity provider; if single sign-on is only allowed, you can choose an email link instead.
  • From your sign-in link (Settings shows it once single sign-on is live): bookmark it, put it on an intranet page, or give it to your provider’s app tile. Followed from another site, it first shows which account it signs in to (by its verified domains) and where you will sign in, and asks you to Continue. Sign in once from the sign-in page with your work address, and that browser skips this step for 90 days.
  • The first time an owner signs in with single sign-on, and for anyone outside your verified domains, we email a code to their address, once, to confirm the mailbox is theirs. The email also has a No, it wasn’t me link: if someone is signing in as you, it stops that sign-in and tells every owner.
  • After a sign-in, the page says where you are: “Signed in to the account that owns your domains as your address through your provider’s host”, with Not you? Sign out. The top of the sidebar (the top bar, on a phone) shows the address you are signed in as on every page, too.
  • Each identity provider speaks only for its own account. Signed in with single sign-on, you see only that account: to use another account you belong to, sign out and sign in to it (with its own link or single sign-on).
  • Your sign-in link and redirect URI name your connection by a long random id, so nobody can find another account’s by guessing.
Section titled “When a person’s identity at your provider changes: Unlink”

The first time someone signs in with single sign-on, their address is linked to the identity your provider sent. After that, a sign-in for that address from a different identity is refused, and so is a sign-in through their identity with a different address; every owner is told whose link refused it, because it may be someone at your provider using an address that is not theirs. When the change is expected (their mailbox was given to someone new, or your provider replaced their account), an owner unlinks them: Settings → Members, the person’s row, Unlink single sign-on, then confirm. Their sessions made through single sign-on end at once, browsers that remembered them for single sign-on forget them, every owner is told, and they link their new identity the next time they sign in with single sign-on.

Go to the sign-in page and choose Single sign-on not working?. Recovery owners can sign in there with an email link even while single sign-on is required (each such sign-in is recorded, and every owner is told); then set single sign-on to Allowed, or fix the draft, test it and apply it. Everyone else: ask a recovery owner to allow email links for now.

If no recovery owner can receive email, contact support. Support verifies who is asking first, with an owner at an address on record, and can then set single sign-on to Allowed; every owner is told at once.

Client secrets expire (Entra’s do). If you entered the day yours expires, every owner is reminded 30, 7 and 1 days before, and once after. Create a new secret in your provider, save it in a draft here, test it and apply it before then: after that day your provider refuses our sign-ins. Pasting a new secret clears the old date: type the new one, so the reminders are about the secret you use.

Nobody is refused because your identity provider rejected sign-in codes, from that network or any other: a stale link or an expired tab fails only that one sign-in, with your provider’s own reason. To protect your identity provider, we send it at most 200 sign-ins at once and 20 a second after that, from every network together, and at most 50 at once from one network; past that a sign-in waits its turn with us, and the turns are shared fairly between networks, so one network’s flood takes one share and your office’s people get theirs. A sign-in waits at most twenty seconds from when it reaches us (so a code that lives only 30 seconds is still sent in time), and if that is not enough it is told what held it. “Many sign-ins are waiting their turn with us for this single sign-on right now. Try again in N seconds” means our queue for the connection was busy: someone may be sending it many sign-ins, or your whole company is signing in at once. “Your identity provider is taking a long time to answer the sign-ins from your network” is said only when every sign-in your network had at your provider was one we had sent and it had not yet answered, for most of that one’s wait; sign-ins left behind when one of our servers stopped are ours, and are worded as ours. “Too many sign-in attempts came from your network” means the network sent very many answers to this connection that were not sign-ins we started (more than 600 a minute): a sign-in started from our pages is never turned away for it, and waits its turn at most. “That sign-in did not finish in time, or was already used” means the answer was not one we can finish: each sign-in we start is answered once, so reloading the page after its answer, opening the link again, or a second click while the first is being answered says this (a reload that never reached us still works); and so does anything we did not start. Start again from the sign-in page. “Single sign-on is not working at our end right now” means our own systems held the sign-in, or could not send it to your provider in time: the fault is ours; try again in a few minutes. If your provider refuses our client secret or our client (for example the secret expired), everyone is told to ask an owner, and the owner’s test sign-in names the fix.

Set the mode to Off and everyone signs in with an email link again; sessions already made with single sign-on stay until they end, at most 12 hours (the page says so beside Off, before you press it). To sign everyone out of single sign-on at once, for example when your identity provider is compromised, turn it off and then delete the connection. Delete connection (its own Delete pane, only while single sign-on is off) removes the connection with its versions, domains and linked identities, and signs out everyone signed in with single sign-on, you too if you did (its dialog says so before you press it); you can set it up again later, and people then link again at their next single sign-on.

Every change here is in the account’s audit log.