Skip to content

Let workloads sign in with a cloud or CI identity

Let a workload sign in with a token its own identity provider already issues it, such as a Kubernetes service account or a CI pipeline's identity, so that no key or secret is stored for it. You declare the provider as a trusted issuer of the tenant, then bind one exact subject of that issuer to the workload.

Who can do it

A tenant administrator. A tenant key manager can also declare, change and test the tenant's trusted issuers, but cannot bind a subject to a workload. A platform super admin can do the same for a tenant: the console then declares the issuer on the tenant's behalf, from the platform. Binding a subject to a workload by a platform administrator is refused on a SaaS deployment.

The issuer controls on Trusted issuers need the permission to change and to test the tenant's trusted issuers. Bind federated subject and Unbind need the permission to manage workload credentials, and choosing an issuer needs the permission to read workload identity trust.

Before you start

  • The tenant's edition includes workload identity. When it does not, the console says so: "Declaring your own trusted issuers requires edition {requiredEdition}; this tenant's edition is {effectiveEdition}." Removing an issuer from the trust set and deleting it stay available.
  • On a deployment you operate yourself, the platform operator has delegated this integration to the tenant.
  • The workload exists. See Create a workload.
  • You know the issuer URL exactly as the provider writes it in the token's iss claim, and the exact sub the workload's tokens carry.

Steps

  1. Declare the issuer:
    1. Open Settings from the tenant sidebar, then the Integrations tab.
    2. On the Trusted issuers row, select Manage, then Declare an issuer.
    3. Choose the Provider, and enter the Issuer URL, an optional Label and the Maximum token lifetime as an ISO-8601 duration, for example PT1H.
    4. Optionally select Check before saving to see whether the deployment would accept the declaration and the form in which it stores the issuer URL.
    5. Select Declare an issuer.
  2. Copy the issuer's Derived audience and set it, exactly as shown, as the audience of the workload's application in your identity provider.
  3. Select Add to trust set. A declared issuer authenticates nobody until it is in the trust set.
  4. Optionally select Test to check that the deployment can reach the issuer.
  5. Bind the workload:
    1. Open Administrative Workloads, select the workload's name and open the Federated identities tab.
    2. Select Bind federated subject.
    3. Choose the Trusted issuer and type the Subject exactly as the token's sub claim carries it, for example system:serviceaccount:payroll:key-rotator.
    4. Select Bind.

To change an issuer later, select Edit and then Save changes. To stop it trusting tokens while keeping its declaration, select Remove from trust set. To withdraw it, select Delete: every workload of the tenant that signs in through the issuer stops authenticating, and the deletion is refused while a Cryptographic Actor binding names the issuer. Workload bindings do not block it. To stop one subject signing in, select Unbind on its row.

What you see when it worked

The console confirms "Trusted issuer declared.", "The issuer is in the trust set." and "Federated subject bound.". The binding is listed on the workload's Federated identities tab. The workload signs in with a token that issuer mints for that subject, and receives the scopes assigned to it.

After Unbind, tokens the subject already obtained stay valid until they expire, within five minutes; suspend the workload when they must be refused at once.

If it fails

What you see Cause What to do
"No trusted issuer can be bound here yet. Declare one in the workload identity settings first." The tenant has no issuer it may bind under Declare an issuer and add it to the trust set
"This deployment would refuse the declaration as entered." The declaration breaks an admission rule; the detail names what to change Correct the field the detail names
"The server refused this declaration", saying the issuer is already declared here or already trusted deployment-wide The tenant, or the deployment, already declares that issuer Edit the existing declaration, or bind to the deployment's issuer
"This issuer and subject are already bound to an administrative workload or a cryptographic actor of this tenant. Remove that binding first." That issuer and subject already sign in as another workload or a cryptographic actor Use the existing principal, or unbind the subject there first
"That change was not applied", with a detail naming how many actor bindings the issuer still has Cryptographic Actor bindings still name the issuer Remove those bindings first, or select Remove from trust set instead, which keeps them
The workload's sign-in is refused as unauthenticated although the binding is in place The audience configured in the provider differs from the Derived audience Copy the derived audience again, character for character

Without the console

Surface How
API POST /api/v3/admin/tenants/{tenantId}/workload-identity/issuers (operation createTenantTrustedIssuer); PUT and DELETE on .../issuers/{issuerId} (operations replaceTenantTrustedIssuer, deleteTenantTrustedIssuer)
API POST .../issuers/{issuerId}/enable and .../disable (operations enableTenantTrustedIssuer, disableTenantTrustedIssuer); POST .../issuers/validate and .../issuers/{issuerId}/test (operations validateTenantTrustedIssuer, testTenantTrustedIssuer)
API POST /api/v3/admin/tenants/{tenantId}/workloads/{workloadId}/issuer-bindings (operation createTenantWorkloadIssuerBinding); DELETE .../issuer-bindings/{bindingId} (operation deleteTenantWorkloadIssuerBinding)