Single sign-on and managed accounts

A domain is a DNS name an organization asserts control of. It proves control with a DNS TXT record and the name only counts once verified. An organization holds up to 20 domains by default, and only one organization can hold a given exact name verified at a time.

A verified domain has a capture setting:

block can only be set on a verified domain. A claim needs a verified domain whose proof is not failing, an active account with a verified address on the domain, and no membership already. It never claims a managed account, and it never touches the account's credentials.

A domain stays verified only while the proof stays published. It is looked up again every day by default, and after it has kept failing for 3 days by default its verification is dropped. The platform operator can change both numbers within a range.

A connection is a sign-in route to an organization's own identity provider. It is owned by one organization and linked to the organizations allowed to use it. Its kind is oidc, saml or scim. A SAML connection starts disabled and stays so until the provider's metadata is uploaded. A SAML sign-in requires the assertion to be signed and answers only the request it started.

A link says how the connection may be used in a linked organization:

• Automatic membership. A first sign-in through the connection creates the membership. The person joins as a member, or as a guest with a named sponsor when the organization allows guests. A link that cannot admit the person is skipped and the sign-in still succeeds. An existing membership of any status is left alone, so a removed or blocked member is not re-admitted by signing in.
• Managed. Accounts created through the connection are managed by the organization. See Managed accounts.

The sign-in itself is under the tenant_connections flag, which defaults OFF. While it is off, starting a sign-in through a connection answers not found.

Who a connection sign-in is#

The key to an identity is the connection plus the issuer and the subject the provider asserts. It is never the email address. An organization's provider controls every claim it makes, so an address it asserts proves nothing about who holds it. Two consequences follow.

• An account that already exists is never linked automatically by email. A person links it themselves, from their own signed-in session after a step-up (the Link your organization sign-in section of Linked accounts), and only when they are a member of that organization, the provider says the address is verified, the address is one of the account's own verified addresses, and a linked organization has verified the address's domain.
• A new account is created only for an address nobody already holds, on a domain the linked organizations have verified.

Sign-in suggests the connection#

When the flag is on, the typed email domain can send a person straight to their organization. Sign-in then shows Sign in with your organization, says the organization manages sign-in for the address, and offers Continue with the organization and Use another method. This happens only when the organization (named in the request, or owning the most specific verified domain for the address) enforces single sign-on and has exactly one active connection. Several connections, or none, route nowhere. The decision reads the typed domain and configuration only, never an account, so the screen is the same for an address that has an account and one that does not.

A session that signed in through an organization's connection is pinned to it. It can enter only the organizations that connection is linked to, or that sit below one it is linked to. An application that asks for any other organization is treated as having no session, so the person is asked to sign in again. The refusal never names the organization, so it cannot be used to learn that one exists. A request that names no organization is allowed, because the pin guards organization entry. The pin is described among the parts of a session on Sessions. It follows the connections flag, which defaults OFF.

An organization can require that its members sign in through one of its connections, or through a connection of an ancestor. The settings are sso.enforce, sso.max_age_s (how old the sign-in may be, 24 hours by default, between 5 minutes and 7 days) and sso.guests_exempt (guests are exempt unless the organization sets it false). A child organization inherits them from its parent.

Enforcement applies only while the sso_enforcement flag is on, and it defaults OFF. With the flag off the entry check is exactly the ordinary one.

Turning it on. It is refused unless an active connection is linked to the organization or an ancestor, and unless the administrator turning it on has linked their own single sign-on identity, so they cannot lock themselves out. Turning it on blocks every active owner and member who has no linked identity and is not a managed account. Guests are not blocked. Both steps run only while the flag is on. A blocked membership gives no access until the person links an identity through the connection, which makes it active again. See Memberships and invitations.

At entry. Entering the organization needs a recent enough single sign-on sign-in on the session. When it is missing, sign-in sends the person through the organization's connection. The answer is the same for a member and a non-member.

At the token endpoint. Redeeming a code, refreshing and exchanging a token for such an organization need that fresh sign-in on the session behind the grant. If it is missing or too old, the answer follows RFC 9470 (Step-up authentication for OAuth): a 400 with the error insufficient_user_authentication, plus acr_values of aal1 and the max_age the application must meet. aal1 is the lowest level, because the challenge cannot say "through the organization's connection", and the connection itself is demanded at sign-in. The matching step-up behaviour is on Step-up.

SCIM (System for Cross-domain Identity Management, version 2.0) lets an organization's provider create, update and remove its members automatically. The server is at /scim/v2/{tenant}, behind the scim flag, which defaults OFF. While it is off every path answers the same not-found an unknown path gets, before any authentication.

• Authentication. A bearer token issued for a SCIM connection. The connection must be active and linked to the named organization, and the organization must be active. A missing or unknown token, a disabled connection and an unknown or unlinked organization all get the same 401.
• Limits. A request body is capped at 64 KiB. A connection may make 600 requests a minute and a list returns at most 100 resources by default, both operator-tunable. After a token is rotated the previous one keeps working for a day by default.
• What it supports. Users and Groups, PATCH and filtering. Bulk, sorting, ETags and password change are not supported, and the discovery documents say so.

Users. A provisioned user is an account, an optional federated link, a membership and a record of the connection that created it. Setting the user inactive suspends the membership and ends its sessions in the organization. Setting it active again, or provisioning the same user again, reactivates it. A delete removes the membership, and for a managed account also deactivates it permanently.

Groups. A SCIM group is an ordinary group linked to the connection. A connection sees and changes only groups it created, so a group an administrator made and another connection's group answer the same not-found. Provisioning a group whose name matches one an administrator made is a conflict, so a provider cannot take it over. Members can be added only if they are active members provisioned by the same connection. A group that holds, or sits under a group that holds, a high-risk permission refuses SCIM-driven additions with a conflict, and removals are never blocked. See Groups, guests and custom roles.

Two rules hold for both resources.

• SCIM never writes authority. It creates no role assignment and no grant. Giving a group a role is an administrator's act.
• SCIM only reverses SCIM. Setting a user active again reinstates only what a SCIM request deactivated. A membership an administrator removed or suspended, or that the platform suspended, stays so until a person acts.

A managed account is one whose lifecycle belongs to an organization. It is created through a connection whose link is marked managed, by the organization that owns the connection, and only when that organization has verified the address's domain. SCIM can create them the same way. A managed account is marked with the organization that manages it. Its way in is that organization's connection. The account area shows a banner: manages this account. Its administrators control your sign-in methods, access tokens and membership. An action that is not open to a managed account is answered with Your organization manages this account, so this is not available here. Ask your organization’s administrator.

A managed account cannot:

• Belong to just any organization. It may be a member only of the managing organization and of organizations that its connection is linked to with the managed setting on.
• Have a personal workspace. It has none, and sign-in does not offer to create one. See The personal workspace.
• Enrol its own sign-in factors, or hold a password of its own. The enrolment routes refuse a managed account, and sign-in does not ask it to choose a password: the rule that every account has a password does not apply to a managed account.
• Recover a credential. There is none to recover. Recovery for such an address sends and stores nothing. See The recovery model.
• Create personal access tokens or close the account. Both are refused, and the account's end belongs to the organization.
• Leave the managing organization. That membership can be ended only by the organization's administrators or by SCIM. The Memberships page shows Managed by this organization and offers no Leave button.
• Be claimed by another organization's domain, or have an existing identity linked to it.

The account pages say so. A banner across the top of every account page reads that the organization manages the account and that its administrators control your sign-in methods, access tokens and membership, the organization's row on Memberships is headed Managed by this organization, and a change the account may not make is refused with Your organization manages this account, so this is not available here. Ask your organization’s administrator. (the error code managed_account, status 403). The same refusal answers a step-up the account has nothing to satisfy.

• Organizations
• Sessions
• Step-up
• Groups, guests and custom roles