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 a custom app

In the Okta Admin Console, go to Applications and Resources > Applications. Click Add application, then choose Create custom app.
The Okta Applications page with the Add application menu open, showing Add from catalog and Create custom app
2

Choose API Services

In the Create and deploy private app integrations dialog, open the Classic experience tab. Select API Services as the sign-in method, then click Next.
The Classic experience tab of the create app dialog with API Services selected as the sign-in method
3

Name the app integration

Enter an App integration name, such as “Ravenna”. Under Client definition, select Use Okta-generated client ID, then click Save.
The New API Services App Integration form with the name Ravenna and Use Okta-generated client ID selected
4

Add a public key

The app opens on its General tab. Okta won’t switch the app to key-based authentication until it has an active key, so add the key first. On the Public keys card, click Edit, keep Save keys in Okta selected, and click Add key.In the Add a public key dialog, leave Key Size at 4096-bit (Recommended) and click Generate new key.
The Add a public key dialog with the 4096-bit key size selected and the Generate new key button
5

Copy the private key

Under Private key - Copy this!, select PEM, then click Copy to clipboard. Store the key somewhere secure, then click Done.
Okta shows the private key only once. If you close the dialog without copying it, you have to generate a new key pair.
The Add a public key dialog after generating a key, with the PEM tab and Copy to clipboard button above the private key, which is blurred
6

Save the key and copy the KID

Back on the Public keys card, click Save. The key’s status changes to Active. Copy its KID (Key ID) from the table. You’ll need it along with the private key.
The Public keys card with one active sig key listed, its KID blurred
7

Switch client authentication to the key

On the Client Credentials card, click Edit and select Public key / Private key. Copy the Client ID for later, then click Save. In the Existing client secrets will no longer be used dialog, click Save again.
The Client Credentials card in edit mode with Public key / Private key selected and the client ID blurred
8

Turn off DPoP

On the General Settings card, click Edit. Under Proof of possession, clear Require Demonstrating Proof of Possession (DPoP) header in token requests, then click Save. Okta turns this on by default for new apps, and Ravenna doesn’t send DPoP headers.
The General Settings card in edit mode with the Require DPoP checkbox cleared
9

Grant required scopes

Scopes are granted in the Okta Admin Console, not in Ravenna. Open the app’s Okta API Scopes tab and click Grant next to each scope below. Okta may ask you to confirm with Grant Access.
  • 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.
To check your work, select Granted under Consent to list only the scopes you’ve granted.
The Okta API Scopes tab filtered to Granted, listing the scopes Ravenna needs, including the Identity Governance scopes
10

Assign admin roles

Open the app’s Admin roles tab and click Edit assignments. On the Administrator assignment by admin page, choose a Role for the first row, then click Add assignment for each additional role:
  • 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
Leave the Applications and Groups fields empty so each role applies across your whole org. Access Requests Administrator pairs automatically with Access Requests Resource Set. Click Save Changes.
The Administrator assignment by admin page with Access Requests Administrator, Help Desk Administrator, and Group Administrator role rows
The Admin roles tab then lists every role assigned to the app.
The Admin roles tab listing Access Requests Administrator, Application Administrator, Group Administrator, and Help Desk Administrator

​
Add integration

1

Find Okta

In Ravenna, go to Settings > Integrations, search for “Okta”, and click Connect.
The Ravenna Integrations settings page filtered to Okta, with the Connect button
2

Enter your Okta details

In Connect Okta to Ravenna, leave Authentication method set to Private Key Authentication. Fill in the values you saved from Okta:
  1. Client ID: the Client ID from your app’s Client Credentials card
  2. Key ID: the KID from your app’s Public keys card
  3. Private Key (PEM format): the private key you copied, including the BEGIN and END lines
  4. Okta Domain: your Okta domain, such as https://your-org.okta.com
The Permissions tab lists what Ravenna uses each permission for.
The Connect Okta to Ravenna dialog with Private Key Authentication selected and the Client ID, Key ID, Private Key, and Okta Domain fields
3

Save

Click Save to connect Okta.

​
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:
  • In Okta, open your app’s General tab and click Edit on the General Settings card
  • Clear Require Demonstrating Proof of Possession (DPoP) header in token requests
  • 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 23, 2026