API Gateway support for custom OAuth 2.0 scopes

What are OAuth 2.0 scopes?

OAuth 2.0 scopes define permissions that control the level of access an application has to a user's data. They ensure that a client application performs only authorized actions. For example, an access token may allow READ and WRITE access or just READ access. A token with READ scope lets the client retrieve information, but not modify it. A WRITE scope allows both reading and updating data.

Scopes improve security by limiting access to sensitive data and functionality. They also offer flexibility in managing access by letting administrators assign scopes based on the application's and user's needs. Each application receives only the permissions it requires, minimizing the risk of unauthorized access.

Custom scopes offer more granular control over API access. You can define permissions precisely and enable applications to interact with APIs securely. Custom scopes help API Gateway administrators tailor permissions to specific needs, enhancing security and access management.

Business benefits of Scopes:

• Enhanced security – Scopes allow precise control over API access. You can restrict access to specific API suites using tenant-level scopes, so only authorized applications make API calls.
• Flexibility – Create and manage scopes that suit your needs. You can associate them with different API suites and Authorized Applications.

What are custom OAuth2.0 scopes

Custom scopes in API Gateway are user-defined OAuth 2.0 scopes. They specify access levels for non-Infor API suites. As an administrator, you can use them to control and limit API calls through API Gateway.

Benefits of custom scopes in API Gateway:

In addition to general benefits, custom scopes offer:

1. Globalization support. You can include descriptions in global languages like Chinese, Arabic, French, and Spanish.
2. Improved user experience. The API Gateway UI simplifies creating, managing, and associating custom scopes. Features like search, sorting, and tile-based displays enhance usability.
3. Audit and monitoring. You can track scope-related activities using audit events, which supports compliance and security efforts.

Examples:

• ReadOnlyScope. Grants read-only access to specific endpoints.
• AdminScope. Allows management of user roles, settings, and configurations.
• HRScope. Gives access to employee data, payroll, and HR systems based on the user's HR role.

Required role to access custom scopes

To manage custom scopes, you need the IONAPI-Admin role in the User Management system. This role grants permissions to create, edit, and configure scopes. It also lets you associate scopes with API suites and applications.

Creating a custom scope

Steps:

1. Verify Role. Make sure you have the IONAPI-Admin role.
2. Open IONAPI UI. Go to the interface and find OAuth2.0 Custom Scopes under OAuth2.0 Settings.
3. Add Scope. Click '+ Add' and provide details:
   • Name. Enter a valid name (only English characters allowed).
   • Description. Optionally, add a description using global characters.
4. Save. Click Save to create the scope.

Associating a custom OAuth 2.0 scope with an API suite

1. Open the custom scopes page

   In the IONAPI interface, go to OAuth2.0 Settings and select OAuth2.0 Custom Scopes.

   Click the name of the custom scope you want to associate with an API suite.

2. Link the custom scope to API suites
   1. Scroll to the API Suites tab at the bottom of the custom scope page.
   2. Click the '+' icon to open the selection UI for non-Infor API suites.
   3. In the search bar, type the name of the API suite. Matching results appear in a dropdown.
   4. Select the desired suite(s) and click Associate. The system automatically saves your changes.
   5. Associated suites are listed under the API Suites tab, and the same custom scope appears on each suite’s details page for clear cross-reference.

Associating a Custom OAuth 2.0 Scope with an Authorized App

1. Enable Scope toggle
   • In the IONAPI Admin UI, open Configuration > OAuth2.0 Settings.
   • Turn on 'Enable scopes per authorized app' to activate the scope dropdown for all apps.
2. Assign a custom scope to an App
   • Open the Authorized Apps page and find the app that needs the custom scope.
   • In the Scope dropdown, type the scope name. Matching scopes appear as you type.
   • Select the scope to complete the association.
   • To verify, download the credentials and check the scopes list. The custom scope should be included.
   • The association also appears under the Authorized App tab of the scope, helping you track and manage linked apps.

This process mirrors how standard scopes are associated, ensuring a consistent and familiar experience. Following these steps helps you manage custom scopes efficiently and securely across your system.

Deleting a custom scope

1. Check Associations. Ensure the scope is not linked to any suite or app.
2. Open Custom Scopes List. Locate the tile for the scope.
3. Delete. Hover to reveal the delete option and confirm the action.

Limitations of custom OAuth 2.0 scopes

Scope limit per tenant

You can create up to 100 custom scopes per tenant. This limit helps keep the system manageable and avoids clutter that could complicate authorization and permission management.

Scope name validations

Custom scopes must follow these naming rules to ensure consistency and prevent conflicts:

• The name must not start with the prefix infor-. This prefix is reserved and using it causes conflicts and integration issues.
• The name can be up to 50 characters long to maintain clarity and ease of management.
• The description cannot exceed 500 characters. Keep descriptions concise to clearly explain each scope’s purpose.
• Each scope name must be unique. Duplicate names are not allowed to avoid confusion in authorization management.
• The name cannot be openid since this is reserved for OpenID Connect and using it can interfere with authentication processes.
• Custom scope names do not support globalized characters.

Troubleshooting custom scopes issues

When working with custom OAuth 2.0 scopes, you might encounter various issues that affect scope creation, association, or API access. This table outlines common problems and provides practical solutions to help you quickly identify and resolve these issues. Following these guidelines ensures your authorization system remains efficient, secure, and well-integrated within your environment.

Issue	Description	Solution
Scope name conflicts	Custom scope name conflicts with reserved prefixes or existing scopes.	Avoid names starting with "infor-" or "openid". Make sure each scope name is unique and does not duplicate existing ones.
Exceeding character limits	Scope name or description exceeds allowed length.	Keep scope names less than or equal to 50 characters and descriptions less than or equal to 500 characters. Shorten if necessary.
Globalization issues	Scope names contain unsupported globalized characters.	Use only universally supported characters; avoid special or locale-specific characters.
Authorization errors	Authorization fails due to misconfigured scopes.	Verify scope names and descriptions to meet guidelines. Confirm scopes are correctly defined and integrated.
Exceeding scope limits	Tenant exceeds the maximum allowed number of custom scopes.	Review scopes, consolidate or delete unnecessary ones to stay within the 100-scope tenant limit.
Integration problems	Custom scopes cause integration issues with other systems.	Confirm names and descriptions comply with integration requirements. Avoid reserved prefixes or conflicting names.
Scopes not visible in Authorized App page	Scope dropdown does not appear in Authorized App details.	Ensure the Scopes toggle is enabled under Configuration > OAuth2.0 Settings.
API Gateway returns 403 after scope association	API calls return 403 Forbidden errors after associating custom scopes.	Check token requests include all required custom scopes. Confirm custom scope matches API suite. Review target server policies and authentication settings.