About
The scope defines the permissions to resources, ie the scope from a access request (ie from an access token or grant)
They are used to grant a application (client) different levels of access to data on behalf of the end user (owner).
Each authorization server may declare one or more scopes.
Example
Pet store API
The scopes for a hypothetical pet store api may include:
- read_pets,
- write_pets,
- read_orders,
- write_orders,
- admin.
Google Drive
This is the scope that Google Drive is asking when you are connecting to their service.
scope=email openid https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/docs.test https://www.googleapis.com/auth/drive https://www.googleapis.com/auth/drive.photos.readonly https://www.googleapis.com/auth/peopleapi.readonly https://www.googleapis.com/auth/meetings https://www.googleapis.com/auth/drive.activity.readonly https://www.googleapis.com/auth/experimentsandconfigs https://www.googleapis.com/auth/photos.native
If you use it in a URL, you need to encode it (ie the space should become %20)
Value
The value of the scope is expressed as a list of space-delimited, case-sensitive strings.
The strings are defined by the authorization server. If the value contains multiple space-delimited strings, their order does not matter, and each string adds an additional access range to the requested scope.
scope := 'scope-token' ( 'SP' scope-token )*
scope := 'scope-token' ( 'SP' scope-token )*
scope-token := ( '%x21' / '%x23-5B' / '%x5D-7E' )+
scope-token := ( '%x21' / '%x23-5B' / '%x5D-7E' )+
where: scope-token can be composed from the following ASCII characters in hexadecimal:
- x21. ie !
- x23-5B ie # to [
- x5D-7E ie ] to~
The authorization server SHOULD document its scope requirements and default value (if defined).
Flow
Request
The client can specify the scope of the access request at:
- the authorization endpoint with the scope request parameter
- and token endpoint with the scope request parameter
The authorization server MAY fully or partially ignore the scope requested by the client, based on the authorization server policy or the resource owner's instructions.
If the client omits the scope parameter when requesting authorization, the authorization server MUST either:
- process the request using a pre-defined default value
- or fail the request indicating an invalid scope.
Response
In turn, the authorization server (ie authorization endpoint and token endpoint) uses the scope response parameter to inform the client of the scope of the access token issued.
See:
If the issued access token scope is different from the one requested by the client, the authorization server MUST include the scope response parameter to inform the client of the actual scope granted.