OIDC job tokens

Every job can receive a short-lived OIDC JWT that proves which job it is. You use it to authenticate to clouds and secret managers by federation instead of storing long-lived credentials in Slipway.

permissions:
  id_token: write          # opt in; the token is exposed as $SLIPWAY_ID_TOKEN
jobs:
  - name: deploy
    steps:
      - run: echo "$SLIPWAY_ID_TOKEN" | cut -d. -f2 | base64 -d | jq .   # inspect claims

• Lifetime: 15 minutes. Not stored by Slipway.
• Audience: configurable, because each relying party wants its own (sts.amazonaws.com, a GCP provider URL, api://AzureADTokenExchange, your Vault role audience).
• Signed with the issuer key; public keys are served at /.well-known/jwks.json, with discovery at /.well-known/openid-configuration on your Slipway base URL.

Claims

Claim	Meaning
iss	Your Slipway base URL (SLIPWAY_BASE_URL when self-hosting)
sub	A structured subject identifying the job context, suitable for trust conditions
aud	The audience you requested
org	Organisation
project	Project
pipeline	Pipeline
run_id	The run
job	Job name
ref	Git ref
sha	Commit
environment	The environment, for deploy jobs
actor	Who triggered the run
runner_pool	The pool the job runs in
iat, exp	Standard timing claims

Decode a real token from a test job to see the exact sub format and values for your installation, and write trust conditions against them.

Writing safe trust conditions

The point of federation is that the cloud decides who may assume a role using the token’s claims. Be specific:

Goal	Condition
Only production deploys can assume the prod role	environment == "production"
Only the main branch	ref == "refs/heads/main"
Only this pipeline in this project	match org, project and pipeline
Only jobs on my trusted pool	runner_pool == "prod-network"

Matching on the issuer and audience alone lets any job from any org that your cloud trusts the issuer for assume the role. Always bind at least org and project, and for production also environment.

permissions

permissions: at pipeline or job level narrows what the job’s token may do against Slipway’s own API: contents, artifacts, secrets, deployments and id_token, each none, read or write, or read-all / write-all. Grant only what the job needs.

Provider guides

• AWS: IAM OIDC provider and AssumeRoleWithWebIdentity
• GCP: Workload Identity Federation
• Azure: federated credentials
• Vault: JWT auth method

Self-hosting requirements

The cloud must be able to fetch your JWKS. Your Slipway base URL must be reachable over HTTPS, with a certificate the cloud trusts, from AWS, GCP or Azure, at least for /.well-known/*. For private installs, expose just those two paths through a reverse proxy.