OIDC trusts
A trust lets the tokens of one OIDC issuer call the API of your organization. The workload stores no CloudRaker key. An admin manages trusts on the Trusted issuers page of Dash.
Create a trust
Select Add issuer. Dash has presets for GitHub Actions, GitLab CI, Google Cloud and Kubernetes. Any other issuer with a discovery document works too, if it can send the audience that this page gives. Dash also shows a Microsoft Entra preset, but Entra tokens do not match this API yet.
The audience of the token is always the host of the tenant: https://{slug}.cloudraker.run. Configure your issuer to send this audience.
Microsoft Entra cannot send this audience. An Entra v2.0 access token has the client ID of the API as its audience. Entra also accepts an https Application ID URI only on a verified domain of your directory. The API refuses these tokens at the token checks.
Test a token in Dash shows which trust matches a token, and why. Dash does not store the token.
Token checks
The API refuses a token with 401 invalid_token, or with 400 invalid_grant on the token endpoint, when one of these checks fails:
- The signature uses RS256 or ES256. The API refuses
noneand every HS algorithm. - The
issequals the issuer of a trust exactly. The issuer publishes a discovery document at/.well-known/openid-configuration. - The
audishttps://{slug}.cloudraker.run. - The
expandiatclaims are present.exp - iatis 24 hours or less. The clock skew allowance is 60 seconds. - The token is 8 KB or less.
Exchange a token
Token exchange is the default method. Send the JWT to POST /v2/oauth/token. The API returns a short-lived crt_ token. Use it as a bearer credential on every route.
The endpoint uses RFC 8693 token exchange, and also accepts the RFC 7523 jwt-bearer grant. It takes a form body or a JSON body of 16 KB or less. It needs no Authorization header.
Errors use the RFC 6749 shape. Read OAuth errors.
A change or a delete of a trust revokes its crt_ tokens. The client then exchanges again.
Send the OIDC token directly
You can also send the JWT as the bearer credential on any route. The API verifies it and keeps the result in a cache. The cache time is the shortest of exp, the token lifetime of the trust and 24 hours.
Prefer the exchange. Each new JWT needs a verification, and a crt_ token does not.
GitHub Actions
The job needs the id-token: write permission. The trust subject is, for example, repo:acme@1234/invoices@5678:ref:refs/heads/main. GitHub puts the owner ID and the repository ID in the subject. To see the prefix of your repository, run gh api repos/OWNER/REPO/actions/oidc/customization/sub --jq .sub_claim_prefix. An older repository can have the prefix repo:acme/invoices.
Run agents of your organization
Your organization trusts its own Run issuer by default. You do not add a trust for it. A Run agent can call https://{slug}.cloudraker.run/v2 with no key. Add oidc and scopes to the host in agent.yml. Read Call the CloudRaker API in the Run docs.
This trust has stricter rules than a normal trust:
- It accepts agent tokens only:
identitymust beagent, with anagentclaim. It refuses user tokens. - It refuses tokens of branch preview runs. A token with a
branchclaim gets401 invalid_token. - The token
orgmust be the slug of the host, andissmust be the issuer of this organization. - The token scopes come from
agent.yml, inside a fixed subset.