Stage 6 · L27

Understand bearer tokens, JWT claims and trusted verification

Core · original Session 6

A JWT is a signed claims container. Its readable encoded body is not encryption, and seeing a plausible sub string does not establish trust. The server validates the signature under an explicit HS256 allowlist and a fresh local secret before interpreting claims. The key is never accepted from the incoming token.

This revision requires issuer, audience, subject, issued-at, not-before, expiry, token_use and credential version. sub must parse as a UUID; cv must be an integer rather than a boolean or arbitrary string. Access, verification and reset tokens have distinct purposes. The source Session06 uses a different integer-identity example; the Equipment revision retains UUIDs and adds a current-version check deliberately.

An expired token, bad signature, wrong audience/issuer, missing required claim, malformed UUID, wrong purpose or incorrect version must fail closed. The native matrix signs deliberately altered fixture claims and verifies401; merely decoding a JWT without signature checks would make those tests succeed incorrectly. Do not paste a live token into a lesson, log or online decoder.

Tokens are short-lived, but revocation needs current state too. This course does not build a refresh-token service or session inventory. Verification/reset increments the stored credential version, and current_actor reloads active/version per request. Federated issuer discovery, JWKS rotation and refresh rotation are distinct optional concepts later; local HS256 is not advertised as OIDC.

The Authorization request header carries Bearer plus the access token. The API's401 challenge tells a caller that authentication is required. A browser preflight or signed token does not imply an authorized action. The next stage checks the current stored role and record ownership rather than trusting a role supplied by the caller.

Symmetric signing such as HS256 shares one secret between signer and verifier; any holder capable of verifying with that secret can also sign. Asymmetric signing uses a private signing key and a public verification key, allowing verifiers to avoid holding the private signer. The algorithm and key trust policy come from reviewed configuration. Do not accept an algorithm or arbitrary verification location merely because an incoming token names it.

JWT describes claims; JWS describes a signed payload format. The local compact JWT is represented as a JWS with protected header, payload and signature. Base64url decoding exposes text without establishing trust. JWK is a JSON representation of a key; JWKS is a set of such keys. A key identifier chooses among already trusted keys and is not authorization. This core actually implements HS256; asymmetric/JWK/JWKS are explained boundaries with no installed key-fetch endpoint.

An identity-provider ID token describes a sign-in to its intended client; it is not the API access credential required by this local endpoint. Different purpose and audience are rejection boundaries even when a token is otherwise signed. Later optional protocol lessons explain the full provider flow; this core exercise uses only the local access-token verifier.

JWT: a claims representation
JWS: a signed payload representation (the local compact JWT is a JWS)
HS256: one shared secret signs and verifies
Asymmetric: private key signs; public key verifies
JWK: a structured key; JWKS: a set of keys
Decode ≠ verify signature + issuer + audience + purpose + time.

python run_checks.py --stage 06 --role starter --walkthrough login

The local verifier accepts only its configured HS256 key/algorithm and required access claims, not a token-selected algorithm/key/issuer. Tamper, wrong issuer/audience/purpose and expired/missing claims reject. Asymmetric signing separates private signer and public verifier, but no asymmetric/JWKS endpoint is installed. A JWK describes a key, not trusted authorization; an ID token is not this API access token.