Skip to content

Link or unlink a user and a corporate identity

Authorize a member's account to be bound to their identity at one of your tenant's identity providers, withdraw that authorization before it is used, or unlink an account that is already bound.

Who can do it

A tenant administrator or a tenant access administrator, or a platform super administrator working inside your tenant. Each action needs the permission to change a user's federated link; authorizing a link also needs the permission to read your tenant's identity providers. Without them, the console shows the action disabled and says which permission is missing.

You can only act on someone whose permissions in your tenant you cover, and you must have confirmed your identity recently. On a SaaS deployment, a platform operator working inside your tenant under a support-access session cannot authorize a link or unlink one.

Before you start

  • Your tenant has an identity provider. Without one there is nothing a link could point at.
  • The link binds on the first matching sign-in, without anyone confirming it again: whoever next signs in through that provider with the account's email address becomes this account, with its roles and its history. Coordinate the timing with the person.
  • A member designated as break-glass cannot be linked.

Steps

To authorize a link:

  1. Open Users in the sidebar.
  2. On the person's row, select the eye icon (View).
  3. On the Overview tab, under Federated sign-in, select Authorize a link.
  4. Choose the Identity provider. The Email address the provider must assert is the account's own address; it cannot be changed.
  5. To change the window, open Advanced: authorization window and set Valid for (hours): between 1 and 168, 72 by default.
  6. Select Continue, review the account, and select Authorize the link.

To withdraw an authorization that has not been used, or one that has expired:

  1. Under Federated sign-in, select Withdraw authorization.
  2. Confirm with Withdraw.

To unlink an account that is already bound:

  1. Under Federated sign-in, select Unlink.
  2. Type the person's email exactly as shown, and give the Reason.
  3. Select Unlink.

What you see when it worked

  • Authorizing shows Link authorized. It applies to the next matching sign-in. The section shows the provider and when the authorization expires. The person is emailed, and you are emailed when the authorization is used. The binding happens at the first matching sign-in; the account's sessions end at that moment and its local password stops being a way in.
  • Withdrawing shows No authorization is standing for this account.
  • Unlinking shows that the account no longer signs in to this tenant through the identity provider and that its sessions in this tenant were ended. Its sessions in other organizations keep working. No earlier password comes back: a person who has none sets one with Forgot password on the sign-in page.

A password reset never removes a link. If a link is wrong, unlink it.

If it fails

What you see Cause What to do
The account already carries a link (federated-link-target-already-bound) The account is bound to an identity Unlink it first
An authorization is already outstanding (federated-link-intent-already-declared) A live authorization exists for the account Withdraw it, then authorize again
The provider is not eligible (federated-link-provider-not-eligible) The chosen provider cannot be used for a link to this account Choose another provider of your tenant
The account is not active (federated-link-target-not-active) The account is not active Activate the account first
A refusal that the member cannot be linked (break-glass-designation-ineligible) The member is designated as break-glass Clear the designation first, or keep the account local
A window above 168 hours is refused The window is refused, never shortened Enter a whole number of hours between 1 and 168
"No identity provider is configured for this tenant" Your tenant has no identity provider A platform administrator declares one first
A refusal naming the permissions you lack (scope-subset-violation) The member holds permissions in your tenant that you do not Ask an administrator who holds those permissions

Without the console

Surface How
API POST /api/v3/admin/tenants/{tenantId}/users/{userId}/federated-link-intent (operation declareFederatedLinkIntent) to authorize; DELETE on the same path (operation revokeFederatedLinkIntent) to withdraw; POST /api/v3/admin/tenants/{tenantId}/users/{userId}/federated-link/revoke (operation revokeFederatedLink) with a reason to unlink

The key management CLI and the admin SDK have no command or method for this task.