JWT Structure & Claims

JWT Structure and Claims

In OAuth 2.0 and OpenID Connect (OIDC), JSON Web Tokens (JWTs) are used to securely transmit claims between parties. A JWT is a compact, URL-safe string composed of three base64-encoded parts: the header, payload (claims), and signature. Understanding their structure and the role of standard claims is critical for validating tokens in Zero Trust environments.

---

JWT Structure

A JWT is divided into three segments, separated by dots (.):

1. Header: Contains metadata about the token type and the cryptographic algorithm used (e.g., {"alg": "RS256", "typ": "JWT"}).
2. Payload (Claims): A JSON object containing the actual data (claims) about the subject, issuer, expiration, and other attributes.
3. Signature: A cryptographic hash of the header and payload, signed with a secret key or private key. This ensures token integrity and authenticity.

Example JWT Structure

[header].[payload].[signature]

Diagram:

+----------------+        +----------------+        +----------------+
|   Header       |        |   Payload      |        |  Signature     |
| (metadata)     |        | (claims)       |        | (cryptographic)|
+----------------+        +----------------+        +----------------+

---

Standard Claims in OpenID Connect

OpenID Connect extends OAuth 2.0 by adding identity-related claims to the JWT payload. Key standard claims include:

Claim	Description	Example
sub	Unique identifier for the user (subject).	"sub": "1234567890"
iss	Issuer of the token (e.g., the OIDC provider).	"iss": "https://idp.example.com"
exp	Expiration time (in seconds since epoch).	"exp": 1698765600
iat	Issued-at time (when the token was issued).	"iat": 1698762000
aud	Audience (intended recipient of the token).	"aud": "https://api.example.com"
nonce	Random value used to prevent replay attacks.	"nonce": "random123"

These claims are critical for validating the token's authenticity, ensuring it is issued by a trusted source, and verifying its validity within the intended timeframe.

---

Validation Considerations

When validating a JWT in an OIDC flow, the following steps are essential:

1. Verify the Signature: Ensure the signature matches the header and payload using the issuer's public key (for asymmetric algorithms like RS256).
2. Check the Issuer (iss): Confirm the token was issued by a trusted identity provider (IdP).
3. Validate Expiration (exp) and Not Before (nbf): Ensure the token is not expired or issued in the past.
4. Audience Match (aud): Verify the token is intended for the requesting service.
5. Additional Claims: Validate custom claims (e.g., roles, scopes) based on your application's requirements.

Example: Decoding a JWT with Python

import jwt

token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiaXNzIjoiaHR0cHM6Ly9pZCI..."
try:
    decoded = jwt.decode(token, "secret_key", algorithms=["HS256"])
    print(decoded)
except jwt.ExpiredSignatureError:
    print("Token has expired")

CLI Example: Using jwt.io

1. Paste the JWT into https://jwt.io/.
2. The tool decodes the header, payload, and signature, revealing claims like sub, iss, and exp.

---

Key Takeaways

• JWTs are structured into header, payload (claims), and signature, ensuring secure transmission of identity data.
• Standard claims like sub, iss, and `exp are foundational for validating tokens in OIDC.
• Validation requires checking the signature, issuer, expiration, audience, and other claims to enforce Zero Trust principles.
• Security depends on using strong cryptographic algorithms and verifying all claims against trusted sources.