> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qobra.co/llms.txt
> Use this file to discover all available pages before exploring further.

# SCIM provisioning

> Create Qobra users from your identity provider and revoke their access when they leave, with SCIM 2.0.

## Introduction

SCIM (System for Cross-domain Identity Management) is an open standard that
lets your identity provider (IdP) manage the users of an application. Once
SCIM is connected, your IdP keeps Qobra up to date on its own:

* a user assigned to the Qobra app in your IdP is created in Qobra;
* a change to their name or email in your IdP is applied in Qobra;
* a user unassigned, deactivated or deleted in your IdP loses access to Qobra.

Qobra implements SCIM 2.0 ([RFC 7643](https://www.rfc-editor.org/rfc/rfc7643)
and [RFC 7644](https://www.rfc-editor.org/rfc/rfc7644)). It works with
`Okta`, `Microsoft Entra ID` and any SCIM 2.0 compliant identity provider.

SCIM manages users only. It doesn't assign user groups, plans or the org
chart: you keep managing them in Qobra.

## Before you start

* You need a Qobra role with write access to the integration settings
  (company settings).
* You need admin access to your identity provider to create an application
  and configure its provisioning.
* SCIM is configured on your live environment only: the settings are
  read-only in a sandbox.

SCIM and [SSO](https://docs.qobra.co/authentication_documentation/sso/sso_documentation.md) are
independent: you can use SCIM to manage users and SSO to sign them in, or
only one of the two.

## Step 1: Set up SCIM in Qobra

**1. Open the user provisioning settings**

In Qobra, go to **Settings > User provisioning** and click **Set up SCIM**
on the **From your identity provider** card.

**2. Choose what happens to new users**

In the **New users** step, choose how Qobra creates the users your
identity provider sends:

* **Role**: new users get the default role of your company. You can change
  it in **Settings > Roles**.
* **License**: **Assign a license** to each new user, or **Don't assign a
  license**. When no license is left, the user is created without one.
* **Send the Qobra invitation**: send the invitation email to new users,
  or not. It is only sent to users who aren't in Qobra yet.

![The New users step of the Set up SCIM provisioning dialog, with the role, the license choice and the Send the Qobra invitation switch](https://mintcdn.com/qobra/6UWPSYzbZjqMQE6G/authentication_documentation/images/scim/set-up-new-users.png?fit=max\&auto=format\&n=6UWPSYzbZjqMQE6G\&q=85\&s=d2dd376e7b59523495b18db49044f6da)

**3. Copy the base URL and the token**

Click **Next**. The **Token & ID Provider** step shows the two values your
identity provider needs:

* **SCIM base URL** (1): `https://api.qobra.co/scim/v2`
* **Token** (2): the secret your identity provider sends with every
  request.

![The Token & ID Provider step of the Set up SCIM provisioning dialog, with 1 the SCIM base URL and 2 the token, hidden here](https://mintcdn.com/qobra/6UWPSYzbZjqMQE6G/authentication_documentation/images/scim/set-up-token.png?fit=max\&auto=format\&n=6UWPSYzbZjqMQE6G\&q=85\&s=2715414f6f192513404c7013193a8cdf)

> [!WARNING]
>
> The token is only shown once. Copy it before you click **Done**. If you
> lose it, regenerate it from the SCIM card.

You can change the role, license and invitation settings at any time with
**Edit** on the SCIM card. They apply to the users created afterwards.

## Step 2: Connect your identity provider

> [tab] Okta
>
> **1. Create the Qobra application**
>
> In the Okta Admin Console, go to **Applications > Applications** and
> click **Create App Integration**. Select **SAML 2.0** (or **SWA** if you
> don't use SSO) and give the application a name, such as `Qobra`.
>
> **2. Turn on SCIM**
>
> In the **General** tab of the application, click **Edit** in
> **App Settings**, select **SCIM** as the provisioning option and save.
>
> **3. Configure the SCIM connection**
>
> In the **Provisioning** tab, open **Integration** and click **Edit**:
>
> * `SCIM connector base URL`: the SCIM base URL copied from Qobra.
> * `Unique identifier field for users`: `userName`.
> * `Supported provisioning actions`: **Push New Users** and
>   **Push Profile Updates**.
> * `Authentication Mode`: **HTTP Header**, then paste the Qobra token
>   in **Authorization**.
>
> Click **Test Connector Configuration**, then **Save**.
>
> **4. Enable the provisioning actions**
>
> In **Provisioning > To App**, click **Edit** and enable
> **Create Users**, **Update User Attributes** and **Deactivate Users**.
>
> **5. Assign users**
>
> In the **Assignments** tab, assign the people or the Okta groups who
> should have a Qobra account. Okta creates them in Qobra right away.

> [tab] Microsoft Entra ID
>
> **1. Create the Qobra application**
>
> In the Microsoft Entra admin center, go to
> **Enterprise applications > New application** and click
> **Create your own application**. Name it `Qobra` and select
> **Integrate any other application you don't find in the gallery**.
> If you already use an Enterprise application for Qobra SSO, you can
> configure provisioning on it instead.
>
> **2. Configure the SCIM connection**
>
> In the application, open **Provisioning** and set **Provisioning Mode**
> to **Automatic**. Under **Admin Credentials**:
>
> * `Tenant URL`: the SCIM base URL copied from Qobra.
> * `Secret Token`: the Qobra token.
>
> Click **Test Connection**, then **Save**.
>
> **3. Review the attribute mappings**
>
> Under **Mappings**, turn off **Provision Microsoft Entra ID Groups**:
> Qobra doesn't sync groups. Open **Provision Microsoft Entra ID Users**
> and check that the attributes listed in
> [Supported attributes](#supported-attributes) are mapped. Attributes
> Qobra doesn't support are ignored.
>
> **4. Assign users and start provisioning**
>
> In **Users and groups**, assign the people or the groups who should
> have a Qobra account. Back in **Provisioning**, set
> **Provisioning Status** to **On**.
>
> > [!NOTE]
> >
> > Microsoft Entra ID provisions users in cycles, usually every 40 minutes.
> > To provision a user right away, use **Provision on demand**.

> [tab] Other providers
>
> Any SCIM 2.0 compliant identity provider can connect to Qobra. Configure a
> custom SCIM application with:
>
> * the SCIM base URL copied from Qobra as the endpoint;
> * bearer token authentication, with the Qobra token
>   (`Authorization: Bearer <token>`);
> * `userName` as the unique identifier of users.

## How Qobra handles users

### Creation

When your identity provider creates a user, Qobra:

* uses their work email as their Qobra login email (or their primary email,
  or their `userName` if they have no email);
* names them with their given and family names, or with `name.formatted`,
  or with `displayName`;
* applies the role, license and invitation settings you chose.

If a user with the same email already exists in Qobra, Qobra doesn't create a
duplicate: it links your identity provider to that user and keeps their
history (plans, commission statements).

### Updates

Name and email changes made in your identity provider are applied in Qobra.

> [!NOTE]
>
> The email of a user who existed in Qobra before SCIM is never changed by your
> identity provider: only users created through SCIM have their email updated.

### Deactivation and deletion

When a user is deactivated, unassigned or deleted in your identity provider,
Qobra revokes their access. They can no longer sign in, but they keep their
license and commission statements until an admin archives them in Qobra.

When your identity provider reactivates or reassigns the user, Qobra restores
their access.

If your identity provider gives the `userName` of a deleted user to someone
else, Qobra creates a new user for that person instead of reusing the former
account.

## Supported attributes

| SCIM attribute | In Qobra |
| - | - |
| `userName` | Identifier of the user in your IdP |
| `emails[type eq "work"].value` | Login email |
| `name.givenName` | First name |
| `name.familyName` | Last name |
| `name.formatted` | Full name, without given or family name |
| `displayName` | Full name, without any other name |
| `externalId` | External identifier of the user in the IdP |
| `active` | Access to Qobra |

## Manage the token

Once SCIM is set up, the card in **Settings > User provisioning** is marked
**Active** and sums up your settings for new users.

![The active SCIM card of Settings > User provisioning, with 1 Deactivate SCIM, 2 Edit and 3 Regenerate the token](https://mintcdn.com/qobra/6UWPSYzbZjqMQE6G/authentication_documentation/images/scim/scim-card.png?fit=max\&auto=format\&n=6UWPSYzbZjqMQE6G\&q=85\&s=b80723a7527c3fadf234cffaa39da3b7)

* **Deactivate SCIM** (1): the token stops working right away and your
  identity provider can no longer create users or revoke their access. The
  users it created stay in Qobra.
* **Edit** (2): change the role, license and invitation settings for the users
  created afterwards.
* **Regenerate the token** (3): the current token stops working right away.
  Paste the new one in your identity provider to keep provisioning users.

The **Last request** column of the token shows when your identity provider
last called Qobra, which helps you check that provisioning is running.

## API reference

The SCIM API is available at `https://api.qobra.co/scim/v2` and authenticated
with the token as a bearer token. It supports:

| Endpoint | Methods |
| - | - |
| `/Users` | `GET`, `POST` |
| `/Users/{id}` | `GET`, `PUT`, `PATCH`, `DELETE` |
| `/ServiceProviderConfig` | `GET` |
| `/ResourceTypes` | `GET` |
| `/Schemas` | `GET` |

> [accordion] Filtering and pagination
>
> `GET /Users` supports the `userName eq "..."` filter, case insensitive, and
> pagination with `startIndex` and `count` (100 users per page at most).

> [accordion] Not supported
>
> Groups, bulk operations, sorting, ETags and password changes are not
> supported. `/ServiceProviderConfig` describes what is.

> [accordion] Errors and rate limit
>
> Errors follow the SCIM error format. A `userName` or an email already used
> by another user returns `409` with the `uniqueness` type. Requests are
> limited to 80 per second per token.

## Troubleshooting

> [accordion] The connection test fails
>
> Check that the base URL ends with `/scim/v2` and that the token was pasted
> in full. A `401` means the token is invalid, regenerated or SCIM was
> deactivated: generate a new token from the SCIM card.

> [accordion] A user is not created
>
> Check that the user is assigned to the Qobra application in your identity
> provider and has a valid email. A `409` error means the email or the
> `userName` is already used by another user.

> [accordion] A user still has access after leaving
>
> Check that deactivation is enabled in your identity provider (**Deactivate
> Users** in Okta) and, for Microsoft Entra ID, that the provisioning cycle
> has run.
