- There’s no secret to leak. Nothing is stored in CI variables, config files, or secret managers. The federation rule ID your workload sends is an identifier, not a credential.
- Tokens expire in minutes. An access token lasts 300 seconds by default and 600 at most. The SDKs exchange a fresh one before it expires.
- Access is tied to one workload. A rule names exactly who can authenticate, such as one repository, workflow, and branch, or one IAM role. A token from anywhere else is refused.
- Access is narrow by construction. Every rule is limited to one project and an explicit list of permissions.
Federation is as strong as the identity provider that signs the tokens. Write rules as specific as your workload allows, and keep using the controls your provider gives you, such as protected branches and deployment environments.
Concepts
An organization admin sets up three resources. Together they say: tokens signed by this issuer, that match this rule, can act as this service account.Service accounts
A service account (svc_...) is a named, non-human identity that your organization owns. It’s what a workload acts as: browsers the workload creates are recorded as created by the service account, and it shows when it was last used.
A service account has only a name and a description. It has no permissions of its own. Each federation rule that targets it sets the project and permissions for the tokens that rule issues. See Service accounts.
Issuers
An issuer (wii_...) registers an identity provider with your organization. It tells KERNEL which iss claim to expect and where to get the provider’s public signing keys.
Each issuer has a provider type: github_actions, aws, google_cloud, microsoft_entra, kubernetes, or custom_oidc. The type decides which identity checks a rule on that issuer must make. Registering an issuer accepts no token by itself. Only a rule does that.
Federation rules
A federation rule (wifr_...) decides which tokens from an issuer are accepted and what they can do. A rule has:
- Match conditions. What the token must say about the workload. Each provider type has its own required conditions. A GitHub Actions rule, for example, names a repository by its numeric ID, a workflow, and a branch or environment.
- Expected audience. The
audclaim the token must carry. The SDKs requesthttps://auth.onkernel.com. - Target. The service account the workload acts as.
- Authorization. One project, a permission policy inside that project, and the access token lifetime.
How it works
- Your identity provider issues a token to the workload. Most platforms hand it over without any setup in your code: the GitHub Actions runner, the AWS Security Token Service, the Google Cloud metadata server, or a file Kubernetes mounts into the pod.
- The SDK exchanges it for a KERNEL access token. It sends the token and your federation rule ID to
POST https://auth.onkernel.com/token. The request needs no KERNEL credential. The rule ID only selects which rule to check; the token must still satisfy it. - The SDK calls the API with the access token and exchanges a fresh identity token before the access token expires. There’s no refresh token.
Set up federation in the dashboard
You need to be an organization admin. Members can view service accounts, issuers, rules, and authentication events, but can’t change them.1
Open Connect workload
In the dashboard, open Keys in the sidebar, select Workload identity, and click Connect workload.You also get here from API keys: clicking Create API Key offers Set up identity federation before it issues a key.
2
Issuer: choose your provider
Select Connect a new provider and pick a tile: GitHub Actions, AWS, Google Cloud, Microsoft Entra, Kubernetes, or Custom OIDC. Fill in what the provider needs, such as your AWS issuer URL or your Entra tenant ID, then click Apply and continue.If your organization already trusts the provider, select Use a registered issuer and pick it from the list.
3
Federation rule: say which workloads can connect
Enter a Rule name, then fill in Match conditions for your provider. Under Authorization, choose the Project, the Permissions the workload needs in that project, and the Token lifetime.Grant only what the workload uses. A job that runs browsers needs
browsers:create, browsers:use, and browsers:delete. See Scoping permissions for every action. Federation rules use the same policy format as scoped API keys.4
Target: pick a service account
Select Use an existing account, or Create a service account and give it a name such as
browser-ci. Check the Review summary and click Create rule. The rule is created disabled.5
Test: enable and verify
The last step walks you through four checks:
- Check the issuer’s signing keys. Click Check keys to confirm KERNEL can fetch the provider’s public keys. This grants no access.
- Enable. Turn on the issuer, then the rule.
- Configure your workload. Copy the rule ID (
wifr_...) and set it asKERNEL_FEDERATION_RULE_IDwhere your workload runs. The provider guides below show the rest. - Watch for the first exchange. Run your workload. The wizard shows the exchange as soon as KERNEL issues a token.
Authenticate from your workload
WithKERNEL_FEDERATION_RULE_ID set and no KERNEL_API_KEY, the SDKs find the identity token, exchange it, and refresh the access token for you. Your application code doesn’t change:
KERNEL_IDENTITY_TOKEN_SOURCE, or let the SDK detect it:
Configure it in code
Every setting has a code equivalent. This client reads its identity token from a file and names its rule explicitly:Exchange a token without an SDK
In a language with no KERNEL SDK, make the exchange yourself. It’s one unauthenticated form post:Credential precedence
The SDKs resolve a credential in this order:- An API key or federation credentials passed in code.
KERNEL_API_KEY.KERNEL_FEDERATION_RULE_IDwith an identity token source.
Token lifetime and refresh
An access token lasts for the rule’s Token lifetime: 300 seconds by default, 600 at most. It never outlives the identity token it came from, so a provider token with two minutes left yields an access token of two minutes or less. The SDKs cache the access token and renew it on two thresholds:- Background refresh when less than 120 seconds, or 40% of the token’s lifetime if that’s shorter, remains. Requests keep using the cached token while the new exchange runs.
- Blocking refresh when less than 30 seconds, or 10% of the lifetime, remains. Requests wait for the new token, and fail if the exchange fails.
401, the SDK drops the token, exchanges a fresh identity token, and retries the request once.
Every exchange needs an identity token from your provider. Most providers’ tokens can be exchanged only once:
The built-in SDK sources request a new identity token for every exchange, so you don’t manage this yourself. It matters when you supply tokens through a file or a callback: the source must return a fresh token each time.
What a workload can do
A federated credential can do what its rule’s policy grants, inside the rule’s one project. Three things stay closed to service accounts whatever the policy says: acquiring a browser from a pool, using app deployments and invocations, and managing API keys. See what a service account can’t do. A workload can inspect its own identity and permissions:Turn access off
Disable or archive any link in the chain to stop a workload: the rule, the issuer, or the service account. New exchanges are refused at once, and tokens already issued stop working within about 10 seconds.- Disable when you may turn it back on. In the dashboard, open the row’s menu on the Issuers or Rules tab and select Disable.
- Archive when the workload is gone for good. Archiving can’t be undone. Registering the same name or issuer URL again creates a new resource with a new ID.
Stopping a workload doesn’t delete the browsers it created. Delete those browsers yourself when you end the workload.
See what happened
- Authentication events. The Authentication events tab lists each token KERNEL issued, with its issuer, rule, service account, and project. It also lists exchanges refused after the token was verified, such as a replayed token. Events are kept for 30 days.
- Last exchange. Each rule shows when it last issued a token.
- Last used. Each service account shows when one of its rules last issued a token or one of its API keys last authenticated.
Provider guides
Each guide covers where the identity token comes from, what its claims look like, and what to enter in the dashboard.GitHub Actions
CI without a
KERNEL_API_KEY repository secret.AWS
ECS, Lambda, and EC2 with STS web identity tokens.
Google Cloud
GKE, Cloud Run, and Compute Engine with identity tokens from the metadata server.
Microsoft Entra
Managed identities and app registrations in your tenant.
Kubernetes
Projected service account tokens from your cluster.
Custom OIDC
Any other issuer that signs OIDC tokens.
See also
- Service accounts: what they are, what they can’t do, and service account API keys
- Move a workload from an API key: switch without downtime
- Reference: the token exchange, SDK configuration, and every issuer and rule field
- Troubleshooting: what a refused exchange means and how to fix it