# Okta Data Integration

## Overview <a href="#overview" id="overview"></a>

The Cisco Identity Intelligence security platform reads a variety of user account data and event data to build a full picture of the identity security posture of your Okta tenant, as well as on-going identity threats against your organization.

## Okta OAuth2 Data Integration <a href="#okta-data-integration-1" id="okta-data-integration-1"></a>

Identity Intelligence has created an OAuth2 SPI service application in the Okta network for the purpose of the data ingestion. &#x20;

This bar below is the link to the application in the Okta network :point\_down:<br>

{% embed url="<https://www.okta.com/integrations/cisco-identity-intelligence-read-write-management-api-service/>" %}

To implement this application, do the following:

1. Confirm that your Okta organization is using Okta Identity Engine (OIE), and not Okta Classic. [Upgrade if needed](https://help.okta.com/oie/en-us/content/topics/identity-engine/oie-upgrade-eligibility.htm#:~:text=Okta%20provides%20a%20self%2Dservice,upgrade%20to%20Okta%20Identity%20Engine). If you're unsure which solution you're using, check the footer on any page of the Okta Admin Console. The version number is appended with E for OIE orgs and C for Classic Engine orgs
2. Select **Add Integration** from the link in the bar above :point\_up: or search for the API Integration within the Okta Admin Console (If you have multiple tenants, ensure you're signed into the correct Okta org!). Then select **Next**
3. Select **Install & Authorize**<br>

   <figure><img src="/files/tkWGwQ2tYyu2la7bKVOs" alt=""><figcaption></figcaption></figure>
4. Copy the client secret to a secure location, such as a key vault, if desired
5. Select **Done**
6. Within your Identity Intelligence tenant, go to the **Integrations** page and select **Add Integration**.  Select the Okta integration
7. Enter the display name, Issuer (your Okta URL), Client ID, and Client Secret in the respective fields and select the **Save** button<br>

   <figure><img src="/files/oxjJmrgyDAUvB3Npot6p" alt=""><figcaption></figcaption></figure>
8. Under the **Advanced Tab**, review the answers to the questions in the top section of the page to make sure they are answered correctly. Then ensure the integration is set to "Managed" to enable the relevant data types based on the answers to those questions. Read our documentation about [Managed Integrations ](/integrations/managed-integrations.md)to learn about the benefits<br>

   <figure><img src="/files/oKBmaoSji1mpFzuBU3PN" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
After configuration is completed in both systems, you may see a yellow banner on the Identity Intelligence API Service App page in the Okta Admin Console that states, "Cisco Identity Intelligence - Read - Write Management API Service is not configured until you complete the setup instructions".  You can disregard this message. The integration is fully configured
{% endhint %}

### Test Connectivity

1. On the Integrations page, select the **three dots menu** on the right side of the new Okta integration tile. Select **Test Connectivity**

### Configure Okta Event Streaming

If you have the Log Streaming module as part of your current Okta subscription follow the steps below to configure Log Streaming. **Log Streaming is not required to configure the Okta Data Integration, but it is recommended if you have it.**&#x20;

1. Once successfully verified, select the 3-dot menu again and select **Edit settings** for the Okta integration.  Go to the **Event Streaming** tab
2. Use the information provided to set up Okta log streaming via an AWS Eventbridge. [Instructions can be found here](/integrations/okta-aws-eventbridge-streaming-integration.md)&#x20;
3. After you register the log stream, select **Save.** Then use the 3-dot menu for the integration and select **Collect Now** to begin initial data collection

**NOTE:** Due to Okta API rate limiting, the initial data collection, including historical log data, may take 24 hrs or longer. Your Identity Intelligence technical contact will assist with any questions in this process

## Okta Read-only OAuth 2.0 Client Application (BETA)

The Okta Service Application integration is the preferred method for collecting data from Okta as it the most secure, ensures the best experience and will automatically update when Identity Intelligence supports collection of additional data types. Although it requests certain scopes or permissions, such as "create user", these are required by Okta for Service Apps and Identity Intelligence does not utilize these permissions.  \
\
Although we **highly** recommend using the Okta Service Application, if required, there is also read-only option using OAuth 2.0, which is a widely adopted authorization framework that provides secure and scalable access delegation. In this context, Okta's implementation of OAuth 2.0 allows you to grant specific API permissions to applications while maintaining control over sensitive resources. For this reason, it require a more complex set up and  will require manual updates from your Okta Admin to grant access to new scopes or permissions when Identity Intelligence adds them.&#x20;

This section provides a step-by-step guide for configuring a read-only **OAuth 2.0 API service integration** with Okta. By following this guide, you will enable secure access to Okta APIs with the least privilege principle, ensuring that the integration can only retrieve (read) data without the ability to modify it.

#### Key Features of This Integration

* **Read-Only Access**: Limit the scope of API access to read-only operations, ensuring enhanced security
* **Scoped Permissions**: Use OAuth 2.0 scopes to define the exact level of access the integration is permitted
* **Service Account Integration**: Create a service account that interacts programmatically with Okta APIs
* **Secure Authentication**: Leverage client credentials for authentication to ensure secure communication

#### Prerequisites

Before you begin, ensure you have the following:

1. <mark style="color:$danger;">**IMPORTANT:**</mark>**&#x20;Contact Cisco or Duo Support to have this feature enabled for your Identity Intelligence tenant**
2. **Administrative Access to Okta**: You must have the necessary permissions to create and manage API service integrations within your Okta instance
3. **Okta Developer Account or Production Environment**: A valid Okta environment where the integration will be configured
4. **Understanding of OAuth 2.0**: Familiarity with OAuth 2.0 concepts such as scopes, tokens, and client credentials

#### What You'll Learn

By the end of this section, you will:

* Set up an OAuth 2.0 application in Okta
* Configure client credentials for secure API authentication
* Define and apply the appropriate read-only scopes for the integration
* Test the integration to ensure it retrieves data as expected

Let’s get started with the configuration process!

#### Okta Integration: creation of the OIDC client in Okta with Public/Private Keys authentication for read-only integration

**Step 1: Log into Okta Admin Console**

1. Open your Okta Admin Console (e.g., <https://your-org.okta.com/>)
2. Log in using your admin credentials

**Step 2: Create a custom admin role**

1. Navigate to **Security** > **Administrators** > **Roles** tab
2. Select **Create role**
3. Provide a name and description for the role
4. Under Permissions, select **Identity and Access Management** > **View roles, resources, and admin assignments**
5. Select **Save Role**

<figure><img src="/files/LYkswt4atUpaWOwyRMpM" alt=""><figcaption></figcaption></figure>

**Step 3: Create an API Services Application**

1. In the Okta Admin Console, go to Applications > Applications
2. Select **Create a new app integration**
3. Choose **API Services** and select **Next**<br>

   <figure><img src="/files/3715At84zw61nf3Fn11B" alt=""><figcaption></figcaption></figure>
4. Enter a recongizable name for your App Integration and select **Save**
5. Under Client Credentials, select **Client Authentication** and then **Edit**.
6. Select **Public key / Private key** as the authentication method
7. Check the box to **Save keys in Okta**
8. Select **Add Key**, then select **Generate new key**
9. Choose Private Key in **PEM format** (not JSON), and make sure to <mark style="color:$warning;">**copy the private key and KID to a secure location**</mark> (you won’t be able to see the private key again once you close this window).<br>

   <figure><img src="/files/rDWl0yxdP8mjnLdxiLR6" alt=""><figcaption></figcaption></figure>
10. Select **Done**, then select **Save**
11. Under General Settings, select **Edit**, deselect **Proof of possession**, then select **Save**<br>

    <figure><img src="/files/Z4OHjhpK7AQWYfVneDhP" alt=""><figcaption></figcaption></figure>

&#x20;

**Step 4: Configure Permissions**

1. Go to the Okta API Scopes tab
2. Grant the necessary permissions for the scopes required by Identity Intelligence

<figure><img src="/files/OOUxgPohT4zCDGbaaaCl" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/tP3KBG00g5VE0yZlpLVq" alt=""><figcaption></figcaption></figure>

**Step 5: Configure Admin Roles**&#x20;

1. On the Admin roles tab, add two roles to this application
   1. Add **Super Admin role OR Org Administrator role** (Without Org Admin role, Identity Intelligence will **not** be able to collect `API Service Integration` details for the tenant)
   2. Add the custom role created in the steps above, with a resource set of `All Identity and Access Management resources`\
      \
      **NOTE** - the application is still constrained by the granted API scopes. However, per Okta, a corresponding role must be granted that allows the selected scopes, such as `okta.schemas.read` See [their article](https://developer.okta.com/docs/guides/implement-oauth-for-okta-serviceapp/main/#use-the-client-credentials-grant-flow) for more details on this

<figure><img src="/files/iNgIBOqiWOOjTeYbH6HI" alt=""><figcaption></figcaption></figure>

**Step 6: Configure Okta Integration in Identity Intelligence**

1. Within Identity Intelligence, navigate to **Integrations** > select the **Add Integration** button> select Okta
2. Check the box for <mark style="color:blue;">**public/private key authentication**</mark>

{% hint style="info" %} <mark style="color:$warning;">**NOTE:**</mark>  <mark style="color:$primary;">If you do not see this option, contact Cisco or Duo support to have this feature enabled for your tenant.</mark>&#x20;
{% endhint %}

3. Use the following details to configure the Okta integration in Identity Intelligence:
   1. Display name
   2. Okta domain (URL)
   3. Client ID
   4. KID
   5. Private Key PEM file<br>

      <figure><img src="/files/1tD7jJ4Czx8rVkjFbnWT" alt=""><figcaption></figcaption></figure>
4. Select **Connect** and the API connection will be tested automatically
5. We highly recommend implementing [#configure-okta-event-streaming](#configure-okta-event-streaming "mention")


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.oort.io/integrations/okta-data-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.