Skip to main content
A workload on AWS already has an IAM role. With AWS outbound identity federation, that role can ask the AWS Security Token Service (STS) for a signed token that names it. With workload identity federation, your workload exchanges that token for a KERNEL access token, so you don’t put a 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.
Register one issuer per AWS account.
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:
Set two environment variables on the task, function, or instance:
Then construct the client with no arguments:
In Go, the blank import is what turns the AWS source on. Programs that don’t import it don’t depend on the AWS SDK.

What the SDK does

For every exchange, the SDK calls STS GetWebIdentityToken with your workload’s own AWS credentials:
  • Audience: https://auth.onkernel.com
  • Signing algorithm: RS256
  • Duration: 300 seconds
  • Region: AWS_REGION, then AWS_DEFAULT_REGION, then us-east-1. The call goes to that region’s STS endpoint.
It then exchanges the token at 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

Two details to make note of:
  • sub is the role ARN, not the assumed-role session ARN. Match arn: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