Managing users with SCIM provisioning

• Prerequisites
• Setup Instructions
• Important Notes
• Troubleshooting

Overview

SCIM (System for Cross-domain Identity Management) is a protocol for automatically provisioning and deprovisioning users in your Read AI workspace via an integration with your organization's identity provider (aka your "IdP"). This allows IT teams to centrally manage user access (for example, onboarding and offboarding users), reduce manual updates, and ensure compliance.

With SCIM provisioning, you can automate both creating new users and managing existing users:

• Creating new users: If a user does not already exist in your Read AI workspace and is assigned to the Read AI application in your IdP, SCIM will automatically create the user in Read AI, add them to the workspace, and send them a welcome/onboarding email. The user will be managed by your IdP via SCIM from that point forward.
• Updating existing users to IdP-managed: If a user already has a Read AI account, SCIM will automatically attempt to transition them to being managed by your identity provider. There are some scenarios where this may fail (see troubleshooting below), but when it succeeds, users will be automatically added to your workspace and future updates (attribute changes, deactivation, etc.) will be controlled by your IdP.

SCIM notably does not control how users sign in to Read. Many who enable SCIM provisioning will also set up SAML single sign-on through their IdP as well.

Prerequisites

• You must be a workspace admin in Read AI.
• Your workspace must be on the Enterprise+ plan.
• You must verify the domain(s) for any users you want to provision with SCIM (unless they are already in your workspace).
• You need admin access to your Microsoft Entra tenant or Okta organization.

Setup Instructions

The setup process varies slightly depending on whether you use Microsoft Entra or Okta as your IdP. For step-by-step instructions with screenshots, see:

• For Microsoft Entra: SCIM Setup with Client Credentials
• For Okta: SCIM Setup with Authorization Code

Please make sure to follow the instructions carefully, as a misconfiguration may prevent the integration from working or result in unexpected provisioning behavior.

Important Notes

• SCIM-provisioned users cannot be manually deleted or removed from the workspace; deprovisioning must be managed via your IdP.
• If auto-charge is enabled, additional licenses are purchased automatically when new users are provisioned, up to whatever maximum is configured. If disabled, provisioning will fail when there are not enough available licenses.
• Deprovisioned users are deactivated and their seat is freed automatically. Licenses won't ever be automatically removed, if you want to decrease your total licenses, you will need to do so from the manage billing page.
• Client secrets do not expire, but can be rotated from your Read AI workspace settings if needed.

Troubleshooting

• If you encounter any issues, double check that you followed the setup instructions correctly. The attribute mapping process in particular can be error-prone.
• Errors during provisioning are surfaced in your IdP, but Read AI will also notify workspace admins via email. Common errors include:
  • Insufficient licenses:
    • You have no unused licenses in your workspace, and auto-charge is either disabled, or your limit has been reached.
    • To fix, either purchase more licenses manually, enable auto-charge, or increase your auto-charge seat limit.
  • User is in another workspace:
    • The user you are trying to provision already has a Read AI account and belongs to a different workspace. Provisioning will fail until they leave the other workspace.
    • To fix, either have the user leave their other workspace, or unassign them from your application in your IdP.
  • User's email is unverified:
    • Someone has created an account with the email address of a user assigned to your IdP application, but has not verified their email address. Such users cannot be transitioned to being IdP-managed or added to your workspace, and provisoning will fail.
    • To fix, either have the user verify their email address, or unassign them from your application in your IdP.
  • User is a workspace owner or admin:
    • While provisioned users can be workspace owners or admins, you cannot deactivate an owner or admin via SCIM.
    • To fix, unassign the user from your IdP application so you can manage them manually in the Read AI workspace settings.
• Remember that you must verify domain ownership in order to provision new users or existing users outside of your workspace.