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 uses this domain to start Okta SSO when the person is not already in Harriet.
• If Create account for workspace users is on in company settings, Harriet can create the account on first successful Okta login (see JIT below). Turn that setting off and use SCIM if you want provisioning only from Okta.
• If the person already has a Harriet account, Harriet uses that account’s company Okta integration even when their email is not on the mapped domain (for example a contractor address).

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.

Supported features

OIDC (SSO)

• SP-initiated SSO — Users start sign-in from the Harriet login page (choose Okta), then authenticate with Okta.
• IdP-initiated SSO — Users can start from Okta (Okta Dashboard / app tile) via Third-party Initiated Login. Harriet accepts iss on https://harriethq.com/bots/okta/login/ (the Okta Integration Network initiate URI) and on https://harriethq.com/bots/okta/idp/. Either URL starts Okta SSO immediately — users should not be asked for their email.
• Just-In-Time (JIT) provisioning — When Create account for workspace users is enabled, Harriet can create the account after a successful Okta login. From the Okta dashboard, that includes emails Okta asserts for your org (including contractor addresses). From the Harriet Okta form, Harriet only starts SSO for unknown addresses on your mapped company domain (not consumer domains such as Gmail). Honor your domain allowlist if you have one. Turn the setting off to require SCIM or manual invites.
• Single Logout (SLO) — When a user who signed in via Okta logs out of Harriet, Harriet also ends their Okta session (SP-initiated single logout) and returns them to the Harriet login page. Requires the Harriet login page to be registered as a Sign-out redirect URI on your Okta app (see Part 1). You can turn this off with the Single Logout toggle on the Harriet Okta integration page; logout then only ends the Harriet session.

For glossary definitions, see the Okta Glossary.

SCIM (lifecycle management)

• Create users — Okta can create users in Harriet.
• Update user attributes — Okta can update user profile fields in Harriet (including Harriet role attributes discovered from the SCIM schema).
• Deactivate users — Okta can deactivate users in Harriet when they are unassigned or deactivated in Okta.
• Import users — Okta can read/import existing Harriet users over SCIM.
• Import groups — Okta can read/import existing Harriet groups over SCIM.
• Group push — Okta can push groups to Harriet (magic role group names assign Harriet roles; other group names become matching user groups).

Not supported for SCIM:

• Sync password — Harriet does not accept password sync from Okta.
• Profile sourcing — Harriet is not a profile source for Okta Universal Directory.

For glossary definitions, see the Okta Glossary.

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: add both —
     https://harriethq.com/bots/okta/callback/
https://hrharriet.com/bots/okta/callback/
     With Complete sign-in on the starting domain enabled (the default for new Harriet Okta integrations), sign-in finishes on whichever domain the user started from, so register both.
   • Sign-out redirect URIs:
     https://harriethq.com/accounts/login/ (needed for Single Logout; Okta returns users here after Harriet signs them out).
   • 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). Used to start SSO for addresses on this domain when the person is not already in Harriet. Existing Harriet users are sent to their company’s Okta even if their email uses a different 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. (Optional) Complete sign-in on the starting domain — on by default for newly created integrations: Okta sign-in finishes on whichever Harriet domain the user started from (harriethq.com or hrharriet.com), which requires both sign-in redirect URIs from Part 1 on your Okta app. Integrations created before this setting existed have it off and always complete sign-in on hrharriet.com; enable it once both redirect URIs are registered.
6. (Optional) Single Logout (end Okta session on Harriet logout) is on by default: logging out of Harriet also signs the user out of Okta and returns them to the Harriet login page. Untick it if logout should only end the Harriet session.
7. 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 — Assign Harriet roles from Okta

You can grant Harriet roles from Okta in two ways:

1. Preferred: Map Harriet role attributes on the Okta app user profile. Okta discovers these as selectable attributes from Harriet’s SCIM schema.
2. Fallback: Push Okta groups that use Harriet’s exact magic group names (table below).

If you use both attributes and magic groups for the same role, Harriet treats them as OR: the role stays on while either the attribute is true or the user is in the matching magic group. Removing someone from a magic group does not clear the role if the attribute is still set (and clearing the attribute does not remove the role if they remain in the magic group).

Preferred — Role attributes (how they appear in Okta)

Harriet advertises each role as a boolean SCIM attribute on the user schema. After SCIM is connected (Part 4), Okta can import those attributes into the Harriet app profile so they show up as fields you can map or set on assignments.

1. Complete Part 4 so the Harriet app’s API integration is saved and Update User Attributes is enabled.
2. In Okta, open the Harriet app.
3. Open the app’s Profile Editor (or Provisioning → To App attribute mappings—wording varies by Okta Admin Console version).
4. Refresh or import attributes from the connected SCIM schema if you do not yet see Harriet role fields (for example role_owner, role_support). Okta pulls them from Harriet; you do not type the list by hand.
5. Map or set the boolean attributes on user or group assignments so provisioning writes them to Harriet when users are created or updated.

No extra toggle is required on the Harriet Okta integration page. Discovery happens through SCIM once provisioning is connected.

SCIM attribute (appears in Okta)	Harriet role
role_owner	Account owner
role_super_admin	Permissions administrator
role_hr	Admin
role_support	Support (ticketing)
role_access_personal_data	Access personal data
role_access_pay_data	Access pay data
role_manage_users	Manage users
role_manage_knowledge	Manage knowledge
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/expenses
role_provisioner_view	Provisioner: view
role_provisioner_assign	Provisioner: assign
role_provisioner_view_audit	Provisioner: view audit
role_provisioner_debug_tool_usage	Provisioner: debug tool usage
role_provisioner_manage_budgets	Provisioner: manage budgets
disallow_personal_data_access	Restricted access (limits personal data and other sensitive features—for example contractors)

Fallback — Magic group names

If you prefer group push instead of (or in addition to) attributes, push groups from Okta using these exact names:

Okta group name	Harriet role
Harriet Owner Group	Account owner
Harriet Super Admin Group	Permissions administrator
Harriet Admin Group	Admin
Harriet Support Group	Support (ticketing)
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 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/expenses
Harriet Provisioner View Group	Provisioner: view
Harriet Provisioner Assign Group	Provisioner: assign
Harriet Provisioner View Audit Group	Provisioner: view audit
Harriet Provisioner Debug Tool Usage Group	Provisioner: debug tool usage
Harriet Provisioner Manage Budgets Group	Provisioner: manage budgets
Harriet Restricted Access Group	Restricted access

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 URIs in Okta include https://harriethq.com/bots/okta/callback/ and https://hrharriet.com/bots/okta/callback/ (with Complete sign-in on the starting domain enabled, Harriet uses the domain the user started sign-in from; otherwise always hrharriet.com).
No Okta integration found for this domain	Domain in Harriet matches the email domain, or the person already exists in a Harriet company that has Okta configured.
No user found with this email	User exists in Harriet, or JIT is allowed (self-onboard on, and for the Harriet login form the email is on your mapped company domain). Email matching is not case-sensitive.
Role attributes missing in Okta Profile Editor	SCIM API integration is connected; refresh/import the Harriet app profile from SCIM; API token is a valid Harriet token.
Wrong roles after group push	Group names in Okta match the magic-name table exactly (including spaces and capitalization).
Role not removed after unassigning a group or clearing an attribute	Attribute and magic group are OR’d—clear the attribute and remove the magic group membership.

Related articles

• Integrations overview for IT
• Permissions and groups