Okta

• Users can request time-bounded access to your Okta groups, apps, and admin roles
• Auditors can initiate access reviews that assign managers or group admins to periodically review users with long-lived access to Okta groups, apps, and admin roles
• Admins can add resources from other Opal integrations to an Okta group so an Okta group’s members can automatically gain birthright access to, for example, a GitHub repo, AWS IAM role, etc.
• All access changes are tracked in a permanent audit log that can notify a Slack channel or be exported to your favorite tools.

​

Supported resources

​

Additional capabilities

​

Real-time sync

• New groups
• New apps
• Users added to groups or apps
• New apps added and removed to groups

​

Getting Started

• OAuth App (recommended): Opal authenticates as a dedicated Okta API Services app using a private key. No shared user account needed.
• API token: Opal authenticates as a real Okta user account using a static SSWS token. This method is still fully supported but requires a dedicated Okta user and manual token rotation.

• OAuth App
• API Token

Opal supports authenticating via an Okta API Services app using the OAuth 2.0 Client Credentials flow. This is the recommended method for new integrations.For a full overview of the Okta OAuth for service apps flow, see the Okta guide.

​

1. Create an API Services app in Okta

In Okta Admin Console, go to Applications > Applications > Create App Integration, and select API Services. Give the app a name (e.g. “Opal”) and save. In the app, navigate to General > General Settings. Find Proof of possession and make sure Require Demonstrating Proof of Possession (DPoP) header in token requests is unchecked.

Opal does not currently support DPoP.

​

2. Generate a private key

In the app, navigate to General > Client Credentials and click Edit. Switch the Client authentication method to Public key / Private key and click Add key > Generate new key.In the Private key - Copy this! dialog, select the PEM tab. Save the private key and the Key ID (kid) shown alongside the key. This key will only be shown once.

​

3. Grant OAuth scopes

On the app’s Okta API Scopes tab, grant the scopes that match what you want Opal to manage.

Required OAuth scopes	What Opal can manage
okta.users.read, okta.users.manage, okta.groups.read, okta.groups.manage, okta.apps.read, okta.apps.manage, okta.logs.read, okta.schemas.read, okta.roles.read, okta.roles.manage	Groups, apps, users, system log, custom attributes, and admin roles
okta.users.read, okta.users.manage, okta.groups.read, okta.groups.manage, okta.apps.read, okta.apps.manage, okta.logs.read, okta.schemas.read	Groups, apps, and users
okta.users.read, okta.users.manage, okta.groups.read, okta.groups.manage	Groups and users

​

4. Assign an admin role to the service app

OAuth scopes and admin roles are two separate and complementary authorization layers in Okta: Scopes define what actions the service app is allowed to request (e.g. read users, manage groups), while Admin roles define which resources those actions actually apply to.Both must be configured — granting scopes without an admin role causes Okta to accept the credentials and issue a token, but API calls will return empty results with no error.

Assign the minimum role needed for what you want Opal to manage. Following the principle of least privilege, avoid granting Super Admin unless you specifically need Opal to manage admin role assignments.On the service app detail page, go to the Admin roles > Edit assignments and assign the appropriate role:

What you want Opal to manage	Admin role required on the service app
Groups, apps, users, system log, custom attributes, and Okta admin role management	Super Admin
Groups, apps, users, system log, and custom attributes	Org Admin
Apps only (view and assign users to apps)	App Admin
Groups (view members and manage group memberships)	Group Admin
Group memberships only	Group Membership Admin

Okta also supports custom admin roles that let you scope permissions to specific resource sets rather than granting a broad built-in role. A custom role with the “Identity and Access Management” resource set is accepted by Opal as equivalent to Super Admin for admin role management.

Opal verifies the admin role assigned to the service app as part of its validation checks. This verification itself requires the service app to have Super Admin or a custom role with IAM permissions. If the service app has neither, Opal will show a warning that it could not verify admin role assignments, but core sync (users, groups, apps) will continue to work with Org Admin.

​

5. Upload credentials in Opal

In the Opal New App form, select OAuth App as the authentication method and fill in:

• Organization hostname: the hostname of your Okta org (e.g. mydomain.okta.com)
• Client ID: the Client ID shown on the app’s General tab
• Private Key PEM: the PEM key copied in Step 2
• Key ID: the kid value from Step 2 (optional if you have only one key registered)

The API token method is still fully supported. Use it if your Okta configuration does not permit API Services apps, or if you are migrating an existing integration.

If you have an existing Opal Okta integration using an API token, you can switch to OAuth App at any time from the Setup tab on the app detail page. Your saved API token is preserved as a fallback, and Opal only switches to OAuth once you save the new credentials. To remove the saved token after switching, check Remove saved API token when saving.

​

1. Configure an API token for Opal

Opal uses an Okta API token to connect to your Okta instance.We suggest that you create a separate Okta user that creates and owns the API token. This lets you customize the permission scopes available to Opal and ensure that these scopes don’t change. Additionally, Okta will log any access changes that Opal pushes to Okta under the separate account’s name.To create an account, follow these steps for adding a new user on Okta.Next, grant the appropriate permissions to your new account based on what you’d like Opal to manage. To do this, navigate to Security -> Administrators, and add the desired Okta Admin Roles from the following table:

Required Okta admin roles	What Opal can manage
Super Admin	Okta groups, apps, users, and admin roles
Organization Admin, Application Admin, Group Admin	Okta groups, apps, and users
Group Membership Admin, Read-Only Admin	Okta groups and users

Finally, generate an API token as the new account:

• Log in to the new account on Okta.
• Navigate to Security -> API.
• Click on the Tokens tab.
• Click Create Token on the top left.
• Record the generated token.

​

2. Upload your Okta credentials

Back in the Opal New App form, fill in details about your Okta organization:

• Organization hostname: enter the URL hostname of your Okta organization (e.g. “mydomain.okta.com”)
• API token: enter the API token you just created

If this step is successful, you’ve completed setting up the Okta App.

​

Run app validation checks

​

Automatic import (Okta groups only)

1. In Okta, create a custom group profile attribute opal
   • Navigate to Directory > Profile Editor, then select the desired group profile and click Add attribute.
   • Fill out the form as follows, and click Save:

2. Set the opal attribute to true for all Okta groups you want to auto-import.
3. Enable auto-import in Opal
   • Click into your newly-created Okta app by going to Apps on the left sidebar.
   • Click the Edit button
   • Next to Import Settings > Import setting. Toggle the setting to Auto-import tagged.