JSON Web Token (JWT)
updated by
Extracted elements (30)
JWTs were designed as a simpler, more compact alternative to SAML Assertions that fits in HTTP headers and query parameters. They use JSON encoding and a simpler token model rather than XML/XML DSIG, trading SAML's expressivity for compactness and ease of implementation.
Registered Claim Names are intentionally kept short (recommended not to exceed 8 characters) because a core goal of JWTs is compact representation suitable for HTTP Authorization headers and URI query parameters.
The "typ" and "cty" header values use case-insensitive comparison (per media type rules), unlike all other JWT string comparisons which are case-sensitive. However, "JWT" is RECOMMENDED to always be spelled in uppercase for compatibility with legacy implementations.
Claim Names within a JWT Claims Set MUST be unique. JWT parsers MUST either reject JWTs with duplicate Claim Names or use a JSON parser that returns only the lexically last duplicate member name.
Claims not understood by implementations MUST be ignored in the absence of application-specific requirements to process them.
Even if a JWT can be successfully validated, unless the algorithms used are acceptable to the application, the application SHOULD reject the JWT, since algorithm acceptability is an application-level decision.
If the "aud" claim is present and the principal processing the JWT does not identify itself with a value in the "aud" claim, then the JWT MUST be rejected.
JSON string comparisons in JWT processing (member names and values) MUST use the RFC 7159 Section 8.3 rules (Unicode code-point-by-code-point equality), except for "typ" and "cty" member values which use case-insensitive comparison.
Of the JWA signature and MAC algorithms, only HMAC SHA-256 ("HS256") and "none" MUST be implemented by conforming JWT implementations. RS256 and ES256 are RECOMMENDED. Encrypted JWT support is OPTIONAL; if provided, RSA1_5 with 2048-bit keys, A128KW, A256KW, A128CBC-HS256, and A256CBC-HS512 MUST be implemented.
The "cty" (content type) Header Parameter is NOT RECOMMENDED when nested signing or encryption is not employed. When nested signing or encryption IS employed, "cty" MUST be present and its value MUST be "JWT" to signal that a Nested JWT is carried.
When claims are replicated as Header Parameters in a JWE, the application receiving them SHOULD verify that their values are identical to those in the JWT Claims Set, unless the application defines other processing rules.
A JWT may contain privacy-sensitive information; when it does, measures MUST be taken to prevent disclosure to unintended parties. Options include using an encrypted JWT with recipient authentication, transmitting over TLS, or omitting privacy-sensitive information from the JWT entirely.
An Unsecured JWT is a JWS using the "alg" Header Parameter value "none" with the empty string as its JWS Signature value, used when JWT content is secured by external means rather than an embedded signature or encryption.
The "aud" (audience) claim identifies the recipients the JWT is intended for. Each principal processing the JWT MUST identify itself in the audience claim or reject the JWT. The value is an array of case-sensitive StringOrURI values, or a single StringOrURI when there is one audience. Use is OPTIONAL.
The "exp" (expiration time) claim identifies the time on or after which the JWT MUST NOT be accepted. Its value MUST be a NumericDate (seconds since 1970-01-01T00:00:00Z UTC). Implementers MAY allow a small clock-skew leeway. Use is OPTIONAL.
The "iat" (issued at) claim identifies the time at which the JWT was issued and can be used to determine the JWT's age. Its value MUST be a NumericDate. Use is OPTIONAL.
The "iss" (issuer) claim identifies the principal that issued the JWT. Its value is a case-sensitive StringOrURI. Use is OPTIONAL.
The "jti" (JWT ID) claim provides a unique identifier for the JWT to prevent replay attacks. The value MUST be assigned such that accidental collision with another JWT is negligible; if multiple issuers are used, uniqueness across issuers MUST be ensured. Its value is a case-sensitive string. Use is OPTIONAL.
The JWT Claims Set is a JSON object whose members are the claims conveyed by the JWT. Claim Names are strings and Claim Values can be any JSON value. The Claims Set serves as the JWS Payload or JWE plaintext.
The "nbf" (not before) claim identifies the time before which the JWT MUST NOT be accepted. Its value MUST be a NumericDate. Implementers MAY allow a small clock-skew leeway. Use is OPTIONAL.
The "sub" (subject) claim identifies the principal that is the subject of the JWT. The subject value MUST be locally unique within the issuer context or globally unique. Its value is a case-sensitive StringOrURI. Use is OPTIONAL.
The "typ" (type) Header Parameter declares the media type of the complete JWT, intended to disambiguate among different object types in an application data structure. It is RECOMMENDED that its value be "JWT" spelled in uppercase for compatibility with legacy implementations. Processing is performed by the application, not the JWT implementation.
This document establishes the IANA "JSON Web Token Claims" registry for JWT Claim Names, with Specification Required registration policy and a three-week review period on [email protected]. Initial entries are: "iss", "sub", "aud", "exp", "nbf", "iat", "jti".
This document registers "iss", "sub", and "aud" as Header Parameter Names in the IANA "JSON Web Signature and Encryption Header Parameters" registry, for use as unencrypted replicas of these claims in encrypted JWTs.
This document registers the "application/jwt" media type in the IANA Media Types registry. JWTs are encoded as a series of base64url-encoded values separated by period ('.') characters.
This document registers the URN "urn:ietf:params:oauth:token-type:jwt" in the IANA OAuth URI registry (RFC 6755) to indicate that content is a JWT when content types are declared via URIs.
The contents of a JWT cannot be relied upon in a trust decision unless cryptographically secured and bound to the necessary context. The key(s) used to sign and/or encrypt the JWT will typically need to be verifiably under the control of the party identified as the issuer.
When both signing and encryption are necessary in a Nested JWT, producers should sign first and then encrypt the result (encrypting the signature). This prevents signature-stripping attacks, provides signer privacy, and avoids jurisdictional issues with signatures over encrypted text.
JWT validation proceeds through ten mandatory steps: verify presence of at least one period; extract and base64url-decode the JOSE Header; verify it is a valid UTF-8 JSON object; verify supported parameters; determine JWS or JWE; validate per JWS/JWE spec; handle nested JWT via "cty":"JWT" recursion; decode the Message; verify it is a valid UTF-8 JSON object as the JWT Claims Set. Any step failure means the JWT MUST be rejected.
A JWT is represented as a sequence of URL-safe parts separated by period ('.') characters, where each part contains a base64url-encoded value. The number of parts depends on whether a JWS Compact Serialization (3 parts) or JWE Compact Serialization (5 parts) is used.