oauth2.dev

client_secret_post

IESG

Registry Context

`client_secret_post` identifies client authentication using `client_id` and `client_secret` parameters in the token request body.

Technical Summary

RFC 7591 defines `client_secret_post` as a case-sensitive token endpoint authentication method name corresponding to the request-body client credential mechanism in RFC 6749 Section 2.3.1. RFC 6749 requires the defined credential parameters, prohibits placing them in the request URI, and requires TLS and brute-force protection.

When Used

Used by a client that authenticates to the token endpoint with credentials in the request body. RFC 6749 says this approach should be limited to clients unable to use HTTP Basic or another password-based HTTP authentication scheme, while RFC 9700 recommends asymmetric client authentication.

Normative Requirements

Clients

MUST NOT
1
  1. RFC 6749 - Section 2.3.1

    include the client authentication parameters in the request URI.

    Condition: When using request-body client password authentication

    MUST NOT be included in the request URI

REQUIRED
2
  1. RFC 6749 - Section 2.3.1

    include the `client_id` parameter.

    Condition: When using request-body client credentials corresponding to `client_secret_post`

    client_id REQUIRED

  2. RFC 6749 - Section 2.3.1

    include the `client_secret` parameter.

    Condition: When using request-body client credentials corresponding to `client_secret_post`, except when the secret is an empty string and the permitted omission is used

    client_secret REQUIRED

SHOULD
1
  1. RFC 6749 - Section 2.3.1

    limit use of request-body client credentials to clients unable to directly use HTTP Basic or another password-based HTTP authentication scheme.

    Condition: When selecting request-body client password authentication

    SHOULD be limited to clients unable to directly utilize the HTTP Basic authentication scheme

MAY
1
  1. RFC 6749 - Section 2.3.1

    omit the `client_secret` parameter.

    Condition: When the client secret is an empty string

    client MAY omit the parameter if the client secret is an empty string

Authorization servers

MUST
2
  1. RFC 6749 - Section 2.3.1

    require TLS for requests using password authentication.

    Condition: When receiving client password authentication requests

    MUST require the use of TLS

  2. RFC 6749 - Section 2.3.1

    protect every endpoint using this authentication method against brute-force attacks.

    Condition: When an endpoint uses client password authentication

    MUST protect any endpoint utilizing it against brute force attacks

SHOULD
1
  1. RFC 9700 - Section 2.5

    enforce client authentication.

    Condition: When credential issuance or registration and credential confidentiality are feasible in the deployment

    Authorization servers SHOULD enforce client authentication if it is feasible

MAY
1
  1. RFC 6749 - Section 2.3.1

    support including client credentials in the request body.

    Condition: For client password authentication

    authorization server MAY support including the client credentials in the request-body

authorization server deployment

RECOMMENDED
1
  1. RFC 9700 - Section 2.5

    use asymmetric cryptography for client authentication.

    Condition: When selecting supported client authentication methods

    RECOMMENDED to use asymmetric cryptography for client authentication

client and authorization server

OPTIONAL
1
  1. RFC 7591 - Section 2

    implement and use the `token_endpoint_auth_method` client metadata field.

    Condition: Unless another requirement states otherwise

    implementation and use of all client metadata fields is OPTIONAL

registry authority

SHOULD NOT
1
  1. RFC 7591 - Section 4.2.1

    accept a requested authentication method name that matches another registered name case-insensitively.

    Condition: When registering an OAuth Token Endpoint Authentication Method name

    SHOULD NOT be accepted

Validation Guidance

info

Verify the registry name is represented exactly as `client_secret_post`; RFC 7591 states that method names are case-sensitive.

warning

Reject registration of a name that differs from an existing registered method name only by case.

error

Verify `client_secret_post` is interpreted as request-body client authentication using `client_id` and `client_secret`, allowing omission of `client_secret` only when it is an empty string.

error

Verify client authentication parameters are never placed in the request URI.

error

Verify TLS and brute-force protections are enforced for endpoints accepting this method.

warning

Warn when `client_secret_post` is selected where HTTP authentication or an asymmetric client authentication method is available.

Security Notes

RFC 6749 - Section 2.3.1

Request-body client credentials are not recommended by RFC 6749 and should be limited to clients unable to use HTTP Basic or another password-based HTTP authentication scheme.

RFC 6749 - Section 2.3.1

RFC 6749 requires TLS, prohibits credentials in the request URI, and requires brute-force protection for endpoints using client password authentication.

RFC 9700 - Section 2.5

The OAuth 2.0 Security BCP recommends asymmetric client authentication because authorization servers then need not store sensitive symmetric keys.

Reference

Details

Entry Id
client_secret_post
Token Endpoint Authentication Method Name
client_secret_post
Change Controller
IESG
Reference
RFC7591