17.5Accounts and roles with SAML and OpenID Connect

First sign-in: matching or creating the account

When someone signs in through SAML or OpenID Connect, the platform decides which platform account they are:

1. 1An existing link. If this identity has signed in before, it is linked to an account by the provider's stable identifier, and the person is signed in to that account. Later changes to their email address at the provider do not break the link.
2. 2An existing account with the same email address. If no link exists, the platform looks for an account with the email address the provider sent. It links automatically only when that account has no password sign-in — that is, an account that only ever signs in through single sign-on. The exceptions are listed below.
3. 3A new account. If no account has that address, the platform creates one, using the names from the provider, and gives it the Default role for new SSO users.

The platform does not automatically link an existing account by email address when the account:

• can sign in with a password (otherwise anyone able to make the identity provider assert that address would gain the account);
• is still waiting for its person to choose a password from a setup email;
• holds the System Admin role;
• is already linked to a different identity at the same provider;
• is already linked through the other single sign-on protocol (an account is reachable through SAML or OpenID Connect, never both).

In all refused cases the person sees "Your account has no access to this application. Contact your administrator." The message is deliberately the same in every case, so the sign-in page cannot be used to find out which accounts exist.

For OpenID Connect, an existing account is matched by address only when the provider marks the address as verified (the email_verified claim, or the Microsoft Entra xms_edov claim). If an account with the address exists and the address is not verified, sign-in is refused rather than creating a second account with the same address.

Tip: To move a person who already signs in with a password over to single sign-on, turn off password sign-in on their account first (see Chapter 11, Users, roles and permissions). Their next single sign-on sign-in then links to the account.

Creating an account and linking an identity to an existing account are both recorded in the operations log, so you can see when and through which provider an account was adopted.

Roles

For SAML and OpenID Connect, the platform does not read group or role claims from the identity provider. Roles work like this:

• A new account gets the Default role for new SSO users configured for that protocol.
• After that, roles are managed in the console like any other account's (see Chapter 11, Users, roles and permissions).
• If the account holds one role, it is activated automatically at sign-in. If it holds several, the person picks one after signing in. If it holds none, the person is signed in without permissions until an administrator assigns a role.

To control who may sign in at all, assign the application only to the right users or groups in your identity provider.

Other rules that apply

• A deactivated platform account cannot sign in through single sign-on.
• The platform's own two-factor authentication applies to password sign-in only. For single sign-on, rely on the multi-factor authentication of your identity provider.
• A role that requires two-factor authentication cannot be activated by an account without a password; see Chapter 3, Signing in and your account.