oauth2.dev

urn:ietf:params:oauth:client-assertion-type:jwt-bearer

IESG

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

MUST NOT
1
  1. 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.

MUST
7
  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. 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.

REQUIRED
2
  1. RFC 7521 - Section 4.2

    include the `client_assertion_type` parameter.

    Condition: when using an assertion as a client credential

    client_assertion_type REQUIRED.

  2. RFC 7521 - Section 4.2

    include the `client_assertion` parameter.

    Condition: when using an assertion as a client credential

    client_assertion REQUIRED.

MAY
5
  1. 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.

  2. RFC 7523 - Section 3

    include an `nbf` claim.

    The JWT MAY contain an "nbf" (not before) claim.

  3. RFC 7523 - Section 3

    include an `iat` claim.

    The JWT MAY contain an "iat" (issued at) claim.

  4. 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.

  5. RFC 7523 - Section 3

    include other claims in the JWT.

    The JWT MAY contain other claims.

OPTIONAL
1
  1. RFC 7521 - Section 4.2

    include the `client_id` parameter.

    Condition: when using an assertion as a client credential

    client_id OPTIONAL.

Authorization servers

MUST NOT
1
  1. 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.

MUST
6
  1. 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.

  2. 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.

  3. 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.

  4. RFC 7523 - Section 3

    reject JWTs with an invalid signature or MAC.

    The authorization server MUST reject JWTs with an invalid signature or MAC.

  5. 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)".

  6. 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.

MAY
2
  1. 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.

  2. 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

MUST
2
  1. 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.

  2. 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

error

Require `client_assertion_type` and verify that its value is the absolute URI `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`.

error

Require exactly one JWT in `client_assertion`.

error

If `client_id` is supplied, verify that it identifies the same client as the assertion.

error

Verify required `iss`, `sub`, `aud`, and `exp` claims, including that `sub` equals the client's `client_id` and `aud` identifies the authorization server.

error

Reject expired JWTs and JWTs used before an applicable `nbf` time, allowing configured clock skew where appropriate.

error

Verify the JWT signature or MAC and all other JWT validity requirements.

error

Return `invalid_client` when the client JWT is invalid.

info

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