urn:ietf:params:oauth:client-assertion-type:jwt-bearer
Registry Context
URN used as the `client_assertion_type` value when a client authenticates to an OAuth token endpoint using a JWT.
Technical Summary
OAuth URI registry entry identifying the JWT bearer profile for OAuth 2.0 client authentication. RFC 7523 specifies this exact URN as the `client_assertion_type` value and a single JWT as the `client_assertion` value.
When Used
When a client uses a JWT assertion as its credential at an OAuth 2.0 token endpoint.
Normative Requirements
Clients
RFC 7523 - Section 2.2
include more than one JWT in the `client_assertion` parameter.
Condition: when using a JWT bearer token for client authentication
It MUST NOT contain more than one JWT.
RFC 7521 - Section 4.2
ensure that `client_id` identifies the same client as the client assertion.
Condition: if `client_id` is present
If present, the value of the "client_id" parameter MUST identify the same client as is identified by the client assertion.
RFC 7523 - Section 3
include an `iss` claim containing a unique identifier for the JWT issuer.
The JWT MUST contain an "iss" (issuer) claim that contains a unique identifier for the entity that issued the JWT.
RFC 7523 - Section 3
include a `sub` claim identifying the JWT subject.
The JWT MUST contain a "sub" (subject) claim identifying the principal that is the subject of the JWT.
RFC 7523 - Section 3
set the `sub` claim to the OAuth client's `client_id`.
Condition: when the JWT is used for client authentication
For client authentication, the subject MUST be the "client_id" of the OAuth client.
RFC 7523 - Section 3
include an `aud` claim identifying the authorization server as an intended audience.
The JWT MUST contain an "aud" (audience) claim containing a value that identifies the authorization server as an intended audience.
RFC 7523 - Section 3
include an `exp` claim limiting the JWT's usable time window.
The JWT MUST contain an "exp" (expiration time) claim that limits the time window during which the JWT can be used.
RFC 7523 - Section 3
digitally sign the JWT or apply a MAC.
The JWT MUST be digitally signed or have a Message Authentication Code (MAC) applied by the issuer.
RFC 7521 - Section 4.2
include the `client_assertion_type` parameter.
Condition: when using an assertion as a client credential
client_assertion_type REQUIRED.
RFC 7521 - Section 4.2
include the `client_assertion` parameter.
Condition: when using an assertion as a client credential
client_assertion REQUIRED.
RFC 7523 - Section 3
use the authorization server's token endpoint URL as an `aud` value.
The token endpoint URL of the authorization server MAY be used as a value for an "aud" element.
RFC 7523 - Section 3
include an `nbf` claim.
The JWT MAY contain an "nbf" (not before) claim.
RFC 7523 - Section 3
include an `iat` claim.
The JWT MAY contain an "iat" (issued at) claim.
RFC 7523 - Section 3
include a `jti` claim providing a unique identifier for the JWT.
The JWT MAY contain a "jti" (JWT ID) claim that provides a unique identifier for the token.
RFC 7523 - Section 3
include other claims in the JWT.
The JWT MAY contain other claims.
RFC 7521 - Section 4.2
include the `client_id` parameter.
Condition: when using an assertion as a client credential
client_id OPTIONAL.
Authorization servers
RFC 7523 - Section 3
accept the JWT for processing before the time identified by its `nbf` claim.
Condition: when an `nbf` claim is present
the time before which the token MUST NOT be accepted for processing.
RFC 7523 - Section 3
validate the JWT according to the criteria in RFC 7523 Section 3.
Condition: when relying on a JWT for client authentication
the authorization server MUST validate the JWT according to the criteria below.
RFC 7523 - Section 3
reject a JWT that does not identify it as an intended audience.
The authorization server MUST reject any JWT that does not contain its own identity as the intended audience.
RFC 7523 - Section 3
reject a JWT whose expiration time has passed, subject to allowable clock skew.
The authorization server MUST reject any JWT with an expiration time that has passed, subject to allowable clock skew between systems.
RFC 7523 - Section 3
reject JWTs with an invalid signature or MAC.
The authorization server MUST reject JWTs with an invalid signature or MAC.
RFC 7523 - Section 3
reject a JWT that is otherwise invalid under the JWT specification.
The authorization server MUST reject a JWT that is not valid in all other respects per "JSON Web Token (JWT)".
RFC 7523 - Section 3.2
use the `invalid_client` error code.
Condition: if the client JWT is invalid
The value of the "error" parameter MUST be the "invalid_client" error code.
RFC 7523 - Section 3
prevent replay by retaining used `jti` values for the JWT validity period.
Condition: when a `jti` claim is used
The authorization server MAY ensure that JWTs are not replayed by maintaining the set of used "jti" values.
RFC 7523 - Section 3.2
include `error_description` or `error_uri` information explaining why the JWT was invalid.
Condition: if the client JWT is invalid
The authorization server MAY include additional information regarding the reasons the JWT was considered invalid.
compliant application
RFC 7523 - Section 3
compare issuer values using RFC 3986 simple string comparison.
Condition: in the absence of an application profile specifying otherwise
compliant applications MUST compare issuer values using the Simple String Comparison method defined in Section 6.2.1 of RFC 3986.
RFC 7523 - Section 3
compare audience values using RFC 3986 simple string comparison.
Condition: in the absence of an application profile specifying otherwise
compliant applications MUST compare the audience values using the Simple String Comparison method defined in Section 6.2.1 of RFC 3986.
Validation Guidance
Require `client_assertion_type` and verify that its value is the absolute URI `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`.
Require exactly one JWT in `client_assertion`.
If `client_id` is supplied, verify that it identifies the same client as the assertion.
Verify required `iss`, `sub`, `aud`, and `exp` claims, including that `sub` equals the client's `client_id` and `aud` identifies the authorization server.
Reject expired JWTs and JWTs used before an applicable `nbf` time, allowing configured clock skew where appropriate.
Verify the JWT signature or MAC and all other JWT validity requirements.
Return `invalid_client` when the client JWT is invalid.
Consider replay detection using `jti`; RFC 7523 permits but does not require this protection.
Security Notes
RFC 7523 - Section 6
RFC 7523 does not mandate replay protection for JWT authorization grants or client authentication; implementations may provide it at their discretion.
Reference
Details
- Entry Id
urn:ietf:params:oauth:client-assertion-type:jwt-bearer- Urn
urn:ietf:params:oauth:client-assertion-type:jwt-bearer- Common Name
JWT Bearer Token Profile for OAuth 2.0 Client Authentication- Change Controller
IESG- Reference
RFC7523, RFC-ietf-oauth-rfc7523bis-11