OpenID Connect Scopes
This document discusses scopes included within the OpenID Connect (OIDC) authentication protocol. For more info about OIDC itself, read OpenID Connect Protocol.
OpenID Connect (OIDC) scopes are used by an application during authentication to authorize access to a user's details, like name and picture. Each scope returns a set of user attributes, which are called claims. The scopes an application should request depend on which user attributes the application needs. Once the user authorizes the requested scopes, the claims are returned in an ID Token and are also available through the /userinfo endpoint.
For example, let's say you have built a regular web application, registered it with Auth0, and have configured it to allow a user to log in using a username and password. Once a user logs in to your app, you want to auto-generate and send a personalized welcome email, including the user's name.
A user clicks Login within your app.
Your app redirects the user to the Auth0 Authorization Server (
/authorizeendpoint), including the following scopes:openid(required; to indicate that the application intends to use OIDC to verify the user's identity)profile(so you can personalize the email with the user's name)email(so you know where to send the welcome email)
Your Auth0 Authorization Server redirects the user to the login prompt.
The user authenticates and sees a consent page listing the scopes Auth0 will give to your app, which include access to their profile information and email address.
The user accepts and authorizes your app to have this level of access to their information stored by Auth0.
Your app now has access to the user's profile information and email address.
Standard claims
Standard claims are intended to provide an application with user details, such as name, email, and picture, and are pre-defined for the OIDC protocol. These claims are returned in an ID Token and are also available through the /userinfo endpoint.
You can also create custom claims, which are claims that you define, control, and add to a token using Auth0 Actions. To learn more, read JSON Web Token Claims.
The basic (and required) scope for OIDC is openid, which indicates that an application intends to use the OIDC protocol to verify a user's identity. Beyond that, an application can ask for additional scopes by listing the requested scope names in the scope parameter, separated by spaces.
Standard claims included in the most commonly-used scopes are listed below, but for a full list of available standard claims, read OIDC specification: Standard Claims on openid.net. For a full list of Scopes, see OIDC specification: Requesting Claims Using Scope Values on openid.net.
| Scope | Claims |
|---|---|
openid |
(required) Returns the sub claim, which uniquely identifies the user. In an ID Token, iss, aud, exp, iat, and at_hash claims will also be present. To learn more about the ID Token claims, read ID Token Structure. |
profile |
Returns claims that represent basic profile information, including name, family_name, given_name, middle_name, nickname, picture, and updated_at. |
email |
Returns the email claim, which contains the user's email address, and email_verified, which is a boolean indicating whether the email address was verified by the user. |
For an example showing how to request standard claims for your application, read Sample Use Cases: Scopes and Claims.