oauth2.dev

redirect_uri

IETF

Registry Context

`redirect_uri` identifies where the authorization server sends the user-agent after an authorization request. It is optional in the authorization-code request syntax but is mandatory under specified registration conditions. If supplied during an authorization-code request, it is required in the token request and must have the identical value.

Technical Summary

RFC 6749 defines `redirect_uri` for authorization-code and implicit authorization requests and for authorization-code token requests. RFC 9700 requires exact matching against the registered URI, except that native-app localhost URIs must permit variable ports. RFC 9700 advises clients not to use the implicit grant.

When Used

Authorization requests, authorization-code token requests, and authorization-server validation of client redirection URIs.

Normative Requirements

Clients

MUST
2
  1. RFC 6749 - Section 3.1.2.3

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

    Condition: If multiple redirection URIs, only part of a redirection URI, or no redirection URI has been registered.

    the client MUST include a redirection URI

  2. RFC 6749 - Section 4.1.3

    use a `redirect_uri` value identical to the value in the authorization request..

    Condition: When `redirect_uri` is included in the authorization-code token request.

    their values MUST be identical

REQUIRED
1
  1. RFC 6749 - Section 4.1.3

    include `redirect_uri` in the authorization-code token request..

    Condition: If `redirect_uri` was included in the authorization request.

    redirect_uri REQUIRED, if the "redirect_uri" parameter was included

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
1
  1. RFC 9700 - Section 2.1.2

    use the `code` response type or another response type that causes access tokens to be issued in the token response..

    Condition: Instead of using the implicit grant or another response type issuing access tokens in the authorization response.

    Clients SHOULD instead use the response type code

OPTIONAL
2
  1. RFC 6749 - Section 4.1.1

    include `redirect_uri` in an authorization-code authorization request..

    redirect_uri OPTIONAL.

  2. RFC 6749 - Section 4.2.1

    include `redirect_uri` in an implicit-grant authorization request..

    redirect_uri OPTIONAL.

Authorization servers

MUST NOT
1
  1. RFC 6749 - Section 3.1.2.4

    automatically redirect the user-agent to the invalid redirection URI..

    Condition: If authorization-request validation fails because of a missing, invalid, or mismatching redirection URI.

    MUST NOT automatically redirect the user-agent to the invalid redirection URI

MUST
10
  1. RFC 6749 - Section 10.6

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

    Condition: For the authorization-code grant.

    authorization server MUST ensure that the redirection URI ... is identical

  2. RFC 6749 - Section 10.6

    require public clients to register their redirection URIs..

    authorization server MUST require public clients ... to register their redirection URIs

  3. RFC 6749 - Section 10.6

    validate a request-provided redirection URI against the registered value..

    Condition: If a redirection URI is provided in the request.

    authorization server MUST validate it against the registered value

  4. RFC 6749 - Section 3.1.2.3

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

    Condition: When `redirect_uri` is included in an authorization request and redirection URIs were registered.

    authorization server MUST compare and match the value received

  5. RFC 6749 - Section 3.1.2.3

    compare the two URIs using simple string comparison..

    Condition: If client registration included the full redirection URI.

    authorization server MUST compare the two URIs using simple string comparison

  6. RFC 6749 - Section 4.1.3

    ensure that `redirect_uri` is present in the authorization-code token request..

    Condition: If `redirect_uri` was included in the initial authorization request.

    The authorization server MUST: ensure that the "redirect_uri" parameter is present

  7. RFC 6749 - Section 4.1.3

    ensure that the token-request `redirect_uri` is identical to the value from the initial authorization request..

    Condition: If `redirect_uri` is included in the authorization-code token request.

    The authorization server MUST: if included ensure that their values are identical

  8. RFC 6749 - Section 4.2.1

    verify that the URI to which it will redirect the access token matches a redirection URI registered by the client..

    Condition: When processing an implicit-grant authorization request.

    authorization server MUST verify that the redirection URI ... matches a redirection URI registered by the client

  9. RFC 9700 - Section 4.1.3

    ensure that the requested and registered redirection URIs are equal using simple string comparison..

    Condition: Except for native applications using a localhost URI.

    authorization server MUST ensure that the two URIs are equal

  10. RFC 9700 - Section 4.1.3

    allow variable port numbers..

    Condition: For native applications using a localhost redirection URI.

    authorization server MUST allow variable port numbers

SHOULD
2
  1. RFC 6749 - Section 10.6

    require confidential clients to register their redirection URIs..

    authorization server ... SHOULD require confidential clients to register their redirection URIs

  2. RFC 6749 - Section 3.1.2.4

    inform the resource owner of the error..

    Condition: If authorization-request validation fails because of a missing, invalid, or mismatching redirection URI.

    authorization server SHOULD inform the resource owner of the error

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

    authorization server MAY trust the redirection URI without further checks

Validation Guidance

error

When `redirect_uri` is supplied, validate it against the client's registered redirection URI using exact string equality, except for the permitted variable port on native-app localhost URIs.

error

Require `redirect_uri` in an authorization request under the registration conditions specified by RFC 6749 Section 3.1.2.3.

error

If an authorization-code request contained `redirect_uri`, require the token request to contain an identical value.

error

Do not redirect the user-agent to a missing, invalid, or mismatching redirection URI; present an error to the resource owner instead.

error

Require public clients, and normally confidential clients, to register their redirection URIs.

warning

Do not treat RFC 6749's `OPTIONAL` request syntax as overriding the conditional requirement in Section 3.1.2.3.

warning

Flag use of the implicit grant unless its exceptional RFC 9700 security conditions are satisfied.

Security Notes

RFC 6749 - Section 10.6

An attacker who can replace the authorization request's redirection URI may obtain the authorization code and complete a code-substitution attack. Registration, request validation, and token-endpoint identity checks mitigate this attack.

RFC 9700 - Section 4.1

Pattern-based redirection URI matching has led to exploitable validation errors; current best practice is exact matching, with a limited exception for native-app localhost port numbers.

Reference

Details

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