Skip to content

OIDC federation

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.

Setting it up takes two sides:

  • The spindle operator gives the spindle a signing key and an issuer URL. See For operators.
  • The workflow author sets audience in the workflow and registers the spindle’s issuer with the provider. See For workflow authors and Provider recipes.

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

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

Keep it readable only by the spindle’s user.

VariableDescription
SPINDLE_OIDC_ISSUERThe iss claim. An absolute https URL with no path, query or fragment.
SPINDLE_OIDC_KEY_PATHThe PEM file from above.
SPINDLE_OIDC_KEY_IDOptional 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:

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, configure the mill. Executors never mint tokens, and the NixOS module only applies these options to the standalone and mill roles.

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:
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.

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.

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.

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

ClaimExampleMeaning
isshttps://tokens.spindle.example.comThe spindle’s issuer.
audsts.amazonaws.comThe workflow’s audience, as a single string.
subdid:plc:abc123:refs/heads/main<repository>:<ref>, with :engine:<engine> for an engine’s.
repositorydid:plc:abc123The repository’s DID.
refrefs/heads/mainThe git ref of the run. May be empty, see below.
sha9f2c1e…The commit being run.
actordid:plc:xyz789DID of whoever triggered the run. May be empty.
enginenamespaceOnly on an engine’s own token, the engine it was minted for.
iat, nbf1763000000When it was minted.
exp1763003600When it expires.
jtirandomUnique 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.

Set 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.

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. Ask your spindle’s operator for its issuer URL. For the spindle Tangled runs it’s https://tokens.spindle.tangled.network.

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

Register the spindle as an IAM OIDC identity provider:

  • Provider URL: the issuer, https://tokens.spindle.example.com.
  • Audience: sts.amazonaws.com.
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:

{
"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:

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:

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"

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.
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:

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:

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.

The 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.

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.

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.
  • 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.