Single sign-on
How a connection to your company identity provider signs people in to the console, which addresses it covers, and what happens at the first and every later sign-in.
Single sign-on lets the people of your organization sign in to the console with your company
identity provider: Microsoft Entra ID, Okta, Google Workspace, Keycloak or anything else that
speaks OpenID Connect (OIDC) or SAML 2.0. You manage it under IAM, then Single sign-on
(iam:ListSsoConnections).
Terms
| Term | Meaning |
|---|---|
| Connection | One identity provider connected to your organization, over OIDC or SAML 2.0. It is created switched off. |
| Domain | An email domain, such as example.com, whose people sign in through the connection. |
| Verified domain | A domain whose DNS carries the TXT record the connection gave you. A domain is verified for one connection at most. A connection is turned on only with one. |
| Role on first sign-in | The organization role, with its starter policy, that a person gets when single sign-on first adds them: Admin, Member (the default), Viewer or Billing. |
| Enforced | People at the connection's verified domains must use it: password sign-in, password reset and registering with a password are refused. See Enforce single sign-on for the owner. |
| Groups claim | The OIDC claim or SAML attribute that lists a person's groups at the identity provider, groups unless you change it. |
| Role on first sign-in | Starter policy |
|---|---|
| Admin | PowerUserAccess |
| Member | DeveloperAccess |
| Viewer | ReadOnlyAccess |
| Billing | BillingFullAccess |
How a sign-in works
On the sign-in page a person types their email address. When it is on a verified domain of a connection that is on, the page offers Continue with SSO; when the connection is enforced, it offers nothing else. The console sends them to the identity provider, and they have 10 minutes to come back. The sign-in must be finished in the browser it was started in, and each answer from the identity provider is accepted once.
The identity provider must send an email address on one of the connection's verified domains.
The first time, the console:
- creates an account for the address, or links the account that already has it. An account whose
address was never confirmed is taken over: its password, second factor and sessions are removed
before it is linked. An account with a confirmed address is linked only when it belongs to no
other organization, owns none and has no authenticator app of its own; otherwise the sign-in is
refused with
An account with this address already exists. Sign in with your password instead.; - adds the person to your organization. A pending invitation to your organization for that address decides the role and is accepted; otherwise the connection's role on first sign-in does.
Every later sign-in finds the account by the identity provider's subject. A person whose membership is suspended stays suspended. If the connection maps groups, their mapped IAM groups are updated (see Map identity provider groups to IAM groups).
A session that signed in through single sign-on meets the organization's Require two-factor sign-in: the identity provider decides how its people authenticate. Accounts created by single sign-on have no password, so they have no two-factor setting of their own in the console.
Changing the identity provider
Changing a connection's OIDC issuer or client ID, or its SAML sign-in URL, entity ID or certificate, unlinks every account linked through it. People are linked again at their next sign-in, under the same rules as a first one.
Deleting a connection stops sign-ins through it. The people it added stay members of the organization.
Values for your identity provider
| Item | Value |
|---|---|
| OIDC redirect URI | https://<console host>/api/auth/sso/oidc/callback, the same for every connection |
| OIDC flow | Authorization code with PKCE (S256), state and nonce; scopes openid email profile |
| OIDC ID token signatures | RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, EdDSA |
| OIDC claims read | sub, email (refused unless email_verified is true), name, given_name, family_name |
| SAML SP entity ID (metadata) | https://<console host>/api/auth/sso/saml/metadata/<connection id> |
| SAML reply (ACS) URL | https://<console host>/api/auth/sso/saml/acs/<connection id> |
| SAML signatures | On the response or the assertion; SHA-1 refused unless the connection allows it |
| SAML clock tolerance | 3 minutes |
| Time to finish at the IdP | 10 minutes from Continue with SSO |
| Domain record | TXT _ews-verification.<domain> with the value ews-verification=<token> |