Sign in with your own provider¶
What an organisation's own sign-in provider is and whom it signs in is explained in Organisations and customers.
If your organisation runs its own identity provider, you can let the organisation's administrators sign in to the console with it instead of a password: OpenID Connect, Google Workspace or Microsoft Entra ID. You set it up on the organisation's Access & policy tab, as an administrator of that organisation or of an organisation above it. With an API key, follow Set up your own sign-in provider with a key instead.
Four rules hold whatever the provider:
- Nobody gets an account by signing in. Only someone you have already invited as an administrator can sign in this way, matched on the email address the provider has verified.
- The provider's own second factor counts. If your provider asks for a code, the console does not ask for another.
- Someone who administers more than one organisation cannot sign in through any organisation's provider. They sign in with a password, so one organisation's provider never opens another's.
- Removing a provider does not remove accounts. Anyone who also has a password keeps signing in with it.
Someone you invited who signs in through your provider straight away never chooses a password here: the invitation's own steps -- choosing a password, confirming the address, setting up a code -- are done by the provider's first sign-in. If they ever need to sign in with a password instead, ask the administrator of your deployment, or reset it from the sign-in page if your deployment offers that; either way they set up a code on the way.
Prove your email domain first¶
Your provider signs in only addresses in an email domain your organisation has proved it owns, so nobody's provider can sign in an address at somebody else's company. Prove each domain your administrators' addresses are in before you add a provider:
- Open the organisation, then Settings, then the Access & policy tab. On the Email
domains card, enter the domain (for example
example.com) and select Claim domain. - The domain appears as Waiting for proof, with a Record name (
_artific-challenge.example.com) and a Record value. Copy both and publish a TXT record at that name holding that value, with whoever runs your domain's DNS. - Once it is published, select Check now. If the record is not found yet, the card says so; wait for your DNS to update and check again. When it is found the domain shows Proved.
A domain another organisation has already proved cannot be claimed, and a shared mailbox domain
such as gmail.com never can. An organisation claims at most fifty domains. Selecting Give up on
a domain stops your provider signing in anybody in it at once. A Google Workspace provider's domain
must be one you proved.
Allow your provider's hosts first¶
The sign-in service talks to your provider on your organisation's behalf, so your organisation has to allow your provider's hosts before you add it, the same way it allows any other host it reaches. Saving a provider whose hosts are not allowed is refused and names the field.
| Kind | Hosts to allow |
|---|---|
| OpenID Connect | the issuer's host, and the hosts its discovery document names for tokens, keys and user information -- usually the same one |
| Google Workspace | oauth2.googleapis.com, openidconnect.googleapis.com and www.googleapis.com |
| Microsoft Entra ID | login.microsoftonline.com |
On the same tab, select Add a host on the Allowed hosts card, enter the host and select Allow host. Do this for each host in the table.
Add a provider¶
- Open the organisation, then Settings, then the Access & policy tab.
- On the Sign in with your own provider card, select Add, or Add provider when there is one already. If no domain is proved yet, the card says so and links to the Email domains card.
- Enter a Name: lowercase letters, digits and hyphens, at most 32 characters, with no hyphen at the start or end. It becomes part of the redirect address and cannot change later.
- Choose the Kind of provider and fill in the one field it asks for:
| Kind | Field | What it does |
|---|---|---|
| OpenID Connect | Issuer, an https address | Core reads the provider's discovery document. Its ID tokens must carry email_verified: true. |
| Google Workspace | Workspace domain | Only accounts of that domain sign in; personal Google accounts are refused. |
| Microsoft Entra ID | Directory id | Only accounts of that directory sign in. Its ID tokens must carry the optional claims email and xms_edov. |
- Enter the Client id and the Client secret of the client you created at your provider for this console. The Display name is optional and is what the sign-in page would call the provider.
- Select Save provider.
The secret is never shown again. Every time you change a provider you enter it again; leaving the field empty does not keep the old one.
Register the redirect address¶
Your provider has to know where to send people back to. After you save, the drawer stays open and shows a Redirect address. Select Copy redirect address and add it to your client at the provider as an allowed redirect. If the provider asked for a redirect address before you could create the client, create it with a placeholder, save here, and replace the placeholder with the address shown.
The provider only starts working once the redirect address is registered.
Share the sign-in link¶
The ordinary sign-in page lists no organisation's providers. The drawer therefore also shows a Sign-in link: the console's sign-in address with your provider named in it. Select Copy sign-in link and give it to your administrators; opening it sends them straight to your provider. What they see then is in Sign in.
If the link names a provider that no longer exists, the person lands on the ordinary sign-in page instead.
Change or remove a provider¶
Select a provider in the card to open it again. Remove provider asks for a confirmation and then stops people signing in through it. Accounts stay as they are.
The card holds at most ten providers; at ten it says At most 10 providers.