client_
Registry Context
`client_secret` is a client password used to authenticate a client. Clients can use it through HTTP Basic authentication, or an authorization server may accept it in the request body. The body method is not recommended, and credentials must not appear in the request URI.
Technical Summary
RFC 6749 Section 2.3.1 requires authorization servers to support HTTP Basic authentication for clients issued a client password. An authorization server may alternatively accept `client_id` and `client_secret` in the request body. In that mode, `client_secret` is REQUIRED unless the secret is an empty string, and the credentials MUST NOT appear in the request URI. Password authentication requires TLS and brute-force protection. RFC 9700 recommends asymmetric client authentication instead of symmetric secrets.
When Used
Primarily when a client issued credentials authenticates to the token endpoint.
Normative Requirements
Clients
RFC 6749 - Section 2.3.1
include request-body client credential parameters in the request URI.
Condition: when transmitting client credentials
MUST NOT be included in the request URI.
RFC 6749 - Section 3.2.1
authenticate with the authorization server as described in Section 2.3.
Condition: when the client is confidential or was otherwise issued client credentials and makes a token endpoint request
Confidential clients or other clients issued client credentials MUST authenticate with the authorization server
RFC 6749 - Section 2.3.1
include `client_secret` as a request-body parameter.
Condition: when using request-body client credentials and the client secret is not an empty string
client_secret REQUIRED. The client secret.
RFC 6749 - Section 2.3.1
use HTTP Basic authentication with its client password.
Condition: when the client possesses a client password
Clients in possession of a client password MAY use the HTTP Basic authentication scheme
RFC 6749 - Section 2.3.1
omit the `client_secret` parameter.
Condition: if the client secret is an empty string
The client MAY omit the parameter if the client secret is an empty string.
Authorization servers
RFC 6749 - Section 2.3.1
support HTTP Basic authentication.
Condition: for authenticating clients that were issued a client password
The authorization server MUST support the HTTP Basic authentication scheme
RFC 6749 - Section 2.3.1
require TLS.
Condition: when requests use password authentication
The authorization server MUST require the use of TLS
RFC 6749 - Section 2.3.1
protect every endpoint using client password authentication against brute-force attacks.
the authorization server MUST protect any endpoint utilizing it against brute force attacks.
RFC 6749 - Section 2.3.1
limit request-body client credentials to clients unable to use HTTP Basic or another password-based HTTP authentication scheme.
Condition: when supporting request-body client credentials
SHOULD be limited to clients unable to directly utilize the HTTP Basic authentication scheme
RFC 9700 - Section 2.5
enforce client authentication.
Condition: if the deployment can establish credential issuance or registration and ensure credential confidentiality
Authorization servers SHOULD enforce client authentication if it is feasible
RFC 6749 - Section 2.3.1
support including client credentials in the request body using `client_id` and `client_secret`.
the authorization server MAY support including the client credentials in the request-body
Unspecified actor
RFC 9700 - Section 2.5
use asymmetric cryptography for client authentication.
It is RECOMMENDED to use asymmetric cryptography for client authentication
Validation Guidance
Require clients issued credentials to authenticate when making token endpoint requests.
Ensure HTTP Basic authentication is supported for clients issued a client password.
When request-body authentication is used, require `client_secret` unless the registered secret is an empty string.
Reject client credentials included in the request URI.
Limit request-body credentials to clients unable to use HTTP Basic or another password-based HTTP authentication scheme.
Enforce TLS for password-based client authentication.
Protect every endpoint accepting client password authentication against brute-force attacks.
Prefer asymmetric client authentication methods where supported.
Security Notes
RFC 6749 - Section 2.3.1
Password-based client authentication requires TLS and brute-force protection.
RFC 6749 - Section 2.3.1
Request-body client credentials are not recommended by RFC 6749 and must never be placed in the request URI.
RFC 9700 - Section 2.5
RFC 9700 recommends asymmetric client authentication, such as mutual TLS or signed JWTs, because it avoids storing sensitive symmetric client secrets.
Reference
Details
- Entry Id
client_secret - Name
client_secret - Parameter Usage Location
token request- Change Controller
IETF- Reference
RFC6749