Single sign-on and SCIM

With single sign-on, your people sign in to the console through your own identity provider. With SCIM, your directory adds and removes members for you. Both are on the SSO tab under Settings.

Changing anything on this tab needs the owner or admin role. Other roles can read it.

Making single sign-on active needs a plan that includes it. You can save a configuration as a draft on any plan. See billing.

The same actions are available in the SSO API reference.

The tab has three sections: Identity provider, Verified domains and SCIM provisioning. A typical setup goes in this order: configure the provider as a draft, verify a domain, test a sign-in, make the provider active, then turn on enforcement.

Connect your identity provider

1. Under Identity provider, press Configure SSO.
2. Choose the Protocol: SAML 2.0 or OpenID Connect.
3. Enter the Name shown on the login page, for example the name of your provider.
4. Fill in the provider's details.
   • For SAML: the Sign-on URL and the IdP entity id, both from your provider's metadata, and the Signing certificate in base64.
   • For OpenID Connect: the Authorization URL, the Client id, the Token URL and the Client secret. The secret is encrypted when it is stored and is never shown again.
5. Choose the Default role for new people.
6. Optionally fill in Group to role mapping. See below.
7. Choose the State. Start with draft (configured, not offered).
8. Press Save. The name and the URL are required.

After saving, the section shows your provider with its protocol and state, and a list of the service provider values to enter on your identity provider's side.

To change the configuration later, press Edit configuration. For OpenID Connect, leave the client secret empty to keep the one already stored.

Map groups to roles

Group to role mapping gives people a role based on the groups your provider sends. Write one mapping per line: the group's name, an equals sign, then the role. The roles are owner, admin, billing, member and viewer.

When a person is in several mapped groups, the most privileged match wins. A person in no mapped group gets the default role.

States

• draft: the configuration is stored but not offered on the login page.
• active: people can sign in through your provider. This needs a plan that includes single sign-on.
• disabled: the configuration is kept and sign-in through it is switched off.

Test the sign-in

The Test login link under your provider opens it in a new tab. The result then appears on the tab: whether the last sign-in through the provider succeeded or failed, for which address, when, and the error if there was one. Until someone has signed in, the tab says that there has been no sign-in through the provider yet.

Remove the provider

Press Remove beside the provider.

Verify a domain

A verified domain is what ties an email address to your organization. New people who sign in through your provider with an address on a verified domain join automatically, with the role from your group mapping or the default role. Enforcement applies to exactly these domains.

1. Under Verified domains, enter the domain in Add a domain. It is the part after the @ in your people's addresses.
2. Press Claim. The domain appears in the table as unverified, with a DNS record.
3. Publish that record at your DNS provider. It is a TXT record at _aiml-verify. followed by your domain, containing the token shown.
4. Press Verify.

When the record is found, the domain reads verified. If it is not found, the reason is shown under the status; DNS changes can take a while to appear, so try again later.

Re-check on a verified domain runs the check again. Remove releases the domain.

Enforce single sign-on

In the configuration, tick Require single sign-on for verified domains. and save.

Once it is on, password logins stop working for addresses on your verified domains. Those people can only sign in through your provider. The provider's summary then carries an enforced badge.

The checkbox is disabled until at least one domain is verified. Test a sign-in before you turn it on, so you know your provider works.

Provision members with SCIM

SCIM lets your directory create, update and deactivate members.

1. Under SCIM provisioning, press Create token.
2. Copy the token. It is shown once.
3. In your directory, enter the SCIM address shown in this section and the token as the bearer token.

Users and groups you assign in your directory become members here. Deactivating someone in the directory removes their access. Giving a directory group a role applies that role to its members.

Manage tokens

Each token is listed by a short hint, with when it was created and when it was last used.

• Rotate token creates a new token. Update your directory with it, then revoke the old one.
• Revoke stops a token working.

Directory activity

Directory activity under the tokens is a log of what your directory did and how it was answered: the time, the call, the status and any detail. Open it to check that provisioning works, or to see why a change was refused. Older activity loads earlier entries.

Related

• Organization settings covers roles and managing members by hand.
• Security settings covers two-factor sign-in, session length and the console IP allow-list.