# Workload identity federation

Every seekrit organization has its own **OIDC issuer**. A workload you enroll can
ask it for a short-lived, signed identity token. AWS, Google Cloud, OpenAI and
Anthropic can each be told to trust that issuer, and they exchange the token for
their own short-lived credential. Nothing on the workload, and nothing in
seekrit, holds a provider API key.

This is the same model hosting platforms use for their own OIDC integrations,
but it works for any machine you can enroll: a VM, a bare-metal box, a container
on a host with no identity provider of its own, or a Kubernetes cluster whose
issuer a provider cannot reach.

```text
workload ──(enrollment key or platform JWT)──▶ seekrit
         ◀──── identity token: iss=<your issuer>, aud=sts.amazonaws.com ────
workload ──(identity token)──▶ AWS STS / Google STS / OpenAI / Anthropic
         ◀──── that provider's own short-lived credential ────
```

## Your issuer

```text
https://oidc.seekrit.dev/<your org id>
```

Find it at the top of **Organization → Access → Connect** in the dashboard. Its
discovery document is at `<issuer>/.well-known/openid-configuration` and its
keys at `<issuer>/.well-known/jwks.json`. These are the two URLs each provider
fetches. Tokens are RS256 and live for at most 15 minutes. Workloads still sign
in at `api.seekrit.dev`; `oidc.seekrit.dev` only publishes the issuer.

Trusting this issuer trusts **only your organization's workloads**. Another
seekrit organization's tokens carry a different `iss`, so they cannot match a
policy you write here, even a loose one.

### Subjects

Each token's `sub` names the workload, most general part first:

```text
<org id>:<application id>:<environment id>:<workload id>
org_7Hk2…:app_Q9d…:env_Lm3…:wli_Zx8…
```

Ids, never names: renaming an application can't change what a policy matches.
Because the order runs from general to specific, a trailing wildcard scopes
trust:

| Trust | Subject pattern |
| --- | --- |
| One workload | `org_…:app_…:env_…:wli_…` (exact) |
| Every workload in one environment | `org_…:app_…:env_…:*` |
| Every workload in one application | `org_…:app_…:*` |

OpenAI and Anthropic accept only a single trailing `*`, and AWS can condition
on `sub` but not on custom claims, which is why the scope is encoded in the
subject. Tokens also carry `org_id`, `application_id`, `environment_id` and
`workload_id` claims for verifiers that can match them.

## 1. Enroll a workload

In **Organization → Access → Connect**, choose **Enroll workload** and pick the
application environment it belongs to. Then choose how it signs in to seekrit:

- **Platform token**: the workload already has a JWT from its platform (a
  Kubernetes projected service-account token, GitHub Actions, Trigger.dev, Vercel). seekrit
  verifies that token. There is no seekrit key on the machine, which makes this
  the better choice where it is available. Choosing **GitHub Actions** fills in
  its issuer and keys URL. **Trigger.dev Cloud** derives the keys URL from your
  organization issuer.
- **Enrollment key**: the dashboard generates a P-256 key in your browser and
  downloads it once as a key file. Store it on the workload with restrictive
  permissions. It is one long-lived credential, but it replaces every provider
  key, it never leaves the machine (it only signs one-use assertions), and you
  can rotate or disable it in one place.

Under **Identity tokens**, select AWS, OpenAI or Anthropic for each provider the
workload will call. For Google Cloud, enter your pool provider's URL under
**Other audiences**:
`https://iam.googleapis.com/projects/<number>/locations/global/workloadIdentityPools/<pool>/providers/<provider>`.
seekrit refuses a token for any audience you did not enroll.

Select the workload in the **Workloads** table to open its details. **Identity
tokens** there lists the issuer, subject, environment prefix and audiences to
copy into a provider's console. The same panel is where you grant it
connections, rotate its key, or disable it.

> **Note:** Audiences are fixed at enrollment, like the authentication mode. To add a
>   provider later, enroll a replacement workload and disable the old one.

### Give a Trigger.dev task read access to a GitHub repository

1. Open the [OIDC page for the deployed Trigger.dev environment](https://cloud.trigger.dev/_/oidc).
   In Seekrit's workload form, select **Platform token → Trigger.dev Cloud** and
   paste the issuer and exact subject. Keep the audience set to the Seekrit API
   origin. The subject covers every task in that Trigger.dev environment. Enroll
   a different subject for each preview or staging environment that needs access.
2. Add a **GitHub App** connection in Seekrit Connect for the installation and
   repository. On the enrolled workload, grant that connection the repository's
   numeric ID and **Contents: Read**. Leave **Identity tokens** empty for this flow.
3. Install `@seekrit/sdk` in your Trigger.dev project. Set `SEEKRIT_WORKLOAD_ID`,
   `SEEKRIT_CONNECTION_ID`, `GITHUB_REPOSITORY_ID` and `GITHUB_REPOSITORY`
   (for example `acme/private-api`) in the task environment. These are identifiers.
   Use the Trigger.dev SDK and CLI 4.8.3 or later, redeploy, and start a new
   Production, Staging or Preview run. Token issuance requires an executing
   deployed task. [Trigger.dev OIDC prerequisites](https://trigger.dev/docs/oidc)

```ts
import { SeekritConnect } from "@seekrit/sdk/connect";
import { auth, task } from "@trigger.dev/sdk";

export const checkReadme = task({
  id: "check-private-readme",
  run: async () => {
    const issuer = "https://api.seekrit.dev"; // Use your deployment's API origin if self-hosted.
    const connect = new SeekritConnect({
      workloadId: process.env.SEEKRIT_WORKLOAD_ID!,
      issuer,
      getPlatformToken: async () => (await auth.getOIDCToken({ audience: issuer })).token,
    });
    const { accessToken } = await connect.getToken(process.env.SEEKRIT_CONNECTION_ID!, {
      repositoryIds: [Number(process.env.GITHUB_REPOSITORY_ID)],
      permissions: { contents: "read" },
    });
    const response = await fetch(`https://api.github.com/repos/${process.env.GITHUB_REPOSITORY}/readme`, {
      headers: { Authorization: `Bearer ${accessToken}`, "User-Agent": "seekrit-trigger-task" },
    });
    if (!response.ok) throw new Error(`GitHub returned ${response.status}`);
    const { sha } = await response.json();
    return { sha };
  },
});
```

The SDK asks Trigger.dev for a fresh five-minute token when the Connect session
needs renewal. GitHub sets the lifetime of its installation token. Keep both
tokens inside the task and return only the result of the operation.

## 2. Trust the issuer at each provider

### AWS

1. In IAM → **Identity providers**, add an **OpenID Connect** provider with
   provider URL `oidc.seekrit.dev/<your org id>` and audience
   `sts.amazonaws.com`.
2. Create (or edit) a role with a trust policy for that provider, conditioned on
   the subject:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::123456789012:oidc-provider/oidc.seekrit.dev/org_7Hk2…"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": { "oidc.seekrit.dev/org_7Hk2…:aud": "sts.amazonaws.com" },
        "StringLike": { "oidc.seekrit.dev/org_7Hk2…:sub": "org_7Hk2…:app_Q9d…:env_Lm3…:*" }
      }
    }
  ]
}
```

The workload then needs `AWS_ROLE_ARN` and `AWS_WEB_IDENTITY_TOKEN_FILE`, which
`seekrit identity run --aws <role-arn>` sets for you.

### Google Cloud

Create a workload identity pool with an OIDC provider for the issuer, map
`google.subject` to the token's `sub`, and add a condition on the subject:

```bash
gcloud iam workload-identity-pools create seekrit --location=global

gcloud iam workload-identity-pools providers create-oidc seekrit-oidc \
  --location=global --workload-identity-pool=seekrit \
  --issuer-uri="https://oidc.seekrit.dev/org_7Hk2…" \
  --attribute-mapping="google.subject=assertion.sub" \
  --attribute-condition="assertion.sub.startsWith('org_7Hk2…:app_Q9d…:env_Lm3…:')"
```

Grant roles to the federated principal
(`principal://iam.googleapis.com/projects/<number>/locations/global/workloadIdentityPools/seekrit/subject/<subject>`),
or let it impersonate a service account through `roles/iam.workloadIdentityUser`
for APIs that don't accept federated principals. The provider's default allowed
audience is its own full URL, which is the audience to enroll.
`seekrit identity run --gcp <provider> [--gcp-service-account <email>]` writes
the `external_account` credential file that Application Default Credentials and
`gcloud` read.

### OpenAI

1. In **Organization settings → Security → Workload identity**, add a provider
   with the issuer URL and audience `https://api.openai.com/v1`.
2. On the provider, add a service account mapping on `sub`: the exact subject,
   or a prefix ending in `*`.
3. Give your application the provider and service account ids, and read the
   token from `OPENAI_IDENTITY_TOKEN_FILE`, which `seekrit identity run --openai`
   keeps current:

```ts
import { readFile } from "node:fs/promises";
import OpenAI from "openai";

const openai = new OpenAI({
  workloadIdentity: {
    identityProviderId: process.env.OPENAI_IDENTITY_PROVIDER_ID!,
    serviceAccountId: process.env.OPENAI_SERVICE_ACCOUNT_ID!,
    provider: {
      tokenType: "jwt" as const,
      getToken: async () =>
        (await readFile(process.env.OPENAI_IDENTITY_TOKEN_FILE!, "utf8")).trim(),
    },
  },
});
```

### Anthropic

1. In the Claude Console → **Workload identity**, add a federation issuer with
   the issuer URL and **OIDC discovery** as the JWKS source.
2. Add a federation rule: subject prefix (the exact subject, or a prefix ending
   in `*`), audience `https://api.anthropic.com`, and the target service account.
3. Set `ANTHROPIC_FEDERATION_RULE_ID` and `ANTHROPIC_ORGANIZATION_ID`, plus
   `ANTHROPIC_WORKSPACE_ID` if the rule spans more than one workspace. With
   `ANTHROPIC_IDENTITY_TOKEN_FILE` set by `seekrit identity run --anthropic`,
   the Anthropic SDK's zero-argument client federates on its own and refreshes
   before its token expires.

> **Note:** Anthropic accepts each identity token only once (it checks `jti`), and
>   `identity run` replaces the token file at half its lifetime so that every
>   refresh exchanges a fresh token. Several Anthropic clients in one process tree
>   can still race to exchange the same token at the same moment. Prefer one
>   shared client.

## 3. Run the workload

`seekrit identity run` signs in, writes each provider's token to a private
temporary directory, sets that provider SDK's variables, and refreshes the
tokens until the command exits:

```bash
export SEEKRIT_WORKLOAD_FILE=/etc/seekrit/workload.json
export ANTHROPIC_FEDERATION_RULE_ID=fdrl_…
export ANTHROPIC_ORGANIZATION_ID=…

seekrit identity run \
  --aws arn:aws:iam::123456789012:role/app-prod \
  --anthropic -- node server.js
```

A long-lived key left in the environment would win over federation in most
provider SDKs, so `identity run` removes those variables (`AWS_ACCESS_KEY_ID`,
`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, …) from the command's environment and
names them on stderr. It composes with secrets injection:
`seekrit identity run --aws … -- seekrit run -- node server.js`.

For a platform-federated workload, point it at the platform token instead of a
credential file:

```bash
seekrit identity run --workload-id wli_Zx8… \
  --platform-token-file /var/run/secrets/tokens/seekrit \
  --openai -- python worker.py
```

Elsewhere, `seekrit identity token --audience <aud>` prints one token, and the
JavaScript SDK's `SeekritConnect#getIdentityToken(audience)` returns one in
process. Full flags: [CLI reference](/docs/reference/cli#keyless-provider-access-identity).

## Revocation and limits

- **Disabling a workload** stops new identity tokens immediately. A token already
  issued stays valid until it expires (15 minutes at most), and so does any
  provider credential minted from it, for that provider's own lifetime. Keep the
  provider-side lifetimes short: the AWS role's maximum session duration, the
  Anthropic rule's token lifetime.
- **Audit**: every identity token is a `workload.identity_issued` audit event
  carrying its audience and issuer. Provider-side logs (CloudTrail, Cloud Audit
  Logs) show the subject.
- **Identity, not secrets**: issuing these tokens decrypts nothing. They are
  signed with the deployment's issuer key and are unrelated to your end-to-end
  encrypted secrets.
