JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants
Extracted elements (24)
Client authentication using a JWT is orthogonal to and separable from using a JWT as an authorization grant; they can be used in combination or separately. JWT authorization grants may be used with or without client authentication, and the supported client authentication types are policy decisions at the authorization server's discretion.
The JWT profile is intentionally similar, though not identical, to the SAML 2.0 profile for OAuth 2.0 (RFC 7522). Differences arise where JWT structure and semantics differ from SAML Assertions — for example, JWTs have no direct equivalent to SAML's <SubjectConfirmation> or <AuthnStatement> elements.
The process by which a client obtains the JWT prior to exchanging it with the authorization server is explicitly out of scope for this specification, allowing flexibility in how trust relationships and JWT issuance are managed in specific deployments.
Agreement between system entities on issuer/audience identifiers, token endpoint location, signing keys, one-time-use restrictions, maximum JWT lifetime, and subject/claim requirements must be established out of band. This specification does not define a mechanism for that exchange; profiles such as OpenID Connect Discovery may constrain or prescribe these values.
The 'RS256' algorithm from JSON Web Algorithms (RFC 7518) is a mandatory-to-implement JSON Web Signature algorithm for this profile. All conforming implementations must support RS256 for interoperability.
If a client authentication JWT is invalid, the authorization server MUST return an error response with the 'error' parameter set to 'invalid_client'. The server MAY include 'error_description' or 'error_uri' with additional detail.
If a JWT authorization grant is invalid or outside its valid time window, the authorization server MUST return an error response with the 'error' parameter set to 'invalid_grant'. The server MAY include 'error_description' or 'error_uri' with additional detail.
If client credentials are present in the request alongside a JWT authorization grant, the authorization server MUST validate those client credentials. Whether client authentication is required is a policy decision at the authorization server's discretion.
The authorization server MUST reject a JWT that is not valid in all respects per the JWT specification. The authorization server MUST validate the JWT according to all listed criteria before issuing an access token or relying on client authentication.
The JWT MAY contain a 'jti' (JWT ID) claim providing a unique token identifier. The authorization server MAY enforce replay protection by maintaining the set of used 'jti' values for the JWT's validity window based on the 'exp' claim.
The JWT MAY contain an 'nbf' (not before) claim; if present, the token MUST NOT be accepted for processing before that time. The JWT MAY also contain an 'iat' (issued at) claim; servers may reject JWTs with an 'iat' unreasonably far in the past.
The JWT MUST be digitally signed or have a Message Authentication Code (MAC) applied by the issuer. The authorization server MUST reject JWTs with an invalid signature or MAC.
The JWT MUST contain a 'sub' (subject) claim identifying the principal. For authorization grants the subject typically identifies the resource owner or delegate; for client authentication the subject MUST be the 'client_id' of the OAuth client.
The JWT MUST contain an 'aud' (audience) claim that identifies the authorization server as an intended audience. The authorization server MUST reject any JWT that does not contain its own identity as the intended audience; audience values MUST be compared using Simple String Comparison per RFC 3986 Section 6.2.1.
The JWT MUST contain an 'exp' (expiration time) claim limiting the window during which the JWT can be used. The authorization server MUST reject any JWT whose expiration time has passed, subject to allowable clock skew; the server MAY also reject JWTs with an 'exp' unreasonably far in the future.
The JWT MUST contain an 'iss' (issuer) claim with a unique identifier for the issuing entity. Compliant applications MUST compare issuer values using the Simple String Comparison method defined in RFC 3986 Section 6.2.1, absent an application profile specifying otherwise.
A JWT may contain privacy-sensitive information and should only be transmitted over encrypted channels such as TLS to prevent disclosure to unintended parties. Where it is desirable to prevent disclosure to the client itself, the JWT should be encrypted to the authorization server.
Deployments should determine the minimum amount of information necessary to complete the exchange and include only those claims in the JWT. The 'sub' (subject) claim may represent an anonymous or pseudonymous user rather than a directly identifying value.
To use a Bearer JWT as an authorization grant, the client sends a token request with grant_type set to 'urn:ietf:params:oauth:grant-type:jwt-bearer' and the JWT in the 'assertion' parameter. The 'scope' parameter may optionally be included; client authentication is optional.
To use a JWT Bearer Token for client authentication, the client sets 'client_assertion_type' to 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer' and places the JWT in 'client_assertion'. The 'client_assertion' parameter MUST NOT contain more than one JWT.
Registers the URN 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer' in the IANA OAuth URI registry (established by RFC 6755) as the client assertion type identifier for the JWT Bearer Token Profile for OAuth 2.0 Client Authentication.
Registers the URN 'urn:ietf:params:oauth:grant-type:jwt-bearer' in the IANA OAuth URI registry (established by RFC 6755) as the grant type identifier for the JWT Bearer Token Grant Type Profile for OAuth 2.0.
All security considerations from RFC 7521 (OAuth Assertion Framework), RFC 6749 (OAuth 2.0), and the JWT specification apply to this document and must be considered by implementors.
Replay protection for JWTs used as authorization grants or for client authentication is not mandated by this specification; it is an optional feature that implementations may employ at their discretion via the 'jti' claim mechanism.