User provisioning (SCIM)

Let your identity provider create, update and deactivate Cobrowse account members automatically using SCIM.

Overview

Cobrowse supports user provisioning via SCIM 2.0 (System for Cross-domain Identity Management). Point your identity provider at Cobrowse and it will create account members as people join your team, keep their details up to date and remove access when they leave.

SCIM manages who has an account. SAML SSO manages how they log in. They are designed to be used together but each can be configured on its own.

Requirements

You will need:

• an identity provider that supports SCIM 2.0 outbound provisioning

• your Cobrowse license key

• a public key configured in your Cobrowse account and the private key to generate the authorization token

1. Create a Cobrowse JWT

SCIM uses a signed Cobrowse JWT bearer token. Your identity provider sends the same JWT with every request so it needs permission to create, read, update and delete account members.

A complete set of claims looks like this:

{
  "sub": "<member>",
  "iss": "<license key>",
  "aud": "https://cobrowse.io",
  "iat": <now>,
  "exp": <expiry>,
  "role": null,
  "policy": {
    "version": 3,
    "members": {
      "permissions": ["create", "read", "update", "delete"]
    }
  }
}

The policy claim gives full access to the members resource. Set role to null as provisioning takes its permissions from the policy rather than from a user role.

The claims are signed using RS256 with a private key that you should keep safe. Save the public key in your Cobrowse account so Cobrowse can verify the token is authentic.

You can use https://jwt.io/ to sign these claims with your private key to create a JWT.

Provisioning stops when the JWT expires and your identity provider will report this as a loss of permission rather than an expired token. We recommend choosing an exp that matches how often you are able to rotate the token.

2. Point your provider at the SCIM endpoint

Cobrowse exposes a single SCIM base URL which most providers refer to as the Tenant URL or Base URL:

https://cobrowse.io/api/1/scim

If you use a dedicated or self-hosted instance, then replace cobrowse.io with <your instance domain>.

Some providers ask for more detail than a single base URL. Where they do, use these values:

Setting	Value
SCIM version	2.0
Users resource	/Users
Groups resource	Leave empty. We do not support Groups.

Enter the JWT from step 1 as the bearer token alongside these settings.

3. Choose the provisioning actions

Most providers ask which actions your SCIM service supports. Cobrowse supports creating, updating and deactivating users, so enable those and leave anything else disabled.

Where your provider offers a choice, the following also apply:

• Updates. We accept both PATCH and PUT style updates, so either setting will work.

• Deprovisioning. Choose to disable users rather than delete them. Both revoke access immediately but deleting also removes the SCIM resource so your identity provider has to create them again rather than reactivate them.

• Groups. Leave group provisioning off. See users, not groups below.

4. Map the supported attributes

Cobrowse supports the following user attributes:

Attribute	Description
userName	The username used to log in to Cobrowse. This is usually an email address.
displayName	The name of the user shown in the Cobrowse dashboard.
active	Whether the user can access Cobrowse.
externalId	A unique ID your identity provider uses for reconciliation if provisioning state becomes out of sync.

Only userName is required to create a user. Any attributes outside of this list are ignored and can be safely removed.

Matching on userName

Use userName as the matching attribute and where your provider asks for a matching precedence, set it to 1. This is the unique key we join on, so your identity provider will adopt existing account members by username instead of creating duplicates.

If your provider lets you write the lookup filter yourself, it must be a single equality term, for example:

userName eq "[e-mail]"

We match on userName or externalId. Attribute names, the eq operator, and the username itself are all treated case insensitively. Filters combining several terms with and or or are not supported.

userName is immutable. Changing the user's username in your identity provider will provision a new account member in Cobrowse.

Users, not groups

We support the SCIM Users resource. We do not support Groups so turn off group provisioning in your attribute mappings otherwise you will see provisioning errors.

How Cobrowse handles provisioned users

Roles

Newly provisioned users are assigned the agent role. Roles cannot be managed through SCIM. Roles are assigned through SAML or an administrator can change a user's role in the Cobrowse dashboard.

Deactivation

Setting active to false removes access immediately with no grace period and no lingering session.

Usernames must match your SSO identity

If your users log in through SAML, the SAML attribute Cobrowse uses as the username is nameID. The value mapped to nameID in the SAML assertion must match the value mapped to userName in your provisioning configuration.

If these values do not match, provisioning and login will both appear to work but will create two separate account members for the same user. Please check them against each other before enabling provisioning.

Checking what we support

Our SCIM service describes its own capabilities and some providers read this automatically during setup. You can also request it yourself using the same bearer token as the rest of your configuration:

Endpoint	What it returns
/ServiceProviderConfig	The features we support, such as filtering and the maximum number of results per page.
/ResourceTypes	The resources we expose.
/Schemas	The attributes available on each resource.

curl https://cobrowse.io/api/1/scim/ServiceProviderConfig \
  -H "Authorization: Bearer <your JWT>"

Step-by-step guidance

The steps above apply to any SCIM 2.0 provider. For a walkthrough using a specific provider, see:

Microsoft EntraOkta