Okta Selective Scope Requests Using Step-up Authentication

Organizations encounter scalability and security challenges when utilizing a standard frontend OpenID Connect (OIDC) authorization flow for complex user permission matrices. Okta Authorization Servers evaluate and grant scopes at the exact moment the client application makes the request, which leaves the backend unaware of specific custom scopes. Administrators resolve this limitation by implementing step-up authentication, scope-dependent custom claims, or backend policy enforcement.

• Okta Identity Engine (OIE)
• Okta Classic Engine
• Step-up Authentication
• Custom Scopes
• Custom Roles

Okta Authorization Servers evaluate and grant scopes at the moment the client application makes the /authorize or /token request. If a frontend application natively requests a generic scope string (for example, openid profile email groups), Okta only returns user identity and group memberships, leaving the application's backend unaware of which specific custom scopes (such as accounts:read or phd:write) are legally allowed or required for the target APIs.

Furthermore, custom scopes and custom scope-dependent claims require API Access Management (AM) SKU and must be evaluated by a Custom Authorization Server; they are not supported by the built-in Org Authorization Server (https://{exampleOktaDomain}/oauth2/v1/authorize).

How are permission levels managed across components and APIs?

Manage permission levels across multiple components and APIs by implementing step-up authentication, configuring scope-dependent custom claims, or enforcing backend policies.

Implement Step-up Authentication for Selective Scope Requests

Instead of requesting all administrative scopes during the initial login, the application performs a second authorization request only when needed. 

• The application first requests base OAuth 2.0 scopes (such as openid and profile).
• Once the user authenticates, the application inspects the groups claim.
• If it detects an admin group, the application initiates a new /authorize request for the higher-privilege scopes.

Configure Scope-dependent Custom Claims

Configure the Authorization Server to release specific claims only when the application requests a corresponding custom scope by creating a custom scope and mapping it to the group claim.

1. Create a custom scope (for example, api:admin).
2. Configure a custom claim for the group information.
3. Set the Include in field to The following scopes and select the custom scope. This ensures that the token only presents sensitive group data when Okta successfully grants that specific scope.

Enforce Backend Policies

To avoid the complexity of front-end redirects, move the authorization logic to the API Gateway or backend services.

• The front-end always requests a standard set of scopes.
• The backend API receives the access token, extracts the user groups from the ID token or access token, and performs a check against the group pattern (for example, group-*-test) to permit or deny the action.