# OIDC federation

> Let workflows sign in to AWS, Google Cloud, Namespace and other services with a short-lived token from the spindle instead of a stored key.

A spindle can act as an OpenID Connect issuer. A workflow that asks for a token gets a short-lived, signed JWT that says which repository, ref and commit it’s running. A cloud provider that trusts the spindle’s issuer exchanges that token for its own short-lived credentials, so you don’t store a long-lived cloud key as a [secret](/docs/spindles/secrets/).

Setting it up takes two sides:

* The **spindle operator** gives the spindle a signing key and an issuer URL. See [For operators](#for-operators).
* The **workflow author** sets `audience` in the workflow and registers the spindle’s issuer with the provider. See [For workflow authors](#for-workflow-authors) and [Provider recipes](#provider-recipes).

## For operators

### Generate a key

Tokens are signed with ES256, so the key is an EC P-256 private key in PEM:

```sh
openssl ecparam -name prime256v1 -genkey -noout -out spindle-oidc.pem
```

Keep it readable only by the spindle’s user.

### Configure the spindle

| Variable                | Description                                                               |
| ----------------------- | ------------------------------------------------------------------------- |
| `SPINDLE_OIDC_ISSUER`   | The `iss` claim. An absolute `https` URL with no path, query or fragment. |
| `SPINDLE_OIDC_KEY_PATH` | The PEM file from above.                                                  |
| `SPINDLE_OIDC_KEY_ID`   | Optional `kid` header. Defaults to the RFC 7638 thumbprint of the key.    |

Set `SPINDLE_OIDC_ISSUER` and `SPINDLE_OIDC_KEY_PATH` together. With neither set, OIDC is off: workflows that set `audience` run without a token and without an error.

On NixOS:

```nix
services.tangled.spindle.oidc = {
  issuer = "https://spindle.example.com";
  keyPath = "/var/lib/secrets/spindle-oidc.pem";
  # keyId = "...";  # optional
};
```

On a spindle split into a [mill and executors](/docs/spindles/self-hosting/#mill-and-executors), configure the mill. Executors never mint tokens, and the NixOS module only applies these options to the standalone and mill roles.

### Choose the issuer URL

The spindle serves its discovery document and keys at the root of its own listener:

* `GET /.well-known/openid-configuration`: `issuer`, `jwks_uri` (the issuer followed by `/jwks`) and `id_token_signing_alg_values_supported: ["ES256"]`.
* `GET /jwks`: one EC P-256 key with `use: sig`, `alg: ES256` and its `kid`.

Both are sent with `Cache-Control: public, max-age=300`. Providers fetch them from the issuer’s origin, which is why the issuer can’t have a path. It has to be reachable over HTTPS from the provider.

You have two options:

* **The spindle’s own hostname**, such as `https://spindle.example.com`. If the spindle is already behind an HTTPS reverse proxy that forwards everything to it, there’s nothing else to do.
* **A dedicated hostname** that forwards only the two OIDC paths to the spindle. This keeps the issuer stable if the spindle moves and keeps it apart from the spindle’s API. Tangled’s spindle uses `https://tokens.spindle.tangled.network`:

```nix
services.nginx.virtualHosts."tokens.spindle.example.com" = let
  spindle = "http://${config.services.tangled.spindle.server.listenAddr}";
in {
  forceSSL = true;
  enableACME = true;
  locations."/.well-known/openid-configuration".proxyPass = spindle;
  locations."/jwks".proxyPass = spindle;
  locations."/".return = "404";
};
```

Then set `SPINDLE_OIDC_ISSUER=https://tokens.spindle.example.com`.

### Check it

```sh
curl https://tokens.spindle.example.com/.well-known/openid-configuration
curl https://tokens.spindle.example.com/jwks
```

The `issuer` in the first response must match `SPINDLE_OIDC_ISSUER` exactly, and `jwks_uri` must load.

### Rotating the key

The JWKS holds only the current key. Changing the key or `kid` invalidates every token already handed out. Tokens live at most as long as their workflow’s time budget, so rotate when no runs are in flight, or accept that running workflows’ tokens stop verifying.

Tell workflow authors the issuer URL. Changing it breaks every trust relationship registered with providers.

## The token

An ES256 JWT. The header has `alg: ES256`, `typ: JWT` and the `kid`.

| Claim        | Example                              | Meaning                                                        |
| ------------ | ------------------------------------ | -------------------------------------------------------------- |
| `iss`        | `https://tokens.spindle.example.com` | The spindle’s issuer.                                          |
| `aud`        | `sts.amazonaws.com`                  | The workflow’s `audience`, as a single string.                 |
| `sub`        | `did:plc:abc123:refs/heads/main`     | `<repository>:<ref>`, with `:engine:<engine>` for an engine’s. |
| `repository` | `did:plc:abc123`                     | The repository’s DID.                                          |
| `ref`        | `refs/heads/main`                    | The git ref of the run. May be empty, see below.               |
| `sha`        | `9f2c1e…`                            | The commit being run.                                          |
| `actor`      | `did:plc:xyz789`                     | DID of whoever triggered the run. May be empty.                |
| `engine`     | `namespace`                          | Only on an engine’s own token, the engine it was minted for.   |
| `iat`, `nbf` | `1763000000`                         | When it was minted.                                            |
| `exp`        | `1763003600`                         | When it expires.                                               |
| `jti`        | random                               | Unique per token.                                              |

It lives for the workflow’s time budget, capped at 6 hours, and at least 15 minutes.

Only trusted runs whose workflow sets `audience` get a token. A run is trusted when its code comes from a branch of the repository itself. Pull requests from forks or patches, pull request runs a collaborator had to approve, and manual runs of a fork get no token, the same as they get no secrets.

## For workflow authors

Set [`audience`](/docs/spindles/workflows/#audience) to whatever the provider expects in `aud`. It must be printable ASCII, at most 150 characters. Every step then gets the token as `TANGLED_ID_TOKEN`, masked in logs like a secret.

```yaml
when:
  - event: push
    branch: main


engine: microvm
image: nixos
audience: https://deploy.example.com


steps:
  - name: "Notify deploy service"
    command: |
      curl -fsS -X POST \
        -H "Authorization: Bearer $TANGLED_ID_TOKEN" \
        https://deploy.example.com/hook
```

The service at `deploy.example.com` verifies the token against the spindle’s issuer, as in [Other services](#other-services). Ask your spindle’s operator for its issuer URL. For the spindle Tangled runs it’s `https://tokens.spindle.tangled.network`.

## Provider recipes

The examples use `https://tokens.spindle.example.com` as the issuer and `did:plc:abc123` as the repository DID. Replace both.

### AWS

Register the spindle as an IAM OIDC identity provider:

* **Provider URL:** the issuer, `https://tokens.spindle.example.com`.
* **Audience:** `sts.amazonaws.com`.

```sh
aws iam create-open-id-connect-provider \
  --url https://tokens.spindle.example.com \
  --client-id-list sts.amazonaws.com
```

Create a role with this trust policy. The condition keys are the issuer’s host followed by `:aud` and `:sub`:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::123456789012:oidc-provider/tokens.spindle.example.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "tokens.spindle.example.com:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "tokens.spindle.example.com:sub": "did:plc:abc123:refs/heads/main"
        }
      }
    }
  ]
}
```

Use `did:plc:abc123:*` to allow any ref of the repository, including runs with an empty ref.

In the workflow, point the AWS CLI or SDK at the token with `AWS_WEB_IDENTITY_TOKEN_FILE`:

```yaml
audience: sts.amazonaws.com


dependencies:
  - awscli2


steps:
  - name: "Deploy"
    command: |
      echo "$TANGLED_ID_TOKEN" > /tmp/aws-token
      export AWS_ROLE_ARN=arn:aws:iam::123456789012:role/deploy
      export AWS_WEB_IDENTITY_TOKEN_FILE=/tmp/aws-token
      aws s3 sync dist/ s3://my-bucket/
```

Or exchange it yourself:

```sh
aws sts assume-role-with-web-identity \
  --role-arn arn:aws:iam::123456789012:role/deploy \
  --role-session-name tangled \
  --web-identity-token "$TANGLED_ID_TOKEN"
```

### Google Cloud

Create a workload identity pool and an OIDC provider in it:

* **Issuer URI:** `https://tokens.spindle.example.com`.
* **Attribute mapping:** `google.subject=assertion.sub`, `attribute.repository=assertion.repository`, `attribute.ref=assertion.ref`.
* **Attribute condition:** on the repository, and on the ref if you want one branch.
* **Audience:** leave allowed audiences empty. The workflow’s `audience` is then the provider’s full resource name.

```sh
gcloud iam workload-identity-pools create tangled \
  --location=global


gcloud iam workload-identity-pools providers create-oidc spindle \
  --location=global \
  --workload-identity-pool=tangled \
  --issuer-uri=https://tokens.spindle.example.com \
  --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository,attribute.ref=assertion.ref" \
  --attribute-condition="assertion.repository == 'did:plc:abc123'"
```

Grant the repository access to a service account:

```sh
gcloud iam service-accounts add-iam-policy-binding \
  deploy@my-project.iam.gserviceaccount.com \
  --role=roles/iam.workloadIdentityUser \
  --member="principalSet://iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/tangled/attribute.repository/did:plc:abc123"
```

To allow one branch only, bind `principal://iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/tangled/subject/did:plc:abc123:refs/heads/main` instead.

In the workflow, write a credential config that reads the token from a file, then sign in with it:

```yaml
audience: //iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/tangled/providers/spindle


dependencies:
  - google-cloud-sdk


steps:
  - name: "Deploy"
    command: |
      echo "$TANGLED_ID_TOKEN" > /tmp/gcp-token
      gcloud iam workload-identity-pools create-cred-config \
        projects/123456789/locations/global/workloadIdentityPools/tangled/providers/spindle \
        --service-account=deploy@my-project.iam.gserviceaccount.com \
        --credential-source-file=/tmp/gcp-token \
        --output-file=/tmp/gcp-creds.json
      gcloud auth login --cred-file=/tmp/gcp-creds.json
      gcloud storage cp dist/* gs://my-bucket/
```

`123456789` is the project number, not its ID.

### Namespace

The [Namespace engine](/docs/spindles/engines/#namespace-engine) signs in to your workspace with its own token, audience `federation.namespaceapis.com`, which never reaches your steps. Its subject ends in `:engine:namespace`, and its trust setup, which matches only that, is in [Trusting the spindle](/docs/spindles/engines/#trusting-the-spindle).

To use Namespace from a step on any engine, set `audience: federation.namespaceapis.com`, add a separate trust relationship for the step’s subject, `<repository>:<ref>`, and exchange `TANGLED_ID_TOKEN` with `nsc auth exchange-oidc-token`. Give it only the grant the step needs. Don’t widen the engine’s relationship to `<repository>:*` instead: that pattern also accepts every step’s token, on every branch and engine, with the engine’s grant over all of the workspace’s instances.

### Other services

Any service that accepts OIDC tokens from an external issuer works. Configure it with:

* **Issuer:** the spindle’s issuer URL. Keys are found through `/.well-known/openid-configuration`.
* **Audience:** a value unique to that service, which the workflow sets as `audience`.
* **Algorithm:** ES256.
* **Claims to check:** `aud`, and `repository` or `sub`. Add `ref` to restrict to a branch.

## Security

* **One issuer serves every repository on the spindle.** Trusting the issuer alone lets any repository there, including ones you don’t own, use your role. Always constrain on claims.
* **Match on `repository`.** It’s the repository’s DID, which survives renames. Don’t match on a name or handle.
* **Don’t trust `actor` alone.** It’s whoever triggered the run, and that person can trigger runs in every repository they can push to. Use it only on top of a `repository` check.
* **Untrusted code gets no token.** Pull requests from forks, patch pull requests, approved runs and manual runs of a fork never get one, so a rule on `repository` can’t be met by outside code.
* **Restrict deploys by `ref`** when only one branch should reach production. Anyone who can push a branch to the repository can otherwise get a token.