> ## 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](/docs/least-privilege-posture-management) |
| ------------------------------ | ---- | ----------------------- | ------------------------------------------------------------------- |
| Okta Users and user attributes | ✔️   | ✔️                      | ✔️                                                                  |
| Okta Groups                    | ✔️   | ✔️                      | ✔️                                                                  |
| Okta Group Rules               | ✔️   | ✔️                      | ✔️                                                                  |
| Okta Roles                     | ✔️   | ✔️                      | ✔️                                                                  |
| Okta Apps                      | ✔️   | ✔️                      | ✔️                                                                  |

Note that the Okta integration does not support creating Okta users, groups, roles, or apps. 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](/integrations/okta#run-app-validation-checks) to confirm your Okta sync is working properly.

The Okta integration also supports user account [deprovisioning](/docs/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

## Getting Started

To get started, go to the **Inventory** page, click **+ App** at the top right. Then, click on the Okta Directory tile.

<img src="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" alt="2312" width="2560" height="1406" data-path="images/docs/396cedbe0c4d30cd857ebc63aec81b9829ef091d4b32d3d596c98699e9959fed-opal-101-apps-add-app.png" />

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.

<Tabs>
  <Tab title="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.
    </Note>

    ### 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

    <Info>
      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.
    </Info>

    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](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 (users, groups, apps) will continue to work with Org Admin.
    </Note>

    ### 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>

  <Tab title="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.
    </Note>

    ### 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.

    <img src="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" alt="" width="2267" height="1226" data-path="images/docs/a6b0fd9-Screenshot_2024-03-15_at_1.04.05_PM.png" />
  </Tab>
</Tabs>

***

## 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.

<img src="https://mintcdn.com/opalsecurity/KunPWigry5GIeB5g/images/docs/522e6ba2004d25b6c6f8d879ec92ce426e684073d49eb13ebe713c615a74a189-app-validations-okta.png?fit=max&auto=format&n=KunPWigry5GIeB5g&q=85&s=973b09847d958a17479fa971292d827f" alt="" width="2970" height="1202" data-path="images/docs/522e6ba2004d25b6c6f8d879ec92ce426e684073d49eb13ebe713c615a74a189-app-validations-okta.png" />

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:

<img src="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" alt="" width="1898" height="970" data-path="images/docs/1d06e37-Screen_Shot_2022-09-28_at_4.10.57_PM.png" />

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**.

<img src="https://mintcdn.com/opalsecurity/E-CmJXh0QNjZUl4g/images/docs/5fe4e1f-Okta-import-settings.png?fit=max&auto=format&n=E-CmJXh0QNjZUl4g&q=85&s=2b9ebd0c9f3d5af3180336c8423b456a" alt="2312" width="2958" height="1658" data-path="images/docs/5fe4e1f-Okta-import-settings.png" />

***