Identity Providers

There are a few Identity Provider options that you can choose to run a self-hosted version NetBird.

Self-hosted IDPs

Zitadel

This guide is a part of the NetBird Self-hosting Guide and explains how to integrate self-hosted NetBird with Zitadel.

Step 1. Create and configure Zitadel application

In this step, we will create and configure NetBird application in zitadel.

Create new zitadel project

• Navigate to zitadel console
• Click Projects at the top menu, then click Create New Project to create a new project
• Fill in the form with the following values and click Continue
• Name: NETBIRD

Create new zitadel application

• Click Projects in the top menu and select NETBIRD project from the list
• Click New in APPLICATIONS section to create a new application
• Fill in the form with the following values and click Continue
• Name: netbird
• TYPE OF APPLICATION: User Agent

• Fill in the form with the following values and click Continue
• Authentication Method: PKCE

• Fill in the form with the following values and click Continue
• Redirect URIs: https://<domain>/auth and click +
• Redirect URIs: https://<domain>/silent-auth and click +
• Redirect URIs: http://localhost:53000 and click +
• Post Logout URIs: https://<domain>/ and click +

• Verify applications details and Click Create and then click Close
• Under Grant Types select Authorization Code, Device Code and Refresh Token and click save

• Copy Client ID will be used later in the setup.env

Step 2: Application Token Configuration

To configure netbird application token you need to:

• Click Projects in the top menu and select NETBIRD project from the list
• Select netbird application from APPLICATIONS section
• Click Token Settings in the left menu
• Fill in the form with the following values:
• Auth Token Type: JWT
• Check Add user roles to the access token checkbox
• Click Save

Step 3: Application Redirect Configuration

To configure netbird application redirect you need to:

• Click Projects in the top menu and select NETBIRD project from the list
• Select netbird application from APPLICATIONS section
• Click Redirect Settings in the left menu
• Fill in the form with the following values:
• Toggle Development Mode
• Click Save

Step 4: Create a Service User

In this step we will create a netbird service user.

• Click Users in the top menu
• Select Service Users tab
• Click New
• Fill in the form with the following values:
• User Name: netbird
• Name: netbird
• Description: Netbird Service User
• Access Token Type: JWT
• Click Create

In this step we will generate ClientSecret for the netbird service user.

• Click Actions in the top right corner and click Generate Client Secret
• Copy ClientSecret from the dialog will be used later to set NETBIRD_IDP_MGMT_CLIENT_SECRET in the setup.env

Step 5: Grant manage-users role to netbird service user

In this step we will grant Org User Manager role to netbird service user.

• Click Organization in the top menu
• Click + in the top right corner
• Search for netbird service user
• Check Org User Manager checkbox
• Click Add

Your authority OIDC configuration will be available under:

https://<YOUR_ZITADEL_HOST_AND_PORT>/.well-known/openid-configuration

:::caution Double-check if the endpoint returns a JSON response by calling it from your browser. :::

• Set properties in the setup.env file:

NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://<YOUR_ZITADEL_HOST_AND_PORT>/.well-known/openid-configuration"
NETBIRD_USE_AUTH0=false
NETBIRD_AUTH_CLIENT_ID="<CLIENT_ID>"
NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access api"
NETBIRD_AUTH_AUDIENCE="<CLIENT_ID>"
NETBIRD_AUTH_REDIRECT_URI="/auth"
NETBIRD_AUTH_SILENT_REDIRECT_URI="/silent-auth"

NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="hosted"
NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID="<CLIENT_ID>"
NETBIRD_AUTH_DEVICE_AUTH_AUDIENCE="<CLIENT_ID>"

NETBIRD_MGMT_IDP="zitadel"
NETBIRD_IDP_MGMT_CLIENT_ID="netbird"
NETBIRD_IDP_MGMT_CLIENT_SECRET="<CLIENT_SECRET>"
NETBIRD_IDP_MGMT_EXTRA_MANAGEMENT_ENDPOINT="https://<YOUR_ZITADEL_HOST_AND_PORT>/management/v1"
NETBIRD_MGMT_IDP_SIGNKEY_REFRESH=true

Step 6: Continue with the NetBird Self-hosting Guide

You've configured all required resources in Zitadel. You can now continue with the NetBird Self-hosting Guide.

Keycloak

This guide is a part of the NetBird Self-hosting Guide and explains how to integrate self-hosted NetBird with Keycloak.

Keycloak is an open source software product to allow single sign-on with Identity and Access Management aimed at modern applications and services.

The following guide is an adapted version of the original Keycloak on Docker guide from the official website.

Expected Result

After completing this guide, you can log in to your self-hosted NetBird Dashboard and add your machines to your network using the Interactive SSO Login feature over Keycloak.

Step 1: Check your Keycloak Instance

For this guide, you need a fully configured Keycloak instance running with SSL.

We assume that your Keycloak instance is available at https://YOUR-KEYCLOAK-HOST-AND_PORT. Feel free to change the port if you have configured Keycloak with a different one.

Most of the OIDC software requires SSL for production use. We encourage you to comply with this requirement to make the world more secure 😊.

Step 2: Create a realm

To create a realm you need to:

• Open the Keycloak Admin Console
• Hover the mouse over the dropdown in the top-left corner where it says Master, then click on Create Realm
• Fill in the form with the following values:
• Realm name: netbird
• Click Create

Step 3: Create a user

In this step we will create a NetBird administrator user.

• Open the Keycloak Admin Console
• Make sure, that the selected realm is Netbird
• Click Users (left-hand menu)
• Click Create new user
• Fill in the form with the following values:
• Username: netbird
• Click Create

The user will need an initial password set to be able to log in. To do this:

• Click Credentials tab
• Click Set password button
• Fill in the password form with a password
• Set the Temporary field to Off to prevent having to update password on first login
• Click Save

Step 4: Create a NetBird client

In this step we will create NetBird application client and register with the Keycloak instance.

• Open the Keycloak Admin Console
• Make sure, that the selected realm is Netbird
• Click Clients
• Click Create client button
• Fill in the form with the following values and click Next:
• Client Type: OpenID Connect
• Client ID: netbird-client
• Your newly client netbird-client will be used later to set NETBIRD_AUTH_CLIENT_ID in the setup.env

• Check the checkboxes as on the screenshot below and click Save

Step 5: Adjust NetBird client access settings

In this step we will configure NetBird application client access with the NetBird URLs.

• Open the Keycloak Admin Console
• Make sure, that the selected realm is Netbird
• Click Clients
• Choose netbird-client from the list
• Go to Access Settings section
• Fill in the fields with the following values:
• Root URL: https://YOUR DOMAIN/ (this is the NetBird Dashboard root URL)
• Valid redirect URIs: https://YOUR DOMAIN/* and http://localhost:53000
• Valid post logout redirect URIs: https://YOUR DOMAIN/*
• Web origins: +
• Click Save

Step 6: Create a NetBird client scope

In this step, we will create and configure the NetBird client audience for Keycloak to add it to the generated JWT tokens.

• Open the Keycloak Admin Console
• Make sure, that the selected realm is Netbird
• Click Client scopes (left-hand menu)
• Click Create client scope button
• Fill in the form with the following values:
• Name: api
• Type: Default
• Protocol: OpenID Connect
• Click Save

• While in the newly created Client Scope, switch to the Mappers tab
• Click Configure a new mapper
• Choose the Audience mapping

• Fill in the form with the following values:
• Name: Audience for NetBird Management API
• Included Client Audience: netbird-client
• Add to access token: On
• Click Save

Step 7: Add client scope to NetBird client

• Open the Keycloak Admin Console
• Make sure, that the selected realm is Netbird
• Click Clients
• Choose netbird-client from the list
• Switch to Client scopes tab
• Click Add client scope button
• Choose api
• Click Add choosing Default
• The value netbird-client will be used as audience

Step 8: Create a NetBird-Backend client

In this step we will create NetBird backend client and register with the Keycloak instance.

• Open the Keycloak Admin Console
• Make sure, that the selected realm is Netbird
• Click Clients
• Click Create client button
• Fill in the form with the following values and click Next:
• Client Type: OpenID Connect
• Client ID: netbird-backend
• Your newly client netbird-backend will be used later to set NETBIRD_IDP_MGMT_CLIENT_ID in the setup.env

• Check the checkboxes as on the screenshot below and click Save

The client will need secret to authenticate. To do this:

• Click Credentials tab
• Copy client secret will be used later to set NETBIRD_IDP_MGMT_CLIENT_SECRET in the setup.env

Step 9: Add view-users role to netbird-backend

• Open the Keycloak Admin Console
• Make sure, that the selected realm is Netbird
• Click Clients
• Choose netbird-backend from the list
• Switch to Service accounts roles tab
• Click Assign roles button
• Select Filter by clients and search for view-users

• Check the role checkbox and click assign

Your authority OIDC configuration will be available under:

https://<YOUR_KEYCLOAK_HOST_AND_PORT>/realms/netbird/.well-known/openid-configuration

• Set properties in the setup.env file:

NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT=`https://<YOUR_KEYCLOAK_HOST_AND_PORT>/realms/netbird/.well-known/openid-configuration`.
NETBIRD_USE_AUTH0=false
NETBIRD_AUTH_CLIENT_ID=`netbird-client`
NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access api"
NETBIRD_AUTH_AUDIENCE=`netbird-client`

NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID=`netbird-client`

NETBIRD_MGMT_IDP="keycloak"
NETBIRD_IDP_MGMT_CLIENT_ID="netbird-backend"
NETBIRD_IDP_MGMT_CLIENT_SECRET="<NETBIRD_BACKEND_CLIENT_SECRET>"
NETBIRD_IDP_MGMT_EXTRA_ADMIN_ENDPOINT="https://<YOUR_KEYCLOAK_HOST_AND_PORT>/admin/realms/netbird"

Step 10: Continue with the NetBird Self-hosting Guide

You've configured all required resources in Keycloak. You can now continue with the NetBird Self-hosting Guide.

Authentik

This guide is a part of the NetBird Self-hosting Guide and explains how to integrate self-hosted NetBird with Authentik.

Step 1: Create OAuth2/OpenID Provider

In this step, we will create OAuth2/OpenID Provider in Authentik.

• Navigate to authentik admin interface
• Click Applications on the left menu, then click Providers
• Click Create to create new provider
• Fill in the form with the following values and click Next
  • type: OAuth2/OpenID Provider

• Fill in the form with the following values and click Finish
  • Name: Netbird
  • Authentication Flow: default-authentication-flow (Welcome to authentik!)
  • Authorization Flow: default-provider-authorization-explicit-consent (Authorize Application)
  • Protocol Settings:
    • Client type: Public
    • Redirect URIs/Origins (RegEx): https://<domain>, https://<domain>.*, http://localhost:53000 (Each URI should be entered on a new line)
    • Signing Key: Must be selected! Can be any cert present, e.g. authentik Self-signed Certificate
  • Advanced protocol settings:
    • Access code validity: minutes=10
    • Subject mode: Based on the User's ID

Take note of Client ID, we will use it later

Step 2: Create external applications

In this step, we will create external applications in Authentik.

• Navigate to authentik admin interface
• Click Applications on the left menu, then click Applications
• Click Create to create new application
• Fill in the form with the following values and click Create
  • Name: Netbird
  • Slug: netbird
  • Provider: Netbird

Step 3: Create service account

In this step, we will create service account.

• Navigate to authentik admin interface
• Click Directory on the left menu, then click Users
• Click Create Service Account to create service account
• Fill in the form with the following values and click Create
  • Username: Netbird
  • Create Group: Disable

• Take note of service account username and password, we will need it later

Step 4: Add service account to admin group

In this step, we will add Netbird service account to authentik Admins group.

• Navigate to authentik admin interface
• Click Directory on the left menu, then click Groups
• Click authentik Admins from list of groups and select Users tab at the top
• Click Add existing user and click + button to add user
• Select Netbird and click Add
• Disable Hide service-accounts and verify if user Netbird is added to the group

Step 5: Create a authentication flow for device token authentication

• Navigate to authentik admin interface
• Click Flows and Stages on the left menu, then click Flows then Create
• Fill in the form with the following values and click Create
  • Name: default-device-code-flow
  • Title: Device Code Flow
  • Designation: Stage Configuration
  • Authentication: Require authentication

• Navigate to authentik admin interface
• Click System on the left menu, then click Brands
• Click on the edit button of domain authentik-default
• Under Default flows set Device code flow to default-device-code-flow
• Click Update

Your authority OIDC configuration will be available under:

https://< YOUR_AUTHENTIK_HOST_AND_PORT >/application/o/netbird/.well-known/openid-configuration

• Set properties in the setup.env file:

NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://<YOUR_AUTHENTIK_HOST_AND_PORT>/application/o/netbird/.well-known/openid-configuration"
NETBIRD_USE_AUTH0=false
NETBIRD_AUTH_CLIENT_ID="<PROVIDER_CLIENT_ID>"
NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access api"
NETBIRD_AUTH_AUDIENCE="<PROVIDER_CLIENT_ID>"
NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID="<PROVIDER_CLIENT_ID>"
NETBIRD_AUTH_DEVICE_AUTH_AUDIENCE="<PROVIDER_CLIENT_ID>"

NETBIRD_MGMT_IDP="authentik"
NETBIRD_IDP_MGMT_CLIENT_ID="<PROVIDER_CLIENT_ID>"
NETBIRD_IDP_MGMT_EXTRA_USERNAME="Netbird"
NETBIRD_IDP_MGMT_EXTRA_PASSWORD="<SERVICE_ACCOUNT_PASSWORD>"

# needs disabling due to issue with IdP. Learn more [here](https://github.com/netbirdio/netbird/issues/3654)
NETBIRD_AUTH_PKCE_DISABLE_PROMPT_LOGIN=true

Step 6: Continue with the NetBird Self-hosting Guide

You've configured all required resources in Authentik. You can now continue with the NetBird Self-hosting Guide.

Managed IDPs

Azure AD (Microsoft Entra ID)

This guide is a part of the NetBird Self-hosting Guide and explains how to integrate self-hosted NetBird with Azure AD.

Azure AD is a an enterprise identity service that provides single sign-on and multifactor authentication to your applications. It is a 3rd party managed service and can't be self-hosted.

Before you start creating and configuring an Azure AD application, ensure that you have the following:

• An Azure account: To create an Azure AD application, you must have an Azure account. If you don't have one, sign up for a free account at https://azure.microsoft.com/free/.

• User account with appropriate permissions: You must have an Azure AD user account with the appropriate permissions to create and manage Azure AD applications. If you don't have the required permissions, ask your Azure AD administrator to grant them to you.

Step 1. Create and configure Azure AD application

In this step, we will create and configure NetBird application in azure AD.

• Navigate to Azure Active Directory
• Click App Registrations in the left menu then click on the + New registration button to create a new application.
• Fill in the form with the following values and click Register
  • Name: Netbird
  • Account Types: Accounts in this organizational directory only (Default Directory only - Single tenant)
  • Redirect URI: select Single-page application (SPA) and URI as https://<yournetbirddomain.com>/silent-auth

Step 2. Platform configurations

• Click Authentication on the left side menu
• Under the Single-page application Section, add another URI https://<yournetbirddomain.com>/auth

• Scroll down and setup other options as on the screenshot below and click Save

• Click Add a Platform and select Mobile and desktop applications
• Fill in the form with the following values and click Configure
  • Custom redirect URIs: http://localhost:53000

Step 3. Create a NetBird application scope

• Click Expose an API on the left menu
• Under Application ID URI click Set and then Save
• Click + Add a Scope
• Fill in the form with the following values and click Add scope
• Scope name: api

• Under Authorized client Applications, click on + add a client application and enter the following:
• Fill in the form with the following values and click Add application
• Client ID: same as your Application ID URI minus the api://

Step 4. Add API permissions

Add Netbird permissions

• Click API permissions on the left menu
• Click Add a permission
• Click My APIs tab, and select Netbird. Next check api permission checkbox and click Add permissions.

Add Delegated permissions to Microsoft Graph

• Click Add a permission
• Click Microsoft Graph and then click Application permissions tab
• In Select permissions search for User.Read and under the User section select User.Read.All and click Add permissions

• Click Grant admin consent for Default Directory and click Yes

Step 5. Update token version

• Click Manifest on left menu
• Search for accessTokenAcceptedVersion and change the value from null to 2
• Click Save

Step 6. Generate client secret

• Click Certificates & secrets on left menu
• Click New client secret
• Fill in the form with the following values and click Add
• Description: Netbird
• Copy Value and save it as it can be viewed only once after creation.

• Click Overview on left menu and take note of Application (client) ID, Object ID and Directory (tenant) ID will be required in next step.

Your authority OIDC configuration will be available under:

https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0/.well-known/openid-configuration

• Set properties in the setup.env file:

NETBIRD_DOMAIN="<YOUR_DOMAIN>"
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0/.well-known/openid-configuration"
NETBIRD_USE_AUTH0=false
NETBIRD_AUTH_CLIENT_ID="<Application (client) ID>"
NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access User.Read api://<Application (client) ID>/api"
NETBIRD_AUTH_AUDIENCE="<Application (client) ID>"
NETBIRD_AUTH_REDIRECT_URI="/auth"
NETBIRD_AUTH_SILENT_REDIRECT_URI="/silent-auth"
NETBIRD_AUTH_USER_ID_CLAIM="oid"
NETBIRD_TOKEN_SOURCE="idToken"

NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="none"

NETBIRD_MGMT_IDP="azure"
NETBIRD_IDP_MGMT_CLIENT_ID="<Application (client) ID>"
NETBIRD_IDP_MGMT_CLIENT_SECRET="<CLIENT_SECRET>"
NETBIRD_IDP_MGMT_EXTRA_OBJECT_ID="<Object ID>"
NETBIRD_IDP_MGMT_EXTRA_GRAPH_API_ENDPOINT="https://graph.microsoft.com/v1.0"

Step 7: Continue with the NetBird Self-hosting Guide

You've configured all required resources in Azure AD. You can now continue with the NetBird Self-hosting Guide.

Okta

This guide is a part of the NetBird Self-hosting Guide and explains how to integrate self-hosted NetBird with Okta.

Before you start creating and configuring an Okta application, ensure that you have an Okta workforce identity cloud account. If you don't have one, sign up for a free account at https://www.okta.com/free-trial/.

Step 1. Create and configure Okta single-page application

In this step, we will create and configure Netbird single-page application in okta.

• Navigate to Okta Admin Dashboard
• Click Applications in the left menu and then click on Applications
• Click Create App Integration
• Fill in the form with the following values and click Next
  • Sign-in method: OIDC - OpenID Connect
  • Application type: Single-Page Application

• Fill in the form with the following values and click Save
  • App integration name: Netbird
  • Grant type: Authorization Code and Refresh Token
  • Sign-in redirect URIs: https://<yournetbirddomain.com>/auth, https://<yournetbirddomain.com>/silent-auth and http://localhost:53000
  • Sign-out redirect URIs: https://<yournetbirddomain.com>/
• Click Save

• Navigate to Okta Admin Dashboard
• Click Applications in the left menu and then click on Applications
• Select Netbird application on the list and take a note of the Client ID, we will use it later
• Click on Sign On tab on top menu
• Under OpenID Connect ID Token section, click Edit and update Issuer to use the Okta URL
• Click Save

Step 2. Create and configure Okta native application

In this step, we will create and configure Netbird native application in okta.

• Navigate to Okta Admin Dashboard
• Click Applications in the left menu and then click on Applications
• Click Create App Integration
• Fill in the form with the following values and click Next
  • Sign-in method: OIDC - OpenID Connect
  • Application type: Native Application

• Fill in the form with the following values and click Save
  • App integration name: Netbird Native App
  • Grant type: Device Authorization
• Click Save

• Navigate to Okta Admin Dashboard
• Click Applications in the left menu and then click on Applications
• Select Netbird Native App application on the list and take a note of the Client ID, we will use it later
• Click on Sign On tab on top menu
• Under OpenID Connect ID Token section, click Edit and update Issuer to use the Okta URL
• Click Save

Step 3. Generate api token

In this step, we will generate netbird api token in okta for authorizing calls to user api.

• Navigate to Okta Admin Dashboard
• Click Security in the left menu and then click on API
• Click on Tokens tab on top menu
• Click Create token
• Fill in the form with the following values and click Create token
  • Name: Netbird
• Take note of token value and click OK, got it

Your authority OIDC configuration will be available under:

https://<YOUR_OKTA_ORGANIZATION_URL>/.well-known/openid-configuration

• Set properties in the setup.env file:

NETBIRD_DOMAIN="<YOUR_DOMAIN>"
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://<YOUR_OKTA_ORGANIZATION_URL>/.well-known/openid-configuration"
NETBIRD_USE_AUTH0=false
NETBIRD_AUTH_AUDIENCE="<<NETBIRD_CLIENT_ID>>"
NETBIRD_AUTH_CLIENT_ID="<NETBIRD_CLIENT_ID>"
NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email"
NETBIRD_AUTH_REDIRECT_URI="/auth"
NETBIRD_AUTH_SILENT_REDIRECT_URI="/silent-auth"
NETBIRD_TOKEN_SOURCE="idToken"

NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="hosted"
NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID="<NETBIRD_NATIVE_CLIENT_ID>>"
NETBIRD_AUTH_DEVICE_AUTH_AUDIENCE="<NETBIRD_NATIVE_CLIENT_ID>"
NETBIRD_AUTH_DEVICE_AUTH_SCOPE="openid email"
NETBIRD_AUTH_DEVICE_AUTH_USE_ID_TOKEN=true

NETBIRD_MGMT_IDP="okta"
NETBIRD_IDP_MGMT_EXTRA_API_TOKEN="<api_token>"

Step 4: Continue with the NetBird Self-hosting Guide

You've configured all required resources in Okta. You can now continue with the NetBird Self-hosting Guide.

Google Workspace

This guide is a part of the NetBird Self-hosting Guide and explains how to integrate self-hosted NetBird with Google Workspace.

Before you start creating and configuring an Google Workspace application, ensure that you have the following:

• An Google Workspace account: To create an Google Work application, you must have an Google Workspace. If you don't have one, sign up at https://workspace.google.com/business/signup/welcome.
• User account with admin permissions: You must have an Google Workspace user account with the admin permissions to create and manage Google Workspace applications. If you don't have the required permissions, ask your workspace administrator to grant them to you.
• Create new Netbird project in Google cloud console https://console.cloud.google.com.
• Enable Admin SDK API for Netbird project at https://console.cloud.google.com/apis/library/admin.googleapis.com.

Step 1: Configure OAuth consent screen

• Navigate to OAuth consent page
• Select Internal User Type and click create

• Fill in the form with the following values and click SAVE AND CONTINUE
  • App name: Netbird
  • User support email: <administrator email address>
  • Authorized domain: <your netbird domain>
  • Developer contact information: <developer email address>
• Click ADD OR REMOVE SCOPES
• Select /auth/userinfo.email, /auth/userinfo.profile and openid scopes and then click UPDATE

• Click SAVE AND CONTINUE
• Verify the summary of the OAuth consent screen to ensure that everything is properly configured, and then click BACK TO DASHBOARD

Step 2: Create OAuth 2.0 credentials

• Navigate to API Credentials page
• Click CREATE CREDENTIALS at the top and select OAuth client ID
• Fill in the form with the following values and click CREATE
  • Application type: Web application
  • Name: netbird
  • Authorized JavaScript origins: https://<your netbird domain> and http://localhost
  • Authorized redirect URIs: https://<your netbird domain>/auth, https://<your netbird domain>/silent-auth and http://localhost:53000

• Take note of Client ID and Client Secret and click OK

Step 3: Create service account

• Navigate to API Credentials page
• Click CREATE CREDENTIALS at the top and select Service account
• Fill in the form with the following values and click CREATE
  • Service account name: netbird
  • Service account ID: netbird
• Take note of service account email address, we will use it later
• Click DONE

Step 4: Create service account keys

• Navigate to API Credentials page
• Under Service Accounts click the netbird to edit the service account

• Click the Keys tab
• Click the Add key drop-down menu, then select Create new key
• Select JSON as the Key type and click Create

• Open downloaded json file and take note of client_id will be used later as Service Account Client ID

Step 5: Grant user management admin role to service account

• Navigate to Admin Console page
• Select Account on the left menu and then click Admin Roles
• Click Create new role
• Fill in the form with the following values and click CREATE
  • name: User Management ReadOnly
  • description: User Management ReadOnly
• Click CONTINUE

• Scroll down to Admin API privileges and add the following privileges
  • Users: Read
• Click CONTINUE

• Verify preview of assigned Admin API privileges to ensure that everything is properly configured, and then click CREATE ROLE
• Click Assign service accounts, add service account email address and then click ADD

• Click ASSIGN ROLE to assign service account to User Management ReadOnly role

• Navigate to Account Settings page and take note of Customer ID

• Encode service account json key into base64 format

  base64 -i <SERVICE_ACCOUNT_KEY_PATH>
  

  CopyCopied!

• Set properties in the setup.env file:

NETBIRD_DOMAIN="<YOUR_DOMAIN>"
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://accounts.google.com/.well-known/openid-configuration"
NETBIRD_USE_AUTH0=false
NETBIRD_AUTH_AUDIENCE="<OAUTH_CLIENT_ID>"
NETBIRD_AUTH_CLIENT_ID="<OAUTH_CLIENT_ID>"
NETBIRD_AUTH_CLIENT_SECRET="<OAUTH_CLIENT_SECRET>"
NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email"
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="google"
NETBIRD_MGMT_IDP_SIGNKEY_REFRESH=true
NETBIRD_IDP_MGMT_EXTRA_SERVICE_ACCOUNT_KEY="<BASE64_SERVICE_ACCOUNT_KEY>"
NETBIRD_IDP_MGMT_EXTRA_CUSTOMER_ID="<GOOGLE_WORKSPACE_CUSTOMER_ID>"

Step 6: Continue with the NetBird Self-hosting Guide

You've configured all required resources in Google Workspace. You can now continue with the NetBird Self-hosting Guide.

Auth0

This guide is a part of the NetBird Self-hosting Guide and explains how to integrate self-hosted NetBird with Auth0.

Auth0 is a flexible, drop-in solution to add authentication and authorization services to your applications. It is a 3rd party managed service and can't be self-hosted. Auth0 is the right choice if you don't want to manage an Identity Provider (IDP) instance on your own.

Step 1: Create Auth0 account

To create an Auth0 account, sign up at https://auth0.com.

There are multiple properties of the setup.env file that we will configure in this guide:

• NETBIRD_AUTH_CLIENT_ID
• NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT
• NETBIRD_USE_AUTH0
• NETBIRD_AUTH_AUDIENCE
• NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID (Optional)
• NETBIRD_MGMT_IDP
• NETBIRD_IDP_MGMT_CLIENT_ID
• NETBIRD_IDP_MGMT_CLIENT_SECRET
• NETBIRD_IDP_MGMT_EXTRA_AUDIENCE

Step 2: Create and configure Auth0 application

This Auth0 application will be used to authorize access to NetBird Dashboard (Web UI).

• Follow the steps in the Auth0 React SDK Guide up until "Install the Auth0 React SDK".
• Use https://YOUR DOMAIN and http://localhost:53000 as: Allowed Callback URLs,
• Use https://YOUR DOMAIN and http://localhost as: Allowed Logout URLs, Allowed Web Origins, Allowed Origins (CORS)

• Use Client ID to set NETBIRD_AUTH_CLIENT_ID property in the setup.env file.
• Use Domain to configure NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT property in the setup.env file like so:

 https://<DOMAIN>/.well-known/openid-configuration

Step 3: Create and configure Auth0 API

This Auth0 API will be used to access NetBird Management Service API.

• Follow the steps in the Auth0 Create An API.
• Use API Identifier to set NETBIRD_AUTH_AUDIENCE property in the setup.env file.
• Set NETBIRD_USE_AUTH0 to truein the setup.env file.

Step 4: Enable Interactive SSO Login (Optional)

The Interactive SSO Login feature allows for machine authorization with your Identity Provider. This feature can be used as an alternative to setup keys and is optional.

You can enable it by following these steps:

• Log in to your Auth0 account https://manage.auth0.com/
• Go to Applications (left-hand menu)
• Click Create Application button (top right)
• Fill in the form with the following values:
  • Name: Interactive Login
  • Application type: Native
• Click Create

• Click Settings tab
• Copy Client ID to NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID in the setup.env file

• Scroll down to the Advanced Settings section
• Enable Device Code
• Click Save Changes

Step 5: Create and configuire Machine to Machine application.

This application will be used to authorize access to Auth0 Management API.

• Log in to your Auth0 account https://manage.auth0.com/
• Go to Applications (left-hand menu)
• Click Create Application button (top right)
• Fill in the form with the following values:
  • Name: Netbird API
  • Application type: Machine to Machine Applications
• Click Create

• Fill the form with the following values:
  • API: Auth0 Management API
  • Permissions: read:users, update:users, create:users, read:users_app_metadata, update:users_app_metadata, create:users_app_metadata
  • Click Authorize

• Click Settings tab
• Copy Client ID to NETBIRD_IDP_MGMT_CLIENT_ID in the setup.env file
• Copy Client SECRET to NETBIRD_IDP_MGMT_CLIENT_SECRET in the setup.env file
• Copy DOMAIN to NETBIRD_IDP_MGMT_EXTRA_AUDIENCE in the setup.env file

• Set properties in the setup.env file:

NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://<DOMAIN>/.well-known/openid-configuration"
NETBIRD_USE_AUTH0=true
NETBIRD_AUTH_CLIENT_ID="<Client_ID>"
NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access api email_verified"
NETBIRD_AUTH_AUDIENCE="<IDENTIFIER>"
NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID="<INTERACTIVE_CLIENT_ID>"

NETBIRD_MGMT_IDP="auth0"
NETBIRD_IDP_MGMT_CLIENT_ID="<NETBIRD_API_CLIENT_ID>"
NETBIRD_IDP_MGMT_CLIENT_SECRET="<NETBIRD_API_CLIENT_SECRET>"
NETBIRD_IDP_MGMT_EXTRA_AUDIENCE="https://<DOMAIN>/api/v2/"

Step 6: Continue with the NetBird Self-hosting Guide

You've configured all required resources in Auth0. You can now continue with the NetBird Self-hosting Guide.

JumpCloud

This guide is a part of the NetBird Self-hosting Guide and explains how to integrate self-hosted NetBird with JumpCloud.

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.

Step 1: Create and configure SSO application

• Navigate to to Admin Portal page
• Click SSO Applications on the left menu under USER AUTHENTICATION section
• Click Add New Application and select Custom Application

• On the Which application would you like to integrate screen, confirm that you've selected Custom application and click Next

• 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

• On the Enter General info screen, add NetBird as Display Label and click Next

• On the confirmation screen, review the information and click on Configure Application to proceed

• 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>

• Under Attribute Mapping (optional) section:
  • Standard Scopes: Email, Profile

• Click on the User Groups tab and select the user groups that can access this application

• Click Activate

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

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

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.

Step 3: Generate api token

In this step, we will generate netbird api token in jumpcloud for authorizing calls to user api.

• Navigate to to Admin Portal 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

• If there is no API key generated, click on Generate New API Key button
• Take note of your api token displayed

• Set properties in the setup.env file:

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