OAuth Scopes
Back to current versionRestore this version

Overview#

OAuth Scopes (and OpenID Scopes) are used to obtain one or more OAuth 2.0 or OpenID Connect Claims

Scopes vs Claims

OAuth 2.0#

Within OAuth 2.0 Authorization_endpoint and Token_endpoints allow the OAuth Client to specify the OAuth Scopes of the Authorization Request using the "scope" request parameter.

In turn, the Authorization Server uses the "scope" response parameter to inform the OAuth Client of the scope of the Access Token issued.

The value of the scope parameter 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-token = 1*( %x21 / %x23-5B / %x5D-7E )

When the openid scope parameter is present it implies this is a OpenID Connect Authentication Request.

OpenID Connect Scopes#

OpenID Connect Scopes are used by the Relying Party to request Claims in the Authentication Request

Default scopes#

The  OpenID Connect  specification only defines a single set of standard scopes:

ScopeClaims
emailemail, email_verified
addressaddress
profilename, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, updated_at
phonephone_number, phone_number_verified
openidsub, auth_time, acr

User-Managed Access#

With User-Managed Access. OAuth Scopes is defined as a bounded extent of access that is possible to perform on a Resource Set. In authorization policy terminology, a OAuth Scopes is one of the potentially many "verbs" that can logically apply to a Resource Set ("object"). User-Managed Access associates scopes with labeled Resource Sets. This term derives from Auth 2.0 Resource Set Registration.

Scopes Granted#

The Authorization Server MAY fully or partially ignore the OAuth Scopes requested by the OAuth Client in the Authorization Request, based on the Authorization Policy or the Resource Owner's instructions.

If the issued Access Token scope is different from the one requested by the OAuth Client, the Authorization Server MUST include the "scope" response parameter to inform the OAuth Client of the actual scope granted.

If the OAuth Client omits the scope parameter in the Authorization Request, the Authorization Server MUST either process the request using a pre-defined default value or fail the request indicating an invalid scope. The Authorization Server SHOULD document its scope requirements and default value (if defined).[1]

OAuth Scopes has a lot flexibility in case the person needs to self-approve the release of information from the Authorization Server to the OAuth Client. In OAuth 2.0, OAuth Scopes can be used for various purposes. For example OpenID Connect uses OAuth Scopes to "group" attributes.

For example, we could have a scope called "address" that includes the street, city, state, and country user claims.

There could be OAuth Scopes granted that are based on:

Because of the Scope Granted MAY be different than the Scopes in the Authorization Request/Authentication Request, OAuth Scope Validation MUST be performed.

OAuth Scopes Best Practices#

Although you can name your scopes anything you wish. In simple cases, it is fine to use simple names like used for CRUD - Create, Read, Update or Delete.

In more complex scenarios where there are multiple API or OAuth Clients products, each with multiple resources which each support multiple distinct actions, a WRITE on one resource is not equivalent to a WRITE on another resource. In these cases, it's a best practice to assign each scope a Unique Identifier name, in the form of an URN.

Examples of URNs include:

More Information#

There might be more information for this subject on one of the following:
Introduction to Scopes
Please see our Copyright And Intellectual Property Page and Standard Disclaimer Pages!