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:
- Okta Admin Access — Administrative privileges in your Okta organization
- 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
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.
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.
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.
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.
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
Grant Okta API scopes
On the app's Okta API Scopes tab, grant Risotto these minimum scopes:
okta.apps.readokta.groups.manageokta.groups.readokta.users.manageokta.users.read
Also grant
okta.logs.readif you plan to use the Search System Logs runbook tool.Also grant
okta.eventHooks.manageif 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.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
Open the Okta integration
In your Risotto dashboard, go to Settings > Integrations and click the Okta card. On the Admin API card, click Connect.
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-adminin 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.
- URL: the root URL of your Okta instance, for example
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:
Automatically discover and import applications from your Okta organization
Import Okta groups to use for access control and rule configuration
Using the Import Wizard
- In your Risotto dashboard, go to Settings > Applications
- Click Import
- On the Choose app... step, select the Okta application you want to manage through Risotto
- On the Choose group... step, select the Okta group that grants access to the application
- 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
| 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 tool) |
okta.eventHooks.manage | Register 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.readis 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.manageis 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 for access rule configuration
- Review Pre-work requirements for setup guidance
- Contact your Risotto administrator for organization-specific questions
Something wrong or missing? Report an issue · View as Markdown