oauth2.dev

code

IETF

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

MUST NOT
1
  1. 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.

MUST
9
  1. 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.

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

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

  4. RFC 6749 - Section 4.1.2

    Ignore unrecognized authorization response parameters..

    Condition: When processing the authorization response.

    The client MUST ignore unrecognized response parameters.

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

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

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

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

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

REQUIRED
5
  1. 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.

  2. RFC 6749 - Section 4.1.3

    Include the grant_type parameter in the token request..

    Condition: When exchanging an authorization code.

    grant_type REQUIRED.

  3. RFC 6749 - Section 4.1.3

    Include the authorization code in the token request..

    Condition: When exchanging an authorization code.

    code REQUIRED.

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

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

SHOULD
2
  1. 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

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

MUST
18
  1. 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

  15. RFC 9700 - Section 2.1.1

    Support PKCE..

    Condition: When supporting the authorization code grant.

    Authorization servers MUST support PKCE

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

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

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

REQUIRED
2
  1. 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.

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

SHOULD
4
  1. 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

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

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

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

RECOMMENDED
2
  1. 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.

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

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

MUST NOT
1
  1. 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

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

MUST
1
  1. RFC 9700 - Section 2.1.1

    Use PKCE..

    Condition: When using the authorization code grant.

    Public clients MUST use PKCE

Validation Guidance

error

Require response_type exactly equal to code for an authorization code grant request.

error

Return an authorization error when response_type is missing or not understood.

error

Require code in a successful authorization response, require matching state when applicable, and ignore unknown response parameters.

error

Issue short-lived, single-use authorization codes; a lifetime no greater than 10 minutes is recommended.

error

Deny authorization-code replay and revoke previously issued tokens when possible.

error

At the token endpoint, require grant_type=authorization_code and the code parameter.

error

Require client_id when the client does not authenticate, and enforce required client authentication otherwise.

error

Validate the code, its client binding, and any required redirect_uri binding during code exchange.

error

Require registered redirect URIs for public clients and validate supplied redirect URIs using exact string matching, subject to the native-app localhost port exception.

warning

Require registered redirect URIs for confidential clients unless the implementation has a justified reason not to follow the recommendation.

error

Do not expose open redirectors in clients or authorization servers.

error

Use secure transport for authorization codes and redirect endpoints as required by the applicable TLS conditions.

error

Require public clients to use PKCE and recommend PKCE for confidential clients.

error

Ensure PKCE challenges are transaction-specific, use a verifier-hiding challenge method such as S256, and enforce code_verifier binding without downgrade.

error

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