What your tokens need
KERNEL accepts a token from a custom issuer when it is:- A signed JWT, 16 KiB or smaller, using
RS256,RS384,RS512,PS256,PS384,PS512,ES256,ES384,ES512, orEdDSA. - Issued by exactly the registered issuer URL, in the
issclaim. - For exactly one audience, in the
audclaim, equal to the rule’s expected audience. - About a non-empty subject, in the
subclaim. - Carrying both
iatandexp, not expired, and with a lifetime no longer than the issuer’s maximum. - Carrying a
jticlaim, when the issuer is single-use.
Register the issuer
In the dashboard, open Keys > Workload identity, click Connect workload, and select the Custom OIDC tile. To register an issuer without creating a rule yet, use Register issuer on the Issuers tab; the fields are the same.JWKS source
KERNEL fetches keys only over
https from public internet addresses, and never follows a URL inside a token. A key set holds at most 16 public keys. RSA keys must be at least 2,048 bits.
KERNEL caches an issuer’s keys for five minutes. When a token names a key ID that isn’t in the cache, KERNEL fetches the key set again, at most once a minute. A rotated key is usually picked up on the first token that uses it.
Write a rule
Under Match conditions, a custom rule needs a subject, a claim condition, or both:
Every condition must hold. Claim conditions compare a claim by its JSON text, so a boolean matches
true or false and a number matches its digits. A condition never matches an object or an array; address an array element by its index, such as /groups/0.
Prefer an exact subject. A prefix widens the rule to every subject your issuer can produce under it, including ones created later.
Under Authorization, choose the Project, the Permissions, and the Token lifetime. Then pick a service account, create the rule, and enable the issuer and the rule in the Test step.
Supply the token from your workload
The SDK needs a fresh token from your issuer for every exchange. Pick the way that fits how your platform delivers it.From a file
If an agent writes the token to a file and keeps it current, set:From a callback
When your code fetches the token itself, pass a callback. It runs once per exchange and must return a newly issued token each time:AsyncKernel in Python, the callback can be an async def function.
From a single token
For a short script, setKERNEL_IDENTITY_TOKEN to one token. It’s good for exactly one exchange, so the client works until its first access token expires: 300 seconds by default. Use a file or a callback for anything longer.
Without an SDK
Post the token to the token endpoint yourself. See Exchange a token without an SDK.Next steps
- Reference: every issuer and rule field
- Troubleshooting: what a refused exchange means
- Move a workload from an API key