Scope Management

Overview

Scopes are part of OAuth 2.0 and define what an application is allowed to access when an access token is issued.
OpenID Connect (OIDC), built on OAuth 2.0, uses scopes to control which user claims are returned in the ID token and from the userinfo endpoint.

Scopes help secure user data and APIs by limiting what an application can access.

Common OIDC scopes:

• email – adds email and email_verified
• profile – adds profile-related claims such as given_name, family_name
• phone – adds phone-related claims
• address – adds address-related claims
• groups – adds user groups to the userinfo response
• roles – adds user roles to the userinfo response (roles are also scopes)

Scopes are also linked to field permissions configured in field setup, allowing you to restrict access to individual user attributes. By mapping scopes to user account fields, you can control read and write permissions for specific user data, ensuring that applications only access the fields they are authorized to use.

Note
Scopes restrict API access and define which user attributes are exposed. For related features, see permission management and groups and roles.

---

Prerequisites

Before managing scopes in cidaas, ensure:

• You have admin access to the cidaas Admin UI.
• Required user fields or APIs are already defined so scopes can be mapped correctly.
• You know which applications will require new or updated scopes.

---

Scopes in practice

Scopes provide an additional authorization layer for applications.
cidaas validates that the scopes configured for the client match the scopes granted to the user or included in their tokens.

Typical steps:

1. Define the scopes.
2. Assign them to applications.
3. Configure each API endpoint to require specific scopes.
4. Protect the API using an OAuth2 (cidaas) interceptor.

---

System scopes

cidaas provides a core set of system scopes used for OIDC operations.

OIDC scopes

Scope key	Description	Type
openid	Required for OIDC. Issues an ID token containing identity information about the authenticated user.	OIDC
profile	Allows access to profile-related user claims such as given_name, family_name, and similar attributes. Adds these claims to the ID token and userinfo response.	OIDC
email	Adds email and email_verified to the ID token and the userinfo response.	OIDC
phone	Adds phone number–related claims and verification status to the ID token and userinfo response.	OIDC
address	Adds address-related claims to the ID token and userinfo response.	OIDC
groups	Adds the user's group memberships to the userinfo response.	OIDC
roles	Adds the user's roles to the userinfo response. Roles are also scopes.	OIDC
identities	Provides access to the user's identity objects, including social identities and the internal "self" identity.	OIDC
offline_access	Allows issuing a refresh token. Used for native apps, devices, and clients that can securely store a refresh token.	OAuth2

Note
For a complete list of all available scopes (including administrative scopes) and their descriptions, navigate to Apps → Scope management in the cidaas Admin UI.

---

Administrator perspective

Configuring scopes

Scopes can be assigned to applications, mapped to fields, and grouped using scope groups.

Important
cidaas provides default OIDC scopes for each application.
Admins can define custom scopes for internal APIs and services.

Organize scopes effectively
Use scope groups to manage related scopes without changing application behavior.

---

Create a custom scope

1. Go to Apps → Scope management.
2. Select + Add scope.
3. Provide:
   • Scope key (unique identifier)
   • Locale
   • Scope title & description
   • Security level (Public or Confidential)
   • Scope group (optional)
   • User consent prompt (optional) - When enabled, users will be prompted to consent to this scope before the token is issued. This is especially important for Third Party clients (untrusted clients), which always require user consent for requested scopes. For more details, see Scope Consent.
4. Select Save.

---

Edit or delete a scope

• System scope keys cannot be changed.
• Only custom scopes can be deleted.
• Navigate to Scope management, edit the scope, and save changes or delete it.

---

Scope consent

Scope consent is a security mechanism that requires users to explicitly approve access to their data before a token is issued. When enabled for a scope, the authentication flow pauses to obtain user authorization.

When is scope consent required?

Scope consent is required in the following scenarios:

• Third Party clients: Third Party clients are untrusted clients that always require user consent for requested scopes (excluding cidaas: prefixed scopes, openid, and offline_access). This ensures users maintain control over their personal data when using external applications.
• Scope-level requirement: When the "User consent prompt" setting is enabled for a specific scope in scope management, all users will be prompted to accept this scope consent when authenticating.
• Client-based consent: Consent is requested per client, so users may be asked to consent again when using a different application, even if they've previously consented to the same scope.
• Request-based consent: Using prompt=consent in the authorization request forces consent to be requested, even if the user has previously consented.

For detailed information about implementing scope consent, see Scope Consent.

---

Developer reference

Requesting scopes in different OAuth2 flows

Scopes can be requested in different ways depending on the OAuth2 flow you're using:

Authorization Code Flow (with PKCE)

For user-facing applications, include scope as a query parameter in the authorization request:

GET /authz-srv/authz?
  response_type=code&
  client_id=your_client_id&
  redirect_uri=your_redirect_uri&
  scope=openid email profile&
  state=random_state_string

Client Credentials Flow (M2M)

For Machine-to-Machine (M2M) authentication, include scope in the token request body when calling the token endpoint:

POST /token-srv/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=your_client_id&
client_secret=your_client_secret&
scope=api:read api:write custom:scope

Security Note: The client_secret must be kept secure and stored only on your backend server. Never expose it to client-side code.

Device Code Flow

For devices with limited input capabilities, include scope in the device authorization request:

POST /authz-srv/device/authz
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
scope=openid profile email

Validating scopes in tokens

After receiving an access token, validate that it contains the required scopes before granting access to protected resources. There are two approaches: offline validation (JWT parsing) and online validation (token introspection).

Offline Validation (JWT parsing)

For JWT tokens, parse the token and extract scopes from the scope or scopes claim. Verify the token signature and check that the required scope is present in the token claims.

Steps:

1. Decode and verify the JWT signature using the issuer's public keys
2. Check token expiration (exp claim)
3. Extract scopes from the scope (space-separated string) or scopes (array) claim
4. Verify that all required scopes are present in the token

Limitations:

• Cannot detect revoked tokens
• Cannot detect if user has logged out
• Relies on token expiration for validity

Online Validation (Token Introspection)

For real-time validation that can detect revoked tokens, use the Token Introspection API. This is the recommended approach for production applications.

Basic Scope Validation:

POST /token-srv/introspect
Content-Type: application/json
Authorization: Basic <base64(client_id:client_secret)>

{
  "token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type_hint": "access_token",
  "scopes": ["api:read", "api:write"]
}

Response:

• active: true - Token is valid and contains the requested scopes
• active: false - Token is invalid, expired, revoked, or doesn't contain required scopes
• scope - Space-separated string of all scopes in the token
• scopes - Array of all scopes in the token

Strict Scope Validation:

To require that the token contains all specified scopes (not just one), use strictScopeValidation: true:

{
  "token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type_hint": "access_token",
  "scopes": ["api:read", "api:write"],
  "strictScopeValidation": true
}

• With strictScopeValidation: true: Token must contain ALL specified scopes
• With strictScopeValidation: false (default): Token must contain AT LEAST ONE specified scope

Combined Validation:

You can also validate scopes together with roles and groups:

{
  "token": "eyJhbGciOiJSUzI1NiIs...",
  "scopes": ["api:read"],
  "roles": ["ADMIN"],
  "strictValidation": true
}

• strictValidation: true - Requires ALL criteria (scopes AND roles AND groups) to pass
• strictValidation: false (default) - Requires AT LEAST ONE criteria to pass

Best Practice: Use online validation (introspection) when you need to detect revoked tokens or perform real-time validation. Use offline validation for performance-critical scenarios, but ensure tokens are properly signed and not expired.

For more details on the introspection API, see Token Introspection API documentation. For implementing scope validation in your application, see Permission Management.

Technical APIs

API	Description	Link to API
List all scopes	Retrieves a list of all available scopes	View API
Create or update scope	Creates a new scope or updates an existing scope. Note: This API is not allowed to create cidaas: scopes	View API
Get scope by key	Retrieves a specific scope by its scope key	View API
Delete scope	Deletes a scope identified by its scope key. Only custom scopes can be deleted	View API

Explore related topics

• App management
• Client secret rotation
• OAuth2 flows
• Permission management
• User groups and roles

---

Need help?

For assistance, visit our Support Portal.