Reassigning applications to a different Okta Authorization Server requires migrating group claims, configuring custom scopes, and updating authorization endpoints. Administrators must move applications between a custom Authorization Server and the Org Authorization Server, or between two custom Authorization Servers.

• Okta Identity Engine (OIE)
• Okta Classic Engine
• Authorization Servers
• Custom Authorization Server
• Org Authorization Server

Which steps identify the current Authorization Server?

Identify the Authorization Server currently used by an application by reviewing the System Log events in the Okta Admin Console.

1. Navigate to Reports > System Log in the Okta Admin Console.

2. Enter the following query in the System Log search bar (replace 0oa123456789 with the target Okta Application ID):

   actor.id eq "0oa123456789" AND (eventType sw "app.oauth2.token.grant." OR eventType sw "app.oauth2.as.token.grant." OR eventType sw "app.oauth2.authorize.implicit." OR eventType sw "app.oauth2.as.authorize.implicit.") AND outcome.result eq "SUCCESS"

3. Review the returned eventType to determine the Authorization Server type:

   • Custom Authorization Server: Event types contain .as. (for example, app.oauth2.as.token.grant.access_token).

   • Org Authorization Server: Event types do not contain .as. (for example, app.oauth2.token.grant.access_token).

Moving Applications From Custom Authorization Server to Org Authorization Server

Migrate group claims, verify grant types, update endpoints, and remove the application assignment to move applications from a custom Authorization Server to the Org Authorization Server.

1. Migrate Group Claims: Move any existing group claims from the custom Authorization Server to the application level, as the Org Authorization Server does not support custom claims.
2. Check for Custom Scopes/Claims: Custom scopes are not supported on the Org Authorization Server.
   • However, custom claims that need to appear in the ID Token or via the /userinfo endpoint can be replicated using Federated Claims (Okta Admin Console > Applications > [app] > Sign On tab > Token claims section), which supports Okta Expression Language sourced from user profile attributes, group affiliations, device profile attributes, entitlements (requires Okta Identity Governance), and session data. 
   • Access Tokens cannot carry custom claims or custom scopes on the Org Authorization Server. If downstream services rely on custom claims or group memberships inside the Access Token itself (rather than the ID Token), that capability will break after migration, and there is no workaround on the Org AS.
3. Verify Grant Types: Ensure the application's general settings in Okta have the required Allowed Grant Types enabled (for example, Authorization Code, Client Credentials, Implicit), as the Org Authorization Server relies entirely on application-level grant type settings rather than Access Policy rules.
4. Update Endpoints: Change the authorization endpoints in the application's source code to match the Org Authorization Server endpoints (for example, https://{OktaOrgUrl}/oauth2/v1/authorize).
5. Remove Application Assignment: Navigate to Security > API > Access Policies on the custom Authorization Server and remove the application's assignment.

NOTE:

• Groups Claim Behavior: On the Org Authorization Server, group claims are managed directly within the Application Settings and are returned primarily in the ID Token or via the /userinfo endpoint (often referred to as "fat ID tokens").
• Built-in groups Scope: The Org Authorization Server supports a built-in groups claim configured at the app level, so custom scopes do not need to be created on the server.

Moving Applications From Org Authorization Server to Custom Authorization Server

Migrate group claims, configure custom scopes, configure access policy rules, update endpoints, and add the application to the policy to move applications from the Org Authorization Server to a custom Authorization Server.

1. Migrate Group Claims: Move group claims from the application level to the custom Authorization Server's claim rules.
2. Configure Custom Scopes/Claims: Create and configure any necessary custom scopes and claims on the new custom Authorization Server (Security > API > Authorization Servers > [server] > Claims).
   • This is required if the application currently gets its custom data via Org AS mechanisms using the legacy Profile Editor attribute-mapping method (How to add custom attributes of user profile as claims in token). On a Custom AS, any equivalent claim must be explicitly recreated using an expression such as appuser.{$customAttribute}, with the option to include it in the ID Token, Access Token, or both. 
   • If they were instead configured as Federated Claims (in the Token Claims section on the Sign On/Authentication tab for the application), they will automatically appear in the ID Token/Userinfo Endpoint for a Custom Authorization Server and will not need to be recreated.
3. Configure Access Policy Rules & Grant Types:
   1. Navigate to Security > API > Authorization Servers > select the Custom Authorization Server > Access Policies.
   2. Add or edit an Access Policy Rule assigned to the application, and explicitly check/enable the required Grant Types (for example, Authorization Code, Client Credentials, Resource Owner Password) under the rule conditions.
4. Update Endpoints: Change the authorization endpoints in the application's source code to match the new custom Authorization Server's endpoints (for example, https://{OktaOrgUrl}/oauth2/{authServerId}/v1/authorize).
5. Add Application to Policy: Navigate to Security > API > Access Policies on the custom Authorization Server and add the application to the relevant policy or choose to apply it to all clients.

Scopes & Claims Configuration Differences

Moving Applications From One Custom Authorization Server to Another Custom Authorization Server

Migrate group claims, configure custom scopes, replicate access policy rules, update endpoints, and update the application assignments to move applications between custom Authorization Servers.

1. Migrate Group Claims: Move any existing group claims from the old custom Authorization Server to the new one.
2. Configure Custom Scopes/Claims: Configure any custom scopes and claims on the new custom Authorization Server and then remove them from the old one.
3. Replicate Access Policy Rules & Grant Types: Ensure the new custom Authorization Server's Access Policy rules have the appropriate Grant Types enabled for the application.
4. Update Endpoints: Change the authorization endpoints in the application's source code to match the new custom Authorization Server's endpoints.
5. Remove Application from Old Server: Navigate to Security > API > Old Authorization Server > Access Policies and remove the application.
6. Add Application to New Server: Navigate to Security > API > New Authorization Server > Access Policies and add the application.

 

Related References

• System Logs
• System logs event types
• Add groups claims to the org authorization server
• Add groups claims to the custom authorization server
• Request a token that contains a custom claim
• Adding custom profile attributes as claims in tokens
• Org authorization server discovery endpoints
• Default custom authorization server discovery endpoints
• Custom authorization server discovery endpoints
• Configure an access policy
• Federated claims overview
• When to Use the Org Authorization Server vs a Custom Authorization Server 
• How to add Custom Attributes of User Profile as Claims in Tokens