Skip to main content
If your platform isn’t GitHub Actions, AWS, Google Cloud, Microsoft Entra, or Kubernetes, it can still federate as long as it issues signed OIDC tokens. Register it as a custom issuer, tell KERNEL where its public keys are, and write rules against the token’s subject and claims.
A custom issuer is trusted exactly as you configure it. KERNEL can’t apply provider-specific checks to an issuer it doesn’t know, so the rule you write is the whole boundary. Check the issuer URL and key source, and restrict every rule to specific subjects.

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, or EdDSA.
  • Issued by exactly the registered issuer URL, in the iss claim.
  • For exactly one audience, in the aud claim, equal to the rule’s expected audience.
  • About a non-empty subject, in the sub claim.
  • Carrying both iat and exp, not expired, and with a lifetime no longer than the issuer’s maximum.
  • Carrying a jti claim, 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:
The SDK reads the file again for every exchange. With a single-use issuer, whatever writes the file must replace the token before each refresh. Otherwise turn off single use on the issuer.

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:
With AsyncKernel in Python, the callback can be an async def function.

From a single token

For a short script, set KERNEL_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