Identity providers in your tenant

Adding a provider

Open Federation and add a provider. For an OpenID Provider, enter its issuer, the client ID and secret your tenant uses there, how the secret is sent (in the Authorization header, in the body, or none for a public client), the scopes to ask for (always including openid), and which claims hold the email address, first name and last name. Your tenant reads the provider's discovery document when you save: its issuer must match exactly, and its token endpoint and key set must be reachable over https. Register your tenant's redirect URI, shown on the page, at the provider:

https://<your tenant>/login/federation/callback

Another tenant of this environment can be the provider, which is how the labs use your second lab tenant: create a confidential client there with that redirect URI and the openid email profile scopes, and use its issuer, client ID and secret here. Your tenant cannot be its own provider. For a SAML identity provider, see SAML in your tenant. The issuer is fixed once the provider exists, because connections are keyed on it; the secret is never shown again, and leaving it empty when you edit keeps it.

Signing in with a provider

Providers set to appear on sign-in pages are offered as Sign in with links on your tenant's sign-in page and on the sign-in step of an authorization request. Your tenant sends the person to the provider with state, a nonce and PKCE, exchanges the code at the provider's token endpoint, and checks the ID token: its signature with the provider's keys, its iss, aud and azp, its expiry, its nonce and its at_hash. When the provider says it supports the iss response parameter (RFC 9207), the answer must carry it and match. Claims missing from the ID token are read from the provider's UserInfo for the same sub. The answer is accepted only in the browser that started the sign-in, once, within ten minutes.

A provider sign-in counts as the first step of a sign-in here, recorded in amr as fed. Your tenant's own second step and enrollment rules still apply, except that someone who signs in only through a provider is not asked to set a password. With Accept the provider's two-factor sign-in, a provider sign-in whose amr includes mfa needs no second step here, and the session's amr includes mfa too.

New and existing accounts

A provider identity, its issuer and subject, finds an account here only through a connection. A matching email address is never used: an address the provider sends could belong to someone else here. The first time someone signs in with a provider, they choose on the next page:

• Connect an account you already have. They sign in to that account here, with a new sign-in made after the provider sign-in, and confirm. A browser that was already signed in does not count, because it proves nothing about the person at the provider now. Turn this off with Let people connect an existing account.
• Create a new account, when New sign-ins is set to create accounts. The email address is kept only when the provider says it verified it (email_verified, for OpenID Providers); SAML providers never say so, so their new accounts have no address until the person adds one. You can limit new accounts to verified addresses in your own email domains. An address already used here never creates a second account.

Accounts of Beyond the Login users, such as yours in your home org, sign in with Beyond the Login, so providers connect only to the tenant's own users.

Connections and removal

People see their connected providers on their tenant Security page. They can connect another provider there, which asks the provider for a new sign-in, and remove one as long as another way to sign in remains. A notice goes to their confirmed email address when a provider is connected or removed. Administrators see each user's connections in User Management and can remove them (tenant.federation.links.read and tenant.federation.links.delete). Deleting a user, or removing a provider, removes its connections, so the provider account can be connected again later.

Claims from a provider

A provider may know facts your tenant does not, such as an enrollment. A claims source on the Federation page names an OpenID Provider, the claims it states, and a scope of yours that releases them. When an access token carries that scope, your tenant's UserInfo response for that person carries those claims as the OpenID Connect aggregated and distributed claims (Core section 5.6.2):

{"sub": "...", "_claim_names": {"enrolled": "src1"},
 "_claim_sources": {"src1": {"JWT": "<the provider's signed UserInfo>"}}}

Aggregated reads the provider's UserInfo as a signed JWT (the provider must sign it, as the client setting userinfo_signed_response_alg does in another tenant), checks the signature, issuer and subject, and passes the JWT on whole: the application receives every claim the provider released in that response, not only the ones the source names. Distributed gives the provider's UserInfo address and an access token, so the application can fetch the claims itself. That access token is your tenant's own token at the provider, the one your tenant received when the person last signed in there, handed to the relying party as is: until it expires, whoever holds it can call the provider with everything the provider granted your tenant, not only the claims the source names. So a distributed source may use only a provider whose sign-in asks for no scopes beyond openid, profile and email. Saving such a source, or adding another scope to a provider a distributed source uses, is refused, and a stored source whose provider asks for more is left out of UserInfo. Provider access tokens are kept, encrypted, only while a source uses the provider. A source that cannot answer is left out; the response never fails because of it. Discovery lists claim_types_supported while a source is enabled. ID tokens carry normal claims only, so a sign-in never waits on another provider. When another tenant reads your UserInfo as its own claims source, it gets your normal claims only, never claims you took from a source. Protocol Audit for a UserInfo answer that carried sources names them, such as src1, under Aggregated claim sources or Distributed claim sources, never the signed claims, the endpoint or the token.

Limits, Audit and Logs

A tenant can trust up to 10 providers and 10 claims sources, one person can connect up to 10 providers, and one browser can start 20 provider sign-ins every 15 minutes; all appear in the tenant's Usage view. Changes to providers, sources and connections are recorded in Audit with the provider's ID, never its secret. Sign-ins are recorded under account.federation, with reasons such as provider_redirect, federated_sign_in, link_pending, provider_linked, provider_unlinked, federated_registration, and for refusals invalid_state, issuer_mismatch, id_token_signature_invalid, id_token_nonce_mismatch, fresh_sign_in_required or linked_to_another_account. The BTL organization holds only Beyond the Login accounts, so it does not accept other providers.