Configure the SCIM 2.0 API

qTest Manager supports the System for Cross-domain Identity Management (SCIM 2.0) protocol. This means you can provision users from an external identity provider (IdP), such as Microsoft Entra ID or Okta.

The SCIM 2.0 API supports the following operations:

Create users, deactivate and reactivate users, and read or list users.
Read and list groups, and add or remove group members.
Run several operations in one call.
Expose SCIM discovery documents so IdPs can auto-configure.

This topic explains how to prepare qTest Manager and connect your IdP. For endpoint-level reference and interactive examples, use the SCIM 2.0 API documentation in Download qTest Resources .

Before you start

Before you configure SCIM, you must have a qTest account that is a member of the Administrators user group.

For OnPremises installations, an administrator must also enable the SCIM feature flag.

Enabling SSO disables LDAP in qTest Manager. If you're migrating from LDAP, export users before you switch authentication systems. See Licenses and Users for guidance.

Enable SCIM in qTest OnPremises

To turn on SCIM, you need to add and enable the SCIM feature flag. Check out the dropdowns below for more information.

Enable SCIM in Windows

To turn on the SCIM feature flag in Windows, follow these steps:

Stop the qTest Manager instance with the following command: systemctl stop qtest
Open the qTest Manager app manifest and add the following variable to the extraEnv section:
Copy

name: scim.enabled
```
name: scim.enabled
value: "true"
```
Save your changes to the app manifest.
Start your qTest Manager instance with the following command: systemctl start qtest

Enable SCIM in Linux

These commands use the default installation path, /opt/qtestctl. If you installed qTest in a different location, use that path instead.

To turn on the SCIM feature flag in Linux, follow these steps:

Go to your qtestctl directory and stop the qTest Manager instance:
Copy
```
cd /opt/qtestctl
./qtestctl stop
```
Open the qTest Manager app manifest and add the following variable to the extraEnv section:
Copy
```
name: scim.enabled
value: "true"
```
Save your changes to the app manifest.
Go back to your qtestctl directory and start qTest Manager:
Copy
```
cd /opt/qtestctl
./qtestctl start
```

Connect your identity provider

You'll need to set up some items in qTest Manager as well as your SCIM 2.0 identity provider to establish a connection.

You can set up an IdP of your choice. qTest has been tested with Microsoft Entra ID.

Set up qTest Manager

Before you can configure the IdP, you must set up qTest Manager:

Single Sign-On (SSO) Integration on your tenant for the IdP you want to use. SSO must be active before SCIM can create users.
Create the user groups you want the IdP to manage. Group names in your IdP must match the Group Name in qTest Manager.

After initial setup, you can still create groups in qTest Manager that aren't mapped in the IdP. SCIM ignores those groups unless you configure your IdP to manage them.
Get the API bearer token associated with the admin account you're using.
Confirm that SCIM is on. Send an authenticated GET request to the SCIM discovery endpoint. You do not need a request body:
Copy
Verify SCIM is enabled
```
GET https://<your-qtest-host>/scim/v2/ServiceProviderConfig
Authorization: Bearer <token>
```
A successful response means the flag is on. A 404 Not Found response means the flag is still off, or the service has not restarted with the new values.

Configure SCIM in your IdP

In your IdP, create or enable a SCIM connector for qTest Manager. Your IdP may read the ServiceProviderConfig discovery endpoint to detect supported SCIM features automatically.

Here's the information you'll need to provide for your IdP:

Setting	Value
SCIM base URL	https://<your-qtest-host>/scim/v2
Authentication	OAuth Bearer Token (Authorization: Bearer <token>)
userName	This is the unique identifier you use to create a user. You can also filter users by this value. This is usually the email the user logs in with. For example, userName: jdoe@example.com.
User resource path	The path to where your users are stored. This is in /Users by default. When you manage users you've already created, you'll pair this with the numeric identifier that qTest assigns to a user. For example, /scim/v2/Users/12345.
Group resource path	The path to a group. Groups are addressed by the displayName identifier. For example, /Groups/QA Team. This is from the Group Name defined in User Groups. The qTest group names that you map in your IdP must be identical to the display names of groups in qTest Manager. Otherwise, group synchronization won't work.

Structure SCIM requests

All SCIM endpoints require your bearer token in the Authorization header. SCIM doesn't support HTTP Basic authentication.

Request and response bodies use the SCIM media type application/scim+json. Send it on the Content-Type header for write operations and expect it on responses.

Copy

Example request headers

Authorization: Bearer <token>
Content-Type: application/scim+json

What's next

Learn how to create and update users with SCIM.