some file

JumpCloud SSO with NetBird Self-Hosted

JumpCloud 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.

Add JumpCloud as an external IdP directly in the NetBird Management Dashboard. 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: Start Creating OIDC Application in JumpCloud

  1. Navigate to JumpCloud Admin Portal
  2. Click SSO Applications under USER AUTHENTICATION

SSO Applications

  1. Click Add New Application → Custom Application

Custom Applications

  1. Confirm Custom application and click Next
  2. Select Manage Single Sign-On (SSO) and check Configure SSO with OIDC

SSO with OIDC

  1. Click Next
  2. Enter Display Label: NetBird
  3. Click Next
  4. Review and click Configure Application
  5. On the SSO tab, configure:
    • Redirect URIs: https://<your-netbird-domain>/oauth2/callback (you'll verify this matches exactly in Step 3)
    • Client Authentication Type: Client Secret POST
    • Login URL: https://<your-netbird-domain>/
  6. Under Attribute Mapping, enable:
    • Email scope
    • Profile scope
  7. Click Save to save the SSO configuration
  8. Click the User Groups tab and select at least one user group that can access NetBird
  9. Don't click Activate yet — keep this tab open and proceed to Step 2

Sometimes, the JumpCloud application configuration will add duplicate attributes, like email and email_verified. Remove any duplicates if they appear.

Step 2: Get Redirect URL from NetBird

  1. Open a new tab or window and log in to your NetBird Dashboard
  2. Navigate to Settings → Identity Providers
  3. Click Add Identity Provider
  4. Fill in the fields:
FieldValue
TypeGeneric OIDC
NameJumpCloud (or your preferred display name)
Client IDFrom JumpCloud application (will fill after Step 3)
Client SecretFrom JumpCloud application (will fill after Step 3)
Issuerhttps://oauth.id.jumpcloud.com/ (must include trailing slash)

Important: The Issuer must be exactly https://oauth.id.jumpcloud.com/ (with trailing slash) to match what JumpCloud returns. If you enter it without the trailing slash, the connector will fail to initialize.

  1. Copy the Redirect URL that NetBird displays (but don't click Add Provider yet)

Copy redirect URL

Step 3: Complete JumpCloud Application Setup

  1. Return to the JumpCloud tab
  2. Click the SSO tab
  3. Under Redirect URIs, verify the redirect URL matches the exact URL you copied from NetBird (e.g., https://netbird.hopkins.sh/oauth2/callback). If it doesn't match exactly, update it to match.
  4. Click Save (if you made any changes)

Configure JumpCloud SSO

  1. Click Activate
  2. Note the Client ID and Client Secret — you'll need these for Step 4

Client IDs

Step 4: Complete NetBird Setup

  1. Return to the NetBird tab
  2. Fill in the Client ID and Client Secret from Step 3

JumpCloud configuration

  1. Click Add Provider

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. Unless your user approval setting were changed you will need to log back into your local admin account to approve the user.

Configuring JWT 'groups' Claim

To sync JumpCloud groups with NetBird, you need to enable the group attribute in your JumpCloud OIDC application.

Step 1: Enable Group Attributes in JumpCloud

  1. In JumpCloud Admin Portal, go to Access → SSO Applications
  2. Select your NetBird application
  3. Go to the SSO tab
  4. Under Attribute Mapping, find the Group Attributes section
  5. Check Include group attribute
  6. In Groups Attribute Name, enter: groups
  7. Click Save

Add groups claim

Step 2: Assign User Groups to the Application

  1. In your NetBird application, go to the User Groups tab
  2. Select the groups whose members should have access to NetBird
  3. Click Save

Users will receive group claims based on which assigned groups they belong to.

Step 3: Enable JWT Group Sync in NetBird

  1. In NetBird Dashboard, go to Settings → Groups
  2. Enable JWT group sync
  3. Set JWT claim to groups
  4. Optionally configure JWT allow groups to restrict access

Known issue: If a user belongs to only one group, JumpCloud may return it as a string instead of an array, which can cause issues. Ensure users are members of at least two groups for consistent behavior, or test with your specific setup.

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 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 Management Setup (Recommended) section above.

For detailed instructions on the standalone setup, see the JumpCloud SSO with NetBird Self-Hosted (Legacy) documentation.

If you prefer to have full control over authentication, consider self-hosted alternatives like PocketID.

Troubleshooting

"Connector failed to initialize" error

  • Ensure Attribute Mapping has both Email and Profile scopes enabled
  • Verify at least one User Group is assigned to the application before activation
  • Check that Redirect URIs exactly matches the URL from NetBird (no trailing slashes)
  • Ensure Client Authentication Type is set to Client Secret POST
  • Verify Login URL matches your NetBird domain exactly
  • Make sure the application is Activated and you have the correct Client ID and Client Secret
  • Remove any duplicate attributes in Attribute Mapping (e.g., email and email_verified)

"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