oauth2.dev

redirect_uris

IESG

Registry Context

Client metadata containing an array of registered redirection URI strings for redirect-based OAuth flows.

Technical Summary

A JSON array of redirection URI strings. Redirect endpoint URIs must be absolute and must not contain fragments. Current OAuth security guidance requires exact matching against pre-registered URIs, except that native applications using localhost redirect URIs must be allowed to vary the port.

When Used

During dynamic client registration and when validating the `redirect_uri` parameter in authorization requests.

Normative Requirements

Clients

SHOULD NOT
1
  1. RFC 9700 - Section 2.1.2

    use the implicit grant or other response types that issue 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 (response type token) or other response types issuing access tokens in the authorization response

SHOULD
1
  1. RFC 9700 - Section 2.1.2

    use the `code` response type or another response type that issues access tokens in the token response.

    Condition: instead of the implicit grant or other response types issuing access tokens in the authorization response

    Clients SHOULD instead use the response type code

Implementations

OPTIONAL
1
  1. RFC 7591 - Section 2

    implement and use client metadata fields.

    Condition: unless a field definition states otherwise

    The implementation and use of all client metadata fields is OPTIONAL, unless stated otherwise.

authorization servers

MUST
2
  1. RFC 7591 - Section 2

    implement support for the `redirect_uris` metadata value.

    Condition: when supporting dynamic registration for redirect-based flows

    MUST implement support for this metadata value

  2. RFC 9700 - Section 2.1

    use exact string matching when comparing client redirection URIs against pre-registered URIs.

    Condition: except for port numbers in native application localhost redirection URIs

    authorization servers MUST utilize exact string matching except for port numbers in localhost redirection URIs of native apps

clients and authorization servers

MUST NOT
1
  1. RFC 9700 - Section 2.1

    expose URLs that forward the user's browser to arbitrary URIs obtained from a query parameter.

    Clients and authorization servers MUST NOT expose URLs that forward the user's browser to arbitrary URIs obtained from a query parameter

clients using flows with redirection

MUST
1
  1. RFC 7591 - Section 2

    register their redirection URI values.

    clients using flows with redirection MUST register their redirection URI values

the authorization server

MUST
9
  1. RFC 6749 - Section 10.6

    ensure that the redirection URI used to obtain an authorization code is identical to the URI used when exchanging that code.

    the authorization server MUST ensure that the redirection URI used to obtain the authorization code is identical to the redirection URI provided when exchanging the authorization code

  2. RFC 6749 - Section 10.6

    require public clients to register their redirection URIs.

    The authorization server MUST require public clients

  3. RFC 6749 - Section 10.6

    validate a supplied redirection URI against the registered value.

    Condition: if a redirection URI is provided in the request

    the authorization server MUST validate it against the registered value

  4. RFC 6749 - Section 3.1.2

    retain the registered endpoint URI query component when adding query parameters.

    Condition: when the endpoint URI contains a query component

    which MUST be retained when adding additional query parameters

  5. RFC 6749 - Section 3.1.2.2

    require public clients and confidential clients using the implicit grant to register their redirection endpoint.

    The authorization server MUST require the following clients to register their redirection endpoint

  6. RFC 6749 - Section 3.1.2.3

    compare and match the received redirection URI against at least one registered redirection URI or registered URI component.

    Condition: when `redirect_uri` is included and redirection URIs were registered

    the authorization server MUST compare and match the value received against at least one of the registered redirection URIs (or URI components)

  7. RFC 6749 - Section 3.1.2.3

    compare the two URIs using simple string comparison.

    Condition: if the client registration included the full redirection URI

    the authorization server MUST compare the two URIs using simple string comparison

  8. RFC 9700 - Section 4.1.3

    ensure that the requested and registered redirection URIs are equal.

    Condition: when validating redirection URIs, except for the native application localhost port exception

    the authorization server MUST ensure that the two URIs are equal

  9. RFC 9700 - Section 4.1.3

    allow variable port numbers.

    Condition: for native applications using a localhost redirection URI

    the authorization server MUST allow variable port numbers

SHOULD
4
  1. RFC 6749 - Section 10.6

    require confidential clients to register their redirection URIs.

    SHOULD require confidential clients to register their redirection URIs

  2. RFC 6749 - Section 3.1.2.2

    require all clients to register their redirection endpoint before using the authorization endpoint.

    The authorization server SHOULD require all clients to register their redirection endpoint prior to utilizing the authorization endpoint.

  3. RFC 6749 - Section 3.1.2.2

    require the client to provide the complete redirection URI.

    The authorization server SHOULD require the client to provide the complete redirection URI

  4. RFC 6749 - Section 3.1.2.2

    require registration of the URI scheme, authority, and path.

    Condition: if registration of the complete redirection URI is not possible

    the authorization server SHOULD require the registration of the URI scheme, authority, and path

MAY
2
  1. RFC 6749 - Section 3.1.2.2

    allow the client to register multiple redirection endpoints.

    The authorization server MAY allow the client to register multiple redirection endpoints.

  2. RFC 9700 - Section 4.1.3

    trust the redirection URI without further checks.

    Condition: if the origin and integrity of the authorization request containing it can be verified

    the authorization server MAY trust the redirection URI without further checks

the client

MUST
1
  1. RFC 6749 - Section 3.1.2.3

    include a redirection URI using the `redirect_uri` authorization request parameter.

    Condition: if multiple redirection URIs, only URI components, or no redirection URI were registered

    the client MUST include a redirection URI with the authorization request using the redirect_uri request parameter

the endpoint URI

MUST NOT
1
  1. RFC 6749 - Section 3.1.2

    include a fragment component.

    The endpoint URI MUST NOT include a fragment component.

MAY
1
  1. RFC 6749 - Section 3.1.2

    include an application/x-www-form-urlencoded query component.

    The endpoint URI MAY include an application/x-www-form-urlencoded formatted query component

the redirection endpoint URI

MUST
1
  1. RFC 6749 - Section 3.1.2

    be an absolute URI.

    The redirection endpoint URI MUST be an absolute URI

web servers hosting redirection URIs

MUST NOT
1
  1. RFC 9700 - Section 4.1.3

    expose open redirectors.

    Web servers on which redirection URIs are hosted MUST NOT expose open redirectors

Validation Guidance

error

Require `redirect_uris` to be a JSON array of URI strings when supplied.

error

For clients using redirect-based flows, require registration of their redirection URI values; dynamic registration servers supporting those flows must support this metadata field.

error

Reject each URI that is not absolute or that contains a fragment component.

error

Permit a query component, but preserve an existing registered query component when adding authorization response parameters.

error

Validate authorization-request redirect URIs using exact string matching against pre-registered URIs. For native applications using localhost redirect URIs, allow the port number to vary.

error

When multiple URIs, partial URI components, or no URI were registered, require the authorization request to include `redirect_uri`.

error

For authorization-code flows, ensure the redirect URI used at the authorization endpoint is identical to the one supplied during the corresponding token exchange.

error

Do not expose open redirectors at authorization servers, clients, or web servers hosting redirect endpoints.

warning

Flag use of the implicit grant or other front-channel access-token response types unless their exceptional security conditions are demonstrably satisfied.

Security Notes

RFC 6749 - Section 10.6

Manipulation of a redirect URI can send an authorization code to an attacker-controlled endpoint; registered-value validation and binding the authorization and token requests to the same URI mitigate this attack.

RFC 6749 - Section 3.1.2.2

A missing redirection URI registration requirement can allow the authorization endpoint to operate as an open redirector.

RFC 6749 - Section 10.15

Partial URI registration combined with a client-side open redirector can disclose authorization codes or access tokens to an attacker.

RFC 9700 - Section 4.1

Pattern-based redirect URI matching is error-prone and has enabled attacks; RFC 9700 requires exact matching, subject to the native localhost port exception.

RFC 9700 - Section 2.1.2

The implicit grant and other authorization responses carrying access tokens are vulnerable to token leakage and replay, so RFC 9700 recommends authorization-code-based alternatives.

Reference

Details

Entry Id
redirect_uris
Client Metadata Name
redirect_uris
Client Metadata Description
Array of redirection URIs for use in redirect-based flows
Change Controller
IESG
Reference
RFC7591