> ## Documentation Index > Fetch the complete documentation index at: https://docs.opal.dev/llms.txt > Use this file to discover all available pages before exploring further. # Okta > Connect your Okta instance to use Opal to manage and review access. Opal's integration with Okta lets you manage access to your Okta groups, applications, users, and admin roles. Our integration supports the following, and more: * 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 | Resource | Read | Grant and revoke access | Included in [Risk Center](https://docs.opal.dev/docs/least-privilege-posture-management.md) | | - | - | - | - | | Okta Users and user attributes | ✔️ | ✔️ | ✔️ | | Okta Groups | ✔️ | ✔️ | ✔️ | | Okta Group Rules | ✔️ | ✔️ | ✔️ | | Okta Roles | ✔️ | ✔️ | ✔️ | | Okta Apps | ✔️ | ✔️ | ✔️ | Note that the Okta integration does not support creating Okta groups, roles, or apps. Okta users can only be created through [user provisioning](#user-provisioning). It also does not yet support syncing Okta API tokens nor Okta OAuth apps. ## Additional capabilities The Okta integration also supports automatic **real-time sync**, which syncs groups and resources as soon as they're updated in Okta. You can also run automatic [validation checks](https://docs.opal.dev/integrations/okta.md#run-app-validation-checks) to confirm your Okta sync is working properly. The Okta integration also supports user account [provisioning and deprovisioning](#user-provisioning). ### Real-time sync Opal automatically enables real-time sync for Okta integrations. When access changes occur in Okta, Opal automatically syncs and reflects the change. Real-time sync includes: * New groups * New apps * Users added to groups or apps * New apps added and removed to groups For user changes, real-time sync (behind a feature flag) can also refresh a user's name, manager, title, and custom attributes, and promote their IDP Status (for example, from suspended to active) when Okta reports the change. A user being suspended or deactivated in Okta is reflected in IDP Status by the hourly IDP sync. See [sync schedules and triggers](https://docs.opal.dev/docs/sync-schedules-and-triggers.md) for details. ## Getting Started To get started, go to the **Inventory** page, click **+ App** at the top right. Then, click on the Okta Directory tile. ![2312](https://mintcdn.com/opalsecurity/fu-nWazMe1LxLhxi/images/docs/396cedbe0c4d30cd857ebc63aec81b9829ef091d4b32d3d596c98699e9959fed-opal-101-apps-add-app.png?fit=max\&auto=format\&n=fu-nWazMe1LxLhxi\&q=85\&s=9ce79a7a424f7d3db46e96abb2a411ff) You will see a form to be completed. Opal requires credentials to connect to your Okta instance. There are two supported authentication methods: * **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. > [tab] OAuth App > > 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](https://developer.okta.com/docs/guides/implement-oauth-for-okta-serviceapp/main/). > > ### 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. > > > [!NOTE] > > > > 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 > > > [!NOTE] > > > > 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, users, system log, and custom attributes (no apps) | **Org Admin** | > | Apps only (view apps and assign users and groups to apps) | **App Admin** | > | Groups (view members and manage group memberships) | **Group Admin** | > | Group memberships only | **Group Membership Admin** | > | Groups, apps (including user and group assignments), users, system log, and custom attributes | **Org Admin** and **App Admin** | > > Okta also supports [custom admin roles](https://help.okta.com/oie/en-us/content/topics/security/custom-admin-role/about-creating-custom-admin-roles.htm) 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. > > > [!NOTE] > > > > 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 of users and groups will continue to work with Org Admin. To also sync apps and manage user and group assignments to apps, assign App Admin alongside 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) > [tab] API Token > > 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. > > > [!NOTE] > > > > 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](https://help.okta.com/en-us/Content/Topics/users-groups-profiles/usgp-add-users.htm) 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. > > ![](https://mintcdn.com/opalsecurity/lt0M-hBs5yNe5ff5/images/docs/a6b0fd9-Screenshot_2024-03-15_at_1.04.05_PM.png?fit=max\&auto=format\&n=lt0M-hBs5yNe5ff5\&q=85\&s=be649770b34075af6947d6f52df6f992) *** ## Run app validation checks After you save your app, you can view existing sync issues from the **Setup** tab on the app detail page. Missing permissions and sync issues show in the **App Validations** section. Select the refresh icon to rerun validation checks. ![](https://mintcdn.com/opalsecurity/KunPWigry5GIeB5g/images/docs/522e6ba2004d25b6c6f8d879ec92ce426e684073d49eb13ebe713c615a74a189-app-validations-okta.png?fit=max\&auto=format\&n=KunPWigry5GIeB5g\&q=85\&s=973b09847d958a17479fa971292d827f) You can hover over the validation icons to learn why Opal needs a given permission. To correctly sync your app to Opal, ensure you address any sync errors, marked with the red ! icon. Inspect warnings on a case-by-case basis: warnings might impact features you're not using and may be safely ignored, but this depends on your use case. ## Automatic import (Okta groups only) You can configure your Okta groups to be auto-imported into Opal each time the Okta app is synced. Sync happens throughout the day, approximately once an hour. Sync can also be manually triggered by an admin by clicking the Sync button in the top-right of the app. 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: ![](https://mintcdn.com/opalsecurity/TlQj9FwRe9HHNEYB/images/docs/1d06e37-Screen_Shot_2022-09-28_at_4.10.57_PM.png?fit=max\&auto=format\&n=TlQj9FwRe9HHNEYB\&q=85\&s=f0d0da98e1741663e445b2f37cb4a82f) 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**. ![2312](https://mintcdn.com/opalsecurity/E-CmJXh0QNjZUl4g/images/docs/5fe4e1f-Okta-import-settings.png?fit=max\&auto=format\&n=E-CmJXh0QNjZUl4g\&q=85\&s=2b9ebd0c9f3d5af3180336c8423b456a) ## User provisioning Opal can automatically provision and deprovision users in Okta. When provisioning is enabled, users who don't already have an Okta account are automatically created when they are granted access to an Okta group or resource. Opal matches existing users by email, and creates new users with their name and email from Opal, using their email as the Okta username. Deprovisioning deactivates users in Okta when you deprovision them manually, revoke their account in an access review, or when they're deprovisioned in your IdP or HRIS. This is configurable in **Setup > Edit > Provision Okta users** and **Deprovision Okta users**. For more details, see [User provisioning](https://docs.opal.dev/docs/user-provisioning.md). *** This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.