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

# SSO login with JumpCloud

> How the IT team connects JumpCloud to QX: the SSO login, user provisioning and required SSO.

This guide is for the JumpCloud administrator of your company. It shows how to connect JumpCloud to one QX organization. The work has two parts: the IT team configures JumpCloud, and the owner of the organization configures QX.

## What QX offers

* A person signs in to QX with the SSO login in JumpCloud, through the OIDC protocol. QX never sees the password.
* JumpCloud creates, updates and deactivates the users of QX through user provisioning, with the SCIM 2.0 protocol. QX receives users only. The groups stay in JumpCloud.
* JumpCloud has an owner group and an operator group. At each login, QX gives the person the role of the group.
* The owner turns on required SSO for the whole organization. With the rule on, nobody in the organization signs in with a password, including the owner.
* When the organization requires two-step verification, QX accepts only an SSO login in which the person used a second factor in JumpCloud.
* A session that starts with the SSO login expires 8 hours after the login. It does not extend.

Today QX accepts only JumpCloud, in the US, EU and India regions. QX does not offer SAML.

## The order of the work

Do the steps in this order:

1. The IT team creates the OIDC app in JumpCloud.
2. The IT team binds the two groups to the app.
3. The owner configures the SSO connection in QX.
4. The IT team pastes the QX login URL into the app.
5. The owner issues the provisioning key.
6. The IT team activates user provisioning in JumpCloud.
7. The owner does the login test.
8. The owner enables SSO login.
9. The owner turns on required SSO.

Before you start, check two things:

* The JumpCloud user of the owner has the same e-mail as the QX user of the owner.
* The owner is in the owner group.

## The QX addresses

The owner sees the addresses in **Settings › SSO**, in the box **Addresses for JumpCloud**. Each address has a **Copy** button.

| Address in QX | Field in JumpCloud |
| - | - |
| Login URL | **Login URL**, in the SSO tab of the app |
| Redirect URI | **Redirect URIs**, in the SSO tab of the app |
| User provisioning base URL | **Base URL**, in the Provisioning tab of the app |

The login URL shows only after the owner saves the SSO connection. The other two addresses are these:

```text theme={null}
https://app.useqx.com/sso/callback
https://app.useqx.com/scim/v2
```

## 1. Create the OIDC app in JumpCloud

1. In the JumpCloud Admin Portal, go to **Access › SSO Applications**.
2. Click **+ Add New Application**.
3. Select **Custom Application** and click **Next**.
4. Select **Manage Single Sign-On**, then **Configure SSO with OIDC**, and click **Next**.
5. In **Display Label**, type `QX`.
6. Turn on **Show this application in User Portal**. The portal tile opens QX.
7. Click **Next**, then **Configure Application**.
8. In the SSO tab, in **Redirect URIs**, paste the QX redirect URI.
9. In **Client Authentication Type**, select **Client Secret Basic**. QX does not work with the other two types.
10. Leave **Login URL** empty for now. Step 4 fills the field. JumpCloud accepts the app with no **Login URL** (not confirmed in an official source).
11. In **Subject Claim**, keep **JumpCloud User ID (Recommended Default)**.
12. In Attribute Mapping, select the scopes **Email** and **Profile**. Without the e-mail, QX refuses each login.
13. Select **include group attribute** and type `groups` as the name of the groups attribute.
14. Click **Activate**. JumpCloud shows the client secret only once. Copy the client ID and the client secret, and click **Got It**.

Give the client ID and the client secret to the owner through a safe channel, such as a password manager.

## 2. Bind the two groups to the app

1. Open the **User Groups** tab of the app.
2. Select the owner group and the operator group.
3. Click **Save**.

Each person must be in only one of these two groups. A person in both groups cannot sign in to QX.

## 3. Configure the SSO connection in QX

The owner does these steps in QX:

1. Open **Settings › SSO** and click **Configure SSO connection**.
2. In **Region**, select the region of the JumpCloud account: **US**, **EU** or **India**.
3. In **Client ID** and **Client secret**, paste the values of step 1.
4. In **Owner group** and **Operator group**, type the name of each group exactly as JumpCloud shows it.
5. Click **Save SSO connection**.

After the save, the box **Addresses for JumpCloud** shows the login URL.

## 4. Paste the login URL into JumpCloud

1. Open the app in JumpCloud, in the SSO tab.
2. In **Login URL**, paste the QX login URL.
3. Save the app.

## 5. Issue the provisioning key

The owner does these steps in QX:

1. In **Settings › SSO**, click **Manage provisioning keys**.
2. Click **Issue provisioning key**, then **Issue key**. If the login of the owner is older than 15 minutes, QX asks for the password.
3. Copy the key. QX shows the key only once. The key starts with `qxp_`.
4. Give the key to the IT team through a safe channel. Do not send the key by e-mail or by message.
5. After the IT team pastes the key, check **I pasted the key into JumpCloud** and click **Back to the keys**.

## 6. Activate user provisioning in JumpCloud

1. Open the **Provisioning** tab of the app.
2. Leave **Use mTLS** off.
3. In **Base URL**, paste the user provisioning base URL, with no slash at the end.
4. In **Token**, paste the provisioning key.
5. In **Test User Email**, type an e-mail that no QX user has. JumpCloud creates this test user and then deletes it.
6. Click **Test Connection**.
7. Turn off **Enable management of User Groups and Group Membership in this application**. QX does not receive groups.
8. Click **Activate**. Do not click **Save**.

If the activation fails with the message "QX needs externalId to create or link a user", map `externalId`:

1. In the **Provisioning** tab, open **User Attributes** and click **Edit**.
2. Click **+Add Attribute** and select the type **Expression**.
3. In the JumpCloud attribute field, type this expression:

```text theme={null}
notNullOrEmpty(providerUser.externalId) ? providerUser.externalId : jcUser.id
```

4. In the SCIM attribute field, select `externalId`.
5. Click **Update**, then **Activate** again.

The `externalId` carries the JumpCloud User ID. QX recognizes the person by this identifier. The e-mail alone never identifies the person.

## 7. Do the login test

1. In **Settings › SSO**, the owner clicks **Test login**.
2. QX opens JumpCloud. The owner signs in with their own user.
3. QX shows "The login test passed. The SSO connection is verified."

The test needs three things:

* User provisioning already linked the user of the owner.
* The owner is in the owner group.
* When the organization requires two-step verification, the owner signs in to JumpCloud with the second factor.

## 8. Enable SSO login

1. In **Settings › SSO**, the owner clicks **Enable SSO login**.
2. A person of the operator group opens QX from the tile of the JumpCloud portal and checks the login.

A person signs in to QX from the tile of the JumpCloud portal. The QX page **Sign in with SSO** asks the person to open QX from the portal.

## 9. Turn on required SSO

1. In **Settings › SSO**, the owner clicks **Turn on required SSO**.
2. The owner reads the warning and clicks **Turn on required SSO** again.

Each session that started with a password in the organization ends, including the session of the owner. From then on, each user of the organization signs in with the SSO login.

## How QX treats each person

* User provisioning creates the user of a new person. The **Users** screen shows "Waiting for SSO login". The first SSO login activates the user and gives the role of the group.
* When the person already has a QX user, user provisioning links that user by the e-mail, in the same organization. The user keeps the history.
* After a group change, the role changes at the next SSO login. To change the group, add the person to the new group before you remove the person from the old group.
* To deactivate a person, remove the person from both groups or suspend the person in JumpCloud. User provisioning deactivates the user in QX. All sessions of the user end at the same moment.
* To reactivate a person, put the person back in a group. The user goes back to "Waiting for SSO login" and signs in again at the next SSO login.
* The name and the e-mail of the person change only in JumpCloud. The owner sees the user in QX, but does not change them.

## Replace the provisioning key

The SSO connection keeps up to 2 active keys. With two keys, JumpCloud switches to the new key with no gap in user provisioning.

1. The owner issues a new key, as in step 5. In a session that started with SSO, when the login is older than 15 minutes, QX asks for the identity confirmation in JumpCloud.
2. The IT team opens the **Provisioning** tab of the app and expands **Configuration Settings**.
3. The IT team pastes the new key into **Token Key** and clicks **Update**. The **Save** button does not change the key.
4. The owner checks the **Last use** column of the new key.
5. The owner clicks **Revoke** on the old key, then **Revoke key**.

## Replace the client secret

1. In JumpCloud, the IT team opens the app and selects **Actions › Regenerate Secret**, then **Regenerate**.
2. The owner opens **Edit SSO connection**, pastes the new secret into **Client secret** and clicks **Save SSO connection**.

A new client secret ends all sessions that started with SSO in the organization. Make the change outside working hours.

## When JumpCloud is down

With required SSO on, nobody signs in to QX while JumpCloud is down. The open sessions continue until they expire.

1. If an owner still has an open session, the owner clicks **Turn off required SSO** in **Settings › SSO**.
2. If no owner has an open session, ask QX support. Support turns off required SSO and writes the reason in the audit log.
3. A person with no password clicks **Forgot your password?** on the login page and sets a password.
4. When JumpCloud is back, the owner clicks **Turn on required SSO**.

A user that user provisioning created, and that never signed in to QX, cannot sign in with a password. That user waits for JumpCloud to come back.

## Refusal messages

| Message that the person sees | What the IT team checks |
| - | - |
| Your organization requires a second factor. | The person signs in to JumpCloud with the second factor. |
| Your JumpCloud user must be in one QX group, and in only one. | The group of the person, the group names in QX and the `groups` attribute. |
| Your access to QX is turned off. | The state of the person in JumpCloud and in the groups of the app. |
| QX did not find your user. | The e-mail of the person in JumpCloud and in QX, and user provisioning. |
| JumpCloud did not answer. | The JumpCloud status. Try again in a few minutes. |
| We could not sign you in with SSO. | **Client Authentication Type**, the client secret, the region and the scopes **Email** and **Profile**. |

## Sources

* JumpCloud, [SSO with OIDC](https://jumpcloud.com/support/sso-with-oidc).
* JumpCloud, [Provision and manage users and groups in apps using custom SCIM identity management integration](https://jumpcloud.com/support/provision-and-manage-users-and-groups-in-apps-using-custom-scim-identity-management-integration).
* JumpCloud, [Authorize users to an SSO application](https://jumpcloud.com/support/authorize-users-to-an-sso-application).
* JumpCloud, [Rotate SSO application certificates, SCIM token keys, and OIDC tokens](https://jumpcloud.com/support/rotate-sso-certs).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.