# SCIM provisioning

> Enable SCIM for your identity provider, create and rotate its tokens, and revoke them when they are no longer needed.

**SCIM provisioning** in the Workspace side rail opens `/workspace/scim`. Organization **owners** and **admins** manage it by default, and so does any custom role granted the **Manage SCIM provisioning** permission. Other members don't see the entry, and the page is not available to them.

SCIM lets your identity provider manage the people in your organization. This page sets up the connection: the switch, the base URL, the role settings and the tokens your identity provider uses.

The page has two tabs. **Provisioning** holds the status, the base URL and the tokens. **Roles** holds the role settings and the group role mapping.

## Not available on every plan

SCIM provisioning is an **Enterprise** feature: the Enterprise plan is the only one that includes it, and the Pro trial does not include it. On any other plan, selecting **SCIM provisioning** in the sidebar offers the plan change instead of opening the page. If you open the page from its address, the **Status** section explains that SCIM needs the Enterprise plan, and you cannot enable SCIM or create tokens. You can still see your settings, and you can still switch SCIM off, so a plan change never leaves you locked in. If SCIM is still on, the status reads **SCIM is on, but your plan does not include it**.

## Before you enable SCIM

SCIM needs two things from single sign-on (see the _Single sign-on_ guide):

- **A single sign-on connection** for the organization.
- **A verified domain**, so Probara knows which accounts belong to your organization.

The **Status** section lists each missing item in its own row. A missing connection or domain has a **Go to single sign-on** button. **Enable SCIM** appears only when both are in place.

## Enable SCIM

1. Open **SCIM provisioning** in the Workspace side rail.
2. On the **Provisioning** tab, select **Enable SCIM** in the **Status** section.

While SCIM is enabled, your identity provider can use a token to provision people. Enabling SCIM does not change anyone's access by itself.

## Existing members and people outside your domains

Your identity provider matches an existing member to their membership, so nobody is added twice. A person outside your verified domains receives an invitation by email, and their record is linked to their account when they accept it.

## When a person leaves

When your identity provider sets a person to inactive, Probara deactivates them. Their membership stays, with its role, project access and groups, but their access to the organization ends:

- Their seat is free for someone else, and their next request to the organization is refused.
- Their personal API tokens and their connected apps (OAuth and MCP) for the organization are revoked. Reactivating the person does not restore them, so they must create the tokens and authorize the apps again.
- Their sessions that signed in through your single sign-on connection end, and so does any break-glass access into the organization.
- The record stays on this page, inactive, so your identity provider can still find it by filter.

Probara keeps everything the person created: cases, suites, runs, results, defects, comments and reviews stay, and still name them. Nothing is reassigned, anonymized or deleted. Their open work is the one exception: their assignments on open runs are cleared, and their pending review requests on open reviews are removed. Closed runs and decided reviews keep their history.

Their global account is not touched. Their email, their password and their memberships in other organizations stay as they were. Your organization's CI tokens keep working, because they belong to the organization, not to the person.

The owner of the organization cannot be deprovisioned by SCIM. The request is refused with the detail "The organization owner can't be deprovisioned by SCIM. Transfer ownership first." Transfer ownership first, then deprovision the person.

## Reactivate a person

Set the person to active again to bring them back under the same record. A deactivated person gets their access back with the role their groups or attribute give (see [Roles](#roles)), or the default role of your organization's single sign-on policy when neither gives one (**New sign-ins join as** in the single sign-on guide). Under **Managed in Probara**, their role stays as it is. That role needs a seat, so when no seat is free the request fails with "No seat is available. Free a seat or change the plan, then retry." and nothing changes. Their groups come back. Their API tokens and connected apps do not come back, so they must create and authorize them again. If the person has no account yet, Probara creates one on a verified domain, or sends an invitation to any other address.

Deactivate the people your identity provider manages in the identity provider, not in Probara. If an admin deactivates one of them in **Members**, the next update your identity provider sends for that person as active reactivates them when a seat is free. A profile update that does not mention the active state counts as active, and Okta sends one whenever a profile changes.

## Delete a person

A `DELETE` request removes the person from the organization. Their membership ends, so their seat is free and they leave their groups, their access ends, and their open work is released. Then the record is removed. Their account and everything they created are untouched.

## Groups

When your identity provider pushes a group, Probara creates a user group marked **Managed by your identity provider**. The identity provider sets its name and members. The group grants the same access as any other group: project access, dashboards and saved queries.

- **Members.** Only people who have an account, are members of your organization and are active become members of the group. The identity provider's group still lists everyone it sent. A person who accepts a pending invitation joins the groups the identity provider gave them, and reactivating a person restores their groups.
- **Name clashes.** A group whose name matches a group someone created in Probara, ignoring case, is not taken over. The identity provider receives the error "A group with this name already exists in Probara and is not managed by your identity provider. Rename that group in Probara, or use another name." Rename the Probara group, or choose another name in the identity provider.
- **What stays editable in Probara.** The description, project access, dashboards and saved queries of a managed group. Renaming it, deleting it, or adding or removing its members, is refused with "This group is managed by your identity provider. Change its name and members there."
- **Deprovisioning.** A deactivated person keeps their group memberships in Probara. When your identity provider later sends the whole member list of the group, the people who are not active in Probara are left out, so the group drops a deactivated person until they are reactivated. Reactivation brings them back. Deleting a person removes them from their groups.
- **Plans.** When SCIM is no longer part of your plan, managed groups become ordinary groups you can edit in Probara.

## Roles

SCIM sets each person's role in your organization. Choose where the role comes from on the **Roles** tab of the SCIM page. Only people who can manage SCIM can change these settings.

- **From groups** (the default). A person takes the role of the mapped group with the lowest priority number. A person in no mapped group takes the default role.
- **From an attribute.** A person takes the role your identity provider sends in an attribute. A person without one takes the default role.
- **Managed in Probara.** SCIM sets the role when the person joins and never changes it afterwards, so you manage roles in Probara.

The default role is the one your single sign-on policy gives new sign-ins (**New sign-ins join as**, Viewer unless you changed it). Changing that policy updates the people whose role comes from the default.

### Map groups to roles

On the **Roles** tab, under **Group role mapping**, each group your identity provider manages gets a role and a priority. Set both, or choose **Not mapped** to clear both at once.

- A lower priority number wins. Priorities run from 0 to 1,000,000. When two mapped groups share the lowest number, the role that grants more permissions wins.
- **Owner** is never assigned. An identity provider can grant **Admin**. Ownership changes only through an ownership transfer.
- A change to a mapping updates the roles of the people in that group at once.

### Send the role as an attribute

With **From an attribute**, the role comes from one of two places.

- **The Probara extension.** Send the role identifier in the `role` attribute of the Probara extension schema, `urn:ietf:params:scim:schemas:extension:probara:2.0:User`:

  ```json
  {
    "schemas": [
      "urn:ietf:params:scim:schemas:core:2.0:User",
      "urn:ietf:params:scim:schemas:extension:probara:2.0:User"
    ],
    "userName": "ada@example.com",
    "urn:ietf:params:scim:schemas:extension:probara:2.0:User": {
      "role": "member"
    }
  }
  ```

- **Microsoft Entra ID app roles.** Entra sends a person's app roles in `roles`. Set each app role's value to a role identifier. When a person has several app roles, the role that grants the most permissions applies, and a tie goes to the identifier that sorts first.

The built-in identifiers are `admin`, `member` and `viewer`. A custom role's identifier is in its **Identifier** field: Probara fills it in from the name, so a role named "QA lead" becomes `qa-lead`, and you can edit it when you create the role. A value that names Owner, or a role your organization does not have, is refused and nothing changes. A person without a value takes the default role.

### Strict mode

Strict mode is on by default. While it is on, and the role source is **From groups** or **From an attribute**, admins cannot change the role of a person your identity provider manages. The members list shows the **Managed by your identity provider** chip, and the role control says why it is locked. The owner is never locked, and people your identity provider does not manage are never affected.

Turn strict mode off to let admins change those roles in Probara. A manual change stands until SCIM sets that person's role again: when a group they belong to or their attribute changes, when a mapping changes, when you change the role source or the default role, when they accept an invitation your identity provider sent, or, with the role source **From an attribute**, at the next update your identity provider sends for them.

### Default group

On the **Roles** tab, under **Default group**, choose a manual group, one you created in Probara. Managed groups cannot be chosen. A person SCIM provisions, or who accepts an invitation SCIM sent, joins that group once, to get their starting projects. If you later remove them from the group in Probara, the removal stands.

### Seats

Every role except Viewer takes a seat. When no seat is free, a change from your identity provider is refused with "No seat is available. Free a seat or change the plan, then retry." and nothing changes. A change you make in Probara to the role settings or a mapping is refused the same way.

## Copy the SCIM base URL

On the **Provisioning** tab, the page shows the **SCIM base URL**, `https://app.probara.net/scim/v2`. It is the same for every organization: the token alone tells Probara which organization a request belongs to. Give this address to your identity provider as the base URL of its SCIM connector, together with a token.

## Create a token

Each token authenticates your identity provider. Create one for each identity provider you connect.

1. In the **Tokens** section of the **Provisioning** tab, select **Create token**.
2. Enter a name that tells you which identity provider uses it, for example _Okta production_.
3. Choose how long the token lasts: **30 days**, **90 days**, **180 days** or **365 days**. The default is **365 days**.
4. Select **Create token**.

Probara shows the secret **once**. Copy it into your identity provider before you close the dialog. The page then keeps only the token's name and its last four characters, so the secret cannot be shown again. If you lose it, create a new token and revoke the old one.

Each token has an expiry, and a token cannot be extended. Create its replacement before it expires.

## Connect your identity provider

Each provider needs two values: the SCIM base URL from this page, and a token from [Create a token](#create-a-token). Turn on the provisioning features listed for your provider. The endpoints, filters, PATCH forms and error codes are in the [SCIM developer reference](https://docs.probara.net/en/developers/scim/).

### Okta

1. In Okta, create a SCIM 2.0 app integration for Probara and open its provisioning settings.
2. Set **SCIM connector base URL** to `https://app.probara.net/scim/v2`.
3. Set **Unique identifier field for users** to `userName`.
4. Set the authentication mode to **HTTP Header**, and send the token as `Authorization: Bearer <token>`.
5. Turn on **Push New Users**, **Push Profile Updates** and **Deactivate Users**. Turn on **Push Groups** to send groups.
6. Test the connector, then assign the people and groups to provision.

### Microsoft Entra ID

1. In the Microsoft Entra admin center, open the enterprise application for Probara. If you have none, create a non-gallery application. Then open its provisioning settings.
2. Set **Provisioning Mode** to **Automatic**.
3. Under admin credentials, enter `https://app.probara.net/scim/v2` as the **Tenant URL** and the token as the **Secret Token**. Select **Test Connection**.
4. Check the attribute mappings: `userName` should come from the sign-in name (`userPrincipalName` by default), and the work email from `mail`.
5. Set the scope to **Sync only assigned users and groups**, then turn provisioning on.

### Generic SCIM 2.0 client

1. Enter `https://app.probara.net/scim/v2` as the base URL. Some clients call it the tenant URL or the SCIM endpoint.
2. Enter the token as a bearer token. Some clients call this an OAuth bearer token.
3. Use `userName` as the unique identifier, and send the work email in `emails` with type `work`.
4. Turn on create, update and deactivation for people. Turn on group push if the client supports groups.
5. Leave Bulk, ETag, sort, password change, `/Me` and `/.search` off. Probara answers those with `501`.

### Client behavior to expect

- **Okta** deactivates a person with a PATCH that sets `active` to `false`. Probara ends the person's access and keeps the membership, the record and its remembered groups. Okta renames a group by sending its `id` with the new name, and Probara ignores the `id`.
- **Microsoft Entra ID** deactivates a person with a PATCH that sets `active`, sometimes as the text `"False"`. It sends a DELETE 30 days later. Probara treats the first request as a deactivation and the second as the removal of the membership and the record, and the account stays.
- **Microsoft Entra ID** sends app roles in `roles`, sometimes as JSON-encoded strings. Under **From an attribute**, Probara reads the value of each role.
- **Microsoft Entra ID** reads groups with `excludedAttributes=members`, and removes members with either the filter path or the value array. Probara supports both forms.
- **PUT** replaces the whole person. Every attribute the request leaves out is cleared, so send every attribute you manage on each PUT.
- **Groups and roles.** Under **From groups**, adding someone to a mapped group or removing them recalculates their role. Under **From an attribute** and **Managed in Probara**, a group still grants project, dashboard and saved query access, and the role comes from the attribute or from Probara.

## Rotate a token without downtime

An organization can hold **two active tokens** at once, and the **Tokens** section shows how many are active, for example **1 of 2 active**. To rotate:

1. Create a new token and copy its secret into your identity provider.
2. Confirm that your identity provider works with the new token.
3. Revoke the old token.

A token that has expired no longer counts toward the two-token limit, so you can always create a replacement once the old one has expired.

## Revoke a token

Open the actions menu of a token and choose **Revoke**, then confirm. Revocation takes effect at once: the identity provider stops working with that token immediately.

## Disable SCIM

In the **Status** section of the **Provisioning** tab, select **Disable SCIM** and confirm. Disabling revokes **every** active token at once, so your identity provider stops provisioning people. The tokens and their history stay on the page as revoked. Enabling SCIM again does not restore them; create new tokens for your identity provider.

## Expiry reminders

Before a token expires, Probara emails every owner and admin of the organization. The reminders are sent **30 days**, **7 days** and **1 day** before the expiry, once each. Each expiry is also recorded in the activity feed.

## Who can manage SCIM

Owners and admins can manage SCIM by default. Your organization can also grant the **Manage SCIM provisioning** permission to a custom role, so a role other than owner or admin can enable SCIM and manage its tokens.

If your organization requires single sign-on, the SCIM page is available only from a session that signed in through the organization's single sign-on, as with the other administration pages.