> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravenna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Okta Identity Governance sync

> Sync Okta Identity Governance requestable access into Ravenna as access levels and file OIG access requests when users request them in Ravenna.

Okta Identity Governance (OIG) sync brings the requestable access in your OIG catalog into Ravenna as access levels. Users request that access in Ravenna, and Ravenna files the request in OIG. OIG then runs its own approval and provisioning.

Use it when OIG is the system of record for access approvals and you want users to request access from Ravenna.

## Prerequisites

* An Okta tenant with Okta Identity Governance and Access Requests enabled
* The Okta integration connected with either [setup method](/integrations/okta/setup/overview)
* Okta applications and groups already synced into Ravenna. Ravenna maps catalog entries to them, so entries for unsynced apps or groups are skipped until they sync.

## Required scopes and role

OIG sync needs three scopes beyond the standard set, plus the **Access Requests Administrator** admin role on the app.

* **Client Secret:** the Ravenna app from the Okta OIN marketplace sets up the scopes and the role for you, so there's nothing to configure.
* **Private Key:** grant the scopes on your Okta API service app alongside the [standard scopes](/integrations/okta/setup/private-key#create-okta-api-service-integration-manually), then assign the role. In Okta, open the app under **Applications > Applications**, grant the scopes on the **Okta API Scopes** tab, and assign the role on the **Admin Roles** tab. The role also includes app assignment management.

| Scope | What Ravenna uses it for |
| - | - |
| `okta.accessRequests.catalog.read` | Read the OIG catalog to sync requestable access as access levels |
| `okta.accessRequests.request.read` | Read the access requests Ravenna files in OIG |
| `okta.accessRequests.request.manage` | File access requests in OIG and cancel them when access is revoked |

All three are required. Ravenna requests them together for every OIG call, so a missing scope blocks the sync and requests alike.

<Note>
  OIG uses the v2 Access Requests API, which rejects the older `okta.governance.accessRequests.*` scope names. Grant the `okta.accessRequests.*` scopes listed above.
</Note>

The governance scopes are optional for everything else. Ravenna checks for them only when OIG sync is turned on, and integrations that don't use OIG keep working without them.

## Turn on OIG sync

<Steps>
  <Step title="Grant the scopes and role">
    With Private Key, grant the three `okta.accessRequests.*` scopes and assign the **Access Requests Administrator** role to your Okta API service app. With Client Secret, skip this step.
  </Step>

  <Step title="Enable the setting">
    Go to **Settings > Integrations**, open the **⋯** menu on the Okta integration, and choose **Configure**. Turn on **Sync OIG requestable access as access levels**.
  </Step>

  <Step title="Run a sync">
    Choose **Resync** from the same **⋯** menu, or wait for the next scheduled sync (every 6 hours by default). If Ravenna can't read the OIG catalog, the integration status turns yellow and its tooltip shows a **Missing Okta Identity Governance access** warning.
  </Step>
</Steps>

## How the sync works

On each Okta sync, after groups sync, Ravenna reads the OIG catalog and turns every requestable entry into an access level. If the group sync fails, Ravenna skips the catalog for that run.

* **Application entries:** an entry under an Okta application becomes an access level on the matching Ravenna application.
* **Group entries:** an entry tied to an Okta group becomes an access level on each Ravenna application that group grants. Ravenna also maps the access level to that group. Entries for groups that grant no application are skipped.

Synced access levels use the <Badge color="gray" size="sm" stroke>External</Badge> provisioning method. Okta owns them, so every field except **Access Policy** is read-only in Ravenna. New levels attach to your default access policy, which decides who can request the level and whether the request needs approval in Ravenna before it's filed in OIG.

When an entry leaves the OIG catalog, Ravenna archives its access level. If the entry returns, Ravenna unarchives it. A level isn't archived while its Okta application or group is still waiting to sync into Ravenna.

<Note>
  Turning the setting off stops the catalog sync, but access levels it already created stay active. Requests for them are still filed in OIG.
</Note>

<Callout icon="link" color="#6B7280">Learn more about [external access levels](/documentation/automate/access-provisioning/applications#external-access-levels)</Callout>

## How requests work

<Steps>
  <Step title="The user requests access in Ravenna">
    The user picks an external access level, and the request goes through the level's access policy.
  </Step>

  <Step title="Ravenna files the request in OIG">
    After the request is approved in Ravenna, Ravenna files an OIG access request for the requester against the matching catalog entry.
  </Step>

  <Step title="OIG approves and provisions">
    OIG runs its own approval and provisioning. Ravenna marks the entitlement <Badge color="gray" size="sm" stroke>Skipped Provisioning</Badge> with the reason "Filed with OIG; approval and provisioning are owned by the external system", and tells the requester their request was forwarded. For group-based levels, the new group membership appears in Ravenna on the next Okta sync.
  </Step>
</Steps>

Ravenna doesn't follow the OIG request after filing it. Track approval in Okta. If OIG denies the request or it expires, the entitlement stays **Skipped Provisioning** in Ravenna.

When Ravenna revokes an entitlement that was filed with OIG, it cancels the matching OIG access request. Canceling the request doesn't remove access OIG has already granted, so remove that access in Okta.

<Note>
  Ravenna files each request as a self-request for the requester. If provisioning retries, Ravenna reuses the request it already filed instead of filing a new one.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Missing Okta Identity Governance access warning">
    **Cause**: Ravenna's connection check couldn't read the OIG catalog. Usually a scope or the role is missing on the app.

    **Solution**:

    * With Private Key, grant `okta.accessRequests.catalog.read`, `okta.accessRequests.request.read`, and `okta.accessRequests.request.manage` on the app, and assign the **Access Requests Administrator** role
    * With Client Secret, confirm OIG and Access Requests are enabled in your Okta tenant. The app includes the scopes and role, so contact Ravenna support if the warning persists.
    * Choose **Resync** from the **⋯** menu on the Okta integration

    **Behavior**: The check only reads the catalog. If the catalog syncs but requests fail, check that a Private Key app has `okta.accessRequests.request.manage` and the role.
  </Accordion>

  <Accordion title="A catalog entry has no access level in Ravenna">
    **Cause**: Ravenna couldn't match the entry to a synced application or group, or the entry isn't requestable.

    **Solution**:

    * Confirm the entry is requestable in OIG
    * Confirm the Okta application or group behind it has synced into Ravenna
    * For group entries, confirm the group grants at least one application
    * Run another sync after the application or group appears in Ravenna
  </Accordion>

  <Accordion title="A request shows Failed Provisioning">
    **Cause**: Ravenna couldn't file the request in OIG. Most often the requester has no Okta user linked in Ravenna, or the app is missing `okta.accessRequests.request.manage`.

    **Solution**:

    * Confirm the requester has an Okta user and that it has synced into Ravenna
    * With Private Key, confirm the app has all three `okta.accessRequests.*` scopes and the **Access Requests Administrator** role
    * Submit the request again once both are in place
  </Accordion>

  <Accordion title="A request is approved in Ravenna but the user has no access">
    **Cause**: Ravenna filed the request, and OIG still owns approval and provisioning. Ravenna doesn't reflect OIG approvals, denials, or expirations.

    **Solution**:

    * Find the request in OIG Access Requests and check its status
    * For group-based levels, run a sync after OIG grants access so the membership shows in Ravenna
  </Accordion>
</AccordionGroup>


## Related topics

- [Client secret setup](/integrations/okta/setup/client-secret.md)
- [Private key setup](/integrations/okta/setup/private-key.md)
- [Applications](/documentation/automate/access-provisioning/applications.md)
- [Overview](/integrations/okta/overview.md)
- [Access provisioning](/documentation/automate/access-provisioning/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.