Start here
1
Read the SDK error
The SDK raises a
WorkloadIdentityError with the HTTP status, the OAuth error code, and a description. Match it against the table below.2
Check the authentication events
In the dashboard, open Keys > Workload identity > Authentication events and filter by Rule.
- A
failureevent exists. The token verified and matched the rule, and the reason says what went wrong next. - No event exists. The token was refused before KERNEL could tie it to your organization: the signature, issuer, audience, expiry, or match conditions didn’t hold, or the rule or issuer isn’t enabled.
3
Decode the token
Print the identity token’s claims from inside the workload and compare them with the rule:Check
iss against the issuer URL, aud against the rule’s expected audience, and sub and the other claims against the rule’s match conditions. Don’t paste a live token into a website or a chat.Exchange errors
The same token was sent twice
GitHub Actions and AWS tokens can be exchanged once. Microsoft Entra and custom OIDC tokens can be exchanged once unless you allow reuse. When a token is presented a second time, the SDK’s message says where it came from:
To allow reuse on a Microsoft Entra, Kubernetes, or custom OIDC issuer, select Edit on the issuer and turn off Enforce single-use tokens (JTI replay protection). A reusable token can be exchanged until it expires, so allow reuse only when your token source needs it.
SDK configuration problems
Requests fail after a successful exchange
Provider notes
GitHub Actions- A rule needs a branch or an environment. A job on another branch, or without that environment, doesn’t match.
pull_request,schedule, andreleaseevents aren’t allowed unless you add them to Allowed events.- A rule with a Workflow path matches only when the workflow file comes from the same ref the job runs on.
- The rule pins numeric repository and owner IDs. A repository that was deleted and recreated under the same name has a new ID.
- The subject is the IAM role ARN with its path, such as
arn:aws:iam::123456789012:role/service/browser-worker. GetWebIdentityTokenisn’t served by the global STS endpoint. The SDKs call the regional endpoint forAWS_REGION.
- The subject is the service account’s numeric unique ID, not its email.
- The metadata server returns a token for the service account attached to the workload. Check that it’s the one your rule names.
- A token with an
scpclaim was issued to a signed-in user and never matches. Use a managed identity or client credentials. - v1.0 and v2.0 tokens have different issuers and audiences. Register the issuer version your tokens carry.
- A rule keyed only on a client ID needs the
idtypoptional claim. See Microsoft Entra.
- The default service account token has the wrong audience. Mount a projected token with the audience
https://auth.onkernel.com. - A projected token with
expirationSecondsover 3,600 exceeds the issuer’s default maximum lifetime. - KERNEL must reach the cluster’s discovery document and keys from the public internet. For a private cluster, upload the keys.
Issuer key problems
Check signing keys on the Issuers tab fetches the issuer’s keys and reports the result. When KERNEL can’t use the keys for a reason you can fix, it tells you which:- The key endpoint’s address isn’t on the public internet.
- The endpoint returned the wrong status or didn’t return JSON.
- The discovery document names a different issuer than the one you registered.
- The key set isn’t valid or holds an unsupported key.