--- title: Okta Identity Entity Pack description: >- Sync your Okta user directory into Cloud SIEM to add identity context to signals, risks, and investigations. breadcrumbs: >- Docs > Datadog Security > Cloud SIEM > Ingest and Enrich > Entity Packs > Okta Identity Entity Pack --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # Okta Identity Entity Pack {% callout %} # Important note for users on the following Datadog sites: app.ddog-gov.com {% alert level="warning" %} Entity Packs are not available for the US1-FED Datadog site. {% /alert %} {% /callout %} ## Overview{% #overview %} The Okta Identity Entity Pack syncs your Okta user directory into Cloud SIEM. After you connect it, Cloud SIEM uses that directory to: - Populate the [User Inventory](https://docs.datadoghq.com/help/) with your Okta users. - Attach a user pill to signals so you can see who is behind the activity. - Score risk for a user across all their accounts in [Entity Risks](https://docs.datadoghq.com/security/cloud_siem/triage_and_investigate/entities_and_risk_scoring.md). For what Entity Packs provide in general, and the permissions they require, see [Entity Packs](https://docs.datadoghq.com/security/cloud_siem/ingest_and_enrich/entity_packs.md). Datadog reads your directory through the [Okta Users API](https://developer.okta.com/docs/api/openapi/okta-management/management/tags/user), authenticating with an Okta API token that you create. Read-only access is all that is needed. Datadog never writes to your directory. ## Prerequisites{% #prerequisites %} Setup takes three values: a **Name**, your **Okta Domain**, and an **API Token**. You enter all three in the Entity Pack; the token is created in Okta. Before you begin, make sure you have: - An Okta admin role that can create an API token and read users. **Read-only Administrator** is enough, and broader admin roles work too. See Okta's [standard administrator roles and permissions](https://help.okta.com/en-us/content/topics/security/administrators-admin-comparison.htm). - The **SIEM Entities Admin** permission in Datadog, which is required to connect a directory. Analysts who need the identity context it provides need at least **SIEM Entities Read**. See [Entity Packs](https://docs.datadoghq.com/security/cloud_siem/ingest_and_enrich/entity_packs.md). ## Setup{% #setup %} You can configure one set of credentials per Okta org. To sync more than one, see Connect additional Okta orgs. ### Create the API token{% #create-the-api-token %} 1. In the Okta Admin Console, go to **Security** > **API**. 1. Click the **Tokens** tab, then click **Create token**. 1. Name the token something that identifies Datadog as the consumer; for example, `datadog-cloud-siem`. 1. From **API calls made with this token must originate from**, select **Any IP**. To restrict the token to Datadog's addresses instead, see Network restrictions. 1. Click **Create token**, then copy the token value immediately. Okta shows it only once and stores a hash of it afterward. For the full procedure and the other network zone options, see Okta's [Manage Okta API tokens](https://help.okta.com/en-us/content/topics/security/api.htm). {% alert level="info" %} Create the token from a dedicated service account, such as `datadog-integration@example.com`, rather than from a person's account. A token inherits the permissions of the account that created it, and Okta rejects tokens from accounts that have been deactivated. If that account belongs to someone who leaves or loses their admin role, the sync stops, and the cause is hard to trace. {% /alert %} #### Token expiration{% #token-expiration %} Okta API tokens are valid for 30 days, and every API request renews the token. An active Entity Pack therefore keeps its own token alive. A token left unused for more than 30 days is revoked permanently and cannot be reinstated. #### Network restrictions{% #network-restrictions %} Selecting **Any IP** is the simplest option. If your organization requires a restricted token, scope it to an Okta IP zone containing Datadog's published IP ranges. Datadog publishes those ranges as JSON at a per-site endpoint. For the US1 site, that endpoint is `https://ip-ranges.datadoghq.com/`. Use the one that matches your own Datadog site, and refresh your zone whenever the ranges change. The response includes `version` and `modified` fields you can watch. For the full list of endpoints, see [IP Ranges](https://docs.datadoghq.com/api/latest/ip-ranges.md). Two Okta constraints apply if you take this route. SSWS tokens work only with IP-based zones, not dynamic ones, and they cannot be used with blocklist zones. #### Okta domain{% #okta-domain %} Enter the host you sign in to, without a scheme or path (for example, `example.okta.com`). ### Add credentials in Datadog{% #add-credentials-in-datadog %} 1. In Datadog, go to **Cloud SIEM** > [**Content Packs**](https://app.datadoghq.com/security/siem/content-packs). 1. Filter by **Entity Pack**, then open the **Okta Identity** Entity Pack. It is marked **AVAILABLE** until you connect a directory. 1. Click **Add Credentials**. 1. In the **Add credentials and activate content pack** dialog, complete the three fields: | Field | Description | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Name** | A display name for this set of credentials; for example, `Production credentials`. Use a name that identifies the org if you plan to connect more than one. | | **Okta Domain** | The Okta org to sync; for example, `example.okta.com`. Enter the host only, with no scheme or path. | | **API Token** | The token value you copied from Okta. Paste the value by itself, without the `SSWS` prefix used in raw API requests. | 1. Click **Test Connection**. Datadog validates the credentials against Okta before saving them. If validation fails, see Troubleshooting. 1. When the connection test succeeds, save the credentials to activate the Entity Pack. Datadog encrypts the API token at rest and never returns it in the interface or in API responses. ## Verify the sync{% #verify-the-sync %} Synchronization is continuous. The first sync starts as soon as Datadog validates the credential, and each sync after that begins when the previous one finishes, so you never schedule or trigger a sync yourself. That makes **Last synced** a health check in its own right. A healthy account is always recently synced, so a **Last synced** time that stops advancing means something is wrong. After Datadog validates a credential, the Entity Pack is marked **ACTIVE**. Open its side panel in Cloud SIEM and check the following: ### Credentials{% #credentials %} The **Credentials** section lists each connected account. Expand an account to see: | Field | What it tells you | | ---------------------- | ------------------------------------------------------------------------------------------------- | | **Domain** | The Okta org this account syncs. | | **Status** | Whether synchronization is **Enabled** or disabled for this account. Use the toggle to change it. | | **Last updated** | When the credential itself was last modified. | | **Sync status** | Whether the most recent sync completed; for example, `Synced`. | | **Last synced** | How long ago the most recent sync ran. | | **Last sync duration** | How long that sync took. | Each account also carries a validation badge: | Badge | Meaning | | ----------- | -------------------------------------------------------- | | **VALID** | Datadog can authenticate to Okta with these credentials. | | **INVALID** | Datadog cannot authenticate. See Troubleshooting. | Through the API, a credential reports `initializing` after Datadog accepts it and before the first sync completes. ### Key Metrics{% #key-metrics %} The **Key Metrics** dashboard shows four widgets: - **Users Synced**: How many users a sync updated. This measures directory churn rather than directory size, so it normally reads far lower than your total user count. For the total, use the Entities section below. - **Users by Credential**: The same count, broken out by connected account. - **Sync History by Credential**: Completed syncs over time. A gap means a sync failed or was skipped. - **Sync Duration by Credential**: How long each sync took. An occasional spike is normal. A sustained climb usually means the directory is growing, or that Okta is rate limiting the calls. Each per-credential widget groups by `credential_name`, which is derived from the **Name** you entered. ### Entities{% #entities %} The **Entities** section lists the users this Entity Pack synced. Each row shows **Display Name**, **Principal ID**, **User Type** (for example, `human` or `service_account`), and **Account Status** (for example, **ACTIVE**). Cloud SIEM normalizes Okta's user statuses to the common status model it uses for every identity provider (**ACTIVE**, **SUSPENDED**, **DELETED**). The values here are not Okta's own status names. The entity count is the total number of users synced from this directory, which makes it the figure to compare against the size of your Okta directory. The list covers a time range you can change. To see everything, click **View in User Inventory**. ## Connect additional Okta orgs{% #connect-additional-okta-orgs %} Each set of credentials syncs one Okta org. To sync another, create an API token in that org, then click **Add account** in the **Credentials** section of the Entity Pack side panel. When you connect multiple orgs: - Name each account after the org it syncs. The three per-credential widgets group by `credential_name`, a normalized form of the **Name** you enter, so vague names make those widgets hard to read. - Use the per-account toggle under **Status** to pause synchronization for one org without removing its credential. - Create a separate API token in each org. A token authenticates only against the org that issued it. ## Troubleshooting{% #troubleshooting %} ### The connection test fails{% #the-connection-test-fails %} Work through these causes in order: | Cause | How to confirm | Fix | | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | Token value pasted with the `SSWS` prefix or surrounding whitespace | The value you pasted is longer than the token Okta displayed | Re-paste the token value by itself. | | Okta domain entered with a scheme or path | The **Okta Domain** value starts with `https://`, or ends in `/admin` or a trailing slash | Enter the host only; for example, `example.okta.com`. | | Wrong Okta org host | The value uses `example.okta.com` for a preview org, or omits the `-emea` suffix for an EMEA org | Use the host you sign in to: `example.oktapreview.com` or `example.okta-emea.com`. | | Token creator is not an admin, or cannot read users | The account that created the token has no admin role in the Okta Admin Console | Create the token from an account with **Read-only Administrator** or a broader admin role. | | Token creator was deactivated | The account that created the token is no longer active in Okta | Create a token from an active service account. Okta rejects tokens from deactivated users. | | Token revoked or expired | The token is missing from the **Tokens** tab in Okta, or its last-used date is more than 30 days old | Create a token and add it in Datadog. Okta permanently revokes tokens left unused for 30 days. | | Token restricted to network zones that exclude Datadog | The token's **Token can be used from** setting is anything other than **Any IP** | Set the token to **Any IP**, or confirm the IP zone covers Datadog's published ranges. See Network restrictions. | ### Credentials were working and are now invalid{% #credentials-were-working-and-are-now-invalid %} The cause is usually a change on the Okta side: - The account that created the token was deactivated, or lost the admin role that gave it read access to users. A token's permissions follow the creating account's, so a role change alone can break the sync. This is the common failure when the token belongs to a person rather than a service account. - The token was revoked from the **Tokens** tab, or expired after 30 days without use. - The token's network zone restrictions changed. Okta logs token creation and revocation in the System Log as `API token created` and `API token revoked`. That is the fastest way to confirm whether a token was revoked, and by whom. ### Syncs are slow or intermittent{% #syncs-are-slow-or-intermittent %} Okta applies API rate limits per org and returns `HTTP 429 Too Many Requests` once a limit is exceeded. Tokens created in the Okta Admin Console default to 50% of each rate limit, and any other integration calling with the same token draws on that same budget. - In Okta, check **Reports** > **Rate Limits** for warnings and violations, which Okta also writes to the System Log. - On the token's page in Okta, raise the **Token rate limits** percentage if the default is constraining the sync. - Give Datadog its own token rather than reusing one that other integrations already call with. See Okta's [rate limits overview](https://developer.okta.com/docs/reference/rate-limits/). ### The sync succeeds but no users appear{% #the-sync-succeeds-but-no-users-appear %} - Confirm that the **Domain** value matches the domain whose users you expect. A valid admin user in a different domain than the one you entered can produce an empty result. ### No user pill appears on signals{% #no-user-pill-appears-on-signals %} Cloud SIEM matches identity context to events by email address. If a synced user has no pill on their activity, check that the logs from that source populate the user email field, and that the source's OCSF pipeline is active. See [Open Cybersecurity Schema Framework](https://docs.datadoghq.com/security/cloud_siem/ingest_and_enrich/open_cybersecurity_schema_framework.md). An Entity Pack does not require the matching log integration, and the integration does not require the Entity Pack. If you are syncing the directory but see no Okta activity to attach it to, you may also need the [Okta log integration](https://docs.datadoghq.com/integrations/okta.md). If you still need help, contact [Datadog support](https://docs.datadoghq.com/help/). ## Further reading{% #further-reading %} Additional helpful documentation, links, and articles: - [Learn more about Entity Packs](https://docs.datadoghq.com/security/cloud_siem/ingest_and_enrich/entity_packs.md) - [Set up the Google Workspace Identity Entity Pack](https://docs.datadoghq.com/security/cloud_siem/ingest_and_enrich/entity_packs/google_workspace.md) - [Set up the Microsoft Entra ID Entity Pack](https://docs.datadoghq.com/security/cloud_siem/ingest_and_enrich/entity_packs/microsoft_entra_id.md) - [Browse synced users in the User Inventory](https://docs.datadoghq.com/security/cloud_siem/triage_and_investigate/user_inventory.md) - [Explore entities and risk scoring with Entity Risks](https://docs.datadoghq.com/security/cloud_siem/triage_and_investigate/entities_and_risk_scoring.md) - [Collect Okta logs with the Okta integration](https://docs.datadoghq.com/integrations/okta.md)