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.- OIN app (Client Secret): the Ravenna OIN app includes all five scopes, optional ones too, and sets up 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.
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 and okta.accessRequests.tasks.read are optional. Without condition.read, access levels still sync but who is eligible to request them isn’t. Without tasks.read, requests still sync but Ravenna doesn’t mention who they’re waiting on.
OIG uses the v2 Access Requests API, which rejects the older
okta.governance.accessRequests.* scope names. Grant the okta.accessRequests.* scopes listed above.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, and okta.accessRequests.tasks.read to mention approvers on the ticket. With the OIN app, the installed app includes every scope and sets up the role, so skip this step.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.
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:
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.
On an application with synced OIG levels, new Okta access comes from OIG: add a catalog entry in OIG, and it syncs into Ravenna as a new access level. follows the same rule. It adds Manual levels to the application, and when you ask it for a Group or Application level, it points you to the OIG catalog instead, so every Okta grant goes through OIG’s approval. Copilot also keeps synced levels on their External policy.
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
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.
The access request card on the ticket adds Okta’s outcome to its activity: Granted in Okta, Denied in Okta, Canceled in Okta, Expired in Okta before anyone decided, Rejected by Okta, or Approved in Okta, but Okta couldn’t grant it. When Okta gives a reason, the card shows it.
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. With
okta.accessRequests.tasks.read, Ravenna posts who each open step is waiting on, mentions those approvers, and adds them as ticket followers.
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.
Revoke and expiry
A submitted request can still be withdrawn. Closing the ticket cancels the matching OIG access request and withdraws the request in Ravenna, the same as closing the ticket of a request that’s still pending approval. Revoking a submitted entitlement also cancels the matching OIG access request. When you revoke an active OIG entitlement, Ravenna takes the access back in Okta based on what the access level grants:
Ravenna learns what each access level grants during the Okta sync, so revoke takes access back for a level after that level’s next sync. Until then, the revoke ends in Skipped Revocation with the reason Remove the access in Okta. Removing access uses the
okta.groups.manage and okta.apps.manage scopes and an Okta admin role that covers the group, the same access other Okta provisioning uses.
When OIG grants access for a limited time, Ravenna sets the entitlement’s expiry to OIG’s end date. At that time, Ravenna checks the request in OIG and moves the entitlement to Inactive once OIG has removed the access. If OIG moves the end date, Ravenna follows it. If OIG drops the end date, Ravenna clears the entitlement’s expiry. If OIG still holds the access 30 minutes after the end date, the entitlement shows Failed Revocation with the reason Okta still hasn’t taken this access back after it expired. Check it in Okta.
To keep OIG access past its end date, submit a new request.
Troubleshooting
Missing Okta Identity Governance access warning
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, andokta.accessRequests.request.manageon the app, and assign the Access Requests Administrator role - With the OIN app, 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
okta.accessRequests.request.manage and the role.A catalog entry has no access level in Ravenna
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
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
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, grantokta.accessRequests.condition.readon 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
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