Skip to main content

SCIM provisioning

With SCIM, your identity provider (IdP) adds people to your workspace, keeps their names up to date, sets their role, and removes them when they leave. It works with Okta, Microsoft Entra ID and any other IdP that speaks SCIM 2.0. Only admins can set it up.

SCIM is included in the Scale plan. It works best with single sign-on: set SSO up first and verify your email domains.

What happens to people​

In your IdPIn User Evaluation
Assign someone to the appOn a verified domain: they're added to the workspace at once with the SSO default role, and sign in with SSO. Any other address: they get the usual email invite and join when they accept it.
Change their nameTheir name changes here too (verified domains only).
Add them to a role groupTheir role changes (see Groups and roles).
Deactivate or unassign themThey lose access to the workspace and are signed out. Their API keys and MCP connections for the workspace stop working, and a pending invite is cancelled.
Reactivate themThey're added back (or invited again) with the role they had when they were deactivated. If we don't know it, for example they had no role then, they get the SSO default role.

Removing someone never deletes their work. Their studies, reports, clips and comments stay in the workspace, and their account stays (they may belong to other workspaces). People already in the workspace show up in your IdP's user search, so it can match them instead of creating them twice.

The last admin of a workspace can't be removed or demoted through SCIM. Make someone else an admin first.

SCIM respects your seats. Adding an Admin or Member, or moving an Observer into the Admins or Members group, needs a free paid seat (a pending invite holds one). When the workspace is full, your IdP gets a 403 error for that person that says the seats are taken, and nothing changes here. People with the Observer role are always added.

Get your SCIM details​

  1. Go to Settings → Security.
  2. Turn on SCIM provisioning and click Create token.
  3. Copy the base URL and the token. The token is shown once. Store it in your IdP straight away.

The base URL is https://app.userevaluation.com/api/scim/v2. (https://api.userevaluation.com/scim/v2 works too.)

To replace the token, click Regenerate. The old token stops working at once, so paste the new one into your IdP. Turning SCIM off also stops the token.

Okta​

These steps add provisioning to the app you made for SSO. If you haven't made one yet, follow Single sign-on first.

  1. In the Okta Admin Console, open Applications → Applications and select your User Evaluation app.
  2. On the General tab, click Edit in App Settings, set Provisioning to SCIM, and save.
  3. Open the new Provisioning tab, then Integration → Edit:
    • SCIM connector base URL: the base URL from Settings.
    • Unique identifier field for users: userName.
    • Supported provisioning actions: Push New Users, Push Profile Updates and Push Groups.
    • Authentication Mode: HTTP Header, and paste the token as the Bearer token.
  4. Click Test Connector Configuration, then Save.
  5. Under Provisioning → To App, click Edit and turn on Create Users, Update User Attributes and Deactivate Users. Save.
  6. On the Assignments tab, assign the people or groups who should have access.

To set roles from Okta, open Push Groups, push a group named for the role (for example User Evaluation Admins), and pick Create Group or link it to the existing group. See Groups and roles.

Make sure each user's Okta username, or primary email, is their work email address.

Microsoft Entra ID​

  1. In the Microsoft Entra admin center, open Enterprise applications and select your User Evaluation app (or create a non-gallery app).
  2. Open Provisioning and choose New configuration (or Get started), with Provisioning Mode set to Automatic.
  3. Under Admin Credentials:
    • Tenant URL: the base URL from Settings.
    • Secret Token: the token.
  4. Click Test Connection, then save.
  5. Under Mappings → Provision Microsoft Entra ID Users, check that:
    • userPrincipalName maps to userName, as the matching attribute.
    • mail maps to emails[type eq "work"].value. We send access to this address, so make sure it's the person's work email. If it's empty, we use the userName.
    • Switch([IsSoftDeleted], , "False", "True", "True", "False") maps to active. This is the default mapping.
  6. Under Settings → Scope, choose Sync only assigned users and groups, then assign people or groups to the app under Users and groups.
  7. Set Provisioning Status to On and save.

Entra syncs about every 40 minutes. To try one person straight away, use Provision on demand.

To set roles from Entra, keep Provision Microsoft Entra ID Groups turned on and assign groups whose names end in Admins, Members or Observers. See Groups and roles.

Groups and roles​

User Evaluation has three groups, one for each role: Admins, Members and Observers. You can't create other groups.

  • Your IdP finds the group by name. Any name that ends in the role works, for example User Evaluation Admins, UE Members or Research Observers. Administrators, Users, Researchers, Viewers and Read-only work too.
  • A group with any other name (for example Engineering) is rejected, so pushing it fails in your IdP.
  • Adding someone to a group gives them that role. They must already be assigned to the app.
  • Removing someone from a group sets them back to the SSO default role. If the default is the group's own role, they keep it, except admins, who become Members.
  • Taking someone out of every group doesn't remove them from the workspace. To remove someone, deactivate or unassign them.
  • Deleting or renaming a pushed group in your IdP changes nobody's role.

Good to know​

  • People's email addresses. SCIM never changes the email address of someone's User Evaluation account. If the address in your IdP changes, the new address is used if they ever need inviting again.
  • Domains. Only addresses on your verified domains are added straight away. That stops anyone from using SCIM to add people outside your company without their say-so.
  • Audit log. Every SCIM change appears in Settings → Security → Audit log, by "your IdP (SCIM)".
  • Plan changes. If the workspace leaves the Scale plan, SCIM requests are refused until it's back on Scale. Nobody loses access.

For developers​

The API follows SCIM 2.0 (RFC 7643 and RFC 7644).

  • Auth: Authorization: Bearer <token> on every request. Wrong, regenerated or turned-off tokens get 401; workspaces not on Scale get 403.
  • Endpoints: /ServiceProviderConfig, /ResourceTypes and /Schemas (no token needed), /Users (GET, POST, PUT, PATCH, DELETE) and /Groups (GET, POST, PUT, PATCH, DELETE).
  • Filters: eq comparisons joined with and. Users: userName, externalId, emails.value, id, displayName, active. Groups: displayName, id, members[value eq "…"].
  • Paging: startIndex (from 1) and count (up to 200).
  • PATCH: add, replace and remove, with or without a path, including Okta's {"op":"replace","value":{"active":false}} and Entra's {"op":"Replace","path":"active","value":"False"}.
  • Not supported: bulk operations, sorting, ETags, changing passwords. Attributes we don't keep (phone numbers, titles, the enterprise extension) are accepted and ignored.
curl https://app.userevaluation.com/api/scim/v2/Users?filter=userName%20eq%20%22ada%40example.com%22 \
  -H "Authorization: Bearer $SCIM_TOKEN"