Identity: OAuth 2.1, OIDC & JWT

BoxOffice launches its mobile app. Someone proposes the obvious design: a login screen in the app, the app sends e-mail and password to POST /login, keeps the password in the phone "so the user does not have to type it again", and sends it on every request. Within a week the product team also wants "Sign in with Google", a web checkout, a nightly reconciliation job in order that calls inventory with no user behind it, and an AI assistant that acts on the user's behalf. A homemade login cannot express any of this safely. This page is about the standards that can: sessions and tokens, JWT, OAuth 2.1 and OpenID Connect, and the authorization models that decide what an authenticated caller may do.

Authentication vs authorization

Two different questions are asked on every request:

Vocabulary used below: a principal is the authenticated entity (a user or a workload); a credential is what it presents to prove it; a token is what it receives after authenticating and presents instead of the credential; a claim is a statement inside a token ("sub": "acc-42"). A bearer token works for whoever holds it, like cash.

Sessions vs tokens

After login, the server must remember the user on the next request. Two families of designs:

flowchart LR
    subgraph s ["Server-side session"]
        B1(["Browser"]) -->|"Cookie: sid=9f2c…"| A1["app"]
        A1 -->|"GET session:9f2c"| R[("Redis")]
    end
    subgraph t ["Self-contained token (JWT)"]
        B2(["App"]) -->|"Authorization: Bearer eyJ…"| A2["gateway"]
        A2 -->|"verify signature locally<br/>(cached public key)"| A2
    end

Neither is "the modern one". Large systems combine them: a short-lived JWT (minutes) for APIs and a revocable refresh token or session stored server-side. Revocation latency then equals the access-token lifetime — a number you choose.

JSON Web Token (JWT)

A JWT (RFC 7519) is three Base64URL-encoded parts separated by dots: header.payload.signature. Decoded, a BoxOffice access token looks like this:

header:  { "alg": "RS256", "typ": "at+jwt", "kid": "2026-10-a" }
payload: {
  "iss": "https://auth.boxoffice.com/realms/boxoffice",
  "sub": "acc-42",
  "aud": "boxoffice-api",
  "client_id": "boxoffice-mobile",
  "scope": "orders:read orders:write",
  "iat": 1792310400,
  "exp": 1792311300,
  "jti": "5b0e7c1a-6d1f-4c1e-9a43-0d6c2f6c9e10"
}
signature: RSASSA-PKCS1-v1_5( SHA-256( base64url(header) + "." + base64url(payload) ), private key )

The payload is encoded, not encrypted — anyone can read it. Never put secrets or personal data there you would not show the user.

With asymmetric algorithms (RS256, ES256, EdDSA) the identity provider signs with a private key that never leaves it, and anyone verifies with the public key, published as a JWKS (JSON Web Key Set) at the provider's jwks_uri. With symmetric HMAC (HS256), every verifier holds the same secret and can therefore also forge tokens — acceptable only when issuer and verifier are the same service.

Validation checklist

RFC 8725 (JWT Best Current Practices) is the reference¹. A resource server must check:

public TokenOut issue(User user) {
    var now = Instant.now();
    var claims = new JWTClaimsSet.Builder()
            .issuer(issuer)
            .audience(audience)
            .subject(user.getId().toString())
            .claim("email", user.getEmail())
            .claim("name", user.getName())
            .claim("scope", user.getRole() == Role.ADMIN ? "user admin" : "user")
            .issueTime(Date.from(now))
            .expirationTime(Date.from(now.plus(ttl)))
            .jwtID(UUID.randomUUID().toString())
            .build();
    var header = new JWSHeader.Builder(JWSAlgorithm.RS256)
            .keyID(key.getKeyID())
            .type(JOSEObjectType.JWT)
            .build();
    try {
        var jwt = new SignedJWT(header, claims);
        jwt.sign(new RSASSASigner(key));
        return new TokenOut(jwt.serialize(), "Bearer", ttl.toSeconds());
    } catch (JOSEException e) {
        throw new IllegalStateException("could not sign the token", e);
    }
}

OAuth 2.1

OAuth is a framework for delegated authorization: a client application obtains a limited, short-lived access token to call an API on behalf of a user — or on its own behalf — without ever handling the user's password. The user authenticates only at the authorization server².

Clients are confidential (run on a server, can keep a secret: the BFF, a batch job) or public (run on the user's device, cannot keep a secret: the mobile app, a single-page app — anyone can decompile or read them).

What OAuth 2.1 changes

OAuth 2.0 (RFC 6749, 2012) accumulated a decade of security lessons in separate documents. OAuth 2.1 — an IETF draft that consolidates them, together with the Security Best Current Practice (RFC 9700) — is what new systems should follow³⁴:

Choosing the grant

flowchart TD
    q1{"Is a user<br/>involved?"} -->|no| cc["Client Credentials<br/>(reconciliation job)"]
    q1 -->|yes| q2{"Can the device<br/>open a browser?"}
    q2 -->|yes| pkce["Authorization Code + PKCE<br/>(mobile app, web BFF)"]
    q2 -->|no| dev["Device Authorization<br/>(smart TV, CLI)"]
    pkce --> q3{"A service must call another<br/>on the user's behalf?"}
    q3 -->|yes| tx["Token Exchange<br/>(assistant → order)"]

Authorization Code + PKCE for the mobile app

The app never sees the password. It opens the system browser (not an embedded WebView, where the app could read keystrokes — RFC 8252⁵) at the authorization server, the user logs in there (with MFA or a passkey), and the app receives a short-lived, single-use authorization code through a redirect. The app then exchanges the code for tokens in a direct back-channel request.

PKCE (Proof Key for Code Exchange, "pixy", RFC 7636⁶) binds the code to the app instance that started the flow:

1. The app generates a random code_verifier (43–128 characters) and keeps it in memory.
2. It sends only code_challenge = BASE64URL(SHA-256(code_verifier)) in the authorization request.
3. At the token exchange it sends the original code_verifier; the server hashes and compares.

A malicious app that registered the same redirect scheme and intercepts the code does not have the verifier, so the code is useless.

sequenceDiagram
    autonumber
    actor Ana
    participant App as BoxOffice app
    participant Br as System browser
    participant AS as auth (Keycloak)
    participant GW as API gateway
    participant O as order
    Ana->>App: tap "Log in"
    App->>App: create state, nonce, code_verifier, code_challenge (S256)
    App->>Br: open /authorize?response_type=code&client_id=boxoffice-mobile&scope=openid orders:write&code_challenge&state&nonce
    Br->>AS: GET /authorize
    AS->>Ana: login page (password + MFA, or passkey)
    Ana->>AS: credentials
    AS-->>Br: 302 https://app.boxoffice.com/cb?code=XYZ&state
    Br-->>App: redirect delivered to the app (claimed HTTPS link)
    App->>App: check state
    App->>AS: POST /token {code, code_verifier, redirect_uri}
    AS->>AS: SHA-256(code_verifier) == code_challenge?
    AS-->>App: access_token (15 min) + refresh_token (rotating) + id_token
    App->>GW: POST /orders  Authorization: Bearer access_token
    GW->>GW: verify signature (cached JWKS), iss, aud, exp, scope
    GW->>O: POST /orders + X-Account-Id: acc-42
    O-->>App: 201 Created

The state parameter prevents an attacker from injecting their code into Ana's session (CSRF on the callback); the nonce is echoed inside the ID token and prevents replaying an old one.

# 64 random URL-safe characters
verifier=$(openssl rand -base64 48 | tr -d '=+/\n' | cut -c1-64)
# BASE64URL(SHA-256(verifier)), without '=' padding
challenge=$(printf '%s' "$verifier" | openssl dgst -sha256 -binary \
            | openssl base64 | tr '+/' '-_' | tr -d '=')
echo "verifier=$verifier"; echo "challenge=$challenge"

Where the mobile app keeps tokens. The access token lives in memory; the refresh token in the platform's secure storage (iOS Keychain, Android Keystore-backed storage). The authorization server rotates the refresh token on every use: if a stolen copy and the legitimate app both try to use the same one, the server detects the reuse and revokes the whole family.

OpenID Connect: who is the user?

OAuth answers "may this client call this API?". It deliberately does not tell the client who the user is — the access token is addressed to the API. OpenID Connect (OIDC) adds an identity layer on top of OAuth⁷:

• the openid scope in the authorization request;
• the ID token — a JWT addressed to the client (aud = its client_id) with sub, iss, exp, nonce, auth_time and, with the profile/email scopes, name and e-mail;
• the UserInfo endpoint for more profile claims;
• discovery at /.well-known/openid-configuration, which lists the endpoints and the jwks_uri, so clients and resource servers bootstrap from the issuer URL alone.

Web checkout: OIDC through a Backend-for-Frontend

For the browser, the current recommendation is to keep no tokens in JavaScript at all. A BFF (Backend for Frontend) is a confidential client on the server: it runs the OIDC flow, keeps the tokens, and gives the browser only an HttpOnly, Secure, SameSite session cookie⁸.

sequenceDiagram
    autonumber
    actor Ana
    participant Br as Browser (checkout SPA)
    participant BFF as web BFF (confidential client)
    participant AS as auth (OIDC provider)
    participant GW as API gateway
    Ana->>Br: click "Log in"
    Br->>BFF: GET /login
    BFF-->>Br: 302 to AS /authorize (code + PKCE, scope openid, nonce)
    Br->>AS: login (passkey)
    AS-->>Br: 302 to BFF /callback?code&state
    Br->>BFF: GET /callback?code&state
    BFF->>AS: POST /token {code, code_verifier, client secret or private_key_jwt}
    AS-->>BFF: id_token + access_token + refresh_token
    BFF->>BFF: validate id_token (sig, iss, aud, exp, nonce), store tokens server-side
    BFF-->>Br: Set-Cookie: session=… HttpOnly Secure SameSite=Lax
    Br->>BFF: GET /api/orders (cookie)
    BFF->>GW: GET /orders  Bearer access_token
    GW-->>BFF: 200 orders
    BFF-->>Br: 200 orders

Machines and delegation

Client Credentials: the reconciliation job

When no user is involved, the client authenticates as itself and receives a token that represents the service. The order reconciliation job asks for exactly the scope it needs:

curl -s -X POST https://auth.boxoffice.com/realms/boxoffice/protocol/openid-connect/token \
  -d grant_type=client_credentials \
  -d client_id=order-reconciler \
  -d client_secret="$ORDER_RECONCILER_SECRET" \
  -d scope=inventory:read

Better than a client secret: authenticate the client with a signed JWT (private_key_jwt) or with its workload identity (mTLS certificate or the Kubernetes service-account token) — no shared secret to leak (Zero Trust).

Token Exchange: the assistant acting for the user

The AI assistant must call order on behalf of Ana, with less power than Ana's own token. Token Exchange (RFC 8693) lets a service trade the token it received for a new one with a different audience and narrower scope (aud=order, scope=orders:read), keeping sub=acc-42 and recording the actor (act: assistant). The audit log then shows "assistant, acting for acc-42, read order 1042".

Sender-constrained tokens

A bearer token works for anyone who steals it. Sender-constrained tokens are bound to a key the legitimate client holds: with DPoP (RFC 9449) the client signs a small proof for every request with a private key on the device; with mTLS-bound tokens (RFC 8705) the token is tied to the client certificate. A stolen token alone is then useless. Financial-grade APIs require them; for BoxOffice they are worth it on payment endpoints.

Passkeys

Passkeys (WebAuthn/FIDO2) replace passwords with a key pair per site, kept on the device and unlocked with biometrics. The private key never leaves the device and the signature is bound to the site's origin, so they resist phishing. They change how the user authenticates at the authorization server; the OAuth/OIDC flows after it stay the same.

Validating tokens at the gateway

The gateway is the first enforcement point: it rejects requests without a valid token and forwards a trusted identity downstream (see Edge — API gateway).

With Spring Security (also in Spring Cloud Gateway), local validation is configuration:

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://auth.boxoffice.com/realms/boxoffice  # discovers jwks_uri, checks iss
          audiences: boxoffice-api                                 # rejects tokens for other APIs

/** Signature from the JWKS of auth, plus expiry, issuer and audience checks. */
@Bean
ReactiveJwtDecoder jwtDecoder(@Value("${spring.security.oauth2.resourceserver.jwt.jwk-set-uri}") String jwksUri,
                              @Value("${jwt.issuer}") String issuer,
                              @Value("${jwt.audience}") String audience) {
    var decoder = NimbusReactiveJwtDecoder.withJwkSetUri(jwksUri).build();
    decoder.setJwtValidator(new DelegatingOAuth2TokenValidator<>(
            JwtValidators.createDefaultWithIssuer(issuer),     // exp, nbf, iss
            new JwtClaimValidator<List<String>>("aud", aud -> aud != null && aud.contains(audience))));
    return decoder;
}

@Override
public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
    var cleaned = exchange.mutate()
            .request(r -> r.headers(h -> {
                h.remove("X-User-Id");
                h.remove("X-User-Email");
                h.remove("X-User-Scope");
            }))
            .build();
    return ReactiveSecurityContextHolder.getContext()
            .map(SecurityContext::getAuthentication)
            .filter(JwtAuthenticationToken.class::isInstance)
            .cast(JwtAuthenticationToken.class)
            .map(auth -> cleaned.mutate()
                    .request(r -> r.headers(h -> {
                        var jwt = auth.getToken();
                        h.set("X-User-Id", jwt.getSubject());
                        h.set("X-User-Email", jwt.getClaimAsString("email"));
                        h.set("X-User-Scope", jwt.getClaimAsString("scope"));
                    }))
                    .build())
            .defaultIfEmpty(cleaned)          // anonymous request on an open route
            .flatMap(chain::filter);
}

Authorization models

Authentication produced an identity. Now: may this identity do this action on this object?

OAuth scopes are not a replacement: a scope limits what the client may do (orders:read), not which objects the user may touch. The ownership check — the fix for OWASP API1: BOLA — always runs in the service that owns the data⁹:

@GetMapping("/orders/{id}")
@PreAuthorize("hasAuthority('SCOPE_orders:read')")
public OrderOut get(@PathVariable UUID id, @AuthenticationPrincipal Jwt jwt) {
    Order order = repository.findById(id)
        .filter(o -> o.getAccountId().equals(jwt.getSubject()))  // ownership (BOLA)
        .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND));
    return OrderOut.from(order);                                 // explicit DTO (BOPLA)
}

package boxoffice.orders

import rego.v1

default allow := false

# owners can read their own orders
allow if {
    input.action == "read"
    input.resource.owner_id == input.user.sub
}

# support staff can read any order, never modify it
allow if {
    input.action == "read"
    "support" in input.user.roles
}

permit (
  principal,
  action == Action::"ReadOrder",
  resource
)
when { resource.owner == principal };

permit (
  principal in Role::"support",
  action == Action::"ReadOrder",
  resource
);

Policy engines (OPA, Cedar, OpenFGA) move the rules out of the code into a reviewable, testable artifact that several services share. The service still asks the question for every object.

How it connects

flowchart LR
    AS["auth: OIDC provider<br/>(authorization server)"] --> PKCE["Authorization Code + PKCE<br/>mobile app, web BFF"]
    AS --> CC["Client Credentials<br/>reconciliation job"]
    AS --> TX["Token Exchange<br/>assistant → order"]
    PKCE --> JWT["short-lived JWT access token<br/>+ rotating refresh token"]
    PKCE --> SESS["BFF session cookie<br/>shared store → Caching"]
    JWT --> GW["gateway validates via JWKS<br/>iss, aud, exp → Edge"]
    GW --> SVC["each service checks ownership<br/>RBAC / ABAC / ReBAC"]
    SVC --> BOLA["fixes OWASP API1 (BOLA)"]
    CC --> WI["workload identity<br/>→ Zero Trust"]
    TX --> AI["agents acting for users<br/>→ AI systems"]

Palette components: auth · apigw (the first enforcement point) · client · mobile · cache (server-side sessions) · orchestrator (the assistant acting on the user's behalf). Scenarios: rate-limiter, flash-sale, ai-assistant. Continues in: Edge — API gateway, Zero Trust, Caching — Redis, AI systems — agents, Hands-on 4 — Gateway & identity.

Key takeaways