oauth2.dev

code

IETF

Registry Context

The `code` parameter carries the authorization code returned by the authorization server and later presented to the token endpoint for an authorization code grant.

Technical Summary

RFC 6749 requires `code` in a successful authorization response and in the corresponding token request. Authorization codes must expire shortly after issuance, must not be used more than once, and must be validated for validity, client binding, and applicable redirect URI binding. RFC 9700 additionally requires protections against authorization code injection and misuse, including PKCE for public clients.

When Used

Used in the authorization code grant, first in the authorization response and then in the token request that exchanges the code for tokens.

Normative Requirements

Clients

MUST NOT
1

  1. RFC 6749 - Section 4.1.2

    use the authorization code more than once.

    Condition: when processing or redeeming an authorization code

    The client MUST NOT use the authorization code more than once.

MUST
2

  1. RFC 9700 - Section 2.1.1

    prevent authorization code injection attacks and misuse of authorization codes using one of the specified protections.

    Condition: when using the authorization code grant

    Clients MUST prevent authorization code injection attacks and misuse of authorization codes using one of the following options

  2. RFC 9700 - Section 2.1.1

    use a transaction-specific PKCE challenge or OpenID Connect nonce that is securely bound to the client and the user agent in which the transaction began.

    Condition: when using PKCE or the OpenID Connect nonce alternative

    the PKCE challenge or OpenID Connect nonce MUST be transaction-specific and securely bound to the client and the user agent

REQUIRED
1

  1. RFC 6749 - Section 4.1.3

    include `code` in the token request.

    Condition: when making an authorization code grant token request

    code REQUIRED.

SHOULD
1

  1. 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 in the authorization request

Authorization servers

MUST
8

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

  2. RFC 6749 - Section 4.1.2

    deny the request.

    Condition: when an authorization code is used more than once

    the authorization server MUST deny the request

  3. RFC 6749 - Section 4.1.3

    ensure the authorization 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, or if the client is public, ensure that the code was issued to "client_id" in the request

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

  5. RFC 6749 - Section 4.1.3

    ensure `redirect_uri` is present when it was included in the initial authorization request and, when included, ensure the values are identical.

    Condition: when processing an authorization code token request

    The authorization server MUST: ensure that the "redirect_uri" parameter is present if the "redirect_uri" parameter was included in the initial authorization request, and if included ensure that their values are identical.

  6. RFC 9700 - Section 2.1.1

    support PKCE.

    Authorization servers MUST support PKCE

  7. RFC 9700 - Section 2.1.1

    enforce correct use of `code_verifier` at the token endpoint.

    Condition: if the client sent a valid `code_challenge` in the authorization request

    the authorization server MUST enforce the correct usage of code_verifier at the token endpoint

  8. RFC 9700 - Section 2.1.1

    mitigate PKCE downgrade attacks by accepting a token request containing `code_verifier` only when the authorization request contained `code_challenge`.

    Condition: when processing a token request containing `code_verifier`

    Authorization servers MUST mitigate PKCE downgrade attacks by ensuring that a token request containing a code_verifier parameter is accepted only if a code_challenge parameter was present in the authorization request

REQUIRED
1

  1. RFC 6749 - Section 4.1.2

    include `code` in the authorization response.

    Condition: when the resource owner grants the access request in the authorization code grant

    code REQUIRED.

SHOULD
2

  1. RFC 6749 - Section 4.1.2

    revoke, when possible, all tokens previously issued based on the authorization code.

    Condition: when the authorization code is used more than once

    SHOULD revoke (when possible) all tokens previously issued based on that authorization code

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

  1. RFC 6749 - Section 4.1.2

    limit the authorization code lifetime to no more than 10 minutes.

    Condition: when determining the authorization code lifetime

    A maximum authorization code lifetime of 10 minutes is RECOMMENDED.

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 to prevent authorization code injection and misuse.

    Condition: when using the authorization code grant

    Public clients MUST use PKCE

Validation Guidance

error

Successful authorization responses for the authorization code grant include `code`.

error

Authorization codes expire shortly after issuance, preferably within 10 minutes, and expired codes are rejected as invalid.

error

Authorization codes cannot be replayed; reused codes are rejected.

warning

Previously issued tokens are revoked when code replay is detected, where possible.

warning

Authorization servers document the supported size of issued authorization code values.

error

Authorization code grant token requests include `code`.

error

The token endpoint verifies the code's validity and binding to the authenticated confidential client or public client's `client_id`.

error

When `redirect_uri` was included in the authorization request, the token endpoint requires an identical value in the token request.

error

Clients implement protection against authorization code injection and misuse; public clients use PKCE and confidential clients preferably use PKCE.

error

PKCE challenges are transaction-specific, securely bound to the initiating client and user agent, and use a method such as `S256` that does not expose the verifier.

error

The authorization server supports PKCE, enforces `code_verifier` for codes issued with a valid challenge, and prevents PKCE downgrade attacks.

Security Notes

RFC 6749 - Section 4.1.2

A short authorization code lifetime mitigates the risk of leaked codes.

RFC 6749 - Section 4.1.2

Authorization codes are bound to the client identifier and redirection URI.

RFC 9700 - Section 2.1.1

PKCE protects authorization codes against injection and misuse; RFC 9700 requires it for public clients and recommends it for confidential clients.

Reference

RFC6749

Details

Entry Id
code
Name
code
Parameter Usage Location
authorization response, token request
Change Controller
IETF
Reference
RFC6749