oauth2.dev

scope

IETF

Registry Context

`scope` identifies the access a client requests and the access associated with an issued access token. The authorization server can grant less than requested and reports the actual granted scope when it differs.

Technical Summary

RFC 6749 defines `scope` as a space-delimited, case-sensitive list of authorization-server-defined strings. It is used at authorization and token endpoints. Special rules govern omitted authorization-request scope, successful token responses, and refresh-token requests.

When Used

Authorization requests, token endpoint requests including refresh requests, and successful access-token responses.

Normative Requirements

Clients

MUST NOT
1

  1. RFC 6749 - Section 6

    Include any scope that was not originally granted by the resource owner..

    Condition: When including `scope` in a refresh-token request.

    The requested scope MUST NOT include any scope not originally granted by the resource owner

OPTIONAL
2

  1. RFC 6749 - Section 4.1.1

    Include `scope` in an authorization-code authorization request..

    scope OPTIONAL.

  2. RFC 6749 - Section 6

    Include `scope` in a refresh-token request..

    scope OPTIONAL.

Authorization servers

MUST
3

  1. RFC 6749 - Section 3.3

    Include the `scope` response parameter to inform the client of the actual scope granted..

    Condition: When the issued access-token scope differs from the scope requested by the client.

    the authorization server MUST include the "scope" response parameter

  2. RFC 6749 - Section 3.3

    Either process the authorization request using a pre-defined default scope or fail the request while indicating an invalid scope..

    Condition: When the client omits `scope` from an authorization request.

    the authorization server MUST either process the request using a pre-defined default value or fail the request indicating an invalid scope

  3. RFC 6749 - Section 6

    Make the scope of a newly issued refresh token identical to the scope of the refresh token presented by the client..

    Condition: When issuing a new refresh token in response to a refresh-token request.

    the refresh token scope MUST be identical to that of the refresh token included by the client in the request

REQUIRED
1

  1. RFC 6749 - Section 5.1

    Include `scope` in a successful access-token response..

    Condition: When the granted scope is not identical to the scope requested by the client.

    otherwise, REQUIRED.

SHOULD
1

  1. RFC 6749 - Section 3.3

    Document its scope requirements and any defined default scope value..

    The authorization server SHOULD document its scope requirements and default value

MAY
1

  1. RFC 6749 - Section 3.3

    Fully or partially ignore the scope requested by the client based on authorization-server policy or the resource owner's instructions..

    Condition: When processing a requested scope.

    The authorization server MAY fully or partially ignore the scope requested by the client

OPTIONAL
1

  1. RFC 6749 - Section 5.1

    Include `scope` in a successful access-token response..

    Condition: When the granted scope is identical to the scope requested by the client.

    OPTIONAL, if identical to the scope requested by the client

Validation Guidance

error

Require `scope` in an access-token response when the granted scope differs from the requested scope; permit its omission when the scopes are identical.

error

When an authorization request omits `scope`, verify that the server applies a pre-defined default or fails the request while indicating invalid scope.

warning

Check that the authorization server documents its scope requirements and any default scope.

error

Reject refresh-token requests that include scope outside the scope originally granted by the resource owner.

error

When issuing a replacement refresh token, preserve the scope of the refresh token presented in the request.

info

Do not assume that requested scope will be granted unchanged; the authorization server may ignore it fully or partially.

Security Notes

RFC 6749 - Section 3.3

Clients must account for the actual granted scope when the authorization server returns a scope different from the requested scope.

RFC 6749 - Section 6

A refresh-token request cannot use `scope` to obtain access outside the scope originally granted by the resource owner.

Reference

RFC6749

Details

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