code
Registry Context
The response type code requests an authorization code from the authorization endpoint. The client subsequently exchanges the short-lived, single-use code at the token endpoint.
Technical Summary
In RFC 6749, response_type=code selects the authorization code grant. RFC 9700 additionally requires protection against authorization-code injection and misuse, including PKCE for public clients and PKCE support by authorization servers.
When Used
Used when an OAuth client requests an authorization code that will later be exchanged for tokens.
Normative Requirements
Clients
RFC 6749 - Section 4.1.2
Use an authorization code more than once..
Condition: After receiving an authorization code.
The client MUST NOT use the authorization code more than once.
RFC 6749 - Section 10.5
Require TLS at its redirect endpoint..
Condition: If it relies on the authorization code for resource-owner authentication.
the client redirection endpoint MUST require the use of TLS.
RFC 6749 - Section 3.1.1
Use code as the response_type value when requesting an authorization code..
Condition: When requesting an authorization code.
The value MUST be one of "code" for requesting an authorization code
RFC 6749 - Section 4.1.1
Set response_type to code..
Condition: When constructing an authorization code grant authorization request.
Value MUST be set to "code".
RFC 6749 - Section 4.1.2
Ignore unrecognized authorization response parameters..
Condition: When processing the authorization response.
The client MUST ignore unrecognized response parameters.
RFC 6749 - Section 4.1.3
Set grant_type to authorization_code..
Condition: When exchanging an authorization code.
Value MUST be set to "authorization_code".
RFC 6749 - Section 4.1.3
Use the same redirect_uri value in the authorization and token requests..
Condition: If redirect_uri was included in the authorization request.
their values MUST be identical.
RFC 6749 - Section 4.1.3
Authenticate to the authorization server..
Condition: If confidential, issued client credentials, or assigned other authentication requirements.
the client MUST authenticate with the authorization server
RFC 9700 - Section 2.1.1
Prevent authorization-code injection attacks and misuse of authorization codes..
Condition: When using the authorization code grant.
Clients MUST prevent authorization code injection attacks
RFC 9700 - Section 2.1.1
Use a transaction-specific PKCE challenge or OpenID Connect nonce securely bound to the client and user agent..
Condition: When using PKCE or the permitted OpenID Connect nonce alternative.
the PKCE challenge or OpenID Connect nonce MUST be transaction-specific and securely bound
RFC 6749 - Section 3.1.1
Include the response_type parameter in the authorization request..
Condition: When making an authorization endpoint request.
response_type REQUIRED.
RFC 6749 - Section 4.1.3
Include the grant_type parameter in the token request..
Condition: When exchanging an authorization code.
grant_type REQUIRED.
RFC 6749 - Section 4.1.3
Include the authorization code in the token request..
Condition: When exchanging an authorization code.
code REQUIRED.
RFC 6749 - Section 4.1.3
Include redirect_uri in the token request..
Condition: If redirect_uri was included in the authorization request.
redirect_uri REQUIRED, if the "redirect_uri" parameter was included
RFC 6749 - Section 4.1.3
Include client_id in the token request..
Condition: If the client is not authenticating to the authorization server.
client_id REQUIRED, if the client is not authenticating
RFC 6749 - Section 10.5
Require TLS for its redirect URI..
Condition: If the redirect URI identifies a network resource.
the client SHOULD require the use of TLS with its redirection URI
RFC 9700 - Section 2.1.1
Use a PKCE code challenge method that does not expose the verifier in the authorization request..
Condition: When using PKCE.
clients SHOULD use PKCE code challenge methods that do not expose the PKCE verifier
Authorization servers
RFC 6749 - Section 10.5
Issue authorization codes that are short-lived and single-use..
Condition: When issuing authorization codes.
Authorization codes MUST be short lived and single-use.
RFC 6749 - Section 10.5
Authenticate the client and ensure that the code was issued to that client..
Condition: If the client can be authenticated.
authorization servers MUST authenticate the client and ensure that the authorization code was issued to the same client.
RFC 6749 - Section 10.6
Ensure the redirect URI used to obtain the code is identical to the redirect URI supplied during code exchange..
Condition: For authorization code grant processing.
the authorization server MUST ensure that the redirection URI used to obtain the authorization code is identical
RFC 6749 - Section 10.6
Require public clients to register their redirect URIs..
Condition: For authorization code grant clients.
The authorization server MUST require public clients
RFC 6749 - Section 10.6
Validate a supplied redirect URI against the registered value..
Condition: If a redirect URI is supplied in the request.
the authorization server MUST validate it against the registered value.
RFC 6749 - Section 3.1.1
Return an error response when response_type is missing or not understood..
Condition: If response_type is absent or the response type is not understood.
the authorization server MUST return an error response
RFC 6749 - Section 4.1.2
Make the authorization code expire shortly after issuance..
Condition: When issuing an authorization code.
The authorization code MUST expire shortly after it is issued
RFC 6749 - Section 4.1.2
Deny an attempt to reuse an authorization code..
Condition: If an authorization code is used more than once.
the authorization server MUST deny the request
RFC 6749 - Section 4.1.3
Require client authentication for confidential clients and clients assigned credentials or other authentication requirements..
Condition: When processing an authorization code token request.
The authorization server MUST: require client authentication
RFC 6749 - Section 4.1.3
Authenticate the client when client authentication is included..
Condition: When processing an authorization code token request containing client authentication.
The authorization server MUST: authenticate the client if client authentication is included
RFC 6749 - Section 4.1.3
Ensure the code was issued to the authenticated confidential client or, for a public client, to the client_id in the request..
Condition: When processing an authorization code token request.
The authorization server MUST: ensure that the authorization code was issued to the authenticated confidential client
RFC 6749 - Section 4.1.3
Verify that the authorization code is valid..
Condition: When processing an authorization code token request.
The authorization server MUST: verify that the authorization code is valid
RFC 6749 - Section 4.1.3
Require redirect_uri when it appeared in the authorization request and ensure the values are identical..
Condition: When processing the corresponding token request.
The authorization server MUST: ensure that the "redirect_uri" parameter is present
RFC 9700 - Section 2.1
Use exact string matching when comparing redirect URIs with registered URIs..
Condition: Except for port numbers in localhost redirect URIs of native applications.
authorization servers MUST utilize exact string matching
RFC 9700 - Section 2.1.1
Support PKCE..
Condition: When supporting the authorization code grant.
Authorization servers MUST support PKCE
RFC 9700 - Section 2.1.1
Enforce correct use of code_verifier at the token endpoint..
Condition: If the authorization request contained a valid PKCE code_challenge.
the authorization server MUST enforce the correct usage of code_verifier
RFC 9700 - Section 2.1.1
Reject PKCE downgrade attempts by accepting code_verifier only when code_challenge was present in the authorization request..
Condition: When processing a token request containing code_verifier.
Authorization servers MUST mitigate PKCE downgrade attacks
RFC 9700 - Section 2.1.1
Provide a way for clients to detect PKCE support..
Condition: When supporting the authorization code grant.
Authorization servers MUST provide a way to detect their support for PKCE.
RFC 6749 - Section 4.1.2
Include the code parameter in the successful authorization response..
Condition: If the resource owner grants the access request.
code REQUIRED.
RFC 6749 - Section 4.1.2
Return the exact state value received from the client..
Condition: If state was present in the authorization request.
state REQUIRED if the "state" parameter was present
RFC 6749 - Section 10.5
Transmit authorization codes over a secure channel..
Condition: When transmitting authorization codes.
The transmission of authorization codes SHOULD be made over a secure channel
RFC 6749 - Section 10.6
Require confidential clients to register their redirect URIs..
Condition: For authorization code grant clients.
SHOULD require confidential clients to register their redirection URIs.
RFC 6749 - Section 4.1.2
Revoke, when possible, all tokens previously issued from a reused authorization code..
Condition: If an authorization code is used more than once.
SHOULD revoke (when possible) all tokens previously issued
RFC 6749 - Section 4.1.2
Document the size of authorization code values it issues..
Condition: When issuing authorization codes.
The authorization server SHOULD document the size of any value it issues.
RFC 6749 - Section 4.1.2
Limit the authorization code lifetime to no more than 10 minutes..
Condition: When issuing an authorization code.
A maximum authorization code lifetime of 10 minutes is RECOMMENDED.
RFC 9700 - Section 2.1.1
Publish code_challenge_methods_supported in OAuth Authorization Server Metadata..
Condition: As the mechanism for advertising supported PKCE challenge methods.
It is RECOMMENDED for authorization servers to publish the element code_challenge_methods_supported
RFC 9700 - Section 2.1.1
Use a deployment-specific mechanism to communicate PKCE support..
Condition: Instead of publishing code_challenge_methods_supported in OAuth Authorization Server Metadata.
Authorization servers MAY instead provide a deployment-specific way
clients and authorization servers
RFC 9700 - Section 2.1
Expose open redirectors that forward a browser to an arbitrary URI obtained from a query parameter..
Condition: For redirect-based flows.
Clients and authorization servers MUST NOT expose URLs that forward the user's browser to arbitrary URIs
confidential client
RFC 9700 - Section 2.1.1
Use PKCE..
Condition: When using the authorization code grant.
For confidential clients, the use of PKCE is RECOMMENDED
public client
RFC 9700 - Section 2.1.1
Use PKCE..
Condition: When using the authorization code grant.
Public clients MUST use PKCE
Validation Guidance
Require response_type exactly equal to code for an authorization code grant request.
Return an authorization error when response_type is missing or not understood.
Require code in a successful authorization response, require matching state when applicable, and ignore unknown response parameters.
Issue short-lived, single-use authorization codes; a lifetime no greater than 10 minutes is recommended.
Deny authorization-code replay and revoke previously issued tokens when possible.
At the token endpoint, require grant_type=authorization_code and the code parameter.
Require client_id when the client does not authenticate, and enforce required client authentication otherwise.
Validate the code, its client binding, and any required redirect_uri binding during code exchange.
Require registered redirect URIs for public clients and validate supplied redirect URIs using exact string matching, subject to the native-app localhost port exception.
Require registered redirect URIs for confidential clients unless the implementation has a justified reason not to follow the recommendation.
Do not expose open redirectors in clients or authorization servers.
Use secure transport for authorization codes and redirect endpoints as required by the applicable TLS conditions.
Require public clients to use PKCE and recommend PKCE for confidential clients.
Ensure PKCE challenges are transaction-specific, use a verifier-hiding challenge method such as S256, and enforce code_verifier binding without downgrade.
Verify that the authorization server supports PKCE through OAuth Authorization Server Metadata or another deployment-specific mechanism.
Security Notes
RFC 6749 - Section 10.5
Authorization codes may be disclosed through user-agent history and HTTP referrer headers because they are transmitted through user-agent redirects.
RFC 6749 - Section 10.6
Weak redirect URI validation can cause an authorization code to be delivered to an attacker-controlled URI.
RFC 9700 - Section 2.1.1
RFC 9700 requires authorization-code clients to prevent code injection and misuse. Public clients must use PKCE; confidential clients are recommended to use it.
RFC 9700 - Section 2.1.1
The code_challenge_methods_supported element belongs to OAuth Authorization Server Metadata; it is not OpenID Provider or client metadata.
Reference
Details
- Entry Id
code- Name
code- Change Controller
IETF- Reference
RFC6749