Skip to content

Let an actor authenticate with an external issuer

Bind a subject that a trusted issuer vouches for to a cryptographic actor, so the workload authenticates with the token its own identity provider already issues and no secret is held on the platform. Remove the binding to stop it.

Who can do it

A tenant administrator or a tenant key manager, and a platform super admin working in a tenant on a private-cloud or on-premise deployment, who then binds on the tenant's behalf. The console offers Bind an external identity only to a person who holds the permission to write workload identities, and the revoke control only to the same person.

Before you start

  • The tenant's edition includes workload identity federation. Without it, existing bindings stay readable and can still be revoked, but no new one can be made.
  • On a customer-operated deployment, the platform operator has delegated workload identity federation to the tenant.
  • The issuer is declared as a trusted issuer, in your tenant's Settings or for the whole deployment.
  • The actor is not disabled.
  • A binding conveys identity only. The actor still needs roles, and capability grants for its keys.

Steps

  1. Open Cryptographic Actors, select the actor and open Federated identities.
  2. Select Bind an external identity.
  3. Either paste a token in Token issued to the workload, or type the subject:
    • A pasted token is read in the browser and never sent; only the issuer identifier it carries is sent, to find which of the tenant's trusted issuers published it. The console fills the issuer and the subject from the token.
    • Without a token, choose the Issuer to bind under and type the Subject to bind exactly as the issuer presents it. It is compared character for character.
  4. Check the preview of exactly what will be sent, then select Bind identity.

To remove a binding:

  1. On Federated identities, select the revoke control on the binding's row.
  2. Select Revoke binding.

What you see when it worked

The console says "The binding was created." and the binding is listed with its issuer, subject and the time it was bound. From then on, once the issuer is enabled, a token from that issuer naming that subject authenticates as the actor.

A revoked binding leaves the list at once: from the next request, a token from that issuer naming that subject no longer authenticates as the actor. Revoking cannot be undone; a new binding is needed to restore it.

If it fails

What you see Cause What to do
"No issuer this tenant trusts publishes that identifier." The token was minted by an issuer that is not declared here Declare the issuer as trusted, then bind
"This does not look like a JWT." or "This token was read, but it names no subject." The pasted text is not a token, or carries no subject Type the subject instead
"This tenant trusts no issuer yet" No trusted issuer is declared Declare one in Settings
"Binding an external identity is part of the {edition} edition, and this tenant is not on it." The tenant's edition does not include workload identity federation Change the tenant's edition
"The binding was not created" because the pair is already bound That issuer and subject are already bound in this tenant, to an actor (the message names it when it can) or to an administrative workload Remove that binding first, or use that actor
"This actor is disabled, which is final, so it cannot be bound to an external identity." The actor is disabled Provision a new actor
"That binding no longer exists — it had already been removed." Someone removed it first Nothing to do: the list is refreshed

Without the console

Surface How
API POST /api/v3/admin/tenants/{tenantId}/workload-identity/bindable-issuers/resolve with the token's issuer identifier only (operation resolveBindableIssuer): finds the trusted issuer that publishes it
API POST /api/v3/admin/tenants/{tenantId}/workload-identity/actors/{actorId}/issuer-bindings with issuerId and subject (operation createTenantActorIssuerBinding)
API DELETE /api/v3/admin/tenants/{tenantId}/workload-identity/actors/{actorId}/issuer-bindings/{bindingId} (operation deleteTenantActorIssuerBinding)