Single sign-on, SCIM and roles from groups

Connect your identity provider

1. 1In ConfigCheckup, go to Settings → Your sign-in and security → Single sign-on and copy the sign-in redirect URI.
2. 2At your provider, make a web app for OpenID Connect (Okta: an OIDC web application; Google: an OAuth client for a web application; Entra ID: an app registration) with that redirect URI. Note its issuer, client ID and client secret.
3. 3For Google Workspace, set the OAuth consent screen’s user type to Internal, so only accounts in your own Google Workspace can sign in. ConfigCheckup also checks each Google sign-in comes from an account in one of your verified domains (the hd claim): a personal Google account made with a work address is refused, even with the address confirmed.
4. 4Back in ConfigCheckup, enter them and save. The issuer’s discovery document is read at once, so a mistake shows straight away. The secret is encrypted and never shown again.
5. 5Press Run a test sign-in and sign in as yourself. It checks everything that comes back and signs nobody in; signing in as yourself also links your own account, which you need before you can require single sign-on.

ConfigCheckup asks for openid, email and profile, and any extra scopes you add, such as groups for Okta to send the groups claim. SAML is not offered: every provider above speaks OpenID Connect, and it is the simpler of the two to keep safe.

Prove your email domains

“Sign in with your company” sends people to your provider by the domain of their email address, so a domain must be proved to be yours first. Add it, put the TXT record shown at the domain itself in its DNS, then press Check the TXT records. A domain can be verified by one workspace only. When at least one is verified and a test has passed, turn on Sign in with your company.

How people sign in

On the sign-in page, Sign in with your company asks for a work email address and sends them to your provider. Coming back:

• someone who has signed in this way before is found by their identity at your provider, whatever their address is now;
• a member whose address is in a verified domain is matched by it the first time, and linked. An invitation waiting for them is accepted while its link still works; once it has run out, they join as someone new would, or ask for it to be sent again;
• someone new from a verified domain joins as a Viewer (or the role you choose) while a seat is free, unless you turn joining off. Someone removed from the workspace needs a new invitation.

An address your provider says it has not checked is never used, and neither is one outside your verified domains. While the workspace requires Microsoft sign-in, members sign in with Microsoft only: your provider is not a way round your Entra tenant until you require it instead.

Require single sign-on

Once you are linked, Require single sign-on makes everyone sign in with your provider: password and Microsoft sign-in stop for members, and every session that began another way ends at once. Owners with two-step verification keep their password as a way back in, so a problem at your provider never locks the workspace out. While it is required, the provider cannot be switched off, removed or pointed somewhere else.

The sign-in page finds your provider by the domain of an address, so your own address must be in a verified domain before you can require it, unless you use two-step verification. The page also says how many members have addresses outside your verified domains: they cannot sign in once it is required, until their domain is verified too.

Changing the issuer or client ID (a new app at your provider) turns the provider off until a new test sign-in passes, and unlinks every account: each member is matched by their address again the next time they sign in.

Provisioning with SCIM

Point your provider’s SCIM 2.0 provisioning at the base URL shown on the page, which ends in /api/scim/v2 (/scim/v2 works too), with the SCIM token as a bearer token. The token is shown once; making a new one stops the last one at once. Your provider can then:

• add members (with the role people join with), and change their names;
• turn members off: active=false, or deleting them, suspends them the way an Admin would. They are signed out everywhere, the API keys they made are revoked and their approvals withdrawn. Their work keeps their name. Turning them back on lets them in again, if a seat is free;
• push groups, whose members get roles from the mappings below.

Filters of the form userName eq "…" are supported, and up to 600 requests a minute for each workspace.

Roles from groups

Map a group at your provider (by its name, or its id: Entra ID sends group object ids) to Admin, Technician, Consultant or Viewer. A member your provider manages gets the highest role their groups map to, or the role people join with when none is mapped, so taking someone out of the Admins group takes Admin away. Groups come from SCIM and from the groups claim at each sign-in. Members your provider knows nothing about keep the role an Owner gave them.

Groups give roles, not clients. A member your provider adds, or someone who joins on their first sign-in, sees every client until an Owner or Admin limits them to some on Settings → Team; a limit set there stays whatever their groups say, and someone your provider brings back after they were removed keeps the clients they were limited to before.

Before you map or remove a group, the page says whose roles would change. Mapping the first group is the one to read carefully: every member your provider manages who is in none of the mapped groups gets the role people join with, Admins set by hand on Team among them.

What keeps it safe

• Each ID token’s signature is checked against your provider’s published keys (RS256 or ES256), as are its issuer, audience, lifetime and nonce.
• The sign-in uses the authorisation code flow with PKCE, and its state never leaves a sealed, ten-minute cookie.
• Your provider’s addresses are only ever fetched on the public internet, never from inside ConfigCheckup’s own network.
• Owners are never changed by groups, no group makes anyone an Owner, and the last active Owner is never suspended over SCIM.
• SCIM cannot change an Owner’s address, or that of a member who signs in with a password.
• Every change, from the settings to each member SCIM adds or suspends, is in the audit log.