# JumpCloud

Connect JumpCloud so Risotto can check and change user group membership when it grants access

The JumpCloud integration lets Risotto read your JumpCloud user groups and add or remove members when an access rule grants, revokes, or expires access. You connect it with an admin API key on **Settings > Integrations > JumpCloud**.

> **Note:** **Looking for Dashboard SSO?** This integration manages access to applications
> through Risotto. To sign in to the Risotto dashboard with your identity
> provider, see [Dashboard
> Authentication](https://www.tryrisotto.com/docs/guides/dashboard-authentication).

## How it works

1. You save a JumpCloud admin API key in Risotto. Risotto tests the key against your JumpCloud tenant before it stores the key.
2. Risotto loads your JumpCloud user groups in the background and shows them under a **JumpCloud** heading in every group picker.
3. When you pick a JumpCloud group in an access rule's **Identity Provider Group** field, the rule is pinned to JumpCloud.
4. When the rule grants access, Risotto adds the requestor to the group. When the grant is revoked or expires, Risotto removes them.

## Prerequisites

- A JumpCloud admin account with the **Administrator** role or higher. Risotto uses the account's API key, so the account's role sets what Risotto can do.
- API access enabled for that account. An Administrator with Billing enables it in the JumpCloud Admin Portal under **Settings > Administrators**.
- For a multi-tenant (MSP) admin account only: the **Organization ID** of the tenant Risotto manages.

## Connect JumpCloud

1. **Generate an API key in JumpCloud**

   In the [JumpCloud Admin Portal](https://console.jumpcloud.com), click your admin avatar in the top-right corner and select **My API Key**. Click **Generate New API Key** and copy the value. A new key revokes the previous one, so update any other tool that uses the old key.

2. **Copy the Organization ID (MSP accounts only)**

   If the admin account manages more than one JumpCloud organization, copy the **Organization ID** from **Settings > Organization Profile**. A single-organization account does not need it.

3. **Open the JumpCloud page in Risotto**

   Go to **Settings > Integrations** and click the **JumpCloud** card. On the **API key** card, click **Connect**.

   *Product example: The JumpCloud integration page in the Risotto dashboard, not connected, with Connect on the API key card.*

4. **Enter the credentials**

   The **JumpCloud** dialog opens, with the JumpCloud steps in its **Instructions** pane. Paste the key into **API Key**. For an MSP account, enter the **Organization ID**. Leave it empty for a single organization. Click **Save**.

   *Product example: The JumpCloud setup dialog in the Risotto dashboard, with an API key pasted, the Organization ID empty, and the Save button.*

5. **Check the connection**

   Risotto checks the key by reading one user group before it saves. If JumpCloud rejects the key, the dialog shows the reason and nothing is saved. When the save succeeds, the **API key** card shows **API Key: Set** and the Organization ID, or **Not set (single organization)**.

## Use JumpCloud groups

- **Access rules**: on the [access rule](https://www.tryrisotto.com/docs/dashboard/applications/access-rules) form, open the **Identity Provider Group** picker and choose a group under the **JumpCloud** heading. The rule then grants and revokes membership in that group.
- **Approvers**: group-based approver settings on an access rule accept JumpCloud groups in the same picker.
- **Runbooks**: the **Add User to IdP Group** tool accepts JumpCloud. Set its **Identity provider** option to `jumpcloud` when more than one identity provider is connected, so the tool writes to the same directory as the rule's group reference.

There is no import wizard for JumpCloud applications. Create the application in Risotto and add its access rules by hand.

## Configuration details

| Field               | Description                                                                            |
| ------------------- | -------------------------------------------------------------------------------------- |
| **API Key**         | The admin API key from **My API Key** in the JumpCloud Admin Portal. Stored encrypted. |
| **Organization ID** | Only for multi-tenant (MSP) admin accounts. Risotto sends it as the `x-org-id` header. |

Risotto calls JumpCloud at `console.jumpcloud.com`. There is no URL to configure.

> **Warning:** JumpCloud admin API keys expire after 90 days by default. Set a reminder to
> rotate the key, or choose a longer expiration when you generate it. When the
> key expires, access rules pinned to JumpCloud stop working until you save a
> new key: open the **API key** card's **Connected** menu and choose
> **Configure...**.

## Limits

- Risotto caches the group list. After you connect, the picker can show no JumpCloud groups for a moment while the list loads. Click the refresh icon in the picker to load it again.
- Unlock, password reset, and suspend actions are not available for JumpCloud accounts.

## Disconnect

On **Settings > Integrations > JumpCloud**, click the **Connected** menu on the **API key** card and choose **Disconnect...**.

*Product example: The JumpCloud integration page in the Risotto dashboard once connected, with the API key card's Connected menu open on Disconnect.*

In the **Disconnect from JumpCloud?** dialog, click **Disconnect**. Risotto deletes the stored key and stops managing your JumpCloud users and groups. Access rules that name a JumpCloud group stay in place. Connect JumpCloud again to use them.

## Troubleshooting

### Saving the key fails with 'JumpCloud rejected the API key'

JumpCloud returned a 401. The key is wrong, the key has expired (90 days by default), or API access is disabled for the admin account that owns it. Generate a new key, or ask an Administrator with Billing to enable API access under **Settings > Administrators**.

### Saving the key fails with 'JumpCloud permission error'

JumpCloud returned a 403. The admin account that owns the key does not have the **Administrator** role or higher. Use a key from an account with that role.

### The group picker shows no JumpCloud groups

The group list is still loading, or the connection is not saved. Wait a moment and click the refresh icon in the picker. If the picker still shows no **JumpCloud** heading, check that the **API key** card on **Settings > Integrations > JumpCloud** shows **API Key** as **Set**.

## Related

- [Integrations](https://www.tryrisotto.com/docs/dashboard/settings/integrations)
- [Access rules](https://www.tryrisotto.com/docs/dashboard/applications/access-rules)
- [Okta](https://www.tryrisotto.com/docs/integrations/idp/okta)
- [Microsoft Entra ID](https://www.tryrisotto.com/docs/integrations/idp/microsoft-entra)

Source: https://www.tryrisotto.com/docs/integrations/idp/jumpcloud
