# 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](enforce-single-sign-on.md) 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](map-idp-groups-to-iam-groups.md)).

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>`                      |

## Related

- [Set up single sign-on with OpenID Connect](set-up-sso-with-openid-connect.md)
- [Set up single sign-on with SAML 2.0](set-up-sso-with-saml.md)
- [Verify a domain](verify-a-domain.md) · [Enforce single sign-on](enforce-single-sign-on.md)
- [Provision users with SCIM](provision-users-with-scim.md)
- `iam.sso-connections.list` · `dcloud iam sso-connections list` · `dcloud_iam_sso_connection`
