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

# Connect Okta

> Connect TruU IDV to Okta with a read-only API Services app using private key JWT: the scopes to grant, the values to enter, and how to verify the connection.

This page is for the Okta administrator connecting TruU IDV to your Okta org. When you finish, TruU can look up employees and their groups with read-only scopes you can revoke at any time.

## Before you start

* An Okta administrator who can create an API Services app and grant Okta API scopes (Super Administrator, or an administrator with app and scope management rights).
* Your Okta org URL, for example `https://example.okta.com`.
* An **Owner** or **Admin** seat in TruU IDV.

### Scopes TruU needs

| Scope | Why |
| - | - |
| `okta.users.read` | Read users and the attributes you map |
| `okta.groups.read` | List groups for use case rules and look up a person's memberships |

TruU requests no write scope. Okta profile photos aren't used for Face; use proofing photos or your own storage instead. See [Face](https://docs.truu.ai/idv/factors/face.md).

## Set it up

**1. Create an API Services app**

In the Okta Admin Console, go to **Applications → Applications → Create App Integration**, choose **API Services**, and name it (for example "TruU IDV").

**2. Use public key authentication**

On the app's **General** tab, under **Client Credentials**, choose **Public key / Private key** as the client authentication method. Add a key: generate one in Okta and copy the **private key in JWK format** (shown once), or upload the public half of an RSA key you generated yourself and keep the private JWK. The key must be RSA; TruU signs with RS256. If Okta asks, turn off **Require Demonstrating Proof of Possession (DPoP)**.

**3. Grant the scopes**

On the **Okta API Scopes** tab, grant `okta.users.read` and `okta.groups.read`.

**4. Grant a read-only admin role**

On the **Admin roles** tab, assign **Read-only Administrator** so the app can read users and groups across the org.

**5. Connect in TruU**

Open **Settings → Directory**, choose **Okta**, and enter the **Org URL** (must start with `https://` and be an Okta domain), the **Client ID** and the **Private key (JWK)**. Choose **Connect**.

**6. Review the attribute mapping**

TruU scans your users and proposes which attribute each factor uses. Adjust where coverage is better, then **Save mapping**. See [Attribute mapping and coverage](https://docs.truu.ai/idv/connect/directory/overview.md#attribute-mapping-and-coverage).

## Test it

TruU checks the connection when you connect, daily, and on demand from [Credential health](https://docs.truu.ai/idv/admin/credential-health.md): that a token can be issued with your key, that users can be listed (`okta.users.read`) and that groups can be listed (`okta.groups.read`). Then send yourself a verification and confirm your own record is found.

## How it works

* **Token.** TruU signs a short-lived assertion with your private key and exchanges it for an Okta access token, cached for under an hour.
* **Live lookups.** Users and group memberships are read at verification time.
* **Secrets.** The private key is held in a managed secrets service and never returned. Every connection change is recorded in the [audit trail](https://docs.truu.ai/idv/security/audit-events.md).

## Troubleshooting

| Symptom | Cause | Fix |
| - | - | - |
| "Org URL must be an Okta domain" | The URL is a custom domain or has a path | Use your `*.okta.com`, `*.oktapreview.com` or `*.okta-emea.com` org URL |
| "Private key JWK must be valid JSON" | The key was pasted in PEM format or truncated | Paste the private key as JWK JSON, including the `kid` |
| User list check fails | `okta.users.read` isn't granted, or the app has no admin role | Grant the scope and the Read-only Administrator role |
| Groups check fails | `okta.groups.read` isn't granted | Grant the scope; it can take a moment to apply |

## Related

* [Connect your directory](https://docs.truu.ai/idv/connect/directory/overview.md)
* [Sign-in, SSO and passkeys](https://docs.truu.ai/idv/admin/sign-in.md): Okta can also be used for console SSO


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.