Okta Group & App Sync

This guide will show how to sync your current Okta groups into Herd.

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.

Herd can authenticate to your Okta tenant in one of two ways:

• API service app (recommended) — an OAuth 2.0 API Services application in your Okta org. Herd holds a private signing key and you register only the public key in Okta. No admin account is involved and nothing expires unexpectedly.

• API token (legacy) — a classic Okta API token created by an administrator. Existing connections keep working unchanged; nothing forces a migration.

Both methods appear as tabs under Okta Configuration Settings on the Okta integration tile. Pick one and follow the matching section below.

Prerequisites

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

• Administrator access to your Okta tenant. For the service app you need to be able to create an API Services app integration; for the legacy token, permission to create API tokens.

• Access to the Herd admin console with the Integrations permission (admins always have it).

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 (or company-url.oktapreview.com). Enter it without https://.

Open the Okta configuration 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 Okta Configuration Settings.

4. Choose the API service app (recommended) tab or the API token (legacy) tab.

---

Option A: Connect with an API service app (recommended)

Herd walks you through three numbered steps on the API service app (recommended) tab. You'll switch between Herd and the Okta Admin Console as you go.

Step 1: Signing key

1. In Herd, enter your Okta Domain, then click Generate signing key. Herd creates an RSA-2048 key pair for your organization; the private key stays encrypted in Herd and is never shown.

2. Herd displays the Public key (JWK) and its Key ID (kid). Use Copy public key to copy it.

3. In the Okta Admin Console, go to Applications → Create App Integration and choose the API Services type. Name it something like "Herd".

4. On the new app, open the Client Credentials section, set client authentication to Public key / Private key with keys saved in Okta, add a key, and paste the JWK you copied from Herd.

Step 2: Okta API scopes to grant

On the app's Okta API Scopes tab click Grant for each scope, then under Admin roles assign at least Read-Only Administrator. Every scope is read-only.

Scope	Required	Used for
okta.users.read	Yes	Directory users, their profiles and enrolled MFA factors (user sync, risk posture)
okta.groups.read	Yes	Groups and group memberships (group sync, sync scope)
okta.apps.read	Yes	App inventory and app assignments (technology profile, AI-app access)
okta.userTypes.read	Optional	Directory user types (service-account detection)
okta.schemas.read	Optional	User profile schema (work-information attribute remapping)

The same list appears as checkboxes in Herd, with Copy scopes to copy them in one go. Untick any optional scope you did not grant in Okta: Okta refuses the whole token request if Herd asks for a scope the app hasn't been granted.

Step 3: Client ID

1. Copy the Client ID from the app's General tab (under Client Credentials) and paste it into Herd.

2. Click Save & test connection. Herd requests a token from Okta and reads one user to prove the key, scopes, and admin role all line up before anything is stored. If the test fails, nothing is saved and the message from Okta is shown so you can fix the app.

Rotating the key. Click Rotate signing key on the tile at any time. Okta will reject Herd until you register the new public key on the API Services app, so register it and save again straight away.

If the API Services app is configured in Okta to require DPoP (Demonstrating Proof of Possession) on token requests, Herd reports this when you save rather than connecting. Turn that setting off on the app before connecting.

---

Option B: Connect with an API token (legacy)

Setup Okta Token

1. Log in to your organization's Okta tenant as an administrator.

2. Find Security -> API -> Tokens

1. 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

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.

An Okta API token inherits the privileges of the admin account that creates it, and it never expires.

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 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. If you would rather not tie Herd to an admin's account at all, use the API service app instead.

1. Save the API token to share with Herd.

Share Your Okta Token & Domain In Herd

1. On the API token (legacy) tab, place your Okta domain in the Okta Domain box.

2. Place your Okta API token in the Okta API Token box.

3. Click Save Okta Configuration. Credentials are verified against Okta before they are saved.

---

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 credentials authenticate and can read users. For a service app, the test mints a fresh token first, so it also proves the public key is still registered and the granted scopes match. Credentials are also validated at save time, with specific guidance when something's off (wrong domain format, an expired token, or credentials whose admin role lacks read access — a Read-Only Administrator role or better is required for the user, group and app reads).

The same check reports whether Herd 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 credentials are updated (a Super Administrator token, or the okta.schemas.read scope on a service app).

---

Sync scope: syncing only selected Okta groups

By default Herd syncs your entire directory: every user and every group. If you only want part of your directory in Herd (for example a single "all employees" group in a tenant that also holds hundreds of service or partner groups), you can scope the sync to specific Okta groups.

Once Okta is connected, the Okta Integration tile shows the current scope (Sync scope: entire directory (all users and groups) by default) with an Edit sync scope button.

A scoped sync is a statement about who belongs in Herd. Members of the selected groups are provisioned automatically; users who leave every selected group are deactivated on the next full sync, and groups outside the scope are removed from Herd. Herd previews exactly this impact before anything is written.

1. Click Edit sync scope to open the Okta sync scope dialog. Use Search groups to filter by group name and tick the groups to keep in sync. Leaving every group unticked syncs the whole directory.

2. Click Review changes. Herd works out what applying the scope would do to your current data and shows it: how many users are in the selected groups, how many users would lose their Okta link (and which of those are not active in Slack, Teams or Google either, so would be removed from Herd entirely), and which groups would be removed. A sample of the affected users and groups is listed; counts are always exact.

3. Click Apply scope to save, or Back to change the selection. Nothing is written until you apply.

To return to a full-directory sync, open the dialog, click Clear selection and then Clear scope. The next sync covers the whole directory again and restores anything a scoped sync deprovisioned.

Sync scope is included from the Growth plan upward; on the Trial plan the section shows a Learn more upgrade prompt.

---

Work-information attribute mapping

This screen needs permission to read your Okta user profile schema: the okta.schemas.read scope on a service app, or a legacy API token created by a Super Administrator (a Read-Only Administrator token does not carry it). Without it, the modal explains that instead of listing attributes. Sync and auto-assignment are unaffected, and every field keeps its default attribute.

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.