What Is a JWT Claim? Explained

A JWT claim is a single statement carried in a tokens payload, such as who issued it, who it is about, or when it expires.

A JWT is really just a signed bag of claims, and the claims are where the meaning lives. Each claim is a key-value statement about the subject of the token. Standard claims describe identity and validity; custom claims carry whatever an application needs. In CI, the claims inside an OIDC token are exactly what cloud providers inspect to decide whether to grant access.

What a JWT claim is

A claim is one entry in the JWTs JSON payload - a key and its value asserting something about the token or its subject. The collection of claims, signed by the issuer, is what a verifier reads to make authorization decisions. Claims are readable by anyone since the JWT is only signed, not encrypted.

Registered (standard) claims

Several claims are standardized: the issuer (who minted the token), the subject (who it identifies), the audience (who it is for), the expiry time, and the issued-at time. Verifiers routinely check that the token has not expired and that the audience matches them before trusting it.

Custom claims

Beyond the standard set, an issuer can add application-specific claims. CI OIDC tokens, for example, carry claims describing the repository, the branch or tag, the workflow, and the environment. These let a relying party scope trust to a very specific pipeline rather than the whole account.

JWT claims in CI

When a workflow requests an OIDC token, the cloud provider checks its claims against a trust policy: only tokens whose subject claim matches your repo and branch are allowed to assume a role. Getting that subject-claim condition right is the crux of secure, keyless cloud access from CI.

Scoping access by a JWT claim

# A trust policy condition on the OIDC subject claim
# "sub": "repo:acme/app:ref:refs/heads/main"
# AWS condition (conceptual):
#   StringEquals:
#     token.actions.githubusercontent.com:sub: repo:acme/app:ref:refs/heads/main

Latchkey note

The OIDC token a workflow gets on a Latchkey runner carries the same standard repo, branch, and environment claims, so your cloud trust policies that match on the subject claim keep working unchanged.

Key takeaways

A JWT claim is a single key-value statement in the tokens payload about the token or its subject.
Standard claims cover issuer, subject, audience, and expiry; custom claims carry application data.
CI OIDC tokens carry repo and branch claims, and cloud trust policies scope access by matching them.