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
audiencein the workflow and registers the spindle’s issuer with the provider. See For workflow authors and Provider recipes.
For operators
Section titled “For operators”Generate a key
Section titled “Generate a key”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.pemKeep it readable only by the spindle’s user.
Configure the spindle
Section titled “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:
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.
Choose the issuer URL
Section titled “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) andid_token_signing_alg_values_supported: ["ES256"].GET /jwks: one EC P-256 key withuse: sig,alg: ES256and itskid.
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.
Check it
Section titled “Check it”curl https://tokens.spindle.example.com/.well-known/openid-configurationcurl https://tokens.spindle.example.com/jwksThe issuer in the first response must match SPINDLE_OIDC_ISSUER
exactly, and jwks_uri must load.
Rotating the key
Section titled “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
Section titled “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
Section titled “For workflow authors”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: microvmimage: nixosaudience: https://deploy.example.com
steps: - name: "Notify deploy service" command: | curl -fsS -X POST \ -H "Authorization: Bearer $TANGLED_ID_TOKEN" \ https://deploy.example.com/hookThe 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.
Provider recipes
Section titled “Provider recipes”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.comCreate 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"Google Cloud
Section titled “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
audienceis 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.
Namespace
Section titled “Namespace”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.
Other services
Section titled “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, andrepositoryorsub. Addrefto restrict to a branch.
Security
Section titled “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
actoralone. 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 arepositorycheck. - 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
repositorycan’t be met by outside code. - Restrict deploys by
refwhen only one branch should reach production. Anyone who can push a branch to the repository can otherwise get a token.