Okta & SCIM

Set up Okta for single sign-on (OIDC) and optional SCIM provisioning from the Harriet app in the Okta Integration Network, so people are created, updated, and deactivated automatically, and Okta can assign Harriet roles.

⚠️

SCIM provisioning does not work until the Okta integration has been created in Harriet. Add Harriet from the catalog, complete the OIDC setup below, and select Save first. Then configure SCIM on the same Okta app.

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.
Use the Harriet app from the Okta Integration Network for both OIDC and SCIM. Do not create a custom Okta app.

Add Harriet from the Okta Integration Network

One catalog app covers sign-on and provisioning. Add it once, then configure OIDC and SCIM in the sections below.

Open the catalog. In the Okta Admin Console, go to Applications → Applications and select Browse App Catalog.
Find Harriet. Search for Harriet, open the listing, and select Add Integration.
Select features. If Okta asks which capabilities to enable, select OpenID Connect for single sign-on and SCIM 2.0 for provisioning. You can enable both on this one app.
Finish the add flow and assign the people or groups who should use Harriet.

Supported features

OIDC

SP-initiated SSO from the Harriet login page
IdP-initiated SSO from the Okta dashboard
Single Logout (optional)
Authorization Code grant, with scopes openid, profile, and email

SCIM

Create Users, Update User Attributes, and Deactivate Users
Import users and import groups
Group push (including magic role groups)
Schema discovery, so Okta can import Harriet role attributes

Leave Sync Password off. Harriet does not use Okta passwords.

OIDC (single sign-on)

Copy credentials from the Harriet app you just added, then paste them into Harriet.

Open the Harriet app in Okta and go to the Sign On or General tab. Confirm the sign-on method is OpenID Connect.
Copy the credentials Okta issued for this catalog app: Client ID, Client secret, and your Okta org domain (for example company.okta.com).
Confirm the sign-in redirect URI is https://harriethq.com/bots/okta/callback/. If people also start sign-in on hrharriet.com, add https://hrharriet.com/bots/okta/callback/ as well.
(Optional) Enable IdP-initiated login so people can open Harriet from the Okta dashboard. Set Login initiated by to Either Okta or App, and set Initiate Login URI to https://harriethq.com/bots/okta/login/ or https://harriethq.com/bots/okta/idp/ (or the same path on your custom Harriet domain). Okta appends ?iss= your org URL; Harriet starts SSO from that issuer.
(Optional) Enable Single Logout. Add https://harriethq.com/accounts/login/ (or your custom Harriet domain) to Sign-out redirect URIs. When someone who signed in via Okta logs out of Harriet, Harriet ends their Okta session and returns them to the login page.
Open Company settings → Integrations in Harriet and add or open the Okta integration.
Fill in the fields from the OIN app. Domain: your email domain (for example acme.com). Client ID: from the Harriet app in Okta. Login Domain: your Okta org domain. Secret key: the OIN app 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.
(Optional) Enable Complete sign-in on the starting domain if you registered both harriethq.com and hrharriet.com redirect URIs. Untick Single Logout on this form if Harriet logout should stay local.
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 Create account for workspace users is enabled in company settings (the default), Harriet can create the person after a successful Okta login. Turn that off to require SCIM or invites only. If you see No user found with this email, the account is not in Harriet yet: provision it via SCIM, invite them, or turn that setting on.

SCIM (provisioning)

Configure provisioning on the same Harriet catalog app. No extra SCIM fields are required on the Harriet Okta integration page.

Create a Harriet API token from My preferences → Manage API tokens. Copy it when shown; the full secret is not visible again later.
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. Use Test API Credentials if Okta offers it.
Select To App features. Under Provisioning → To App, enable Create Users, Update User Attributes, and Deactivate Users.
Assign people (if you have not already) so provisioning runs for the right population.

Import role attributes from the SCIM schema

After the API connection is saved, Okta can import Harriet's SCIM schema and show boolean role attributes on the Harriet app profile. This is the preferred way to assign Harriet roles from Okta.

Open Profile Editor for the Harriet app (from Directory → Profile Editor, or from Provisioning → To App mappings).
Refresh or import attributes from the connected application so the Harriet role fields appear. If they are missing, confirm the API token is a Harriet API token and try the refresh again.
Map or set the boolean attributes on people or group assignments so provisioning writes them to Harriet.

SCIM attribute	Harriet role
`role_owner`	Account owner
`role_super_admin`	Permissions administrator
`role_hr`	Admin (legacy)
`role_support`	Support operator
`role_access_personal_data`	Access personal data
`role_access_pay_data`	Access pay data
`role_manage_users`	Manage users
`role_manage_knowledge`	Manage knowledge base
`role_manage_workflows`	Manage workflows
`role_manage_embeds`	Manage embeds
`role_access_billing`	Access billing
`role_manage_integrations`	Manage integrations
`role_export_data`	Export data
`role_view_analytics`	View analytics
`role_manage_api_keys`	Manage API keys
`role_manage_skills`	Manage skill group access
`role_review_skills`	Review shared skills and MCPs
`role_finance`	Manage finance
`role_provisioner_view`	View Harriet Endpoint AI
`role_provisioner_assign`	Manage Harriet Endpoint AI
`role_provisioner_view_audit`	View Endpoint AI audit and usage
`role_provisioner_debug_tool_usage`	View Endpoint AI tool debug data
`role_provisioner_manage_budgets`	Manage LLM budgets
`disallow_personal_data_access`	Disallow personal data access

See Roles & permissions for what each role grants.

Magic groups

You can also push Okta groups with these exact names (spaces and capitalization matter). Any other group name creates a matching team in Harriet without a special role, which is useful for profiles. After membership changes, use Push Now if people or roles do not update immediately.

If you use attributes and magic groups together, Harriet treats each role as OR: removing a group does not clear the role while the matching attribute is still true, and unsetting an attribute does not clear the role while the person is still in the magic group.

Okta group name	Harriet role
Harriet Owner Group	Account owner
Harriet Super Admin Group	Permissions administrator
Harriet Admin Group	Admin (legacy)
Harriet Support Group	Support operator
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 base
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 View Analytics Group	View analytics
Harriet Manage API Keys Group	Manage API keys
Harriet Manage Skill Group Access Group	Manage skill group access
Harriet Review Shared Skills and MCPs Group	Review shared skills and MCPs
Harriet Finance Group	Manage finance
Harriet Provisioner View Group	View Harriet Endpoint AI
Harriet Provisioner Assign Group	Manage Harriet Endpoint AI
Harriet Provisioner View Audit Group	View Endpoint AI audit and usage
Harriet Provisioner Debug Tool Usage Group	View Endpoint AI tool debug data
Harriet Provisioner Manage Budgets Group	Manage LLM budgets
Harriet Restricted Access Group	Disallow personal data access

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 on the Harriet catalog app matches `https://harriethq.com/bots/okta/callback/` (and the hrharriet.com URI if you use that hostname).
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, invite, or Create account for workspace users). Email matching is not case-sensitive.
Role attributes missing in Profile Editor	API integration is saved; the token is a Harriet API token; refresh or import the Harriet app profile from SCIM.
Wrong roles after group push	Okta group names match the magic group table exactly.
Role still present after removing a group	The matching SCIM attribute is still true, or the person is still in the magic group. Harriet treats attribute and group as OR.

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