oauth2.dev

private_key_jwt

IESG

Registry Context

A client authentication method in which the client presents a JWT signed with its private key instead of authenticating with a shared client secret.

Technical Summary

The request includes the required `client_assertion_type` and `client_assertion` parameters. The assertion type is `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`; the assertion is a signed JWT identifying the client, authorization server, and validity period. Invalid assertions result in `invalid_client`.

When Used

Use when a confidential client can register and securely hold an asymmetric private key and the authorization server can obtain the corresponding public key.

Normative Requirements

Clients

MUST
1
  1. RFC 7521 - Section 4.2

    Ensure that `client_id` identifies the same client as the client assertion..

    Condition: when `client_id` is present with assertion-based client authentication

    the "client_id" parameter MUST identify the same client as is identified by the client assertion.

REQUIRED
2
  1. RFC 7521 - Section 4.2

    Include the `client_assertion_type` parameter..

    Condition: when using an assertion for client authentication

    client_assertion_type REQUIRED.

  2. RFC 7521 - Section 4.2

    Include the `client_assertion` parameter containing the assertion used to authenticate the client..

    Condition: when using an assertion for client authentication

    client_assertion REQUIRED.

OPTIONAL
1
  1. RFC 7521 - Section 4.2

    Include the `client_id` parameter..

    Condition: when using an assertion for client authentication

    client_id OPTIONAL.

Authorization servers

MUST NOT
1
  1. RFC 7523 - Section 3

    Accept the JWT for processing before its `nbf` time..

    Condition: when the JWT contains an `nbf` claim

    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 profile's processing criteria..

    Condition: before relying on the 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 the authorization server as an intended audience..

    Condition: when validating the JWT 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..

    Condition: when validating the JWT expiration

    The authorization server MUST reject any JWT with an expiration time that has passed

  4. RFC 7523 - Section 3

    Reject a JWT with an invalid signature or MAC..

    Condition: when validating JWT integrity

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

    Condition: when evaluating a client authentication JWT

    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: when the client JWT is invalid

    The value of the "error" parameter MUST be the "invalid_client" error code.

SHOULD
2
  1. RFC 8414 - Section 2

    Support `RS256` for JWT client authentication signatures..

    Condition: when publishing OAuth authorization server metadata for supported token endpoint signing algorithms

    Servers SHOULD support "RS256".

  2. RFC 9700 - Section 2.5

    Enforce client authentication..

    Condition: when credential issuance or registration and credential confidentiality are feasible for the deployment

    Authorization servers SHOULD enforce client authentication if it is feasible

MAY
2
  1. RFC 7523 - Section 3

    Prevent replay by retaining used `jti` values for the JWT's validity period..

    Condition: when the JWT contains a `jti` claim

    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: when returning an error for an invalid client JWT

    The authorization server MAY include additional information regarding the reasons the JWT was considered invalid

authorization server metadata

MUST NOT
1
  1. RFC 8414 - Section 2

    List `none` as a token endpoint client-authentication signing algorithm..

    Condition: in `token_endpoint_auth_signing_alg_values_supported`

    The value "none" MUST NOT be used.

MUST
1
  1. RFC 8414 - Section 2

    Include `token_endpoint_auth_signing_alg_values_supported`..

    Condition: when `token_endpoint_auth_methods_supported` includes `private_key_jwt`

    This metadata entry MUST be present if either of these authentication methods are specified

client_assertion parameter

MUST NOT
1
  1. RFC 7523 - Section 2.2

    Contain more than one JWT..

    Condition: when carrying a JWT used for client authentication

    It MUST NOT contain more than one JWT.

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

  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

JWT

MUST
5
  1. RFC 7523 - Section 3

    Contain an `iss` claim with a unique identifier for the issuer..

    Condition: when used for client authentication

    The JWT MUST contain an "iss" (issuer) claim

  2. RFC 7523 - Section 3

    Contain a `sub` claim identifying its subject..

    Condition: when used for client authentication

    The JWT MUST contain a "sub" (subject) claim

  3. RFC 7523 - Section 3

    Use the OAuth client's `client_id` as the `sub` value..

    Condition: when used for client authentication

    For client authentication, the subject MUST be the "client_id" of the OAuth client.

  4. RFC 7523 - Section 3

    Contain an `aud` claim identifying the authorization server as an intended audience..

    Condition: when used for client authentication

    The JWT MUST contain an "aud" (audience) claim

  5. RFC 7523 - Section 3

    Contain an `exp` claim limiting its usable time window..

    Condition: when used for client authentication

    The JWT MUST contain an "exp" (expiration time) claim

MAY
4
  1. RFC 7523 - Section 3

    Contain an `nbf` claim identifying the time before which it cannot be accepted..

    Condition: when a not-before restriction is needed

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

  2. RFC 7523 - Section 3

    Contain an `iat` claim identifying its issuance time..

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

  3. RFC 7523 - Section 3

    Contain a `jti` claim providing a unique token identifier..

    The JWT MAY contain a "jti" (JWT ID) claim

  4. RFC 7523 - Section 3

    Contain claims other than those defined by the profile..

    The JWT MAY contain other claims.

JWT issuer

MUST
1
  1. RFC 7523 - Section 3

    Digitally sign the JWT or apply a MAC..

    Condition: under the general RFC 7523 JWT profile

    The JWT MUST be digitally signed or have a Message Authentication Code (MAC) applied by the issuer.

MAY
1
  1. RFC 7523 - Section 3

    Use the authorization server's token endpoint URL as an `aud` value..

    Condition: when identifying the authorization server as an intended audience

    The token endpoint URL of the authorization server MAY be used as a value for an "aud" element

OAuth deployment

RECOMMENDED
1
  1. RFC 9700 - Section 2.5

    Use asymmetric cryptography, including signed JWTs using Private Key JWT, for client authentication..

    It is RECOMMENDED to use asymmetric cryptography for client authentication

OAuth Token Endpoint Authentication Methods registry

SHOULD NOT
1
  1. RFC 7591 - Section 4.2.1

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

    Condition: when evaluating a new registry registration

    Names that match other registered names in a case-insensitive manner SHOULD NOT be accepted.

Validation Guidance

warning

For registry registration, reject a method name that differs from an existing registered name only by case.

error

Require both `client_assertion_type` and `client_assertion` parameters.

error

Verify that `client_assertion_type` equals `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`.

error

Reject a `client_assertion` containing more than one JWT.

error

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

error

Validate `iss`, `sub`, `aud`, `exp`, and JWT integrity before accepting the assertion; for client authentication, require `sub` to equal the client's `client_id`.

error

Apply `nbf` when present and consider validating `iat` values for unreasonable age or future skew.

warning

Use `jti` replay detection where replay resistance is required.

error

For `private_key_jwt`, require an asymmetric digital signature and validate it using the client's registered public key; do not accept a MAC as satisfying this method.

error

Return `invalid_client` when the client JWT is invalid.

error

In OAuth authorization server metadata, include `token_endpoint_auth_signing_alg_values_supported` when `private_key_jwt` is advertised, and reject `none`.

warning

Support `RS256` unless deployment requirements justify a different supported algorithm set.

Security Notes

RFC 9700 - Section 2.5

Asymmetric client authentication avoids requiring the authorization server to store sensitive symmetric client keys and is more robust against key leakage.

RFC 7523 - Section 3

Replay detection can be implemented by retaining used `jti` values until the corresponding assertion expires.

Reference

Details

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