Skip to navigation

OIDC trusts

Let a workload call the API with its own identity token and no stored key.
View as Markdown

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.

FieldMeaning
IssuerThe https issuer URL. The token iss must equal it exactly.
SubjectThe rule for the token sub: an exact value or a glob.
ConditionsOther claims that the token must have, by name and value.
ScopesThe scopes of the token. One or more.
Environmentlive or test.
LimitsOptional requests per minute for this trust, inside the organization limits.
Token lifetimeThe lifetime of an exchanged token: 60 to 86400 seconds. The default is 900.

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 none and every HS algorithm.
  • The iss equals the issuer of a trust exactly. The issuer publishes a discovery document at /.well-known/openid-configuration.
  • The aud is https://{slug}.cloudraker.run.
  • The exp and iat claims are present. exp - iat is 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.

curl -s -X POST "https://$CRK_SLUG.cloudraker.run/v2/oauth/token" \
--data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
--data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:jwt" \
--data-urlencode "subject_token=$OIDC_TOKEN"
{
"access_token": "crt_…",
"token_type": "Bearer",
"expires_in": 900,
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
"scope": "parse extract jobs:read"
}
ParameterRule
grant_typeToken exchange or urn:ietf:params:oauth:grant-type:jwt-bearer.
subject_tokenThe JWT, for token exchange.
subject_token_typeurn:ietf:params:oauth:token-type:jwt or urn:ietf:params:oauth:token-type:id_token.
assertionThe JWT, for jwt-bearer.
audience, resourceOptional. If you send one, it must be the tenant host.
scopeIgnored. The token gets the scopes of the trust.

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.

curl -s "https://$CRK_SLUG.cloudraker.run/v2/me" \
-H "Authorization: Bearer $OIDC_TOKEN"

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.

permissions:
id-token: write
steps:
- name: Parse a file with no stored key
env:
AUDIENCE: https://acme.cloudraker.run
run: |
ID_TOKEN=$(curl -sf -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
"$ACTIONS_ID_TOKEN_REQUEST_URL&audience=$AUDIENCE" | jq -r .value)
CRT=$(curl -sf -X POST "$AUDIENCE/v2/oauth/token" \
--data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
--data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:jwt" \
--data-urlencode "subject_token=$ID_TOKEN" | jq -r .access_token)
curl -sf -X POST "$AUDIENCE/v2/parse" \
-H "Authorization: Bearer $CRT" -H "Content-Type: application/json" \
-H "Prefer: wait=30" \
-d '{ "file": { "url": "https://www.irs.gov/pub/irs-pdf/fw9.pdf" } }'

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: identity must be agent, with an agent claim. It refuses user tokens.
  • It refuses tokens of branch preview runs. A token with a branch claim gets 401 invalid_token.
  • The token org must be the slug of the host, and iss must be the issuer of this organization.
  • The token scopes come from agent.yml, inside a fixed subset.
Allowed in agent.ymlRefused
The capability scopes, jobs:read, run, read and canceladmin, secrets, act_as, git, preview