> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravenna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Private key setup

> Connect Okta to Ravenna using JWT private key authentication with manual configuration for the highest security in regulated environments.

<Info>Most secure integration method with manual configuration</Info>

The Private Key integration method provides the highest level of security for connecting to your Okta organization. This method requires manual configuration in Okta but offers enhanced security through public/private key cryptography.

<Warning>This integration method requires manual setup and cannot be configured through the Okta Integration Network marketplace.</Warning>

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

<Steps>
  <Step title="Create app integration">
    Log in to Okta and navigate to **Applications**, then select **Create App Integration**
    <Frame>![Custom](https://d1kzozfjh72w00.cloudfront.net/docs/images/okta/create-application.png)</Frame>
  </Step>

  <Step title="Select integration type">
    Select **API Services** as the integration type
    <Frame>![Custom](https://d1kzozfjh72w00.cloudfront.net/docs/images/okta/select-api-integration.png)</Frame>
  </Step>

  <Step title="Name the app integration">
    Provide a name for your integration (e.g., "Access Management Integration") and click Save
    <Frame>![Custom](https://d1kzozfjh72w00.cloudfront.net/docs/images/okta/name-integration.png)</Frame>
  </Step>

  <Step title="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
       <Frame>![Custom](https://d1kzozfjh72w00.cloudfront.net/docs/images/okta/private-key/private-key-authn.png)</Frame>
  </Step>

  <Step title="Generate PEM key pair">
    Generate a new PEM key pair for the integration
    <Frame>![Custom](https://d1kzozfjh72w00.cloudfront.net/docs/images/okta/private-key/generate-pem.png)</Frame>
  </Step>

  <Step title="Save private key and KID">
    <Warning>
      Copy and securely store both:

      * The Private PEM Key
      * The KID (Key Identifier)

      You will need both values to configure the integration
    </Warning>

    <Frame>![Custom](https://d1kzozfjh72w00.cloudfront.net/docs/images/okta/private-key/private-key.png)</Frame>
  </Step>

  <Step title="Disable DPoP requirement">
    Uncheck the **Require DPoP** option to ensure compatibility
    <Frame>![Custom](https://d1kzozfjh72w00.cloudfront.net/docs/images/okta/turn-off-dpop.png)</Frame>
  </Step>

  <Step title="Grant required scopes">
    Add the following Okta API scopes to the integration:

    * `okta.users.read`
    * `okta.users.manage`
    * `okta.groups.read`
    * `okta.groups.manage`
    * `okta.apps.read`
    * `okta.apps.manage`
    * `okta.factors.read`
    * `okta.factors.manage`
      <Frame>![Custom](https://d1kzozfjh72w00.cloudfront.net/docs/images/okta/needed-scopes.png)</Frame>
  </Step>

  <Step title="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)
      <Frame>![Custom](https://d1kzozfjh72w00.cloudfront.net/docs/images/okta/admin-roles.png)</Frame>
  </Step>
</Steps>

### Add integration

<Steps>
  <Step title="Navigate to integrations">
    Go to **Settings > Integrations**
    <Frame>![Custom](https://d1kzozfjh72w00.cloudfront.net/docs/images/okta/ravenna-organization-integrations.png)</Frame>
  </Step>

  <Step title="Select Okta integration">
    Select **Okta** from the available integrations
    <Frame>![Custom](https://d1kzozfjh72w00.cloudfront.net/docs/images/okta/select-okta-integration-type.png)</Frame>
  </Step>

  <Step title="Select Private Key method">
    Select **Private Key** as your authentication method
  </Step>

  <Step title="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
       <Frame>![Custom](https://d1kzozfjh72w00.cloudfront.net/docs/images/okta/private-key/add-okta-private-key-information.png)</Frame>
  </Step>

  <Step title="Complete setup">
    Click **Add Okta** to complete the integration setup
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Invalid credentials error">
    **Cause**: Private key or KID is incorrect

    **Solution**:

    * 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
  </Accordion>

  <Accordion title="Missing scopes or partial sync">
    **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 Okta
    * 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)
  </Accordion>

  <Accordion title="Password or MFA reset fails with a permission error (403)">
    **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
  </Accordion>

  <Accordion title="DPoP requirement error">
    **Cause**: DPoP (Demonstrating Proof-of-Possession) is enabled

    **Solution**:

    * Disable **Require DPoP** in the Okta integration settings
    * Save the changes and retry the connection
  </Accordion>

  <Accordion title="Key validation failed">
    **Cause**: Private key format is incorrect

    **Solution**:

    * 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
  </Accordion>
</AccordionGroup>

## Features

Once connected, you can use Okta actions in workflows:

<Card title="Okta Actions" icon="okta" href="/documentation/automate/workflows/workflow-builder#okta-actions">
  Manage user group memberships, assign applications, and check group membership for access management
</Card>