Skip to main content

Okta Setup Guide

  • Updated

This guide connects your Okta tenant to Wisq using SCIM (System for Cross-domain Identity Management). Once it is set up, Wisq automatically creates, updates, and deactivates user accounts based on how they are assigned in Okta. Questions at any point? Contact your Wisq Agent Strategist.

What you'll need

  • Admin access to your Okta tenant.

Wisq will send you the following via Proton Mail:

  • SCIM connector base URL
  • Client ID
  • Client Secret
  • SCIM Username
  • SCIM Password
  • Access token endpoint URI
  • Authorization endpoint URI

Setup

1. Enable SCIM provisioning in Okta

  1. Log into your Okta Admin Console.
  2. Go to Applications → Applications and open your Wisq application.
  3. On the General tab, find the Provisioning section and click Edit.
  4. Select SCIM as the provisioning method, then click Save.

2. Configure the SCIM connection

  1. Go to Provisioning → Integration and click Edit in the SCIM Connection section.
  2. Enter the SCIM connector base URL Wisq provided.
  3. Set Authentication Mode to OAuth 2.
  4. Set the Unique identifier field for users to userName.
  5. Check Push New Users and Push Profile Updates, then click Save.

3. Configure OAuth 2 authentication

  1. Enter the Access token endpoint URI and Authorization endpoint URI Wisq provided.
  2. Enter the Client ID and Client Secret.
  3. Click Save.

4. Authenticate the SCIM connection

  1. Click Authenticate with Wisq. In the pop-up, enter the SCIM Username and SCIM Password from Proton Mail and click Sign in.
  2. If prompted, click Allow or Authorize. You should see a success message confirming the connection.

5. Enable provisioning actions

  1. On the Provisioning tab, click To App in the left sidebar, then Edit.
  2. Enable Create Users, Update User Attributes, and Deactivate Users, then click Save.

Wisq provisions users, not groups. Assigning the Wisq app to an Okta group is fine — Okta pushes the group's members as users. You do not need Okta's Push Groups feature: Wisq's SCIM endpoint is users-only, so pushing group objects has nothing to write to and will report errors.

6. Define mappings

Okta auto-maps common fields (userName, givenName, familyName, email, and so on). The more you send via SCIM, the better Harper can answer user questions — we recommend sharing these standard attributes:

  • First name (Given Name)
  • Last name (Family Name)
  • Email (Primary Email)
  • Job title (Title)
  • Street Address (addresses.streetAddress)
  • City (addresses.locality)
  • State (addresses.region)
  • Country Code (addresses.country)
  • Cost Center (user.costCenter)
  • Full Time / Part Time (user.userType)

In Provisioning → To App you'll see Attribute Mappings. Verify the attributes above are present, and add any that are missing.

7. (Optional) Custom attributes

To send additional user attributes to Wisq, add custom attributes to the Wisq app profile in Okta and map them using the Wisq SCIM extension format:

urn:ietf:params:scim:schemas:extension:wisq:1.0:User:$CustomAttribute

Replace $CustomAttribute with your attribute name — for example employeeId, departmentCode, or managerEmail.

7a. Add the custom attribute(s) to the Wisq app user profile

  1. Go to Directory → Profile Editor and select your Wisq application.
  2. Click Profile, then Add Attribute.
  3. Create the attribute:
    • Display name: a human-friendly label (e.g. "Employee ID").
    • Variable name: the Okta internal name (e.g. employeeId).
    • Type: string (or the appropriate type).
    • External name: e.g. urn:ietf:params:scim:schemas:extension:wisq:1.0:User:employeeId.
  4. Click Save, and repeat for each custom attribute.

7b. Map Okta user attributes to the Wisq app attributes

  1. Open the Mappings for the Wisq app and select the direction Okta User → Wisq.
  2. For each custom attribute, map it from the appropriate Okta user field (or use an Okta expression to transform a value).
  3. Click Save Mappings.

7c. Verify SCIM is updating profiles

  1. Go to Applications → Applications → Wisq → Provisioning → To App.
  2. Confirm Push Profile Updates / Update User Attributes is enabled.
  3. Assign (or re-assign) a test user and confirm the custom attributes appear in Wisq.

Custom attributes are only sent if they are added to the Wisq app profile and mapped — adding them without mapping won't send them. When you update a mapping, make sure profile updates are enabled so Okta pushes the change to Wisq.

8. Test offboarding

Before rolling out widely, test deactivation as well as creation. A deprovisioning problem is silent — new users and profile updates keep syncing normally, so the only symptom is that departed employees keep their Wisq access. Far better to catch it now than after go-live.

  1. Confirm Deactivate is still on. Provisioning → To App → Deactivate Users should be Enabled (step 5).
  2. Deactivate a test user the way you will day to day — one of:
    • Deactivate the user in Okta — Directory → People → select the user → Deactivate; or
    • Unassign the user from the Wisq app — Applications → Wisq → Assignments → remove the user; or
    • Remove the user from the assigned group, if you assign access by group.
  3. Let us know once you've done this and we'll confirm Wisq received the deactivation. Then reactivate or re-assign the test user to restore their access.

These three methods are separate paths in Okta, so test whichever one your offboarding process actually uses — testing a different one can pass while the path you rely on is still misconfigured. If you assign access by group, group removal is the path to test.

Troubleshooting

The three issues we see most often, and how to resolve them. If none of these match, send us the error text and a screenshot and we'll investigate from our side.

Users fail to provision, with an error icon next to their name

Usually the user's Okta profile hasn't had the Wisq attribute mappings applied yet, so a required attribute (commonly addressType) is still empty. Mappings are not applied retroactively — a user assigned before the mapping existed keeps the old profile until it is re-applied.

  1. Go to Applications → Applications → Wisq → Assignments → People. Users with a problem show an error icon.
  2. Click the edit icon on one of them — this shows that user's attributes before mapping, where addressType will be empty (the cause).
  3. Click Reapply Mappings. addressType should change from empty to work.
  4. Re-provision the user to re-sync them to Wisq. Re-opening the edit view should now show the attribute populated and the error gone.

Provisioning fails with "Error authenticating: Method Not Allowed"

This one is on our side, not yours — it means SCIM hasn't been fully enabled for your Wisq space yet. Contact your Wisq Agent Strategist and we'll enable it; no change is needed in Okta.

User data has stopped syncing to Wisq

Most often the SCIM connection has lost its authorization — for example an expired token — which stops updates silently while the configuration still looks correct.

  1. Go to Applications → Applications → Wisq → Provisioning → Integration and scroll to the bottom. Look for any alert about API credentials, token expiration, or connectivity.
  2. If you see Authenticate or Re-Authenticate, click it. You should get a success message confirming the connection.
  3. Then under Provisioning → To App, click Force Sync to re-sync all users. This starts a task and can take a while.
  4. Check the result under Dashboard → Dashboard → Tasks and open the task you just ran — any failures are listed there. If the errors look like they're on Wisq's end, send them to us in as much detail as you can and we'll investigate.