oauth2.dev

state

IETF

Registry Context

The `state` parameter is an opaque client value used to maintain state between an authorization request and callback and can carry a value that binds the callback to the user-agent session for CSRF protection. When supplied, it is returned unchanged in successful and error authorization responses.

Technical Summary

RFC 6749 marks `state` as RECOMMENDED in authorization code and implicit authorization requests and says it SHOULD be used to prevent CSRF. It is REQUIRED in corresponding success and redirectable error responses when present in the request, with the exact value received from the client. RFC 6749 requires clients to protect their redirection URIs against CSRF and requires CSRF binding values to be non-guessable. RFC 9700 adds that `state` or an OpenID Connect nonce MUST be used for CSRF protection when PKCE is unavailable, and that application state requiring integrity protection MUST be protected against tampering and swapping.

When Used

Use in redirect-based authorization flows to correlate the callback with the initiating transaction, carry application state, or bind the callback to the initiating user-agent session. Prefer the authorization code grant with PKCE; RFC 9700 says clients SHOULD NOT use the implicit grant unless its injection and leakage risks are mitigated.

Normative Requirements

Clients

MUST
5

  1. RFC 6749 - Section 10.12

    Implement CSRF protection for its redirection URI..

    The client MUST implement CSRF protection for its redirection URI

  2. RFC 6749 - Section 10.12

    Ensure that a binding value used for CSRF protection contains a non-guessable value..

    Condition: When a binding value is used for CSRF protection, including through `state`.

    The binding value used for CSRF protection MUST contain a non-guessable value

  3. RFC 6749 - Section 10.12

    Keep the user-agent's authenticated state in a location accessible only to the client and user-agent..

    Condition: When binding an authorization callback to the user-agent's authenticated state for CSRF protection.

    the user-agent's authenticated state MUST be kept in a location accessible only to the client and the user-agent

  4. RFC 9700 - Section 4.7.1

    Use `state` or an OpenID Connect nonce for CSRF protection..

    Condition: If the authorization server does not support PKCE.

    state or nonce MUST be used for CSRF protection

  5. RFC 9700 - Section 4.7.1

    Protect `state` against tampering and swapping..

    Condition: If `state` carries application state and the integrity of its contents is a concern.

    clients MUST protect state against tampering and swapping

SHOULD NOT
1

  1. RFC 9700 - Section 2.1.2

    Use the implicit grant or another response type that issues access tokens in the authorization response..

    Condition: Unless access-token injection is prevented and the identified token-leakage vectors are mitigated.

    clients SHOULD NOT use the implicit grant

SHOULD
3

  1. RFC 6749 - Section 10.12

    Use the `state` request parameter to deliver the CSRF binding value to the authorization server..

    Condition: When making an authorization request.

    The client SHOULD utilize the "state" request parameter

  2. RFC 6749 - Section 4.1.1

    Use `state` to prevent cross-site request forgery..

    Condition: When constructing an authorization code authorization request.

    The parameter SHOULD be used for preventing cross-site request forgery

  3. RFC 6749 - Section 4.2.1

    Use `state` to prevent cross-site request forgery..

    Condition: When constructing an implicit grant authorization request.

    The parameter SHOULD be used for preventing cross-site request forgery

RECOMMENDED
2

  1. RFC 6749 - Section 4.1.1

    Include an opaque `state` value in an authorization code authorization request to maintain state between the request and callback..

    Condition: When constructing an authorization request using the authorization code grant.

    state RECOMMENDED

  2. RFC 6749 - Section 4.2.1

    Include an opaque `state` value in an implicit grant authorization request to maintain state between the request and callback..

    Condition: When constructing an authorization request using the implicit grant.

    state RECOMMENDED

Authorization servers

REQUIRED
4

  1. RFC 6749 - Section 4.1.2

    Include the exact `state` value received from the client in the successful authorization response..

    Condition: If `state` was present in an authorization code authorization request.

    REQUIRED if the "state" parameter was present; the exact value received

  2. RFC 6749 - Section 4.1.2.1

    Include the exact `state` value received from the client in the authorization error response..

    Condition: If `state` was present in an authorization code authorization request and the error is returned by redirecting to the client.

    REQUIRED if a "state" parameter was present; the exact value received

  3. RFC 6749 - Section 4.2.2

    Include the exact `state` value received from the client in the successful access token response..

    Condition: If `state` was present in an implicit grant authorization request.

    REQUIRED if the "state" parameter was present; the exact value received

  4. RFC 6749 - Section 4.2.2.1

    Include the exact `state` value received from the client in the authorization error response..

    Condition: If `state` was present in an implicit grant authorization request and the error is returned by redirecting to the client.

    REQUIRED if a "state" parameter was present; the exact value received

Validation Guidance

info

Verify that authorization requests using `state` treat it as an opaque client-generated value suitable for correlating the request and callback.

warning

Verify that `state` is used for CSRF protection in authorization requests where another sufficient mechanism is not used.

error

Verify that every redirectable successful or error authorization response contains the exact `state` value from the corresponding request when one was supplied.

error

Verify that the client implements CSRF protection for its redirection URI and that any CSRF binding value is non-guessable.

error

Verify that authenticated user-agent state used for callback binding is stored where only the client and user-agent can access it.

error

Verify that application data carried in `state` is protected against tampering and swapping when its integrity matters.

warning

Flag use of the implicit grant unless authorization-response access-token injection and leakage risks are mitigated.

Security Notes

RFC 6749 - Section 10.12

A CSRF attack against a client's redirection URI can inject an attacker's authorization code or access token into the client's callback.

RFC 6749 - Section 10.12

RFC 6749 requires clients to protect their redirection URIs against CSRF and recommends using `state` to carry a binding value tied to the user-agent's authenticated state.

RFC 6749 - Section 10.12

A CSRF binding value must be non-guessable, and the authenticated user-agent state to which it is bound must be protected by client and user-agent-only access.

RFC 9700 - Section 4.7.1

RFC 9700 recognizes PKCE and the OpenID Connect nonce as alternative CSRF protections, but requires `state` or nonce when the authorization server does not support PKCE.

RFC 9700 - Section 4.7.1

When `state` carries application state whose integrity matters, clients must protect it against tampering and swapping, for example through session binding or cryptographic protection.

RFC 9700 - Section 2.1.2

RFC 9700 advises clients not to use the implicit grant unless access-token injection and leakage risks are mitigated.

Reference

RFC6749

Details

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