Skip to main content
The Private Key method authenticates to Okta with public/private key cryptography instead of a shared secret. You create and own the app in the Okta Admin Console, so you also control which API scopes it is granted. This is the method Ravenna recommends. It can’t be installed through the OIN marketplace, so setup takes a few more manual steps.
Not sure which authentication method to use? See how the two methods compare and why Ravenna recommends Private Key.
Already connected via Client Secret? You can switch a live Okta integration to Private Key without disconnecting. Complete the Okta-side setup below, then in Ravenna go to Settings > Integrations, open the ⋯ menu on the Okta integration, and choose Update Credentials. Pick Private Key and enter the new values. The integration keeps the same ID, and no cleanup or resync is triggered.

​
Prerequisites

Before you begin, ensure you have:
  • Okta Super Admin or Application Administrator access
  • Your Okta organization domain
  • Permissions to create Application Integrations
  • Ability to grant admin roles to service accounts

​
Setup guide

​
Create Okta API Service Integration manually

1

Create app integration

Log in to Okta and navigate to Applications, then select Create App Integration
Custom
2

Select integration type

Select API Services as the integration type
Custom
3

Name the app integration

Provide a name for your integration (e.g., “Access Management Integration”) and click Save
Custom
4

Configure private key authentication

Configure the authentication method:
  1. Select Private Key/Public Key as the Client Authentication Method
  2. Click Add Key to generate a key pair
  3. Copy the Client ID for later use
    Custom
5

Generate PEM key pair

Generate a new PEM key pair for the integration
Custom
6

Save private key and KID

Copy and securely store both:
  • The Private PEM Key
  • The KID (Key Identifier)
You will need both values to configure the integration
Custom
7

Disable DPoP requirement

Uncheck the Require DPoP option to ensure compatibility
Custom
8

Grant required scopes

Scopes are granted in the Okta Admin Console, not in Ravenna. In Okta, open your app under Applications > Applications, go to the Okta API Scopes tab, and grant the following scopes:
  • okta.users.read
  • okta.users.manage
  • okta.groups.read
  • okta.groups.manage
  • okta.apps.read
  • okta.apps.manage
  • okta.factors.read
  • okta.factors.manage
  • okta.logs.read (required for the copilot to search the Okta System Log when diagnosing access issues, sign-in failures, and MFA events)
  • okta.appGrants.read (recommended, see below)
If you plan to turn on Okta Identity Governance sync, also grant:
  • okta.accessRequests.catalog.read
  • okta.accessRequests.request.read
  • okta.accessRequests.request.manage
  • okta.accessRequests.condition.read
These scopes cover Ravenna’s built-in features. Because you own this app, you can grant additional scopes later if a Foundry action needs them.
Grant okta.appGrants.read. It lets Ravenna read back the list of scopes you granted on this app, which is otherwise invisible to us. With it, a Foundry action that needs a scope you have not granted tells you which one to add, instead of failing at Okta with an error that names no fix. Without it, Ravenna cannot check scopes before calling Okta. It grants no access to user, group, or application data.
Custom
9

Assign admin roles

Grant the following admin roles to the integration:
  • Application Administrator
  • Group Administrator
  • Help Desk Administrator or Super Administrator (required for password and MFA reset)
If you plan to turn on Okta Identity Governance sync, also assign:
  • Access Requests Administrator
Custom

​
Add integration

1

Navigate to integrations

Go to Settings > Integrations
Custom
2

Select Okta integration

Select Okta from the available integrations
Custom
3

Select Private Key method

Select Private Key as your authentication method
4

Enter integration details

Provide the following information from your Okta setup:
  1. Okta Domain: Your Okta domain (e.g., https://your-org.okta.com)
  2. Client ID: The Client ID from your Okta integration
  3. Private Key PEM: The Private Key PEM you saved earlier
  4. KID: The Key Identifier (KID) you saved earlier
    Custom
5

Complete setup

Click Add Okta to complete the integration setup

​
Troubleshooting

Cause: Private key or KID is incorrectSolution:
  • Verify the Private Key PEM is copied correctly (including BEGIN/END markers)
  • Ensure the KID matches the key in Okta
  • Check that the key hasn’t been deleted in Okta
  • Try generating a new key pair if needed
Cause: The integration was created with a subset of the required Okta API scopes or admin roles.Behavior: Ravenna no longer blocks integration setup when some scopes are missing. The integration is created with the scopes you granted, and any resource Ravenna can’t read (users, groups, or applications) syncs as empty until the missing scope is added.Solution:
  • Verify all required scopes are granted in the Okta Admin Console on your app’s Okta API Scopes tab
  • Check that Application Administrator role is assigned
  • Ensure Group Administrator role is assigned
  • For password and MFA reset, assign Help Desk Administrator or Super Administrator
  • Review the integration’s admin role assignments
  • After granting the missing scopes, trigger a resync from the integration page (no need to disconnect and reconnect)
Cause: The action needs an Okta API scope your app has not been granted. Okta rejects the whole token request, and its error does not say which scope is missing.Solution:
  • Grant okta.appGrants.read on your app’s Okta API Scopes tab. Ravenna can then read back your granted scopes and name the missing one in the error, before it ever calls Okta
  • Grant the scope the error names, then rerun the action. No reconnect or resync is needed
  • If the scope name looks invented, check it against Okta’s available scopes. Okta admin role permissions such as okta.groups.create look like scopes but are not, and Okta rejects them
Cause: Okta enforces credential reset through admin roles, separately from API scopes, so the integration can have every scope and still be blocked. Application Administrator and Group Administrator cannot reset credentials.Solution:
  • Assign Help Desk Administrator or Super Administrator to the integration
  • Retry the action; no resync or reconnect is needed
Cause: DPoP (Demonstrating Proof-of-Possession) is enabledSolution:
  • Disable Require DPoP in the Okta integration settings
  • Save the changes and retry the connection
Cause: Private key format is incorrectSolution:
  • Ensure the key is in PEM format
  • Verify the key includes the full BEGIN/END markers
  • Check for any line breaks or formatting issues
  • Generate a new key pair if the format is corrupted

​
Features

Once connected, you can use Okta actions in workflows:

Okta Actions

Manage user group memberships, assign applications, and check group membership for access management
Last modified on October 7, 2026