grant_
Registry Context
`grant_type` identifies the authorization grant used in a token request. RFC 6749 defines values for authorization code, resource owner password credentials, client credentials, and refresh-token requests, and uses absolute URIs for extension grants. RFC 9700 now prohibits use of the resource owner password credentials grant.
Technical Summary
OAuth token-endpoint request parameter. RFC 6749 requires `authorization_code`, `password`, `client_credentials`, or `refresh_token` for the corresponding defined request and permits absolute-URI identifiers for extension grants. Unsupported grant types are represented by the `unsupported_grant_type` error code. RFC 9700 states that the password grant MUST NOT be used.
When Used
Token endpoint requests using authorization code, client credentials, refresh token, or extension grants. The resource owner password credentials value is historically defined by RFC 6749 but prohibited by RFC 9700.
Normative Requirements
Clients
RFC 6749 - Section 3.2
use the HTTP POST method.
Condition: when making an access token request
client MUST use the HTTP "POST" method
RFC 6749 - Section 4.1.3
set `grant_type` to `authorization_code`.
Condition: when using the authorization code grant
Value MUST be set to "authorization_code"
RFC 6749 - Section 4.3.2
set `grant_type` to `password`.
Condition: when using the resource owner password credentials grant as historically defined by RFC 6749
Value MUST be set to "password"
RFC 6749 - Section 4.4
use the client credentials grant only if it is a confidential client.
Condition: when using the client credentials grant
client credentials grant type MUST only be used by confidential clients
RFC 6749 - Section 4.4.2
set `grant_type` to `client_credentials`.
Condition: when using the client credentials grant
Value MUST be set to "client_credentials"
RFC 6749 - Section 6
set `grant_type` to `refresh_token`.
Condition: when requesting an access token using a refresh token
Value MUST be set to "refresh_token"
RFC 6749 - Section 4.1.3
include `grant_type` in the token request.
Condition: when using the authorization code grant
grant_type REQUIRED
RFC 6749 - Section 4.3.2
include `grant_type` in the token request.
Condition: when using the resource owner password credentials grant
grant_type REQUIRED
RFC 6749 - Section 4.4.2
include `grant_type` in the token request.
Condition: when using the client credentials grant
grant_type REQUIRED
RFC 6749 - Section 6
include `grant_type` in the refresh request.
Condition: when requesting an access token using a refresh token
grant_type REQUIRED
Authorization servers
RFC 6749 - Section 3.2
require TLS for requests to the token endpoint.
Condition: when requests are sent to the token endpoint
authorization server MUST require the use of TLS
RFC 6749 - Section 3.2
treat parameters sent without a value as omitted from the request.
Condition: when processing token endpoint parameters
Parameters sent without a value MUST be treated as if they were omitted
RFC 6749 - Section 3.2
ignore unrecognized request parameters.
Condition: when processing a token endpoint request
authorization server MUST ignore unrecognized request parameters
client and authorization server
RFC 6749 - Section 3.2
include request or response parameters more than once.
Condition: in token endpoint requests and responses
Request and response parameters MUST NOT be included more than once
RFC 9700 - Section 2.4
use the resource owner password credentials grant.
resource owner password credentials grant ... MUST NOT be used
extension grant specification
RFC 6749 - Section 8.3
register additional token endpoint parameters in the OAuth Parameters registry.
Condition: when an extension grant type requires additional token endpoint parameters
they MUST be registered in the OAuth Parameters registry
Validation Guidance
Require TLS for token endpoint requests.
Require token requests to use HTTP POST.
Treat an empty `grant_type` value as omitted.
Do not reject a token request solely because it contains unrecognized parameters.
Reject as nonconforming any token request in which `grant_type` appears more than once.
Reject token requests that omit `grant_type` for authorization code, resource owner password credentials, client credentials, or refresh-token requests.
Reject token requests whose `grant_type` does not equal the value defined for the selected standard grant.
Use `unsupported_grant_type` when the authorization server does not support the requested grant type.
Require registration of additional token endpoint parameters introduced by an extension grant type.
Reject use of the resource owner password credentials grant, including `grant_type=password`.
Permit `grant_type=client_credentials` only for confidential clients.
Security Notes
RFC 9700 - Section 2.4
RFC 9700 prohibits the resource owner password credentials grant because it exposes the resource owner's credentials to the client, increases the credential-leakage attack surface, and is incompatible with many multi-step and cryptographic authentication methods.
Reference
Details
- Entry Id
grant_type - Name
grant_type - Parameter Usage Location
token request- Change Controller
IETF- Reference
RFC6749