Tokens, JWT, Claims & Endpoints

Token Types & Intended Consumers

Every token in the OAuth / OIDC ecosystem is minted for a specific consumer. Routing a token to the wrong consumer creates severe security vulnerabilities:

graph TD
    subgraph AuthServer["🔑 Authorization Server (IdP)"]
        TokenGen["Issue Token Pair"]
    end

    subgraph ClientApp["💻 Client Application (Relying Party)"]
        IDT["👤 Consumes ID Token
(Reads user profile, sub, email)"]
        RT["🔄 Stores Refresh Token
(HTTP-only cookie / Secure vault)"]
        AT_Send["📤 Forwards Access Token"]
    end

    subgraph APIGateway["🛡️ API Gateway / Resource Server"]
        JWKS["Verifies RS256 with JWKS"]
        RS["🗄️ Consumes Access Token
(Evaluates scopes, roles & RBAC)"]
    end

    TokenGen -->|"ID Token (Signed JWT)"| IDT
    TokenGen -->|"Refresh Token"| RT
    TokenGen -->|"Access Token (Bearer)"| AT_Send

    AT_Send -->|"Authorization: Bearer <Access Token>"| JWKS
    JWKS --> RS
    RT -.->|"POST /token (grant_type=refresh_token)"| TokenGen
          

The Evolution of Tokens: Opaque to JWE

How token standards evolved across the internet:

• Opaque Random Strings (Pre-2012): Tokens were completely opaque random strings (e.g. SlAV32hkKG). Every API call required the Resource Server to make a synchronous back-channel database lookup or introspection call to the Authorization Server to check validity and user identity.
• JSON Web Tokens (RFC 7519, 2015): Encoded self-contained identity and access claims into structured JSON. Allows APIs to validate expiration (exp) and scopes locally without database round-trips.
• JSON Web Signature (JWS - RFC 7515): Added cryptographic signatures (RS256, ES256) to ensure the token payload cannot be forged or tampered with.
• JSON Web Encryption (JWE - RFC 7516): Encrypts the payload for end-to-end confidentiality when passing sensitive PII across untrusted intermediaries.

Bearer Token Masquerade Risk & Mitigation

Scope vs Claim vs Response Type: The 3 Pillars

JWT Anatomy & Tamper-Proofing (RFC 7519)

A JSON Web Token consists of three base64url-encoded strings separated by periods: header.payload.signature

// 1. HEADER (Specifies Algorithm and Key ID)
{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "key_2026_01"
}

// 2. PAYLOAD (Identity and Access Claims)
{
  "iss": "https://authmatrix.local",
  "sub": "usr_alice_123",
  "aud": "https://api.authmatrix.local",
  "exp": 1755003600,
  "iat": 1755000000,
  "roles": ["Admin"],
  "permissions": ["read:reports", "write:users", "delete:audit"]
}

// 3. SIGNATURE (Asymmetric RSA SHA-256)
RS256(Base64URL(Header) + "." + Base64URL(Payload), PrivateKey)

Access Token Payload Anatomy (Okta & Enterprise Standard)

While OAuth 2.0 does not dictate access token formats, modern enterprise providers (Okta, Entra ID, Auth0) issue signed JWT access tokens packed with authorization metadata:

// Decoded Enterprise Access Token (JWT Payload)
{
  "ver": 1,
  "jti": "AT.upPJqU-Ism6Fwt5Fpl8AhNAdoUeuMsEgJ_VxJ3WJ1hk",
  "iss": "https://authmatrix.local/oauth2/default",
  "aud": "https://api.authmatrix.local",
  "sub": "alice@authmatrix.local",
  "uid": "00u2yulup4eWbOttd1t7",
  "iat": 1755000000,
  "exp": 1755003600,
  "cid": "0oa2yrbf35Vcbom491t7",
  "scp": ["openid", "profile", "email", "read:reports", "write:users"],
  "roles": ["Admin", "SecurityEngineer"]
}

Standard & Custom JWT Claims

1. Standard JWT Claims (RFC 7519 Section 4.1)

RS256 vs HS256 Cryptography

Dynamic JWKS Key Verification (RFC 7517)

APIs verify incoming tokens without calling the Authorization Server on every request. Instead, they dynamically download public keys from /.well-known/jwks.json:

GET /.well-known/jwks.json HTTP/1.1
Host: accounts.example.com

// Response
{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "alg": "RS256",
      "kid": "key_2026_01",
      "n": "u1WguZo5WOk5Y...",
      "e": "AQAB"
    }
  ]
}

Key Rotation: When an IdP rotates signing keys, it publishes the new key in the JWKS array. The API matches the JWT header's kid (Key ID) to the JWKS key without downtime.

The Four OAuth Endpoints

1. Token Introspection (RFC 7662)

Allows Resource Servers to validate opaque tokens or check real-time revocation status:

POST /introspect HTTP/1.1
Host: authorization-server.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=

token=2YotnFZFEjr1zCsicMWpAA

// Response
{
  "active": true,
  "scope": "read:reports write:users",
  "client_id": "client_app_123",
  "sub": "usr_alice_123",
  "exp": 1755003600
}

2. Token Revocation (RFC 7009)

Explicitly invalidates an active token upon user logout:

POST /revoke HTTP/1.1
Host: authorization-server.example.com
Content-Type: application/x-www-form-urlencoded

token=8xLOxBtZp8&token_type_hint=refresh_token

Web Access Management (WAM) Policies

Modern Zero Trust policy engines evaluate token claims and environmental signals in real time before granting access to sensitive business operations: