Scopes and Claims

Description

In modern identity and access management systems — especially those built on OAuth 2.0 and OpenID Connect (OIDC) — the concepts of Scopes and Claims are foundational. Together, they determine what information a client can access and what information about a user or entity is included in tokens.

Scopes define the level of access an application is requesting.
Claims represent pieces of information about the subject (usually a user) that are shared in the issued token.

By combining scopes and claims effectively, systems can enforce least privilege access, support custom authentication flows, and maintain privacy and compliance standards.

What Are Scopes?

Scope in OAuth2 and OIDC is a mechanism to limit an application’s access to a user’s account or identity information. A scope is essentially a named permission level or access category.

For example:

scope=openid email profile

This string requests access to the user’s identity (openid), email address (email), and basic profile data (profile).

Purpose of Scopes

Enable user consent by informing what the app wants to access.
Support authorization granularity.
Help identity providers issue appropriately scoped tokens.
Restrict exposure of sensitive data.

Standard OAuth2 Scopes

Scope	Meaning
`read`	Read-only access to resource
`write`	Write or update access
`admin`	Full control over resource
`offline_access`	Get refresh tokens

Standard OpenID Connect Scopes

Scope	Description
`openid`	Required for OIDC authentication
`profile`	Access to name, gender, picture, etc.
`email`	Access to the user’s email address
`address`	Access to the user’s postal address
`phone`	Access to the user’s phone number

What Are Claims?

Claims are key-value pairs included in identity or access tokens (usually in JWT format), providing information about the authenticated user or session.

Example JWT Payload (Decoded)

{
  "sub": "1234567890",
  "name": "Jane Doe",
  "email": "[email protected]",
  "iat": 1620000000,
  "exp": 1620003600
}

Here:

sub: Unique subject ID
name: Full name of the user
email: Email address
iat: Issued At (timestamp)
exp: Expiry time

Categories of Claims

Type	Examples	Description
Standard Claims	`sub`, `iss`, `aud`, `exp`, `iat`	Token metadata required by OIDC/OAuth2
Identity Claims	`email`, `name`, `picture`, `locale`	Data about the user
Custom Claims	`roles`, `department`, `accountType`	Application-specific data included via policy

How Scopes and Claims Interact

Scopes often determine which claims are included in a token. For example:

If the scope includes profile, the ID token may contain claims like name, family_name, picture.
If the scope includes email, the token may include email and email_verified.

The Identity Provider (IdP) uses scope → claim mappings to decide what to include in the token. These mappings can be default or custom-defined by administrators.

Why They Matter

✅ Security
Scopes restrict access to sensitive data and actions; claims ensure trust in identity.

✅ User Consent
Scopes make permission requests transparent and understandable.

✅ Custom Workflows
Custom claims allow apps to enforce business rules (e.g., show admin panel only if role=admin).

✅ Standards Compliance
Scopes and claims are central to OAuth2/OIDC implementations used in enterprise security systems.

Use Cases

1. Third-Party App Permissions

An app wants to read calendar events but not modify them.

Scope: calendar.read
Token Claim: scope: calendar.read

2. Single Sign-On

A web app needs to know who the user is.

Scope: openid email
Claims: sub, email

3. Role-Based Access

A dashboard is only available to users with the “manager” role.

Custom Claim: role: manager
Scope may be implicit or managed via ID token claims

Custom Scopes and Claims

Identity platforms like Auth0, Okta, AWS Cognito, and Keycloak support the definition of custom scopes and custom claims to fit application-specific needs.

Example Custom Scope

scope=read:invoices write:expenses

Example Custom Claim

{
  "role": "super_admin",
  "tenant_id": "org-abc-123"
}

Custom claims are usually namespaced (e.g., https://yourapp.com/claims/role) to avoid collisions with standard claims.

Common Claims in OIDC

Claim	Description
`sub`	Unique user ID
`iss`	Issuer (Identity Provider)
`aud`	Audience (intended recipient)
`exp`, `iat`, `nbf`	Token expiry, issued at, not before
`email`, `email_verified`	User’s email and verification status
`name`, `given_name`, `family_name`	Name information
`picture`	Profile picture URL
`locale`	User’s language preference

Real-World Example

Scenario: A SaaS app integrating with Google Login

The app requests this scope:

scope=openid email profile

2. The user logs in via Google and consents.

3. The app receives an ID token like:

{
  "sub": "1087928234",
  "email": "[email protected]",
  "email_verified": true,
  "name": "Alicia Smith",
  "picture": "https://photo.jpg"
}

The app now knows who the user is and can personalize the interface.

Best Practices

Always request minimal scopes necessary for operation (least privilege).
Avoid excessive claims unless required.
Validate all claims server-side (especially aud, iss, and exp).
Namespace custom claims to avoid clashes.
Respect user consent — don’t request private scopes unless justified.
Use secure transport (HTTPS) for all token exchanges.

Examples

Scope Request

scope=openid email profile calendar.read offline_access

ID Token (Decoded Payload)

{
  "sub": "abc123",
  "email": "[email protected]",
  "role": "admin",
  "exp": 1723458901
}

Custom Claim Namespace Example

{
  "https://myapp.com/claims/role": "editor"
}

Related Keywords

Access Control
Access Token
Authentication
Authorization
Claims Mapping
Custom Claims
ID Token
Identity Federation
Identity Provider
JWT
Least Privilege
OAuth2
OpenID Connect
Permission Scope
Profile Scope
Refresh Token
Role Based Access
Scope Granularity
Token Claims
User Consent