mirror of
https://github.com/netbirdio/docs.git
synced 2026-04-27 04:46:35 +00:00
DEX Docs Overall Updates
This commit is contained in:
Brandon Hopkins
@@ -1,105 +1,202 @@
|
||||
import {Note} from "@/components/mdx";
|
||||
|
||||
# JumpCloud with NetBird Self-Hosted
|
||||
# JumpCloud
|
||||
|
||||
This guide is a part of the [NetBird Self-hosting Guide](/getting-started/self-hosting) and explains how to integrate
|
||||
**self-hosted** NetBird with [JumpCloud](https://jumpcloud.com/).
|
||||
[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.
|
||||
|
||||
Before you start creating and configuring an JumpCloud application, ensure that you have the following:
|
||||
- An JumpCloud account: To create application, you must have an JumpCloud account. If you don't have one, sign up at https://jumpcloud.com/.
|
||||
- User account with admin permissions: You must have an JumpCloud account with the admin permissions. If you don't have the required permissions, ask your administrator to grant them to you.
|
||||
## Connector Setup (Recommended)
|
||||
|
||||
Add JumpCloud as a connector to the embedded IdP. This is the simplest approach and recommended for most deployments.
|
||||
|
||||
## Step 1: Create and configure SSO application
|
||||
### Prerequisites
|
||||
|
||||
- Navigate to to [Admin Portal](https://console.jumpcloud.com/) page
|
||||
- Click `SSO Applications` on the left menu under `USER AUTHENTICATION` section
|
||||
- Click `Add New Application` and select `Custom Application`
|
||||
<p>
|
||||
<img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-new-sso-app.png" alt="high-level-dia" className="imagewrapper-big"/>
|
||||
</p>
|
||||
- On the `Which application would you like to integrate` screen, confirm that you've selected `Custom application` and click `Next`
|
||||
<p>
|
||||
<img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-new-sso-app-confirm-selection.png" alt="high-level-dia" className="imagewrapper-big"/>
|
||||
</p>
|
||||
- On the `Select the features you would like to enable` screen, select `Manage Single Sign-On (SSO)` and check `Configure SSO with OIDC` and click `Next`
|
||||
<p>
|
||||
<img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-new-sso-app-features.png" alt="high-level-dia" className="imagewrapper-big"/>
|
||||
</p>
|
||||
- On the `Enter General info` screen, add `NetBird` as `Display Label` and click `Next`
|
||||
<p>
|
||||
<img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-new-sso-app-general-info.png" alt="high-level-dia" className="imagewrapper-big"/>
|
||||
</p>
|
||||
- On the confirmation screen, review the information and click on `Configure Application` to proceed
|
||||
<p>
|
||||
<img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-new-sso-app-confirmation.png" alt="high-level-dia" className="imagewrapper-big"/>
|
||||
</p>
|
||||
- On the `New Application` screen, click on the SSO tab and enter the following values:
|
||||
- Under `Endpoint Configuration` section:
|
||||
- Redirect URIs: `https://<domain>/silent-auth`, `https://<domain>/auth` and `http://localhost:53000`
|
||||
- Client Authentication Type: `Public (None PKCE)`
|
||||
- Login URL: `https://<domain>`
|
||||
- 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 the embedded IdP.
|
||||
|
||||
### 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-sso-configuration.png" alt="high-level-dia" className="imagewrapper-big"/>
|
||||
<img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-new-sso-app.png" alt="New SSO app" className="imagewrapper-big"/>
|
||||
</p>
|
||||
- Under `Attribute Mapping (optional)` section:
|
||||
- Standard Scopes: `Email`, `Profile`
|
||||
<p>
|
||||
<img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-sso-atributes-configuration.png" alt="high-level-dia" className="imagewrapper-big"/>
|
||||
</p>
|
||||
- Click on the `User Groups` tab and select the user groups that can access this application
|
||||
<p>
|
||||
<img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-user-groups.png" alt="high-level-dia" className="imagewrapper-big"/>
|
||||
</p>
|
||||
- Click `Activate`
|
||||
<p>
|
||||
<img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-oidc-app.png" alt="high-level-dia" className="imagewrapper-big"/>
|
||||
</p>
|
||||
- Take note of `Client ID`, will be used later
|
||||
|
||||
## Step 2: Create an account administrator for integration
|
||||
The NetBird management system requires an API token to get user information from JumpCloud. This API is bound to an administrator user configured in JumpCloud's admin portal.
|
||||
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.
|
||||
|
||||
The following steps will assume that you are creating a new account. If you already have a user for this purpose, confirm it has the required role described below and skip to Step 3 in this guide.
|
||||
- Navigate to to [Admin Portal](https://console.jumpcloud.com/) page
|
||||
- Go to account `Settings` and click on the add button (+)
|
||||
- On the `Create New Administrator` window, enter the following values:
|
||||
- First Name: `NetBird`
|
||||
- Last Name: `Integration`
|
||||
- Administrator Email: `netbird-user@<yourdomain>` # this email will be used to receive the login instructions
|
||||
- Role: `Read Only`
|
||||
- Click `Save`
|
||||
<Note>
|
||||
Optional
|
||||
|
||||
NetBird offers the ability to automatically delete a user from the JumpCloud side when the user is deleted from the associated account.
|
||||
To enable this functionality, simply include the `--user-delete-from-idp` flag in the management startup command within your Docker Compose configuration. If you choose to enable this feature,
|
||||
please ensure that you assign the `Help Desk` role to the `NetBird Integration` user following the steps outlined above.
|
||||
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="high-level-dia" className="imagewrapper-big"/>
|
||||
<img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-add-admin-user.png" alt="Add admin user" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
After following the steps above, you will receive the login instructions for the newly created user in the email configured. Please follow the instructions to set a password for the user.
|
||||
<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>
|
||||
|
||||
## Step 3: Generate api token
|
||||
In this step, we will generate netbird api token in jumpcloud for authorizing calls to user api.
|
||||
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**
|
||||
|
||||
- Navigate to to [Admin Portal](https://console.jumpcloud.com/) page
|
||||
- Login with the user created in the previous step or with an existing user
|
||||
- Click on the account initials displayed at the top-right and select `My API Key` from the drop-down
|
||||
<p>
|
||||
<img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-profile.png" alt="high-level-dia" className="imagewrapper-big"/>
|
||||
</p>
|
||||
- If there is no API key generated, click on `Generate New API Key` button
|
||||
- Take note of your api token displayed
|
||||
<p>
|
||||
<img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-api-key-generation.png" alt="high-level-dia" className="imagewrapper-big"/>
|
||||
<img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-profile.png" alt="Profile" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
- Set properties in the `setup.env` file:
|
||||
```json
|
||||
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
|
||||
@@ -117,5 +214,39 @@ NETBIRD_MGMT_IDP="jumpcloud"
|
||||
NETBIRD_IDP_MGMT_EXTRA_API_TOKEN="<API_TOKEN>"
|
||||
```
|
||||
|
||||
## Step 4: Continue with the NetBird Self-hosting Guide
|
||||
You've configured all required resources in JumpCloud. You can now continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-5-run-configuration-script).
|
||||
### 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/embedded-idp)
|
||||
Reference in New Issue
Block a user