Skip to content

Map identity-provider groups to roles

Give members a role in your tenant because of a group your identity provider asserts for them, and withdraw that mapping when the group should no longer confer the role.

Who can do it

A tenant administrator or a tenant access administrator, or a platform super administrator working inside your tenant, holding the permission to manage federation mappings. The console has no control for this task; it is done through the Admin API.

Before you start

  • Your tenant has its own identity provider declared. See Sign in with your company's identity provider.
  • Federation admits nobody by default. A member signing in through the provider receives a role only when a group mapping or an admission rule names it.
  • You can map a group only to a role whose every permission you hold yourself. A mapping confers the role on everyone the provider later asserts the group for, so the platform holds you to the same rule as assigning the role directly.
  • The role must exist in your tenant, be assignable to people in a tenant of your type, and not be a service-to-service role.
  • Your edition must include tenant-configured identity federation to create a mapping. Deleting one does not depend on your edition.
  • Both operations ask for a recent sign-in.

Steps

  1. Find the provider's identifier: GET /api/v3/admin/tenants/{tenantId}/idp.

  2. Create the mapping with POST /api/v3/admin/tenants/{tenantId}/idp/mappings and a body naming the provider, the group exactly as the provider asserts it, and the role:

    {
  "idpConfigId": "3f1c2a9e-4b7d-4e2a-9c11-0a2b3c4d5e6f",
  "externalGroup": "ANKASecure-Key-Managers",
  "ankaRoleName": "TENANT_KEY_MANAGER"
}

  3. To withdraw a mapping, list them with GET /api/v3/admin/tenants/{tenantId}/idp/mappings, then DELETE /api/v3/admin/tenants/{tenantId}/idp/mappings/{mappingId}.

What you see when it worked

Creating answers 201 with the stored mapping; deleting answers 204. Both are recorded in the audit trail. Members signing in through the provider with that group receive the role when they next sign in through the provider.

When your tenant's quorum approval is on and the mapped role confers approval rights, the creation answers 202 and waits for your approvers.

If it fails

What you get Cause What to do
404 The provider is unknown, or the role is unknown or belongs to another tenant Check both identifiers
400 The request is malformed, or the role is service-to-service only Correct the body, or choose a role meant for people
422 (federated-role-not-assignable) The role cannot be assigned in a tenant of this type, such as a PLATFORM_ role Choose a tenant role
403 (scope-subset-violation) You do not hold every permission the role carries; extensions.missingScopes names them Ask someone who holds them, or map a narrower role
403 (federation-not-entitled) Your edition does not include tenant-configured federation Contact your account manager
403 (impersonation-operation-forbidden) On a SaaS deployment, a platform operator in a support-access session cannot create a mapping The tenant's own administrator creates it
409 The same mapping already exists Nothing to do

A role that a mapping still names cannot be deleted: delete the mapping first.

Without the console

Surface How
API POST /api/v3/admin/tenants/{tenantId}/idp/mappings (operation createMapping)
API DELETE /api/v3/admin/tenants/{tenantId}/idp/mappings/{mappingId} (operation deleteMapping)

No ankasecure-km command and no Admin SDK method manage group mappings.