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
• 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, 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 from the Admin roles tab with Edit assignments. 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
okta.accessRequests.condition.read	Read OIG request conditions to sync who is eligible to request each access level

The first three are required. Ravenna requests them together for every OIG call, so a missing one blocks the sync and requests alike. okta.accessRequests.condition.read is optional: without it, access levels still sync but who is eligible to request them isn’t.

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

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

1. Grant the scopes and role

   With Private Key, grant the three required okta.accessRequests.* scopes and assign the Access Requests Administrator role to your Okta API service app. Also grant okta.accessRequests.condition.read to turn on eligibility sync. With Client Secret, the installed app sets up the scopes and role, so skip this step. Its scopes can’t be changed, so if eligibility doesn’t sync, switch to Private Key to grant okta.accessRequests.condition.read.

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

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

How the sync works

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

• Application entries: an entry under an Okta application becomes one access level per active OIG request condition that covers it, on the matching Ravenna application. An access policy in Ravenna is an access condition in OIG, so each level copies its own condition: who can request it and for how long. A condition that covers several groups or bundles produces one level per group or bundle, since an OIG request grants one of them.
• 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.

Levels are named after the condition (for example Everyone). When one condition covers several groups or bundles, each level adds its own name (Contractors — Read Only, Contractors — Admins).

When several conditions cover the same entry, a requester is only offered the highest-priority one they’re eligible for, which is the condition OIG applies to their request. The other levels stay on the application for requesters who only match those conditions.

Synced access levels use the External provisioning method and an External access policy. Okta owns both, so they’re read-only in Ravenna. The access level shows what came from Okta: who is eligible to request it and, for group-scoped entries, the group it provisions into. Whether a request needs approval in Ravenna before it’s filed in OIG is copied from your default access policy when the level is first synced. See eligibility sync.

When an entry leaves the OIG catalog, or the condition behind a level is deleted or deactivated, Ravenna archives the access level. If it returns, Ravenna unarchives it. A level isn’t archived while its Okta application or group is still waiting to sync into Ravenna, or while no active condition covers its entry.

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

Eligibility sync

On each sync, Ravenna copies each level’s OIG request condition onto its External access policy. Who can request a level in Ravenna then matches who can request it in OIG, so users don’t file requests OIG will refuse.

The sync owns these policy settings:

Setting	Value Ravenna syncs
Eligible Groups	The requester groups of the level’s OIG request condition, mapped to the matching Ravenna user groups. A condition that allows Everyone gives the level no eligible groups, so all users can request it.
Access duration	The condition’s access duration: a fixed duration, or a choice up to the condition’s maximum.
Questions	The requester questions on the condition’s approval sequence. Ravenna reads them as a user the condition applies to, so a condition whose requester groups have no synced members keeps the questions it had.
Expiry	Always No expiry. OIG owns how long access lasts.
Ineligible groups	Always cleared. OIG conditions have no exclusions.

The first time Ravenna moves a level onto an External policy, it copies the level’s current policy, including whether a request needs approval in Ravenna before it’s filed in OIG. A new level starts from a copy of your default access policy. After that, the approval settings aren’t editable on the level.

On external levels, the access level form shows Access Policy as External and Eligible Groups locked, and hides the other policy settings. You can’t change an external level’s policy, including with the bulk Set Policy action.

Eligibility sync needs the optional okta.accessRequests.condition.read scope. Without it, Ravenna can’t see the conditions, so it syncs one access level per catalog entry, on an External policy with no expiry and no eligible groups. Once the scope is granted, that level becomes the entry’s highest-priority condition’s level and keeps its id and history; the other conditions get their own levels. The sync status reports Request conditions could not be read: grant okta.accessRequests.condition.read to sync eligibility.

Ravenna leaves a level’s eligible groups as they were when it can’t fully resolve them. This happens when:

• A requester group in the OIG condition hasn’t synced into Ravenna yet
• The condition uses a requester type other than Everyone or groups
• The entry is owned by a group rather than an Okta application

Ravenna never opens a level to everyone because it couldn’t read OIG. OIG still checks its own conditions when Ravenna files the request.

Learn more about external access levels

How requests work

1. The user requests access in Ravenna

   The user picks an external access level, and the request goes through the level’s access policy. The request form asks the questions synced from the level’s OIG approval sequence, so OIG gets the answers it requires.

2. Ravenna files the request in OIG

   After the request is approved in Ravenna, Ravenna asks OIG once more what it requires for this requester and files an OIG access request against the matching catalog entry. If OIG’s questions changed since the last sync, the request fails with a message on the ticket asking to resync the integration and request again, instead of OIG rejecting it silently.

3. OIG approves and provisions

   OIG runs its own approval and provisioning. Ravenna marks the entitlement and the access request Submitted and tells the requester their request was forwarded. The ticket stays open until OIG decides. The ticket timeline shows that Ravenna submitted the access request to the connected system. For group-based levels, the new group membership appears in Ravenna on the next Okta sync.

How Ravenna follows the request

Every 5 minutes, Ravenna checks OIG for each request it filed that’s still Submitted.

What happens in OIG	Entitlement in Ravenna	On the ticket
Approved and access granted	Active	Reply to the requester that their access is ready
Approved, but Okta couldn’t grant it	Failed Provisioning	Reply to the requester, plus a private note with the error
Denied, canceled, or expired	Failed Provisioning, with the reason	Reply to the requester saying who decided
Okta rejects the request right after it’s filed, for example a required access duration or question was missing	Failed Provisioning, with the reason	Reply to the requester, plus a private note with the reason and a link to search Okta’s System Log for the request

The access request follows its entitlement to Provisioned or Failed. When OIG grants access, Ravenna closes the ticket, the same as any other provisioned request. Otherwise the ticket stays open.

Ravenna reports the final outcome only. OIG runs each approval step as a task in Okta Access Requests and doesn’t report a step’s approval on the request until the whole sequence finishes, so a request stays Submitted in Ravenna while it moves through its approvers.

A submitted request can still be withdrawn. When Ravenna revokes a submitted entitlement, it cancels the matching OIG access request. Ravenna doesn’t remove access OIG has already granted, so revoking an active OIG entitlement in Ravenna is skipped. Remove that access in Okta.

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.

Troubleshooting

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.

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

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

An external access level's eligible groups don't match OIG

Cause: Ravenna couldn’t read the OIG request conditions or couldn’t fully resolve them, so it kept the level’s previous eligible groups.

Solution:

• Check the Okta integration’s sync status for Request conditions could not be read. With Private Key, grant okta.accessRequests.condition.read on the app.
• Confirm every requester group in the OIG request condition has synced into Ravenna
• Confirm an active request condition covers the catalog entry
• Choose Resync from the ⋯ menu on the Okta integration

A request is Submitted in Ravenna but the user has no access

Cause: OIG hasn’t finished approving or granting the request. Ravenna checks OIG every 5 minutes and updates the entitlement once OIG grants, denies, cancels, or expires it.

Solution:

• Find the request in OIG Access Requests and check who it’s waiting on
• If OIG already shows a final status, wait up to 5 minutes for Ravenna’s next check