Skip to main content
This page is the reference for workload identity federation. To set it up, start with the guide for your provider.

Token exchange

A workload gets a KERNEL access token by posting its identity token to the KERNEL authorization server. The SDKs make this request for you.

Request

POST https://auth.onkernel.com/token takes a form-encoded body and no credential. The endpoint is strict about what it accepts:
  • Any other parameter, including client_id and client_secret, is rejected.
  • A parameter sent twice is rejected.
  • A request with an Authorization header is rejected. The identity token is the only proof.

Response

There’s no refresh token. To get another access token, exchange a fresh identity token.

Access token lifetime

The access token expires at the earliest of:
  • The rule’s token lifetime (max_token_ttl_seconds): 300 seconds by default, 600 at most.
  • The identity token’s own expiry.

Errors

Errors use the OAuth error format, with an error code and an error_description. The endpoint doesn’t say why a token was refused, so that a caller can’t probe your configuration. See Troubleshooting to find the reason.

Discovery

A client can find everything it needs from the API host:
  1. GET https://api.onkernel.com/.well-known/oauth-protected-resource returns resource, the exact value to send as the resource parameter, and authorization_servers, which names the authorization server.
  2. GET https://auth.onkernel.com/.well-known/oauth-authorization-server returns the token_endpoint, and lists urn:ietf:params:oauth:grant-type:jwt-bearer under grant_types_supported.

SDK configuration

Federation support is in @onkernel/sdk for TypeScript, the kernel package for Python, and github.com/kernel/kernel-go-sdk for Go. The Go SDK needs Go 1.23 or later.

Environment variables

When KERNEL_IDENTITY_TOKEN_SOURCE isn’t set, the SDK uses the first of these that applies:
  1. KERNEL_IDENTITY_TOKEN_FILE
  2. KERNEL_IDENTITY_TOKEN
  3. GitHub Actions, when the runner exposes ACTIONS_ID_TOKEN_REQUEST_URL
AWS and Google Cloud are never detected. Set KERNEL_IDENTITY_TOKEN_SOURCE to aws_sts or gcp_metadata.

Credential precedence

When KERNEL_API_KEY and KERNEL_FEDERATION_RULE_ID are both set, the SDK uses the API key and logs one warning. The SDKs differ in two edge cases:

Identity token sources

Import the TypeScript names from @onkernel/sdk/lib/credentials, the Python names from kernel, and the Go names from github.com/kernel/kernel-go-sdk/lib/credentials, its awssts subpackage, and github.com/kernel/kernel-go-sdk/option. The built-in sources request a token for this audience: the source’s own audience setting, then KERNEL_IDENTITY_TOKEN_AUDIENCE, then the auth base URL.

Federation options

Pass these with the identity token source: to oidcFederationProvider in TypeScript, WorkloadIdentityCredentials in Python, and option.FederationOptions in Go. If you point the client at a base URL other than https://api.onkernel.com, you must also set the auth base URL. The SDK refuses to pair a custom API with the default authorization server.

Exchange a token once

To manage the access token yourself, call the exchange directly. It makes one request, caches nothing, and needs no KERNEL credential:
expiresAt and expires_at are Unix seconds. In Go, ExpiresAt is a time.Time. Python also has async_exchange_federation_assertion. The call spends the identity token. Don’t call it again with the same token, even after a timeout.

Refresh and retries

  • The SDK caches the access token and shares it between copies of a client that use the same base URL.
  • It refreshes in the background when less than 120 seconds, or 40% of the token’s lifetime if that’s shorter, remains.
  • It blocks requests on a refresh when less than 30 seconds, or 10% of the lifetime, remains.
  • Concurrent requests share one exchange. The identity token source is never called twice at once.
  • A 401 from the API drops the cached token and retries the request once with a token from a fresh exchange. A second 401 is returned to you. A request whose body can’t be sent again isn’t retried. In Python, a client with max_retries=0 doesn’t retry a 401 at all.

Errors

A failed exchange or a misconfiguration surfaces as a WorkloadIdentityError. For a token that was already exchanged, the message adds advice that depends on where the token came from: a file that wasn’t rotated, a static value, or a callback that returned the same token.

Safeguards

The SDKs protect the identity token in transit:
  • The token endpoint must be https. Plain http is allowed only for localhost, 127.0.0.1, and ::1.
  • An identity token over 16 KiB is refused before it’s sent.
  • Token requests don’t follow redirects.
  • Errors and logs never include the identity token or the access token.

Issuers

An issuer (wii_...) registers one identity provider.

Provider types

The supported algorithms are RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, and EdDSA. GitHub Actions, Google Cloud, and Microsoft Entra issuers are recognized by their issuer URL and must use their own type. You can’t register https://accounts.google.com as custom_oidc to skip Google’s identity checks.

Key sources

  • Keys are fetched over https from public internet addresses only.
  • ca_cert_pem replaces the system root certificates for that fetch. It holds public CA certificates only.
  • A key set holds at most 16 keys, all public. RSA keys must be at least 2,048 bits.
  • Fetched keys are cached for five minutes. A token that names an unknown key ID triggers a new fetch, at most once a minute.
  • GitHub Actions issuers always use discovery.

How a token is verified

KERNEL accepts an identity token only when:
  • It’s a signed JWT of 16 KiB or less, and its signature verifies against one of the issuer’s keys.
  • iss equals the issuer URL exactly.
  • aud holds exactly one value, equal to the rule’s expected_audience.
  • sub is a non-empty string of 1,024 characters or less.
  • exp and iat are both present, the token hasn’t expired, and exp minus iat is within max_lifetime_seconds. KERNEL allows 30 seconds of clock difference.
  • For a single-use issuer, the token has a token ID that hasn’t been exchanged before. The token ID is jti, or uti for Microsoft Entra.
  • The rule’s match conditions all hold.
A single-use token is spent only when an access token is issued. A token refused for another reason isn’t spent.

Federation rules

A federation rule (wifr_...) maps tokens from one issuer to one service account, one project, and one policy.

Match fields

match.type must equal the issuer’s preset_type. Every condition a rule sets must hold. These fields are available for every type:

GitHub Actions

AWS and custom OIDC

At least one of subject, subject_prefix, or claims is required. For AWS, subject is the IAM role ARN, including its path.

Google Cloud

Microsoft Entra

At least one of these is required: subject, or a claims condition on /oid, /appid, or /azp.
  • KERNEL adds a /tid condition for the issuer’s tenant. A rule that names a different tenant is rejected.
  • A rule with no subject and no /oid also requires /idtyp to be app.
  • A token with an scp claim never matches.

Kubernetes

The token’s subject must be exactly system:serviceaccount:<namespace>:<service_account>.

Service accounts

See Service accounts.

Authentication events

Each event records one exchange outcome. Events never hold tokens or claims. A failure is recorded only after the token has verified and matched an enabled rule. A token that fails signature, issuer, audience, expiry, or match checks leaves no event, because KERNEL can’t yet tie it to your organization. Repeated failures for the same token and reason are recorded once. Events are kept for 30 days. Through the API, a query returns the last seven days by default and spans at most 30 days. You can filter by issuer, rule, service account, project, outcome, and time range.

Auth context

GET https://api.onkernel.com/auth/context describes the credential that makes the request. For a federated token, it returns the service account, the project, the current policy, and which issuer and rule the token came from:
external_subject_digest is a digest of the identity token’s subject. The token and its claims are never returned. A service account API key gets the same response without workload_identity, and with authentication.method set to api_key. The call needs no permission in the policy.

Management API

Manage service accounts, issuers, and rules in the dashboard. These are the endpoints behind it, listed for reference. They aren’t currently accessible with an API key or a federated token: a call with either returns 403, including through the SDK methods for these endpoints.

Who can manage them

  • Any organization member can view service accounts, issuers, rules, and authentication events.
  • Only an organization admin can change them: create, update, archive, and verify.
The same applies to service account API keys: only an organization admin can create, rotate, rename, change the permissions of, or delete one, and only from the dashboard.

Updates and versions

Every resource has a security_version that increases when a change affects what it trusts or grants. An update (PATCH) must send the version it’s based on as expected_version. If the resource changed in the meantime, the update returns 409 Conflict. Read the resource again and retry.

Lists and archiving

  • Lists take limit (1 to 100, default 20) and offset, and return X-Has-More and X-Next-Offset headers. Service account, issuer, and rule lists also take status: active (the default), archived, or all.
  • DELETE archives. History stays, and the archived resource stops granting access. Creating a resource with the same name or issuer URL later creates a new ID.
  • A problem the admin can fix, such as a key endpoint that isn’t public or a discovery document that names a different issuer, returns 400 with the reason. A 503 means a condition that may pass on retry, such as a timeout.

Limits