In the world of Single Sign-On (SSO) and Identity protocols (like OpenID Connect and OAuth 2.0), Scopes and Claims are two sides of the same coin. They define what an application is allowed to do and what it knows about the user.
1. Scope Name
A Scope is a high-level identifier used to request specific permissions or groups of information. Think of a scope as a bucket of permissions.
When an application redirects a user to an Identity Provider (IdP) like Okta, Google, or Azure AD, it asks for specific scopes. The user then sees a consent screen asking, "Do you allow this app to access your profile and email?"
Purpose: To limit the amount of access an application has (Principle of Least Privilege).
Examples: openid, profile, email, address, phone.
Analogy: A scope is like a keycard that says you have access to the "Executive Suite."
2. Claim Name
A Claim is a specific piece of information (an assertion) about the user, usually found inside a JSON Web Token (JWT). If the scope is the bucket, the claims are the items inside the bucket.
Once the IdP authenticates the user, it packages these claims into an ID Token or Access Token. Each claim has a "Claim Name" (the key) and a "Claim Value."
Purpose: To provide the application with the actual identity data it needs to function.
Examples: sub (subject/user ID), given_name, family_name, email_verified, locale.
Analogy: A claim is like the text printed on your ID card, such as your "Date of Birth" or "Home Address."
The Relationship: Mapping Scopes to Claims
In OpenID Connect (OIDC), requesting a single Scope Name usually grants the application multiple Claim Names.
| Scope Name | Common Claims Returned (Claim Names) |
openid | sub, iss, aud, exp, iat |
profile | name, family_name, given_name, preferred_username, picture |
email | email, email_verified |
address | address (formatted string or object) |
phone | phone_number, phone_number_verified
|
| Feature | Scope | Claim |
| Location | In the Authorization Request (URL) | In the Identity/Access Token (JWT) |
| User Experience | What the user consents to | What the app reads about the user |
| Granularity | Broad (Coarse-grained) | Specific (Fine-grained) |
| Format | Space-separated strings | Key-value pairs in JSON |
Pro-Tip: If you are configuring an SSO integration and the app isn't seeing the user's last name, you usually need to check two things:
More
In OAuth 2.0 and OpenID Connect (OIDC), scopes and claims are both used to communicate information about what a user can do or who they are, but they function at different stages of the authorization process.
1. Scopes: The "Permission" Request
Scopes are used during the Authorization Request. They define the extent of access that an application (the client) is requesting from the user. Think of a scope as a "bucket" of permissions.
When they are used: At the very beginning of the handshake. When the application redirects you to a login page, it sends a list of scopes.
What they do: They tell the Authorization Server which resources the application wants to touch.
Examples:
read:contacts: The app wants to see your contact list.
openid: A special OIDC scope that tells the server to return an Identity Token.
offline_access: The app wants a refresh token to stay logged in.
2. Claims: The "Identity" Data
Claims are used inside the Tokens (specifically ID Tokens and sometimes Access Tokens). A claim is a specific piece of information—an assertion made by the server about the user or the session.
When they are used: After the user authenticates. The server issues a JWT (JSON Web Token) containing these claims.
What they do: They provide the actual data needed to identify the user or make fine-grained access control decisions.
Examples:
sub (Subject): The unique ID for the user.
email: The user's email address.
exp: The expiration time of the token.
role: (Custom claim) The user’s job title or group
Is the profile scope included in the request?
Is the family_name claim correctly mapped in your Identity Provider's token configuration?
