netbird-docs/src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx

import {Note} from "@/components/mdx";

# JumpCloud

[JumpCloud](https://jumpcloud.com/) is a cloud-based directory platform that provides identity, access, and device management. It offers single sign-on (SSO), multi-factor authentication (MFA), and centralized user management.

## Connector Setup (Recommended)

Add JumpCloud as a connector to the embedded IdP. This is the simplest approach and recommended for most deployments.

### Prerequisites

- NetBird self-hosted with embedded IdP enabled
- JumpCloud account with admin permissions

### Step 1: Create OIDC Application in JumpCloud

1. Navigate to [JumpCloud Admin Portal](https://console.jumpcloud.com/)
2. Click **SSO Applications** under **USER AUTHENTICATION**
3. Click **Add New Application** → **Custom Application**
4. Confirm **Custom application** and click **Next**
5. Select **Manage Single Sign-On (SSO)** and check **Configure SSO with OIDC**
6. Click **Next**
7. Enter **Display Label**: `NetBird`
8. Click **Next**
9. Review and click **Configure Application**
10. On the **SSO** tab, configure:
    - **Client Authentication Type**: `Confidential`
    - Leave redirect URIs empty for now
11. Click **Activate**
12. Note the **Client ID** and **Client Secret**

### Step 2: Add Connector in NetBird

1. Log in to your NetBird Dashboard
2. Navigate to **Settings** → **Identity Providers**
3. Click **Add Identity Provider**
4. Fill in the fields:

| Field | Value |
|-------|-------|
| Type | Generic OIDC |
| Name | JumpCloud (or your preferred display name) |
| Client ID | From JumpCloud |
| Client Secret | From JumpCloud |
| Issuer | `https://oauth.id.jumpcloud.com` |

5. Click **Save**

### Step 3: Configure Redirect URI

After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your JumpCloud application:

1. Return to JumpCloud Admin → **SSO Applications** → **NetBird**
2. Click the **SSO** tab
3. Under **Redirect URIs**, add the redirect URL from NetBird
4. Click **Save**

### Step 4: Assign User Groups

1. Click the **User Groups** tab
2. Select the user groups that can access NetBird
3. Click **Save**

### Step 5: Test the Connection

1. Log out of NetBird Dashboard
2. On the login page, you should see a "JumpCloud" button
3. Click it and authenticate with your JumpCloud credentials
4. You should be redirected back to NetBird and logged in

---

## Standalone Setup (Advanced)

Use JumpCloud as your primary identity provider instead of NetBird's embedded IdP. This option gives you full control over authentication and user management, is recommended for experienced JumpCloud administrators as it also requires additional setup and ongoing maintenance.

For most deployments, the [embedded IdP](/selfhosted/identity-providers#local-user-management) is the simpler choice — it's built into NetBird, fully integrated, and requires minimal configuration to get started. For this implementation, go back up to the [Connector Setup (Recommended)](#connector-setup-recommended) section above.

### Prerequisites

- JumpCloud account with admin permissions (sign up at https://jumpcloud.com/)
- Docker and Docker Compose for NetBird

### Step 1: Create and Configure SSO Application

1. Navigate to [Admin Portal](https://console.jumpcloud.com/)
2. Click **SSO Applications** under **USER AUTHENTICATION**
3. Click **Add New Application** → **Custom Application**

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-new-sso-app.png" alt="New SSO app" className="imagewrapper-big"/>
</p>

4. Confirm **Custom application** selected and click **Next**

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-new-sso-app-confirm-selection.png" alt="Confirm selection" className="imagewrapper-big"/>
</p>

5. Select **Manage Single Sign-On (SSO)** and check **Configure SSO with OIDC**
6. Click **Next**

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-new-sso-app-features.png" alt="SSO features" className="imagewrapper-big"/>
</p>

7. Enter **Display Label**: `NetBird`
8. Click **Next**

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-new-sso-app-general-info.png" alt="General info" className="imagewrapper-big"/>
</p>

9. Review and click **Configure Application**

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-new-sso-app-confirmation.png" alt="Confirmation" className="imagewrapper-big"/>
</p>

10. On the **SSO** tab, configure:
    - **Redirect URIs**: 
      - `https://<domain>/silent-auth`
      - `https://<domain>/auth`
      - `http://localhost:53000`
    - **Client Authentication Type**: `Public (None PKCE)`
    - **Login URL**: `https://<domain>`

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-sso-configuration.png" alt="SSO configuration" className="imagewrapper-big"/>
</p>

11. Under **Attribute Mapping (optional)**:
    - **Standard Scopes**: `Email`, `Profile`

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-sso-atributes-configuration.png" alt="Attribute configuration" className="imagewrapper-big"/>
</p>

12. Click **User Groups** tab and select groups that can access the application

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-user-groups.png" alt="User groups" className="imagewrapper-big"/>
</p>

13. Click **Activate**

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-oidc-app.png" alt="OIDC app" className="imagewrapper-big"/>
</p>

14. Note the **Client ID**

### Step 2: Create Administrator for Integration

The NetBird management system requires an API token to get user information from JumpCloud.

<Note>
If you already have an integration user, confirm it has the required role and skip to Step 3.
</Note>

1. Navigate to [Admin Portal](https://console.jumpcloud.com/)
2. Go to **Settings** and click the add button (+)
3. Fill in:
   - **First Name**: `NetBird`
   - **Last Name**: `Integration`
   - **Administrator Email**: `netbird-user@<yourdomain>`
   - **Role**: `Read Only`
4. Click **Save**

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-add-admin-user.png" alt="Add admin user" className="imagewrapper-big"/>
</p>

<Note>
**Optional**: To enable automatic user deletion from JumpCloud when deleted from NetBird, add the `--user-delete-from-idp` flag to the management startup command and assign the `Help Desk` role instead.
</Note>

5. Check email for login instructions and set a password

### Step 3: Generate API Token

1. Log in to [Admin Portal](https://console.jumpcloud.com/) with the integration user
2. Click the account initials (top-right) → **My API Key**

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-profile.png" alt="Profile" className="imagewrapper-big"/>
</p>

3. If no key exists, click **Generate New API Key**
4. Copy the API token

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-api-key-generation.png" alt="API key generation" className="imagewrapper-big"/>
</p>

### Step 4: Configure NetBird

Set properties in the `setup.env` file:

```shell
NETBIRD_DOMAIN="<YOUR_DOMAIN>"
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://oauth.id.jumpcloud.com/.well-known/openid-configuration"
NETBIRD_USE_AUTH0=false
NETBIRD_DASH_AUTH_USE_AUDIENCE=false
NETBIRD_AUTH_AUDIENCE="<CLIENT_ID>"
NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access"
NETBIRD_AUTH_CLIENT_ID="<CLIENT_ID>"
NETBIRD_AUTH_REDIRECT_URI="/auth"
NETBIRD_AUTH_SILENT_REDIRECT_URI="/silent-auth"
NETBIRD_TOKEN_SOURCE="idToken"

NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="none"

NETBIRD_MGMT_IDP="jumpcloud"
NETBIRD_IDP_MGMT_EXTRA_API_TOKEN="<API_TOKEN>"
```

### Step 5: Continue with NetBird Setup

You've configured all required resources in JumpCloud. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-5-run-configuration-script).

---

## Troubleshooting

### "Invalid redirect URI" error

- Ensure all redirect URIs are configured in JumpCloud
- Check for trailing slashes
- Verify URLs match exactly

### Users can't access NetBird

- Verify the user belongs to an assigned user group
- Check that the user group is assigned to the NetBird application

### API token not working

- Verify the integration user has appropriate permissions
- Generate a new API token if the current one is invalid

### Device authorization not available

- JumpCloud has limited device auth support
- Set `NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="none"`

---

## Related Resources

- [JumpCloud Documentation](https://jumpcloud.com/support)
- [JumpCloud Admin Console](https://console.jumpcloud.com/)
- [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management)