# Opal

Connect Opal (opal.dev) as an access governance provider so Risotto routes access requests into Opal's approval and fulfillment workflows

Connect [Opal](https://opal.dev) to Risotto as an **access governance provider**. Once connected, Risotto routes access requests for selected applications into Opal — Opal owns the approval workflow and performs the grant, while employees keep requesting access conversationally through Slack.

> **Note:** **This is the access governance integration, not a generic Opal tool.** It
> tells Risotto to delegate *approval and fulfillment* of access requests to
> Opal. It is a fulfillment provider that sits alongside — not in place of —
> your [Identity Provider](https://www.tryrisotto.com/docs/integrations/idp/okta). You can use Okta or
> Google Workspace for identity and Opal for fulfillment at the same time. For
> background on how fulfillment differs from directory sync, see the [Access
> Governance Overview](https://www.tryrisotto.com/docs/integrations/access-governance/overview).

> **Info:** The Opal integration is generally available — connect it directly from
> **Settings → Integrations → Opal**, no need to contact Risotto to have it
> enabled.

## What the Opal integration enables

With Opal connected, Risotto can:

- Submit access requests to Opal on behalf of a user, for applications you route to Opal.
- Let Opal evaluate its own approval policies (reviewers, just-in-time duration, segregation-of-duty rules).
- Receive the outcome of a request (approved, denied, fulfilled) and reflect it back in the Slack thread and ticket.
- Link requesters and reviewers directly to the request in Opal.

## Prerequisites

Before connecting Opal, make sure you have:

1. **An Opal tenant** — An active Opal Cloud organization. By default Risotto talks to Opal Cloud at `https://api.opal.dev/v1`; you only override this if Opal directs you to a non-default host.
2. **An Opal API key** — A token from Opal with permission to create access requests on behalf of users and to read resources. Generate it in Opal under **Settings → API Tokens** (it looks like `sk-…`).
3. **Opal admin access** — Required to create the API key and to register an Events Streaming destination.
4. **Resources configured in Opal** — The applications/resources you want Risotto to route should already exist in Opal with their owners and request policies set up.

> **Warning:** Opal API keys carry the permissions of the user or service account that
> created them. Create the key from a dedicated service account scoped to the
> minimum resources Risotto needs, and store it in a secret manager.

## Setup Process

### Step 1: Create an Opal API key

1. **Open API tokens in Opal**

   In your Opal admin console, go to **Settings → API Tokens** and create a new token for Risotto (e.g., "Risotto").

2. **Copy the token**

   Copy the generated token. You'll paste it into Risotto in the next step.

   > **Warning:** Opal shows the full API token only once, at creation time. Copy it immediately and store it securely — you cannot retrieve it again later.

### Step 2: Connect Opal in Risotto

The Opal connection is on the **Opal** page of **Settings → Integrations**.

1. **Open the Opal connection**

   In your Risotto dashboard, go to **Settings → Integrations** and click the **Opal** card. On the **Opal API key** card ("Sends access requests to Opal for approval."), click **Connect**. If Opal is already connected, click **Connected**, then **Configure...**.

   *Product example: Opal's integration page, not connected, with Connect on the Opal API key card.*

   The **Opal** dialog opens. The form holds the connection fields (**API key**, **Base URL (optional)**, **Portal URL (optional)**, the **Enabled** switch and the **Send requestor to Opal** switch), then an **Events Streaming** section with the **Webhook signing secret** field, and **Cancel** and **Save**. Beside the form, the **Instructions** pane lists the steps in Opal and holds the **Webhook URL** for Step 3. On a narrow screen, click **Instructions** to show the steps.

2. **Enter your Opal credentials**

   Fill in the connection fields:

   - **API key** *(required)* — The token you copied in Step 1 (`sk-…`). Risotto validates it when you save.
   - **Base URL** *(optional)* — Defaults to `https://api.opal.dev/v1`. Override this **only** if Opal directed you to a non-default host.
   - **Portal URL** *(optional)* — Defaults to `https://app.opal.dev`. This is the user-facing Opal dashboard URL that Risotto uses for **View in Opal** deep links. Leave it blank to use the Opal Cloud default when the API base is also default.

3. **Turn on the integration**

   Switch **Enabled** on to start routing requests to Opal. While the switch is off, any Opal-shaped access rules fall back to direct fulfillment, so you can finish configuration before going live.

4. **Choose whether to send the requestor**

   **Send requestor to Opal** is on by default. With it on, each access request that Risotto submits also tells Opal who asked for access, so Opal approvers see the requestor. The requestor can be a different person from the employee who gets the access. For this to work, turn on **Let this service user record who asked for access** in Opal for the service user that owns the API key. A personal API key cannot use this setting.

   If Opal refuses the requestor, Risotto sends the request again without it, so the request still goes through. Then:

   - If you did not change the switch, Risotto turns it off and sends admins one notification, "Risotto turned off Send requestor to Opal". The audit log records **Opal Requestor Auto-Disabled**.
   - If an admin turned the switch on, it stays on. Risotto notifies admins with "Opal refused to record who asked for access".

   After you fix the setting in Opal, turn **Send requestor to Opal** on again and click **Save**.

5. **Save and verify the connection**

   Click **Save**. When the API key or the Base URL changed, Risotto checks the connection with Opal before it saves. If the check fails, the error shows under the **API key** field (for example, an invalid token or an unreachable host) and nothing is saved. When the save succeeds, Risotto shows "Opal settings saved".

   The **Opal API key** card then shows the **API host**, the **Portal** (when you set one), and whether **Enabled**, **Send requestor** and **Event streaming** are on.

### Step 3: Set up inbound resolution (Events Streaming)

Risotto learns the outcome of a request through Opal's **Events Streaming** (webhooks). Configure it so approvals and grants flow back to Slack in near real time. Both values are in the same **Opal** dialog: the **Webhook URL** in its **Instructions** pane, and the **Webhook signing secret** field in the form's **Events Streaming** section.

1. **Copy the Webhook URL from Risotto**

   In the **Opal** dialog's **Instructions** pane, copy the **Webhook URL** Risotto generated for your organization with the copy button beside it.

2. **Register the destination in Opal**

   In Opal, go to **Settings → Events** and add a new Events Streaming destination, pasting the Webhook URL as the destination. Opal generates a **signing secret** when you create the destination.

3. **Paste the signing secret back into Risotto**

   Copy the signing secret from Opal and paste it into the **Webhook signing secret** field in the **Opal** dialog, then click **Save**. Risotto verifies every inbound event against this secret (HMAC) to confirm it genuinely came from Opal.

   *Product example: The Opal dialog with the API key and webhook signing secret entered, Enabled and Send requestor to Opal on, and Save.*

   On the **Opal API key** card, **Event streaming** reads **On · waiting for the first event** until Opal sends one, then shows when the last event arrived.

   > **Note:** Without a signing secret, Risotto rejects every event Opal sends. To stop accepting events from Opal, clear the **Webhook signing secret** field and save. **Event streaming** then reads **Off**.

   > **Warning:** **The webhook signing secret is revealed only once.** Opal displays the secret a single time when you create the destination. Paste it into Risotto right away — if you lose it, you'll have to rotate the secret in Opal and update Risotto with the new value.

### Step 4: Route applications to Opal

1. **Choose what to import**

   In your Risotto dashboard, go to **Settings → Applications**, click **Import**, and choose **From Opal**. **From Opal** appears once the **Enabled** switch in the Opal dialog is on. The import dialog opens on the **Opal** tab.

   Under **Import into**, choose where the import goes:

   - **New apps**: each entry becomes its own application in Risotto.
   - **An existing app**: each resource, group, or bundle becomes an access rule in the application you pick. Only the **Advanced** view is available, because an Opal app or container always imports as its own application.

   The **Opal** tab has three views:

   - **Apps**: Opal resources that contain other requestable items, for example an Okta app. Each import becomes one application in Risotto, with one access rule for each requestable group in it.
   - **Connectors**: whole Opal apps. Each import becomes one application in Risotto, with one access rule for each requestable group and resource in the Opal app.
   - **Advanced**: single **Resources**, **Groups**, or **Bundles**. Each entry becomes its own application in Risotto with one access rule. Risotto does not add or remove access rules for these entries.

   To put **Advanced** entries into one application that you already have, choose **An existing app** under **Import into** and pick the app. Each resource, group, or bundle then becomes an access rule in that app, with no membership sync. **Apps** and **Connectors** always import as their own application. See [Move Opal rules to another application](#move-opal-rules-to-another-application).

   Applications imported from **Apps** and **Connectors** stay in sync with Opal: Risotto adds and removes their access rules when the requestable items change in Opal. To add an Opal app that you did not import before, import it again.

   The **Apps** view shows how much each import creates. Each row has a badge, for example **12 requestable**, and the total, for example "of 40". The badge is the number of access rules that the import creates. The total is every group in the Opal app. Use **Sort by** to order the list by **Requestable**, **Name**, or **Size**. If the counts do not load, the row shows "count unavailable".

   Every view has a search box. Risotto searches your Opal tenant as you type. A view lists up to 200 matches. If more items match, a message under the list tells you to refine your search. **Select all listed** selects only the rows on screen.

   Check the items you want, then click **Import**. The button counts your selection, for example **Import 2 items**, or **Import 2 items into Snowflake** for an existing application. Risotto then confirms, for example "Imported 2 applications".

   *Product example: The Import dialog on its Opal tab, importing two Opal apps as new apps, with Import 2 items.*

   The lists do not show everything in your Opal tenant:

   - **Advanced** lists a resource, group, or bundle only if Opal accepts requests for it. Risotto reads the item's request configurations in Opal. The item is requestable when at least one configuration allows requests, also a configuration that allows requests only from some people (for example, members of one Okta group). If Opal sends no request configurations for the item, Risotto uses Opal's requestable flag. Risotto does not show a message for items it leaves out. The import applies the same check and rejects an item that fails it with "Opal resource is not requestable" (or group, or bundle).
   - **Apps** and **Connectors** use Opal's requestable flag. They sync only the groups and resources that the flag marks as requestable, and the **requestable** badge counts the same way. A group that only a conditional configuration allows does not become an access rule under the app. Import it from **Advanced** instead.
   - No view lists an item that you already imported. If every match is imported, the list says, for example, "All Opal groups have already been imported."

   > **Tip:** To keep several roles of one system under one application in Risotto (for example, Snowflake roles), import the Opal app or container from **Apps** or **Connectors**, not each role from **Advanced**. Requesters then ask for one application, and Risotto matches the role they need. You can also open an existing application, set **Delegated Access** to **Opal**, and select the **Opal App**. Its requestable items then sync in as access rules under that application. You cannot delegate an application that already holds Opal rules: move those rules to another application first.

   > **Note:** If an Opal resource requires an access level, open its access rule in Risotto and choose one under **Access level**. Risotto sends that level to Opal with every request for the rule. Only resource rules have this setting: Risotto does not send an access level for a group, and a bundle uses the access levels set on its members in Opal.

2. **Let Risotto sync access rules**

   For an application imported from **Apps** or **Connectors**, Risotto keeps a copy of the access rules in sync with Opal, hourly and when someone requests access.

   An entry imported from **Advanced** keeps the access rule it got at import time. For a resource or a group, Risotto reads the maximum and recommended duration from Opal every hour and updates the rule. Risotto does not rename, turn off, or delete the rule. Bundles do not get this update.

   Applications you do not route to Opal continue to use your existing access rules.

> **Warning:** **Opal does not emit an event when access expires.** Opal sends events when a
> request is created, approved, denied, or granted, but it does **not** publish
> an event when a time-bound grant later expires. Risotto compensates with an
> adaptive **reconciliation backstop** that periodically re-checks the state of
> outstanding grants in Opal, so an access that has expired in Opal is still
> reflected accurately in Risotto even though no webhook fired. No extra
> configuration is required for this — it runs automatically once Opal is
> connected.

### Move Opal rules to another application

You can move an access rule that Risotto imported from **Advanced** into another application. Use this to group several Opal roles of one system under one application. You need the Org Admin or Manager role.

- To move every rule of an application that one **Advanced** import created, open the application in **Settings → Applications** and click **Move to app**.
- To move one rule, open the application that holds it, click the rule's ⋮ menu in **Access Rules**, and choose **Move to app**.

In the **Move to another app** dialog, choose the application in **Move to**, then click **Move rule** (or **Move N rules**).

- The target application must not be delegated to Opal or another system. Only applications that are not delegated can hold Opal rules from other applications.
- You cannot move a rule that an Opal sync manages, which is a rule under an application that you imported from **Apps** or **Connectors**. You cannot move a rule that you made by hand.
- An application can hold up to 100 access rules, and rule names must be unique in the application.
- When you move the last rule out of an application that an **Advanced** import created, Risotto deletes that application, with its keywords and notes. The dialog tells you before you move.
- Requests for a moved rule still go to Opal.

## The end-user experience

### What the requester sees in Slack

1. The employee asks Risotto for access to an Opal-managed application in Slack, as usual.
2. Risotto matches the request to an access rule. If the request names one access rule exactly, Risotto submits it without a confirmation step. If several access rules could match (for example, separate Member and Admin rules for one app), the agent recommends one and asks the requestor to confirm it.
3. Risotto collects any other details Opal needs (such as a business justification) **before** submitting, so the request isn't bounced back for missing information.
4. If the item has a maximum duration in Opal, Risotto asks how long the requester needs access, up to that maximum. The requester can ask for minutes (for example, "for 30 minutes"). The agent sends the duration to Opal in minutes.
5. Risotto confirms it has submitted the request to Opal and posts a **View in Opal** link so the requester can follow the approval there.
6. If Opal refuses the request when Risotto submits it, Risotto tells the requester in the thread. The message names the application and gives the reason from Opal, for example "Opal rejected the access request for **Snowflake**. Test Owner Group has no approvers set." Then Risotto escalates the ticket to your team.
7. When Opal approves and grants (or denies) the request, Risotto updates the same Slack thread with the outcome.

> **Note:** Risotto cannot cancel an Opal request after it submits it. To cancel a
> request, cancel it in Opal. Risotto gets the cancellation from Opal and tells
> the requestor in the Slack thread that the request was canceled.

### What reviewers see

Reviewers are notified and act inside **Opal**, using their existing approval policies. Risotto does not change who approves or how. The request appears in Opal as an on-behalf-of request submitted by Risotto for the named employee, with the justification the user provided in Slack. While **Send requestor to Opal** is on, the request also names the person who asked for access.

### What "View in Opal" links do

The **View in Opal** link deep-links to the specific access request in your Opal tenant, using the **Portal URL** configured in the Opal dialog (defaulting to `https://app.opal.dev`). Requesters use it to track status; reviewers and admins use it to approve, deny, or audit the request. Because Opal remains the system of record, the full approval history and any time-bound expiration live in Opal.

## Troubleshooting

**Opal rejects the request when Risotto submits it**

- The requester sees the reason that Opal gives, and the ticket escalates to your team.
- Fix the cause in Opal. For example, set approvers on the group, or allow the requester to request the group.
- A reviewer who denies the request in Opal is a different case. Risotto then tells the requester that the request was not approved, without a reason.

**API key validation failed on save**

- Verify the **API key** is valid (`sk-…`) and hasn't been revoked in Opal.
- Leave **Base URL** blank unless Opal directed you to a non-default host; if set, confirm it's reachable.
- Make sure the key's account has permission to create access requests on behalf of others.

**Requests aren't dispatching to Opal**

- Confirm the **Enabled** switch is on — while it's off, Opal-shaped rules fall back to direct fulfillment.
- Confirm the application is routed to **Opal** and mapped to the correct Opal resource.

**A group or resource does not appear in the Opal import list**

- Check that the item is requestable in Opal. **Advanced** lists an item only when at least one of its request configurations in Opal allows requests. A group that Opal's own requestable filter returns is listed, even when its top-level requestable flag is off.
- Check **Settings → Applications**. The import list does not show items that you already imported.

**The import shows "Failed to import applications", but the application appears later**

- On a large Opal tenant, the import can take longer than the dashboard waits. Risotto can still finish the import.
- Refresh **Settings → Applications** before you try again. If you import the same item again, the import fails with `Application '<name>' already exists`.

**Outcomes aren't coming back to Slack**

- Check **Event streaming** on the **Opal API key** card. **Off** means no signing secret is saved, and Risotto rejects every event. **On · waiting for the first event** means no verified event has arrived yet.
- Verify the Opal Events Streaming destination points at the **Webhook URL** from the Opal dialog's **Instructions** pane.
- Confirm the **Webhook signing secret** in Risotto matches the one Opal generated. If unsure, rotate the secret in Opal and re-enter it in Risotto.
- Remember that **expirations** are reconciled on a schedule rather than via webhook, so an expired grant may take a short time to reflect.

## Support

For additional help with the Opal integration:

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

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