# Okta

Configure Okta identity provider integration with Risotto

Connect your Okta identity provider to Risotto to enable automated access management and group-based application provisioning.

> **Note:** **Looking for Dashboard SSO?** This integration is for managing user access to
> applications through Risotto. To configure SSO for signing into the Risotto
> dashboard itself, see [Dashboard Authentication
> Setup](https://www.tryrisotto.com/docs/guides/dashboard-authentication).

Risotto authenticates to Okta using OAuth 2.0 with a private key JWT. Instead of a static API token, you create an API Services app in Okta, generate a public/private key pair, and grant the app the scopes and admin roles Risotto needs.

## Prerequisites

Before setting up the Okta integration, ensure you have:

1. **Okta Admin Access** — Administrative privileges in your Okta organization
2. **Permission to create API Services apps** — Required to register Risotto as an OAuth client

## Setup Process

### Step 1: Create an API Services App in Okta

1. **Create the app integration**

   In your Okta admin console, go to **Applications > Applications** and click **Create App Integration**.

   Select **API Services**, click **Next**, give the app a name (e.g., "Risotto"), and click **Save**.

2. **Copy the Client ID**

   On the **General** tab of the new app, copy the **Client ID**. You'll paste
   this into Risotto in Step 3.

3. **Switch to public key / private key authentication**

   In the **Client Credentials** section, click **Edit** and change the client
   authentication method to **Public key / Private key**.

4. **Generate a key pair**

   In the **Public keys** section, click **Add**, then **Generate new key**.

   Okta will display the **private key in JSON format**. Copy the entire JSON object — you'll paste it into Risotto in Step 3. Make sure the new key is marked as **Active**.

   > **Warning:** Okta only shows the private key once. Save it somewhere secure before closing
   > the dialog.

5. **Disable proof of possession**

   In the **General Settings** section of the app, uncheck **Proof of possession** and click **Save**.

### Step 2: Grant Scopes and Admin Roles

1. **Grant Okta API scopes**

   On the app's **Okta API Scopes** tab, grant Risotto these minimum scopes:

   - `okta.apps.read`
   - `okta.groups.manage`
   - `okta.groups.read`
   - `okta.users.manage`
   - `okta.users.read`

   Also grant `okta.logs.read` if you plan to use the [Search System Logs](https://www.tryrisotto.com/docs/integrations/tools/okta/search_system_logs) runbook tool.

   Also grant `okta.eventHooks.manage` if you plan to turn on [Automation triggers](https://www.tryrisotto.com/docs/integrations/identity/okta-automation-triggers) or [Okta Identity Governance](https://www.tryrisotto.com/docs/integrations/access-governance/okta-identity-governance). Both register an Okta event hook, and Okta refuses event hook calls without this scope.

2. **Assign admin roles**

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

   - **Read-only Administrator**
   - **Group Membership Administrator**
   - **Help Desk Administrator** — required for factor and password resets

### Step 3: Configure the Integration in Risotto

1. **Open the Okta integration**

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

   *Product example: The Okta integration page in the Risotto dashboard, not connected, with Connect on the Admin API card.*

2. **Enter your Okta details**

   The **Okta** dialog opens, with the Okta steps in its **Instructions** pane. Fill in the three fields:

   - **URL**: the root URL of your Okta instance, for example `https://northwind.okta.com`. Do **not** include `-admin` in the URL.
   - **Client ID**: the Client ID you copied from the app's **General** tab.
   - **Private Key (JSON)**: the full JSON private key you copied when you generated the key pair.

3. **Save and verify**

   Click **Save**.

   *Product example: The Okta setup dialog in the Risotto dashboard, with the URL, Client ID and Private Key (JSON) filled in and the Save button.*

   Before it saves, Risotto signs in to Okta with the new credentials and reads one group. If Okta refuses, the dialog shows Okta's reason and nothing is saved, so you can fix the URL, key, scopes, or roles and save again. When the save succeeds, the **Admin API** card shows the **URL** and **Client ID**, with the **OIG Enabled** and **Automation triggers** switches below them.

## Import Applications and Groups

Once connected, use Risotto's import wizard to:

- **Import Applications**: Automatically discover and import applications from your Okta organization
- **Import Groups**: Import Okta groups to use for access control and rule configuration

### Using the Import Wizard

1. In your Risotto dashboard, go to **Settings** > **Applications**
2. Click **Import**
3. On the **Choose app...** step, select the Okta application you want to manage through Risotto
4. On the **Choose group...** step, select the Okta group that grants access to the application
5. On the **New rule...** step, configure the access rule and click **Create rule**

## Automation Triggers

Once the connection uses an API Services app, the **Admin API** card on **Settings > Integrations > Okta** has an **Automation triggers** switch. It subscribes Risotto to Okta account events (an account created, activated, suspended, locked, or deactivated) so an [automation](https://www.tryrisotto.com/docs/dashboard/automations) can react to them. The app needs the `okta.eventHooks.manage` scope. Turning the switch on or off also needs the **Super Administrator** role on the app for the moment of the change. See [Okta Automation Triggers](https://www.tryrisotto.com/docs/integrations/identity/okta-automation-triggers).

## Sign-in Verification

Tools that require user verification send the requester an Okta Verify push by default. To have requesters sign in to a separate OIDC app in your Okta org instead, see [Sign-in Verification](https://www.tryrisotto.com/docs/dashboard/settings/identity/sign-in-verification).

## How Risotto finds a user in Okta

To add or remove a person from a group, or to check their access, Risotto looks up the person in Okta by email address. Risotto accepts an Okta user only when the user's primary email is the same as that address. Upper and lower case do not matter. A user whose email only starts with the same text is not a match. For example, a lookup for `jane@acme.co` does not find `jane@acme.com`.

- If no primary email matches, Risotto reports that it cannot find the user. If your Okta users keep their Slack email in a different profile attribute, contact Risotto support to match on that attribute.
- If two or more Okta users have the same primary email, Risotto does not pick one. It reports that it cannot find the user.

## Configuration Details

### Required Information

| Field                  | Format                                    | Example                           |
| ---------------------- | ----------------------------------------- | --------------------------------- |
| **URL**                | `https://[your-org].okta.com`             | `https://northwind.okta.com`      |
| **Client ID**          | OAuth client ID from the API Services app | `0oa1a2b3c4d5e6f7g8h9`            |
| **Private Key (JSON)** | JWK private key in JSON format            | `{"kty":"RSA","kid":"…","d":"…"}` |

### Required Okta API Scopes

| Scope                    | Purpose                                                                                                                                                                                                                                                                           |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `okta.apps.read`         | Read application catalog and assignments                                                                                                                                                                                                                                          |
| `okta.groups.read`       | Read groups and memberships                                                                                                                                                                                                                                                       |
| `okta.groups.manage`     | Add and remove users from groups                                                                                                                                                                                                                                                  |
| `okta.users.read`        | Read user profiles                                                                                                                                                                                                                                                                |
| `okta.users.manage`      | Update users (e.g., factor and password resets)                                                                                                                                                                                                                                   |
| `okta.logs.read`         | Read System Log events (optional — required only for the [Search System Logs](https://www.tryrisotto.com/docs/integrations/tools/okta/search_system_logs) tool)                                                                                                                   |
| `okta.eventHooks.manage` | Register the Okta event hook (optional: needed for [Automation triggers](https://www.tryrisotto.com/docs/integrations/identity/okta-automation-triggers) and [Okta Identity Governance](https://www.tryrisotto.com/docs/integrations/access-governance/okta-identity-governance)) |

### Required Admin Roles

- **Read-only Administrator** — Read access to users, groups, and applications
- **Group Membership Administrator** — Manage user group memberships
- **Help Desk Administrator** — Reset factors and passwords

## Best Practices

> **Note:** **Group Structure**: Organize your Okta groups to align with application
> access levels. For example: - `Asana Admin Users` - Full admin access to Asana
>
> - `Asana Standard Users` - Standard user access to Asana - `Asana Read Only` -
>   View-only access to Asana

> **Tip:** **Rate Limiting**: Risotto automatically handles Okta API rate limits with
> built-in retries and delays to prevent service interruptions.

> **Warning:** **Security**: Treat the JSON private key like any other secret. Store it in a
> password manager or secret vault, rotate it on your organization's schedule,
> and revoke the key in Okta if it is ever exposed.

## Troubleshooting

### Common Issues

**Connection Failed**

- Confirm the **URL** is your root Okta domain (e.g., `https://northwind.okta.com`) and does not contain `-admin`
- Verify the **Client ID** matches the API Services app you created
- Make sure the public key in Okta is **Active** and that you pasted the matching private key JSON
- Confirm **Proof of possession** is disabled on the app's General Settings

**Permission Denied / Missing Scope Errors**

- On the app's **Okta API Scopes** tab, confirm all required scopes are granted
- On the app's **Admin roles** tab, confirm Read-only Administrator and Group Membership Administrator are assigned
- When Okta refuses a call, Risotto sends an **Okta Connection Error** notice. If Okta names a missing scope, the notice says "Your Okta API Services app did not grant `<scope>`, which this endpoint needs." Grant that scope on the app's **Okta API Scopes** tab.
- If Okta gives no reason, the notice says Okta "returned 403 for `<path>` without a reason." Make sure the admin role assigned to the Risotto app covers that resource.
- Okta also refuses some actions because of the target user's status, for example an unlock for a user who is not locked out. These refusals do not cause an **Okta Connection Error** notice.

**Groups Not Importing**

- Confirm `okta.groups.read` is granted to the app
- Verify groups exist and are visible to the assigned admin roles in Okta

**Factor or Password Resets Failing**

- Confirm the **Help Desk Administrator** role is assigned to the app
- Confirm `okta.users.manage` is granted
- Help Desk Administrator cannot reset passwords for other admins. To reset admin passwords, the app needs the **Super Administrator** role.

**Unlock Says the User Is Not Locked Out**

The **Okta Unlock User** tool reads the user's status in Okta before it unlocks the account:

- **Locked out**: the tool unlocks the account.
- **Active**: the tool still sends the unlock, because Okta can block an active user on an unknown device. If Okta refuses, the tool replies that the user is not locked out and can sign in with their current password. Use a password reset if they forgot it.
- **Any other status**, for example suspended or deprovisioned: the tool does not send the unlock. It replies that the user is not locked out and gives the status.

A user whose lockout ends before Risotto runs, for example when Okta unlocks the account automatically, gets the "not locked out" reply. This is expected.

## Support

For additional help with Okta integration:

- Check the [Applications documentation](https://www.tryrisotto.com/docs/dashboard/applications) for access rule configuration
- Review [Pre-work requirements](https://www.tryrisotto.com/docs/guides/initial/pre-work) for setup guidance
- Contact your Risotto administrator for organization-specific questions

Source: https://www.tryrisotto.com/docs/integrations/idp/okta
