OpenID Connect and OAuth2 Standard Scopes

Emmanuel Gautier · October 24, 2024

OpenID Connect and OAuth 2.0 define a set of standard scopes that can be used to control the level of access to resources but also to

What are Scopes?

Scopes are a way to define the level of access that a client application has to a user's resources. They allow the client application to request specific permissions from the user, such as read access to a user's profile or write access to a user's calendar. Scopes are defined by the authorization server and can be used to control the level of access that a client application has to a user's resources.

During the authorization process, the client application requests specific scopes from the user. The user then grants or denies these scopes, depending on their preferences. If the user grants the scopes, the authorization server issues an access token to the client application, which can be used to access the requested resources.

OpenID Connect Scopes

OpenID Connect defines a set of standard scopes that can be used to control the level of access that a client application has to a user's resources. These scopes are used to request specific permissions from the user and are defined in the OpenID Connect specification.

Some of the standard scopes defined by OpenID Connect include:

openid: This scope is used to indicate that the client application is requesting authentication and identity information about the user.
profile: This scope is used to request access to the user's profile information, such as their name, email address, and profile picture.
email: This scope is used to request access to the user's email address.
address: This scope is used to request access to the user's address information.
phone: This scope is used to request access to the user's phone number.
offline_access (or offline): This scope is used to request access to refresh tokens, which can be used to obtain new access tokens without requiring the user to re-authenticate.

How to name scopes?

One of the most pain point as a developer is to name things, right? Scopes are no exception. The OAuth2 specification does not provide a strict guideline on how to name scopes. However, it is recommended to use a clear and descriptive name that reflects the purpose of the scope. For example, if you are requesting read access to a book resource in your application, you could name the scope read_books.

When naming scopes, it is important to consider the following:

Clarity: The scope name should clearly indicate the purpose of the scope and the level of access it provides.
Consistency: Use consistent naming conventions across scopes to make it easier to manage and understand them.
Descriptiveness: Use descriptive names that clearly convey the purpose of the scope to developers and users.

Here is a bad example of how scopes can be named:

{
  "scopes": {
    "r": "Read access",
    "w": "Write access",
    "rp": "Read profile",
    "wp": "Write profile"
  }
}

As naming variables, functions, or classes, scopes should be named in a way that makes it easy to understand their purpose and use.

Here is a better example of how scopes should be named:

{
  "scopes": {
    "read_books": "Read access to book resources",
    "write_books": "Write access to book resources",
    "read_profile": "Read access to user profile information",
    "write_profile": "Write access to user profile information"
  }
}

Google Scope Naming Strategy

Google has one of the most widely used but also one of the largest set of APIs. Scope naming strategy at Google must be consistent and clear to developers but be reliable, scalable and not change over time. In order to answer this need, Google define scope naming including the API domain, service, resource and action. For example, https://www.googleapis.com/auth/drive.file would mean that the client application is requesting access to the user's Google Drive files.

Here some of the Google services scopes documentation:

Ory Scope Naming Strategy

In this section we will look to Ory scope naming strategy example. Fosite, a Go library developed by Ory which provides an OpenID Connect SDK, give an example of a hierarchical scope naming strategy. This naming strategy tends to be more self-descriptive and flexible enough to be used in various contexts.

This example begin with the more generate part of the scope and then goes to the more specific part. For example, photos.read would mean that the client application is requesting read access to the user's photos. If you need to request read access for a specific photos type for example, you could use photos.read.albums to request read access to the user's photo albums.

Ory Fosite GitHub