How to set up Okta with Harriet

Use Okta with Harriet for single sign-on (SSO) and optional SCIM provisioning (create, update, and deactivate users). Configuration spans Okta Admin Console, Company settings → Integrations in Harriet, and (for SCIM) the Harriet app in the Okta Integration Network.

Important: SCIM provisioning does not work until the Okta integration has been created in Harriet. Complete the Harriet integration steps below and click 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 can create one from My preferences → Manage API tokens (open your name in the top-right menu, then My preferences). Users with the Manage API Keys role can also manage tokens if your org assigns that role.
• Decide your company email domain (for example acme.com). Harriet matches users to Okta by this domain.
• For SSO, 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.

Harriet’s public web origin is https://harriethq.com unless your deployment uses a custom domain. Replace it below if your IT team gave you a different base URL.

Part 1 — Create an OIDC application in Okta

1. Sign in to the Okta Admin Console.
2. Go to Applications → Applications and click Create App Integration.
3. Choose OIDC - OpenID Connect, then Web Application, and click Next.
4. Set a name (for example Harriet) and configure:
   • Sign-in redirect URIs:
     https://harriethq.com/bots/okta/callback/
   • Sign-out redirect URIs: optional for Harriet SSO.
   • Controlled access: assign the users or groups who should be able to sign in to Harriet via Okta.
5. Note the Client ID and Client secret from the app’s General tab (you will paste these into Harriet).
6. Under Sign On (or General → Grant type), ensure the app allows the Authorization Code grant type.
7. Confirm requested scopes include openid, profile, and email (Harriet uses these when exchanging the authorization code).

Keep your Okta domain handy (for example dev-12345678.okta.com or company.okta.com). You will enter it as Login Domain in Harriet.

Part 2 — Configure the Okta integration in Harriet

1. In Harriet, go to Company settings → Integrations.
2. Add or open the Okta integration.
3. Fill in the fields (labels match the integration page):
   • Domain — Your organization’s email domain (for example acme.com). Users sign in with addresses on this domain.
   • Client ID — From your Okta OIDC application.
   • Login Domain — Your Okta org domain (for example company.okta.com), used for SSO and API requests.
   • Secret key — The Okta application client secret (not your Harriet API token).
4. (Optional) Enable Disable other login methods (SSO only) if users should only sign in via Okta and not password, Slack, Google, or Microsoft buttons on the login page.
5. Click Save. This step creates the integration record Harriet needs before SCIM can work.

Part 3 — Test SSO

1. Open the Harriet login page and choose Okta (or go to the Okta sign-in flow your org uses).
2. Enter a work email on your configured domain (for example person@acme.com).
3. Complete authentication in Okta. You should return to Harriet signed in.

If you see No user found with this email, the account is not in Harriet yet—provision the user via SCIM (below) or add them manually, then try again.

Part 4 — Enable SCIM provisioning in Okta

Complete Part 2 and Save the Harriet integration before these steps.

1. Create a Harriet API token (if you have not already): My preferences → Manage API tokens. Copy the token when shown; you cannot view the full secret again later.
2. In Okta, install the Harriet app from the Okta Integration Network (Okta Marketplace).
3. Open the Harriet app in Okta. Go to Provisioning (under App integration):
   • Open Integration.
   • Enable API integration.
   • Paste your Harriet API token into API Token (not the Okta client secret).
   • Click Save.
4. Under Provisioning → To App, enable:
   • Create Users
   • Update User Attributes
   • Deactivate Users
5. Assign users or groups to the Harriet application in Okta so provisioning runs for the right population.

No additional SCIM fields are required on the Harriet integration page once the API token is saved in Okta.

Part 5 — (Optional) Map Okta groups to Harriet roles

To assign Harriet roles automatically, push groups from Okta to Harriet using these exact group names:

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 contractors)

Any other group names pushed from Okta create matching user groups in Harriet without special role assignments.

After changing group membership in Okta, use Push Now (or your org’s equivalent resync) if users or roles do not update immediately.

Troubleshooting

Symptom	What to check
SCIM never creates users	Harriet Okta integration was saved before Okta SCIM was enabled; API token in Okta is a Harriet token, not the OIDC client secret.
SSO redirect error	Sign-in redirect URI in Okta exactly matches https://<your-harriet-host>/bots/okta/callback/.
No Okta integration found for this domain	Domain in Harriet matches the email domain users type at login.
No user found with this email	User exists in Harriet with that email (SCIM or manual). Email matching is not case-sensitive.
Wrong roles after group push	Group names in Okta match the table above exactly (including spaces and capitalization).

Related articles

• Integrations overview for IT
• Permissions and groups