oauth2.dev

client_secret_jwt

IESG

Registry Context

A token-endpoint client authentication method in which the client sends a JWT protected using its client secret.

Technical Summary

The client sends a JWT as the `client_assertion`, using the JWT bearer client-assertion type. RFC 7521 defines the assertion request parameters, while RFC 7523 defines JWT formatting and validation requirements.

When Used

When a client is registered to authenticate at the token endpoint using `client_secret_jwt`.

Normative Requirements

Clients

MUST NOT
1
  1. RFC 7523 - Section 2.2

    Place more than one JWT in the `client_assertion` parameter..

    Condition: When using a JWT for client authentication.

    The `client_assertion` MUST NOT contain more than one JWT.

MUST
3
  1. RFC 7521 - Section 4

    Use TLS for requests to the token endpoint..

    Condition: For token-endpoint requests carrying assertions.

    All requests to the token endpoint MUST use TLS.

  2. RFC 7521 - Section 4.2

    Ensure a supplied `client_id` identifies the same client as the client assertion..

    Condition: When `client_id` is included with assertion-based client authentication.

    If present, `client_id` MUST identify the same client as the assertion.

  3. RFC 7523 - Section 3

    Include a `sub` claim whose value is the OAuth client's `client_id`..

    Condition: When creating a client-authentication JWT.

    For client authentication, the subject MUST be the OAuth client's `client_id`.

REQUIRED
1
  1. RFC 7521 - Section 4.2

    Include both `client_assertion_type` and `client_assertion`..

    Condition: When using an assertion as a client credential.

    The section marks both parameters REQUIRED.

OPTIONAL
1
  1. RFC 7521 - Section 4.2

    Include the `client_id` parameter..

    Condition: When using an assertion as a client credential.

    The `client_id` parameter is OPTIONAL.

Authorization servers

MUST NOT
1
  1. RFC 7523 - Section 3

    Accept the JWT before the time identified by its `nbf` claim..

    Condition: When the JWT contains an `nbf` claim.

    The `nbf` claim identifies the time before which the token MUST NOT be accepted.

MUST
3
  1. RFC 7523 - Section 3

    Validate the JWT according to the criteria in RFC 7523 Section 3..

    Condition: Before relying on a JWT for client authentication.

    The authorization server MUST validate the JWT according to the listed criteria.

  2. RFC 7523 - Section 3

    Reject a JWT that is invalid in any other respect under the JWT specification..

    Condition: When validating the client-authentication JWT.

    The authorization server MUST reject a JWT that is not valid in all other respects.

  3. RFC 7523 - Section 3.2

    Return the `invalid_client` error code..

    Condition: When the client-authentication JWT is invalid.

    The `error` parameter MUST be `invalid_client`.

Client and authorization server

MUST
4
  1. RFC 7523 - Section 3

    Include an `iss` claim and, absent an overriding application profile, compare issuer values using RFC 3986 Simple String Comparison..

    Condition: When creating or validating the client-authentication JWT.

    The JWT MUST contain `iss`; compliant applications MUST use Simple String Comparison unless a profile specifies otherwise.

  2. RFC 7523 - Section 3

    Include an `aud` claim identifying the authorization server, reject JWTs that omit the server's identity, and, absent an overriding application profile, compare audience values using RFC 3986 Simple String Comparison..

    Condition: When creating or validating the client-authentication JWT.

    The JWT MUST contain `aud`; the server MUST reject an unintended audience, and compliant applications MUST use Simple String Comparison unless a profile specifies otherwise.

  3. RFC 7523 - Section 3

    Include an `exp` claim and reject the JWT after its expiration time, subject to allowable clock skew..

    Condition: When creating or validating the client-authentication JWT.

    The JWT MUST contain `exp`, and the authorization server MUST reject an expired JWT.

  4. RFC 7523 - Section 3

    Apply a digital signature or MAC to the JWT and reject an invalid signature or MAC..

    Condition: When creating or validating the client-authentication JWT.

    The JWT MUST be signed or MACed, and invalid signatures or MACs MUST be rejected.

Designated Experts

SHOULD NOT
1
  1. RFC 7591 - Section 4.2.1

    Accept a requested authentication method name that matches an existing registered name case-insensitively..

    Condition: When reviewing a registry request.

    Names matching registered names in a case-insensitive manner SHOULD NOT be accepted.

OAuth deployment

RECOMMENDED
1
  1. RFC 9700 - Section 2.5

    Use asymmetric cryptography for client authentication, such as mutual TLS or `private_key_jwt`..

    Condition: When selecting a client authentication method.

    Asymmetric cryptography is RECOMMENDED for client authentication.

Validation Guidance

error

Flag a proposed registry name that differs from an existing name only by case.

error

Require `client_assertion_type` and exactly one JWT in `client_assertion`.

error

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

error

Require TLS for the token-endpoint request.

error

Validate `iss`, `sub`, `aud`, `exp`, any present `nbf`, and all other JWT validity requirements.

error

Verify the JWT signature or MAC before accepting the client authentication.

error

Return `invalid_client` when client JWT validation fails.

warning

Prefer an asymmetric authentication method for new deployments; `client_secret_jwt` relies on shared symmetric key material.

Security Notes

RFC 7521 - Section 4

Token-endpoint requests transmit credentials and therefore require TLS.

RFC 7523 - Section 3

JWTs must be integrity protected, and invalid signatures or MACs must be rejected to prevent forged client assertions.

RFC 7523 - Section 6

RFC 7523 does not mandate replay protection; deployments can use unique `jti` values and track their use when replay resistance is required.

RFC 9700 - Section 2.5

Asymmetric client authentication is more robust against authorization-server key leakage because the server need not store a sensitive symmetric key.

Reference

Details

Entry Id
client_secret_jwt
Token Endpoint Authentication Method Name
client_secret_jwt
Change Controller
IESG
Reference
OpenID Connect Core 1.0 - Section 9, RFC-ietf-oauth-rfc7523bis-11