Okta & SCIM

Set up Okta for single sign-on (OIDC) and optional SCIM provisioning, so people are created, updated, and deactivated in Harriet automatically — and Okta groups map to Harriet roles.

⚠️

SCIM provisioning does not work until the Okta integration has been created in Harriet. Complete the OIDC setup below and select Save first, then configure SCIM in Okta.

Before you start

You need Owner (or equivalent) access in Harriet to add integrations.
For SCIM, you need a Harriet API token. Account owners create one from My preferences → Manage API tokens (open your name in the top-right menu). People with the Manage API Keys role can also manage tokens.
Know your company email domain (for example acme.com) — Harriet matches people to Okta by this domain.
Each person must already exist in Harriet (or be created via SCIM) before they can sign in with Okta. Harriet does not auto-create accounts on first OIDC login.

Create the OIDC app in Okta

Create the app integration. In the Okta Admin Console, go to Applications → Applications, select Create App Integration, choose OIDC - OpenID Connect and Web Application.
Set the redirect URI. Name the app (for example Harriet) and set the sign-in redirect URI to https://harriethq.com/bots/okta/callback/. Under controlled access, assign the users or groups who should sign in to Harriet.
Check grant type and scopes. The app must allow the Authorization Code grant, and requested scopes must include openid, profile, and email.
Note the credentials. Copy the Client ID and Client secret from the app's General tab, and keep your Okta domain handy (for example company.okta.com).

Configure the integration in Harriet

Open Company settings → Integrations and add or open the Okta integration.
Fill in the fields. Domain: your email domain (for example acme.com). Client ID: from the Okta app. Login Domain: your Okta org domain, used for SSO and API requests. Secret key: the Okta application client secret (not your Harriet API token).
(Optional) Enable Disable other login methods (SSO only) if people should sign in only via Okta, and not with a password or the Slack, Google, or Microsoft buttons.
Select Save. This creates the integration record SCIM needs.
Test it. Open the Harriet login page, choose Okta, and sign in with a work email on your domain. If you see No user found with this email, the account is not in Harriet yet: provision it via SCIM or add it manually.

Enable SCIM provisioning

Create a Harriet API token from My preferences → Manage API tokens. Copy it when shown; the full secret is not visible again later.
Install the Harriet app from the Okta Integration Network (Okta Marketplace).
Connect the API. In the Harriet app in Okta, go to Provisioning → Integration, enable API integration, paste the Harriet API token into API Token, and select Save.
Enable provisioning events. Under Provisioning → To App, enable Create Users, Update User Attributes, and Deactivate Users.
Assign people. Assign users or groups to the Harriet application in Okta so provisioning runs for the right population. No additional SCIM configuration is needed on the Harriet side.

Map Okta groups to Harriet roles

To assign Harriet roles automatically, push groups from Okta using these exact names (spaces and capitalization matter):

Okta group name	Harriet role
Harriet Owner Group	Owner
Harriet Admin Group	Admin
Harriet Support Group	Support (ticket access)
Harriet Access Personal Data Group	Access Personal Data
Harriet Access Pay Data Group	Access Pay Data
Harriet Manage Users Group	Manage Users
Harriet Manage Knowledge Group	Manage Knowledge
Harriet Manage Workflows Group	Manage Workflows
Harriet Manage Embeds Group	Manage Embeds
Harriet Access Billing Group	Access Billing
Harriet Manage Integrations Group	Manage Integrations
Harriet Export Data Group	Export Data
Harriet Manage API Keys Group	Manage API Keys
Harriet Finance Group	Finance
Harriet Restricted Access Group	Restricted access (disables personal data and other sensitive features, for example for contractors)

Any other group name pushed from Okta creates a matching user group in Harriet without special role assignments, useful for building teams that profiles can target. After changing membership in Okta, use Push Now if people or roles do not update immediately.

What happens on deactivation

With Deactivate Users enabled, deactivating a person in Okta (or removing their assignment to the Harriet app) deactivates their Harriet account through SCIM. They can no longer sign in, including with any non-Okta method. This is the offboarding path: leavers lose Harriet access when they lose Okta access, with no separate checklist step.

Troubleshooting

Symptom	What to check
SCIM never creates users	The Harriet Okta integration was saved before SCIM was enabled in Okta; the token in Okta is a Harriet API token, not the OIDC client secret.
SSO redirect error	The sign-in redirect URI in Okta exactly matches `https://harriethq.com/bots/okta/callback/`.
No Okta integration found for this domain	Domain in Harriet matches the email domain people type at login.
No user found with this email	The person exists in Harriet with that email (via SCIM or manually). Email matching is not case-sensitive.
Wrong roles after group push	Okta group names match the table above exactly.

For the other ways people sign in, see Single sign-on.