Docs

Integrations / Identity / Okta

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.

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.

  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 runbook tool.

    Also grant okta.eventHooks.manage if you plan to turn on Automation triggers or 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.

  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.

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

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.

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

FieldFormatExample
URLhttps://[your-org].okta.comhttps://northwind.okta.com
Client IDOAuth client ID from the API Services app0oa1a2b3c4d5e6f7g8h9
Private Key (JSON)JWK private key in JSON format{"kty":"RSA","kid":"…","d":"…"}

Required Okta API Scopes

ScopePurpose
okta.apps.readRead application catalog and assignments
okta.groups.readRead groups and memberships
okta.groups.manageAdd and remove users from groups
okta.users.readRead user profiles
okta.users.manageUpdate users (e.g., factor and password resets)
okta.logs.readRead System Log events (optional — required only for the Search System Logs tool)
okta.eventHooks.manageRegister the Okta event hook (optional: needed for Automation triggers and 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

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:

Something wrong or missing? Report an issue · View as Markdown