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

# Okta

> Configure the Okta integration with RAD Security to import users, groups, and System Log events.

# Okta Integration Setup

This guide walks you through connecting your Okta org to RAD Security so it can import user and group data and read the Okta System Log for identity visibility.

<Note>
  This page covers the **Okta data integration**. To let your team sign in to RAD Security with Okta, see [Okta SSO Setup](/rad-security/platform/enterprise-authentication/okta-sso-setup) instead.
</Note>

## Choose a setup path

Okta offers two ways to authorize a machine-to-machine application, and the choice determines whether the integration can be read-only.

|                        | Option 1: OIN API Service Integration                       | Option 2: Custom API Services App                 |
| ---------------------- | ----------------------------------------------------------- | ------------------------------------------------- |
| **Setup effort**       | Low - install a catalog listing                             | Higher - create the app and grant scopes yourself |
| **Scopes**             | Fixed by the listing, including `okta.users.manage` (write) | You grant each scope individually                 |
| **Read-only possible** | No                                                          | **Yes** - this is the only read-only route        |
| **Credential**         | Client secret                                               | PEM private key (`private_key_jwt`)               |

<Info>
  If your organization requires least-privilege or read-only access to Okta, you must use **Option 2**. The OIN listing's scopes are set by the listing itself and cannot be narrowed.
</Info>

## Prerequisites

Before you begin, ensure you have:

<Check>
  * **Super Administrator** access to your Okta org - only a Super Admin can grant API scopes
  * Your Okta org URL (e.g. `https://your-org.okta.com`)
  * Access to a RAD Security workspace with integration permissions
</Check>

***

## Option 1: OIN API Service Integration

The quickest path. Okta issues a client ID and client secret, and the scopes come pre-configured with the listing.

<Warning>
  This listing's scopes include `okta.users.manage`, which grants **write** access to your users. You cannot narrow the scope set on an OIN integration. If you need read-only access, use [Option 2](#option-2-custom-api-services-app-read-only).
</Warning>

### Step 1: Install the Synqly Identity Connector

<Steps>
  <Step title="Access the Okta Admin Console">
    Log in to Okta with Super Administrator privileges and open the **Admin Console**.
  </Step>

  <Step title="Navigate to API Service Integrations">
    Go to **Applications > API Service Integrations**.
  </Step>

  <Step title="Add the Integration">
    1. Click **Add Integration**
    2. Search for and select **Synqly Identity Connector**
    3. Click **Next**
  </Step>

  <Step title="Install and Authorize">
    Click **Install and Authorize** to complete the setup.
  </Step>

  <Step title="Save the Credentials">
    Okta displays the **Client ID** and **Client Secret**. Copy both to a secure location now.

    <Warning>
      Okta shows the client secret **once**. If you navigate away without copying it, you must generate a new one.
    </Warning>
  </Step>
</Steps>

### Step 2: Configure in RAD Security

Navigate to **Data Sources > Integrations > IAM** in your RAD Security workspace and enter:

| Parameter                              | Description                                          |
| -------------------------------------- | ---------------------------------------------------- |
| **Client ID**                          | The Client ID from Step 1                            |
| **Client Secret or Private Key (PEM)** | The Client Secret from Step 1                        |
| **Base URL**                           | Your Okta org URL (e.g. `https://your-org.okta.com`) |

<Note>
  RAD Security encrypts and stores these values. Rotate the client secret in Okta if you suspect exposure, then update the integration.
</Note>

***

## Option 2: Custom API Services App (Read-Only)

Create the application yourself and grant only the scopes you need. This is the **only** way to run the Okta integration read-only.

<Warning>
  **A client secret will not work for this path.** A custom API Services app on the Okta org authorization server must authenticate with `private_key_jwt`. Posting a `client_credentials` request with a client secret to `https://your-org.okta.com/oauth2/v1/token` returns:

  ```
  401 invalid_client
  Client Credentials requests to the Org Authorization Server must use the
  private_key_jwt token_endpoint_auth_method.
  ```

  You must register a public key with Okta and give RAD Security the corresponding **PEM private key**.
</Warning>

### Step 1: Pre-flight - check the public client app admin setting

<Steps>
  <Step title="Open Account Settings">
    Go to **Settings > Account**.
  </Step>

  <Step title="Confirm Public client app admins is DISABLED">
    Verify that **Public client app admins** is **disabled**.

    <Warning>
      If this setting is enabled, Okta automatically assigns **Super Administrator** to new API service apps once scopes are granted - the exact opposite of read-only. Confirm it is disabled *before* you create the app.
    </Warning>
  </Step>
</Steps>

### Step 2: Create the API Services app

<Steps>
  <Step title="Create the App Integration">
    Go to **Applications > Applications > Create App Integration**, select **API Services**, and give the app a descriptive name (e.g. "RAD Security Integration").

    <Info>
      No user or group assignment is needed. An API Services app acts on its own behalf, not on behalf of a signed-in user.
    </Info>
  </Step>

  <Step title="Note the Client ID">
    On the app's **General** tab, copy the **Client ID**.
  </Step>
</Steps>

### Step 3: Configure client authentication and generate a key

<Steps>
  <Step title="Set Client authentication to Public key / Private key">
    Under **General Settings > Client Credentials**, edit **Client authentication** and select **Public key / Private key**.
  </Step>

  <Step title="Add a key">
    Under **PUBLIC KEYS**, click **Add**, then **Generate new key**. Choose **RSA**.
  </Step>

  <Step title="Copy the PEM private key">
    Click the **PEM** button under **Private key** and copy the entire value, including the `-----BEGIN` and `-----END` lines.

    <Warning>
      Okta displays the private key **once** and does not store it. If you lose it, you must generate a new key pair.
    </Warning>
  </Step>

  <Step title="Save">
    Click **Save**.
  </Step>
</Steps>

### Step 4: Confirm DPoP is not required

<Steps>
  <Step title="Check Proof of possession">
    Under **General Settings > Proof of possession**, confirm that **Require Demonstrating Proof of Possession (DPoP) header in token requests** is **unchecked**.

    <Info>
      This setting is off by default, so this is a confirmation rather than a change. If DPoP is ever enabled, token requests fail with `400 invalid_dpop_proof` - never `401 invalid_client`. Use that distinction to tell the two failure modes apart.
    </Info>
  </Step>
</Steps>

### Step 5: Grant API scopes

<Steps>
  <Step title="Open the Okta API Scopes tab">
    On the app, go to the **Okta API Scopes** tab.
  </Step>

  <Step title="Grant each scope">
    Click **Grant** on each of the following:

    * `okta.users.read` - list and read users
    * `okta.groups.read` - list groups and group members
    * `okta.logs.read` - read the Okta System Log

    Leave `okta.users.manage` **off** for a read-only integration.

    <Warning>
      Only a **Super Administrator** can grant API scopes, and *selecting* a scope is not the same as *granting* it. Each scope must show as granted before the integration will work.
    </Warning>
  </Step>
</Steps>

### Step 6: Assign an admin role

<Steps>
  <Step title="Open the Admin roles tab">
    On the app, go to the **Admin roles** tab and click **Admin assignments granted to this app > Edit assignments**.
  </Step>

  <Step title="Assign Read-only Administrator">
    Assign the **Read-only Administrator** role, then click **Save Changes**.

    <Warning>
      **Scopes alone are not sufficient.** Okta enforces the API scope *and* the admin role as an intersection - a request succeeds only if both allow it.
    </Warning>

    <Note>
      A custom admin role cannot be substituted here, because custom admin roles cannot be granted the **View System Log** permission. See [Okta's support article](https://support.okta.com/help/s/article/Can-custom-Admin-roles-view-system-logs?language=en_US) and the [admin role comparison](https://help.okta.com/en-us/content/topics/security/administrators-admin-comparison.htm).
    </Note>
  </Step>
</Steps>

### Step 7: Configure in RAD Security

Navigate to **Data Sources > Integrations > IAM** in your RAD Security workspace and enter:

| Parameter                              | Description                                                                               |
| -------------------------------------- | ----------------------------------------------------------------------------------------- |
| **Client ID**                          | The Client ID from Step 2                                                                 |
| **Client Secret or Private Key (PEM)** | The full **PEM private key** from Step 3, including the `-----BEGIN` and `-----END` lines |
| **Base URL**                           | Your Okta org URL (e.g. `https://your-org.okta.com`)                                      |

<Note>
  The **Client Secret or Private Key (PEM)** field carries either credential type. For this path it holds signing material, not a shared secret - paste the PEM private key exactly as Okta produced it.
</Note>

***

## Read-only trade-off

Omitting `okta.users.manage` makes the integration read-only and disables the connector's user-management actions:

* Disable and enable a user
* Force a password reset
* Expire a user's sessions

Reading users and groups and ingesting System Log events are unaffected. If you later need these actions, grant `okta.users.manage` and assign an admin role that permits them.

## Operational limits

<AccordionGroup>
  <Accordion title="System Log retention" icon="clock-rotate-left">
    Okta retains System Log events for **90 days**. This caps how far back RAD Security can backfill historical activity - events older than 90 days are no longer available from Okta at any scope or role.
  </Accordion>

  <Accordion title="System Log rate limits" icon="gauge-high">
    A single OAuth application may consume at most **50% of your org's `/api/v1/logs` rate-limit bucket**. If other applications are also polling the System Log, plan capacity accordingly.
  </Accordion>
</AccordionGroup>

## Verify Integration

After completing the setup, verify your integration is working:

1. Navigate to **Data Sources > Integrations > IAM** in RAD Security
2. Locate your Okta integration
3. Check the connection status shows as **Connected**
4. Confirm users and groups are syncing

<Check>
  Your Okta integration is now configured. RAD Security can sync identity data and audit events based on the scopes and admin role you granted.
</Check>

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 invalid_client" icon="triangle-exclamation">
    **Most common cause:** a client *secret* was supplied for a custom **API Services** app. The Okta org authorization server rejects this outright with:

    ```
    Client Credentials requests to the Org Authorization Server must use the
    private_key_jwt token_endpoint_auth_method.
    ```

    **Solution:**

    * For a custom API Services app, put the **PEM private key** in **Client Secret or Private Key (PEM)** - a client secret can never work on this path
    * Confirm the app's **Client authentication** is set to **Public key / Private key**
    * Verify the Client ID matches the app that owns the key pair
    * Check the PEM was pasted whole, including the `-----BEGIN` and `-----END` lines
    * If you want to use a client secret, install the OIN listing instead ([Option 1](#option-1-oin-api-service-integration))
  </Accordion>

  <Accordion title="400 invalid_dpop_proof" icon="shield-exclamation">
    DPoP is enabled on the app. Uncheck **General Settings > Proof of possession > Require Demonstrating Proof of Possession (DPoP) header in token requests**.

    <Info>
      This error is distinct from `401 invalid_client`. If you see `401 invalid_client`, DPoP is not the problem.
    </Info>
  </Accordion>

  <Accordion title="Insufficient permissions or empty results" icon="lock">
    Okta enforces **scope AND admin role** as an intersection, so a request can fail even when the scope is granted.

    **Solution:**

    * Confirm each scope shows as **Granted** on the **Okta API Scopes** tab - selecting is not granting
    * Confirm scopes were granted by a **Super Administrator**
    * Confirm the app has the **Read-only Administrator** role on the **Admin roles** tab
    * Replace any custom admin role with a standard one - custom roles cannot read the System Log
  </Accordion>

  <Accordion title="App unexpectedly has Super Administrator" icon="user-shield">
    **Public client app admins** was enabled in **Settings > Account** when the app's scopes were granted, so Okta auto-assigned **Super Administrator**.

    **Solution:**

    * Disable **Public client app admins** in **Settings > Account**
    * Remove the Super Administrator assignment on the app's **Admin roles** tab and assign **Read-only Administrator**
  </Accordion>

  <Accordion title="Historical events are missing" icon="file-excel">
    Okta's System Log retention is 90 days, so older events cannot be backfilled. Also verify the `okta.logs.read` scope is granted and the app holds a standard admin role with **View System Log (system events)** permission.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Identity & Access Overview" icon="key" href="/rad-security/integrations/identity-and-access">
    Learn about other identity integration options
  </Card>

  <Card title="Okta SSO Setup" icon="right-to-bracket" href="/rad-security/platform/enterprise-authentication/okta-sso-setup">
    Let your team sign in to RAD Security with Okta
  </Card>

  <Card title="Microsoft Entra ID" icon="microsoft" href="/rad-security/integrations/microsoft-entra-id-setup">
    Add Microsoft Entra ID as an additional identity source
  </Card>

  <Card title="User Management" icon="users" href="/rad-security/platform/workspace">
    Configure RBAC and manage users in your workspace
  </Card>
</CardGroup>