KERNEL_API_KEY in Secrets Manager, a task definition, or a Lambda environment.
Running on EKS? You can use this guide with the pod’s IAM role, or use the cluster’s own service account tokens with the Kubernetes provider.
Before you start
- You’re an organization admin in KERNEL.
- You can change IAM account settings and role policies in the AWS account.
- Your workload uses the TypeScript, Python, or Go SDK.
Configure AWS
1
Enable outbound identity federation
In the AWS console, open IAM > Account settings and enable outbound identity federation. Or run:Note the account’s token issuer URL. Each AWS account has its own, and it looks like
https://a1b2c3d4-0000-4111-8222-333344445555.tokens.sts.global.api.aws.2
Let the role request tokens
Attach a policy to the role your workload runs as. This one allows tokens for KERNEL only, and caps their lifetime at five minutes:
Configure KERNEL
1
Register your AWS account as an issuer
In the dashboard, open Keys > Workload identity, click Connect workload, and select the AWS tile.
- Paste the issuer URL into STS token issuer URL.
- Check Outbound web identity federation is enabled for this AWS account.
- Click Apply and continue.
2
Name the role in a rule
Under Match conditions, enter the IAM role ARN your workload runs as, such as
arn:aws:iam::123456789012:role/service/browser-worker.The token’s subject is the full role ARN, including its path. A role created with the path /service/ has role/service/browser-worker in its ARN, and the rule must include it.Under Authorization, choose the Project, the Permissions, and the Token lifetime.3
Pick a service account and enable
Choose or create a service account, click Create rule, then turn on the issuer and the rule in the Test step. Copy the rule ID (
wifr_...).Configure your workload
The AWS source needs the AWS SDK for your language, which each KERNEL SDK keeps optional:What the SDK does
For every exchange, the SDK calls STSGetWebIdentityToken with your workload’s own AWS credentials:
- Audience:
https://auth.onkernel.com - Signing algorithm:
RS256 - Duration: 300 seconds
- Region:
AWS_REGION, thenAWS_DEFAULT_REGION, thenus-east-1. The call goes to that region’s STS endpoint.
https://auth.onkernel.com/token. AWS tokens are always single-use in KERNEL, and the SDK requests a new one for each refresh.
To configure the source in code, for example to set the region:
What the token looks like
subis the role ARN, not the assumed-role session ARN. Matcharn:aws:iam::<account>:role/<path>/<name>.- AWS’s own claims are nested under the key
https://sts.amazonaws.com/. They aren’t top-level claims.
Narrow the rule
A rule that names one role ARN is already specific. To add a condition on a nested claim, open Advanced matching in the rule and add an Additional claim condition. Claim paths are JSON Pointers, so each/ inside the AWS key is written ~1:
Conditions are exact matches, and every condition must hold.
Next steps
- Reference: AWS match fields
- Troubleshooting: what a refused exchange means
- Move a workload from an API key