# Okta Identity Governance

Route Risotto access requests through Okta Identity Governance (OIG) using Access Requests V2 (RCAR)

Enable Risotto to request application access through Okta's Identity Governance as an **access governance provider**, using **Access Requests V2**, also known as **Resource-Centric Access Requests (RCAR)**. Risotto submits the request on the user's behalf; Okta owns the approval workflow and performs the grant.

> **Note:** **This is the access governance integration, not the Okta IdP integration.**
> The [Okta Identity Provider integration](https://www.tryrisotto.com/docs/integrations/idp/okta) handles
> *directory sync and group membership* — reading groups and managing
> assignments directly. Okta Identity Governance is a *separate surface*:
> Risotto **delegates approval and fulfillment** of access requests to OIG. OIG
> builds on top of your existing Okta IdP connection, but it is configured and
> reasoned about independently. See the [Access Governance
> Overview](https://www.tryrisotto.com/docs/integrations/access-governance/overview) for how fulfillment
> differs from identity.

> **Warning:** This integration supports **Okta Access Requests V2 (RCAR)** only — the newer,
> resource-centric model that dynamically pulls groups and bundles assigned to
> applications. It does **not** support the legacy **OIG V1 / Request Types**
> model (Configuration Lists and Access Request Teams). See Okta's [RCAR
> overview](https://support.okta.com/help/s/article/resource-centric-access-requests-rcar-6-17-2024-blog-post?language=en_US)
> for background on the difference.

## What OIG enables

With Okta OIG configured, Risotto can:

- Request access to applications through Okta's OIG Catalog.
- Support multiple access types per catalog entry.
- Collect required fields (business justification, duration, etc.) from users **before** the request is dispatched.
- Request access on behalf of users through the configured API Services app.

## Prerequisites

Before configuring OIG features:

1. **Okta IdP Connected** — Complete the [Okta integration setup](https://www.tryrisotto.com/docs/integrations/idp/okta) first. OIG adds access governance capabilities to that existing connection.
2. **API Services App Created** — You'll add scopes and roles to this existing app.
3. **Admin Access** — Permission to modify the API Services app in Okta.
4. **OIG Enabled** — Okta Identity Governance (an IGA license) must be enabled in your Okta organization.

## Configuration

### Step 1: Add OIG API Scopes

1. **Open your API Services app**

   In your Okta admin console, go to **Applications > Applications** and open the API Services app you created for Risotto (e.g., "Risotto").

2. **Grant additional scopes**

   On the app's **Okta API Scopes** tab, grant these additional scopes for OIG functionality:

   - `okta.eventHooks.manage` — Manage event hook (webhook) lifecycle
   - `okta.accessRequests.catalog.read` — Read OIG Catalog entries and request fields
   - `okta.accessRequests.condition.read` — Read access request conditions
   - `okta.accessRequests.request.manage` — Create access requests on behalf of users
   - `okta.accessRequests.request.read` — Read existing access requests
   - `okta.governance.entitlements.read` — Read the access a user already holds, so Risotto does not ask Okta for access they have

### Step 2: Assign Admin Roles

1. **Add OIG-required roles**

   On the app's **Admin roles** tab, assign these additional roles:

   - **Access Requests Administrator** — Required when OIG is enabled, for managing access request workflows
   - **Super Administrator** — Required whenever Risotto changes the Okta event hook

   > **Warning:** **Super Administrator is needed again for every later event hook change, not
   > only at setup.** Okta restricts event hook reads and writes to super admins,
   > so a change made without the role fails with a `403` and nothing changes.

   The role has to be on the app each time you:

   - Switch the **OIG Enabled** toggle on, which registers the hook.
   - Switch **OIG Enabled** off, which removes OIG's events and deletes the hook if nothing else is using it.
   - Turn [Okta automation triggers](https://www.tryrisotto.com/docs/integrations/identity/okta-automation-triggers) on or off, or update their subscriptions, which share the same hook.
   - Re-enable OIG after a disable, which registers a new hook.

   As soon as a change lands, the **Admin API** card in Risotto shows "You can remove the "Super Administrator" role", so you can grant the role before the change and remove it after.

## OIG Catalog Configuration

### Understanding OIG Catalog Entries

Okta OIG Catalog Entries represent applications that users can request access to. Each entry can have multiple **Access Types** (child applications) that define different permission levels.

When a user requests access through Risotto:

- If only one access type exists, Risotto requests that access directly.
- If multiple access types exist, Risotto prompts the user to choose which access level they need.

### Configure "Request on Behalf of"

For Risotto to request access for users, each OIG application must allow requests on behalf of others:

1. **Open OIG Catalog settings**

   In your Okta admin console, navigate to **Identity Governance > Access Requests > Catalog**.

2. **Configure each application**

   For each application Risotto will manage:

   1. Open the catalog entry
   2. Go to **Request Policies**
   3. Enable **Allow requests on behalf of others**
   4. Save your changes

> **Tip:** Configure all applications that Risotto will manage with "Request on behalf
> of" enabled. This allows Risotto to submit access requests for users through
> Slack.

## Risotto Dashboard Configuration

### Enable OIG Integration

1. **Navigate to Okta settings**

   In your Risotto dashboard, go to **Settings > Integrations** and click the **Okta** card. On the **Connections** tab, find the **Admin API** card.

2. **Turn on OIG Enabled**

   The **Admin API** card shows **Connected**, with the **URL** of your Okta org and the **Client ID** of your API Services app. Below the Client ID, turn on the **OIG Enabled** switch. The switch is there only when Okta is connected through an API Services app.

   *Product example: Okta's Admin API card, connected, with the OIG Enabled switch.*

3. **Confirm in the dialog**

   The **Turn on Okta Identity Governance** dialog opens. It reminds you that the change needs the `okta.eventHooks.manage` scope and the **Super Administrator** role on the API Services app, and lists the events Okta will send to Risotto. Click **Register and turn on**.

   *Product example: The Turn on Okta Identity Governance confirmation, listing the events Okta will send, with Register and turn on.*

   When the change lands, Risotto shows "Okta OIG enabled", and the **Admin API** card shows "You can remove the "Super Administrator" role". If the app is missing the scope or the role, the dialog shows **Okta refused the request** with what to fix, and nothing changes in Okta. Fix it in Okta, then click **Try again**.

   > **Warning:** When you enable OIG, Risotto registers an Okta **event hook** so it can
   > receive access-request outcomes. Okta reveals the event hook's
   > **verification/secret value only once**, during registration — Risotto
   > captures it automatically at setup time. If you ever delete and re-create the
   > event hook, you must re-enable the integration so Risotto can capture the new
   > secret; the old one cannot be retrieved.

### Import OIG Catalog Applications

1. **Import applications**

   In your Risotto dashboard, go to **Settings > Applications**, click **Import**, and choose **From Okta OIG catalog**. The option appears once **OIG Enabled** is on.

2. **Choose catalog entries**

   The **Import** dialog opens on its **OIG Catalog** tab, which lists the catalog entries available through Okta Identity Governance, each with its name and Okta entry ID. Entries you already imported are not listed. Use the **Search catalog entries...** box to filter the list, then check the entries you want (or use **Select all** / **Clear**). The button in the bottom right shows how many apps you chose, for example **Import 2 apps**. Click it to import them into Risotto.

   *Product example: The Import dialog on its OIG Catalog tab, with two catalog entries checked and Import 2 apps.*

3. **View imported applications**

   After importing, your OIG apps will appear under **Settings > Applications**.

4. **Configure keywords**

   You can still configure keyword matching for each OIG application: open the application and edit **Keywords** under **Default rule properties**. Keywords help Risotto identify when users are asking about a specific application.

   All other access configuration (approval workflows, required fields, access duration) is determined on the Okta OIG side.

## The end-user experience

### What the requester sees in Slack

1. The employee asks Risotto for access to an OIG-managed application in Slack.
2. If the catalog entry has multiple access types, Risotto asks which one they need.
3. Risotto collects every **required field** Okta has configured for that request (such as a business justification or duration) **before** dispatching. Gathering required fields up front means Okta accepts the request on the first submission instead of rejecting it for missing information.
4. Risotto submits the request to Okta on the user's behalf and posts a **View in Okta** link so the requester can follow the approval.
5. When Okta resolves the request, Risotto updates the same Slack thread with the outcome.

> **Warning:** **Required fields are collected before dispatch.** Okta rejects an access
> request that is missing any required field. Risotto reads each application's
> access-request conditions and prompts the user for those fields in Slack
> *before* it submits — so make sure your OIG request policies have the correct
> required fields configured, or Risotto won't know to ask for them.

### What reviewers see

Reviewers approve or deny inside **Okta**, using their existing OIG access-request workflows. The request appears in Okta as an on-behalf-of request submitted by the Risotto API Services app for the named employee, including the access type and required fields the user provided in Slack.

### What "View in Okta" links do

The **View in Okta** link deep-links to the specific access request in Okta. Requesters use it to track status; reviewers and admins use it to act on or audit the request. Okta remains the system of record for the approval history and any time-bound expiration.

## Required Okta API Scopes

| Scope                                | Purpose                                     |
| ------------------------------------ | ------------------------------------------- |
| `okta.eventHooks.manage`             | Manage event hook (webhook) lifecycle       |
| `okta.accessRequests.catalog.read`   | Read OIG Catalog entries and request fields |
| `okta.accessRequests.condition.read` | Read access request conditions              |
| `okta.accessRequests.request.manage` | Create access requests on behalf of users   |
| `okta.accessRequests.request.read`   | Read existing access requests               |
| `okta.governance.entitlements.read`  | Read access a user already holds            |

> **Note:** These scopes are **in addition to** the scopes configured for the base Okta
> IdP integration. See [Okta Integration](https://www.tryrisotto.com/docs/integrations/idp/okta) for the
> complete list.

## Required Admin Roles

| Role                              | Purpose                                                              |
| --------------------------------- | -------------------------------------------------------------------- |
| **Access Requests Administrator** | Manage access request workflows                                      |
| **Super Administrator**           | Register, update and remove the event hook — needed for every change |

## Best Practices

> **Note:** **Least Privilege**: Risotto confirms in the dashboard when a change to the
> event hook has landed, and that is the point at which the **Super
> Administrator** role is spare again. Remove it then, and grant it again for
> the next event hook change — turning OIG or automation triggers on or off.
> Everything else OIG does runs on **Access Requests Administrator** and the
> scopes above.

> **Tip:** **Test Access Requests**: Before going live, test the full access request flow
> with a non-admin user. Verify that Risotto can submit requests and that
> approvals work as expected.

## Troubleshooting

### Access Request Failed

- Verify the API Services app has the required scopes and roles.
- Confirm "Request on behalf of" is enabled for the application.
- Check that the user exists in Okta and is eligible for the requested access.

### Enabling or Disabling OIG Fails

- Risotto checks the app's permissions before it changes the event hook. When the app lacks the `okta.eventHooks.manage` scope or the **Super Administrator** role, the dialog shows **Okta refused the request** and names what is missing. Grant it in Okta, click **Try again**, and remove the role once the **Admin API** card says you can.
- This applies to turning OIG **off** as well as on: Risotto removes OIG's events from the hook in Okta rather than only forgetting them locally.
- If the app holds the role and the toggle still fails, check **Workflow > Event Hooks** in Okta for more than one hook pointing at Risotto. Risotto refuses to guess between them — remove the extra hooks and retry.

### OIG Catalog Not Showing

- Confirm OIG is enabled in your Okta organization.
- Verify the API Services app has the **Access Requests Administrator** role and the OIG scopes above.
- Refresh the application import in Risotto.

### Missing Required Fields

- Risotto collects fields configured in Okta's access request conditions.
- Verify your OIG policies have the expected required fields configured.
- Check that conditional fields are triggering based on the selected access type.

### Outcomes Not Returning to Slack

- Confirm the event hook registered during setup is still present and verified in Okta (**Workflow > Event Hooks**).
- If the event hook was deleted or its secret changed, re-enable OIG in Risotto so it can re-register and re-capture the secret.

## Support

For additional help with Okta OIG integration:

- Review the [Access Governance Overview](https://www.tryrisotto.com/docs/integrations/access-governance/overview) for how fulfillment differs from identity.
- Check the [Okta Integration](https://www.tryrisotto.com/docs/integrations/idp/okta) for base configuration.
- Review [Applications documentation](https://www.tryrisotto.com/docs/dashboard/applications) for access rule configuration.
- Contact your Risotto administrator for organization-specific questions.

Source: https://www.tryrisotto.com/docs/integrations/access-governance/okta-identity-governance
