Custom OAuth 2.0 scopes in API Gateway
Custom OAuth 2.0 scopes in API Gateway allow you to define permission boundaries for non-Infor API access control. They are specifically designed for non-Infor API suites.
With custom scopes, you create named permissions, associate them with specific non-Infor API suites and non-Infor authorized applications, and enforce those permissions at the gateway level. When an application requests an access token, the scopes included in the token are determined by the intersection of the application's assigned scopes, the scopes in the token request, and the scopes configured on the service account or the scopes approved during user consent.
Key capabilities
Create tenant-specific OAuth 2.0 scopes with custom names and descriptions.
Associate scopes with non-Infor API suites to control API access.
Assign scopes to authorized applications to restrict each application's access to only the specific API suites it requires.
Who this affects
API administrators with the IONAPI-Administrator role create, manage, and associate custom scopes with API suites and authorized applications.
Application developers request appropriate scopes when configuring applications that consume non-Infor APIs.
Required permissions
Access to the API Gateway Admin UI is required.
The IONAPI-Administrator role in Infor OS > Security > User Management is required.
Custom scope lifecycle and relationships
Custom scope lifecycle
Create the scope with a unique name and optional description.
Associate the scope with one or more non-Infor API suites.
Assign the scope to authorized applications that require access to those suites.
Enable enforcement on the authorized application by turning on Enforce Scopes.
Configure the service account or consent flow. For backend applications, add the same scopes to the service account in Infor OS Security (IFS). For front-end applications, ensure that the scopes are available for user approval.
Include scopes in the token request. The client must explicitly pass the required scopes when requesting a token.
To create, associate, assign, enforce, and delete custom scopes, see Managing custom OAuth 2.0 scopes.
For implementation scenarios and configuration patterns, see Custom OAuth 2.0 scope usage examples in API Gateway.
Scope-to-suite-to-application relationship
A single scope can be associated with multiple API suites.
A single scope can be assigned to multiple authorized applications.
An API suite can have multiple scopes associated with it.
An authorized application can have multiple scopes assigned to it.
This many-to-many relationship provides flexibility to model access control requirements precisely.
Scope enforcement behavior
After scopes are assigned to an authorized application, enable enforcement so the gateway validates those scopes at runtime.
When Enforce Scopes is enabled, the gateway validates the application's token scopes against the target API suite's associated scopes on every request.
When Enforce Scopes is disabled, the gateway does not enforce scopes for tokens obtained by using that authorized application's credentials. Requests are allowed regardless of scope configuration.
Before you enable Enforce Scopes, ensure that scopes are assigned to the application and included in token requests.
Rules, limits, and auditing
Custom scope naming rules
| Rule | Details |
|---|---|
| Maximum length | 50 characters |
| Allowed characters | English characters only. Globalized characters are not allowed. |
| Reserved prefix | Must not start with infor-. This prefix is reserved for Infor system scopes. |
| Reserved name | Cannot be openid. This name is reserved for OpenID Connect. |
| Uniqueness | Each scope name must be unique within the tenant. |
Scope description rules
| Rule | Details |
|---|---|
| Maximum length | 500 characters |
| Allowed characters | Global characters are supported, including Chinese, Arabic, French, and other languages. |
Tenant scope limit
Each tenant can have a maximum of 100 custom scopes.
If you approach this limit, review existing scopes and consolidate or remove unused scopes.
Audit events
Custom scope operations generate audit events for compliance tracking and monitoring.
Auditable actions include scope creation, modification, deletion, and association changes.
These events are available through the standard audit event mechanisms in Infor OS.
Troubleshooting
Scope name rejected during creation
Possible causes: The name starts with infor-, is openid, exceeds 50 characters, contains non-English characters, or duplicates an existing scope.
Resolution: Verify that the name uses only English characters, is 50 characters or fewer, does not use reserved names or prefixes, and is unique within the tenant.
Scope selection list not visible on Authorized Apps page
Cause: Enable Scopes per authorized app is not turned on in OAuth 2.0 Settings.
Resolution: Navigate to Configuration > OAuth 2.0 Settings and turn on Enable Scopes per authorized app.
API Gateway returns 403 after scope configuration
Possible causes:
- The token request does not include the required scope.
- The scope is not associated with the target API suite.
- The authorized application does not have the scope assigned.
- Enforce Scopes is enabled but the token was requested without scopes.
- The token was issued before the scope association was configured.
- The scope name is inconsistent between the suite association and the application assignment.
- Target server policies or authentication settings are rejecting the request.
Resolution steps:
- Check both enforcement conditions. Verify that Enable Scopes per authorized app is turned on and the application's Enforce Scopes toggle is on.
- Verify that the scope is associated with the correct API suite. Check the scope's API Suites tab.
- Confirm that the application has the scope assigned. Check the scope's Authorized App tab.
- Verify that the scope name is consistent across all associations.
- Download the application's credentials and verify that the scope appears in the scopes list.
- Inspect the token request to ensure that the request includes the scope.
- Request a new access token. Tokens issued before scope changes do not reflect updated configuration.
- If the application calls both Infor and non-Infor suites, verify that the token includes the correct scope type for each suite.
- Review target server policies and authentication settings.
Cannot delete a custom scope
Cause: The scope is still associated with API suites or authorized applications.
Resolution: Open the scope details, remove all associations from the API Suites tab and Authorized App tab, then retry deletion.
Exceeding the 100-scope tenant limit
Resolution: Review existing scopes, consolidate scopes that serve similar purposes, and delete unused scopes.
Best practices
Naming conventions
Use descriptive, purpose-driven names such as inventory-access, order-management, and partner-data-access.
Establish a consistent naming pattern across the organization.
Avoid generic names such as scope1 or custom-scope.
Document the naming convention so all administrators follow the same pattern.
Access control design, lifecycle management, and security
For best practices on access control design, scope lifecycle management, token management, and security recommendations, see OAuth 2.0 scopes best practices.