Single sign-on

Enterprise: single sign-on needs a Control Tower Enterprise license.

People can sign in to the console through your identity provider, over OpenID Connect or SAML 2.0: Okta, Microsoft Entra ID, Google Workspace, OneLogin, Auth0, Keycloak, Ping, JumpCloud, ADFS. With SCIM, the provider can also add, deactivate and remove people. Their groups at the provider decide their role here: admin, approver or viewer. Every sign-in, and every refused one, goes into the audit log.

#Set it up

1. Set CT_PUBLIC_URL to the address people use for the console, such as https://controltower.example.com. The identity provider sends people back there, so it must be the public address, not an internal one.

2. People → Single sign-on → + Identity provider. The form shows the sign-in redirect URL to register at your provider, https://controltower.example.com/admin/sso/<id>/callback. After you save, each provider's own URL is shown when you edit it.

3. At your identity provider, create an OpenID Connect web application:

   • sign-in redirect URL: the one above;
   • grant type: authorization code;
   • scopes: openid email profile, plus whatever puts groups in the ID token (see Groups).

   Copy its issuer URL, client ID and client secret back into Control Tower.

4. Test checks that Control Tower can reach the provider and read its settings (<issuer>/.well-known/openid-configuration).

5. The sign-in page now shows Sign in with name.

#SAML

Choose SAML 2.0 when adding the identity provider:

1. Enter the IdP's SAML sign-in URL (its single sign-on URL for HTTP-Redirect), its signing certificate (PEM, or the bare base64 many IdPs show), and its entity ID (issuer). Save.
2. Edit it to see what to give the IdP: the ACS (reply) URL …/admin/sso/<id>/acs, the entity ID (audience) …/admin/sso/<id>/metadata, or just the metadata URL (the same address), which the IdP can read itself.
3. In the IdP's SAML app, send the email as the NameID or as an attribute (email, mail, or set Email attribute), and groups as an attribute (set Groups attribute to its name, for example groups or Entra's http://schemas.microsoft.com/ws/2008/06/identity/claims/groups).
4. Test checks the certificate can be read and hasn't expired.

What a SAML sign-in must pass:

• The assertion is signed with the certificate you entered. A signed response around an unsigned assertion isn't enough, and signature-wrapping tricks (an extra, unsigned assertion placed beside the signed one) are refused.
• It answers this sign-in. Control Tower starts every SAML sign-in itself. The response must answer the request it sent (InResponseTo), from the same browser over https, within 10 minutes, and only once: posting the same response again is refused. Sign-ins started from the IdP's own app dashboard (IdP-initiated) are refused; people start from Control Tower's sign-in page.
• It's for this service provider (audience), current (with a minute's clock skew), and, with the entity ID set, from your IdP.

#Groups and roles

Set Groups claim to the ID-token claim that lists someone's groups (usually groups). A list is read as it is; a single text value is one group, spaces and all ("Domain Admins"), unless it's comma-separated. Then list the groups for each role. Someone in several gets the highest role (admin, then approver, then viewer, then member). Groups can also make people admins or members of teams, set at each sign-in. Someone in none gets the Anyone else role, or is refused.

With a groups claim set, the provider decides roles at every sign-in. Moving someone to another group changes their role the next time they sign in, and ends their other sessions. Leave the groups claim empty to manage roles in Control Tower instead: the Anyone else role applies when someone is first created, and an admin changes it from then on.

Putting groups in the ID token:

#Who gets in

A sign-in is refused, and the reason is shown and recorded, when:

• the provider refuses or the person cancels;
• the email isn't in an allowed domain, or the provider says it isn't verified;
• the person is in none of the groups and Anyone else is refused;
• they haven't been added, and new people aren't created from this provider;
• the email already signs in through a different identity. Someone else at the provider can't take over an existing person's account by claiming their address.

Someone an admin added by email is linked to their provider identity the first time they sign in with it. From then on they're recognised by that identity, even if their email changes. People created by single sign-on have no password; an admin can still give them a one-time password.

#Security

• The sign-in uses the authorization code flow with PKCE, plus state and nonce. The state travels in a short-lived (10 minute) encrypted cookie that works only for the sign-in callback. A callback can't be replayed, and a stolen or altered state is refused.
• The ID token's issuer, audience, expiry and nonce are checked, and so is its signature, against the keys the provider publishes. The OIDC spec allows skipping the signature for tokens fetched directly over TLS; Control Tower checks both.
• Issuers and SAML sign-in URLs must use https. Plain http is allowed only for a provider on the same machine (localhost), for development.
• SAML signatures are checked by node-saml with xml-crypto 6, pinned; the checks above are tested against tampered, unsigned, foreign-signed, wrapped, misaddressed, expired and replayed responses.
• Sign-in attempts are limited per address (three times CT_LOGIN_RPM a minute).

#Only single sign-on

Only single sign-on: turn passwords off makes everyone sign in through the identity provider, and ends existing password sessions.

• It needs CT_ADMIN_KEY. The admin key keeps working as a sign-in (as admin) and as a bearer token, which is how you get back in if the identity provider is down or misconfigured.
• You must have used it. An admin can only turn it on after signing in with single sign-on themselves (or with the admin key), so nobody turns passwords off without knowing SSO works.
• The last provider can't be removed while it's on.
• Turning it off from outside the console:

curl -X PUT -H "Authorization: Bearer $CT_ADMIN_KEY" -H 'content-type: application/json' \
  -d '{"sso_only": false}' https://controltower.example.com/admin/api/sso/settings

#API

Admins only, except GET /admin/api/sso, which the sign-in page reads without signing in.

Refused sign-ins come back to the sign-in page as /?sso_error=<reason>. A password sign-in while passwords are off answers 403 sso_required.