> For the complete documentation index, see [llms.txt](https://herd-security.gitbook.io/herd-security-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://herd-security.gitbook.io/herd-security-docs/okta/okta-group-and-app-sync.md).

# Okta Group & App Sync

## Overview

Okta group sync allows for current Okta customers to pull all user group information from their current Okta tenant into Herd. Allowing for organizations to assign trainings, campaigns, events, and stacks, to groups instead of individual users.

## Prerequisites

In order to complete this setup, you'll need:

* Access to Okta API token permissions. Allowing you to create or utilize an API token from your Okta tenant.
* Access to the Herd admin console.

## Setup Okta Token

1. Log in to your organization's Okta tenant as an administrator.
2. Find *Security* -> *API* -> *Tokens*

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

3. Create a new token with the following permissions:

For Group Sync:

* `okta.users.read`
* `okta.groups.read`

For App Sync:

* `okta.apps.read`

For Work-Information Attribute Mapping (optional):

* `okta.schemas.read`

{% hint style="info" %}
As part of user sync, Herd also reads each user's MFA factors via `/users/{id}/factors`, which is covered by the `okta.users.read` scope. No additional scope is required.
{% endhint %}

{% hint style="warning" %}
An Okta API token inherits the privileges of the admin account that creates it.

A **Read-Only Administrator** account covers everything Herd syncs — users, groups and app assignments. It does **not** carry `okta.schemas.read`, and Okta does not expose that permission when building a custom admin role either, so in practice a token used for [work-information attribute mapping](#work-information-attribute-mapping) must be created by a **Super Administrator**.

Attribute mapping is optional. If you don't need it, a Read-Only Administrator token is sufficient and everything else — group sync, app sync, user sync, auto-assignment — works normally.
{% endhint %}

<figure><img src="/files/1LqN6bWa9x0m7lREodkG" alt=""><figcaption></figcaption></figure>

4. Save the API token to share with Herd.

## Find Your Okta Domain

The easiest way to find your Okta domain is to look in the URL when logged in to the Okta admin console. It's typically formatted as `company-url.okta.com` .

## Share Your Okta Token & Domain In Herd

1. Log in to the Herd admin console.
2. Select **Settings** in the left side toolbar, then switch to the **Integrations** tab — the **Okta** card lives in the **Identity** section.
3. Under **Okta Integration**, open the **Okta Configuration Settings**.

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

4. Place your Okta domain in the first box.
5. Place your Okta API token in the second box.
6. Save Configuration.

## Sync Okta Group & Apps

By selecting Sync groups, Herd will pull group information from Okta into Herd. Groups will be automatically attached to respective users. In order to use the security advisor feature, you'll need to sync apps as well.

***

## Validating the connection

Once Okta credentials are configured, the Okta Integration tile shows a live connection status and a **Test connection** button — Herd probes your Okta tenant and confirms the API token authenticates and can read users. Credentials are also validated at save time, with specific guidance when something's off (wrong domain format, an expired token, or a token whose admin account lacks read access — a **Read-Only Administrator** role or better is required for the user, group and app reads).

The same check reports whether the token can read your Okta **user profile schema**. If it can't, Herd saves the credentials and syncs as normal, and notes on the tile that work-information attribute mapping is unavailable until the token is replaced with one created by a Super Administrator.

***

## Work-information attribute mapping

{% hint style="warning" %}
This screen requires an API token created by a **Super Administrator**. Reading your profile schema needs Okta's `okta.schemas.read` permission, which a Read-Only Administrator token does not carry — with one, the modal explains that instead of listing attributes. Sync and auto-assignment are unaffected, and every field keeps its default attribute.
{% endhint %}

By default, Herd reads each user's work information from Okta's standard profile attributes — `department`, `division`, `title`, `organization`, `userType`, `manager`, `managerId`, `employeeNumber`, and `costCenter`. If your Okta profile stores these under **custom attributes**, remap them: on the Okta Integration tile, click **Edit attribute mapping**.

The **Work information attribute mapping** modal lists each Herd field with a dropdown of every attribute in your live Okta profile schema (custom attributes included), so you can point, say, Herd's **Department** at your `org_dept` custom attribute. Saving a change triggers a full re-sync that backfills every existing user from the new attributes. **Reset to defaults** restores the standard mapping.

These fields flow everywhere work information is used — user profiles, the Department column and filters, manager linking and escalations, dynamic group rules, and [custom message variables](/herd-security-docs/settings/settings/general-and-approvals.md#custom-variables-directory-lookup-variables).