sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-04-16 07:26:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Embedded DEX and IdP Docs (#533)

Browse Source 
* DEX Docs Overall Updates

* No IdP required, Multiple IdPs supported, Onboarding flow

* File Name Change

* Add Announcement

* Specify that Embedded IdP is Recommended

* Condense Pages to index.mdx and Extra Remove Idp Info Quickstart

* Fix Links

* Remove API Reference

* Remove Gap

* Remove API Changes

* Update Quickstart

* New Local Page and Fixes

* Fixing Gaps

* Update idp doc

* Update quickstart

* Minor changes and banner

* Fix Broken Links

* Remove Password Reset

---------

Co-authored-by: braginini <bangvalo@gmail.com>
This commit is contained in:
Brandon Hopkins
2026-01-07 10:26:54 -08:00
committed by GitHub
parent c75d0884e8
commit de7571f552
25 changed files with 2673 additions and 952 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
src/components/NavigationDocs.jsx
View File

@@ -279,31 +279,16 @@ export const docsNavigation = [
{ title: 'Profiles', href: '/client/profiles' },
],
},
{
title: 'USE CASES',
links: [
{ title: 'Site-to-Site and Site-to-VPN', href: '/use-cases/setup-site-to-site-access' },
{ title: 'Serverless and NetBird', href: '/use-cases/netbird-on-faas' },
{ title: 'Routing peers and Kubernetes', href: '/use-cases/routing-peers-and-kubernetes' },
{ title: 'NetBird Client on AWS ECS', href: '/use-cases/examples' },
{ title: 'NetBird on Mikrotik Router', href: '/use-cases/client-on-mikrotik-router' },
{ title: 'Distributed AI on Kubernetes', href: '/use-cases/distributed-multi-cloud-ai-argocd-microk8s-vllm' },
{ title: 'Self-hosted vs. Cloud-hosted NetBird', href: '/selfhosted/self-hosted-vs-cloud-netbird' },
],
},
{
title: 'SELF-HOST NETBIRD',
links: [
{ title: 'Quickstart guide', href: '/selfhosted/selfhosted-quickstart' },
{ title: 'Advanced guide', href: '/selfhosted/selfhosted-guide' },
{ title: 'Management SQLite Store', href: '/selfhosted/sqlite-store' },
{ title: 'Management Postgres Store', href: '/selfhosted/postgres-store' },
{ title: 'Activity Events Postgres Store', href: '/selfhosted/activity-postgres-store' },
{ title: 'Quickstart Guide', href: '/selfhosted/selfhosted-quickstart' },
{
title: 'Supported IdPs',
title: 'Authentication',
isOpen: false,
links: [
{ title: 'Using IdPs on Self-Hosted', href: '/selfhosted/identity-providers' },
{ title: 'Authentication and IdPs', href: '/selfhosted/identity-providers' },
{ title: 'Local User Management', href: '/selfhosted/identity-providers/local' },
{
title: 'Self-hosted IdPs',
isOpen: true,
@@ -327,10 +312,26 @@ export const docsNavigation = [
},
]
},
{ title: 'Advanced guide', href: '/selfhosted/selfhosted-guide' },
{ title: 'Management SQLite Store', href: '/selfhosted/sqlite-store' },
{ title: 'Management Postgres Store', href: '/selfhosted/postgres-store' },
{ title: 'Activity Events Postgres Store', href: '/selfhosted/activity-postgres-store' },
{ title: 'Management geolocation', href: '/selfhosted/geo-support' },
{ title: 'Troubleshooting', href: '/selfhosted/troubleshooting' },
],
},
{
title: 'USE CASES',
links: [
{ title: 'Site-to-Site and Site-to-VPN', href: '/use-cases/setup-site-to-site-access' },
{ title: 'Serverless and NetBird', href: '/use-cases/netbird-on-faas' },
{ title: 'Routing peers and Kubernetes', href: '/use-cases/routing-peers-and-kubernetes' },
{ title: 'NetBird Client on AWS ECS', href: '/use-cases/examples' },
{ title: 'NetBird on Mikrotik Router', href: '/use-cases/client-on-mikrotik-router' },
{ title: 'Distributed AI on Kubernetes', href: '/use-cases/distributed-multi-cloud-ai-argocd-microk8s-vllm' },
{ title: 'Self-hosted vs. Cloud-hosted NetBird', href: '/selfhosted/self-hosted-vs-cloud-netbird' },
],
},
{
title: 'GET MORE HELP',
links: [

10
src/components/announcement-banner/AnnouncementBannerProvider.jsx
View File

@@ -12,11 +12,11 @@ import { useLocalStorage } from '@/hooks/useLocalStorage'
const BANNER_ENABLED = true
export const announcement = {
tag: '',
text: 'NetBird v0.60 Released - Native SSH Access',
link: '/manage/peers/ssh',
linkText: 'Read Release Documentation',
linkAlt: 'Learn more about the NetBird v0.60 release',
tag: 'New',
text: 'Simplified IdP Integration',
link: '/selfhosted/identity-providers',
linkText: 'Learn More',
linkAlt: 'Learn more about the embedded Identity Provider powered by DEX for self-hosted installations',
isExternal: false,
closeable: true,
}

272
src/pages/selfhosted/identity-providers/authentik.mdx
View File

@@ -1,135 +1,194 @@
import {Note} from "@/components/mdx";
# Authentik with NetBird Self-Hosted
# Authentik
This guide is a part of the [NetBird Self-hosting Guide](/docs/selfhosted/selfhosted-guide) and explains how to integrate
**self-hosted** NetBird with [Authentik](https://goauthentik.io).
[Authentik](https://goauthentik.io) is an open-source identity provider focused on flexibility and security. It serves as a self-hosted alternative to commercial solutions like Okta and Auth0, providing single sign-on (SSO), multi-factor authentication (MFA), access policies, user management, and support for SAML and OIDC protocols.
## Connector Setup (Recommended)
Add Authentik 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
- Authentik instance with admin access
### Step 1: Create OAuth2/OpenID Provider in Authentik
1. Navigate to Authentik admin interface
2. Click **Applications** on the left menu, then click **Providers**
3. Click **Create** to create a new provider
4. Select **OAuth2/OpenID Provider** and click **Next**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-new-provider-type.png" alt="Select provider type" className="imagewrapper-big"/>
</p>
5. Fill in the form with the following values:
- **Name**: `NetBird`
- **Authentication Flow**: `default-authentication-flow (Welcome to authentik!)`
- **Authorization Flow**: `default-provider-authorization-explicit-consent (Authorize Application)`
- **Client type**: `Confidential`
- **Redirect URIs/Origins**: Leave empty for now (you'll add this after creating the connector in NetBird)
- **Signing Key**: Select any cert present, e.g., `authentik Self-signed Certificate`
6. Click **Finish**
7. Note the **Client ID** and **Client Secret**
### Step 2: Create Application in Authentik
1. Click **Applications** on the left menu, then click **Applications**
2. Click **Create** to create a new application
3. Fill in the form:
- **Name**: `NetBird`
- **Slug**: `netbird`
- **Provider**: Select the `NetBird` provider you created
4. Click **Create**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-new-application.png" alt="Create application" className="imagewrapper-big"/>
</p>
### Step 3: 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 | Authentik (or your preferred display name) |
| Client ID | From Authentik provider |
| Client Secret | From Authentik provider |
| Issuer | `https://authentik.example.com/application/o/netbird/` |
5. Click **Save**
### Step 4: Configure Redirect URI
After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your Authentik provider:
1. Return to Authentik admin → **Providers** → **NetBird**
2. Click **Edit**
3. Under **Redirect URIs/Origins**, add the redirect URL from NetBird
4. Click **Update**
### Step 5: Test the Connection
1. Log out of NetBird Dashboard
2. On the login page, you should see an "Authentik" button
3. Click it and authenticate with your Authentik credentials
4. You should be redirected back to NetBird and logged in
---
## Standalone Setup (Advanced)
Use Authentik 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 Authentik administrators as it also requires additional setup and ongoing maintenance.
For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) 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.
<Note>
If you prefer not to self-host an Identity and Access Management solution, then you could use a managed alternative like
[Auth0](/selfhosted/identity-providers#auth0).
If you prefer not to self-host an Identity and Access Management solution, you could use a managed alternative like [Auth0](/selfhosted/identity-providers/managed/auth0).
</Note>
## Step 1: Create OAuth2/OpenID Provider
In this step, we will create OAuth2/OpenID Provider in Authentik.
### Prerequisites
- 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`
- Authentik instance running with SSL
- Docker and Docker Compose installed for NetBird
### Step 1: Create OAuth2/OpenID Provider
Follow steps 1-2 from the connector setup above, but configure the provider as follows:
- **Client type**: `Public`
- **Redirect URIs/Origins (RegEx)**:
- Regex: `https://<domain>/.*`
- Strict: `http://localhost:53000`
- **Advanced protocol settings**:
- Access code validity: `minutes=10`
- Subject mode: `Based on the User's ID`
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-new-provider-type.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-new-provider-config.png" alt="Provider configuration" className="imagewrapper-big"/>
</p>
- 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):
- Regex: `https://<domain>/.*`
- Strict: `http://localhost:53000`
- 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** for later use.
Take note of `Client ID`, we will use it later
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-new-provider-config.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
### Step 2: Create Application
## Step 2: Create external applications
In this step, we will create external applications in Authentik.
Follow step 2 from the connector setup to create the NetBird application.
- 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
1. Navigate to Authentik admin interface
2. Click **Directory** on the left menu, then click **Users**
3. Click **Create Service Account**
4. Fill in the form:
- **Username**: `Netbird`
- **Create Group**: Disable
5. Click **Create**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-new-application.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-new-service-account.png" alt="Create service account" className="imagewrapper-big"/>
</p>
## Step 3: Create service account
In this step, we will create service account.
6. Note the service account username
7. Create an app password: Go to **Directory** → **Tokens and App passwords**
8. Create a new app password, selecting the NetBird service account as the **User**
9. Save the app password for later use
- 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`
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-new-service-account.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
### Step 4: Add Service Account to Admin Group
- Take note of the NetBird service account `username`, we will need it later.
- N.B. The `password` defined when creating the NetBird service account is not required.
Users should instead create an app password for the NetBird service account within `Directory > Tokens and App passwords` in authentik's `Admin interface.
Be sure to select the NetBird Service account object as the `User` when creating the app password.
Take note of the app password as we will need it later.
1. Click **Directory** on the left menu, then click **Groups**
2. Click **authentik Admins** from the list and select **Users** tab
3. Click **Add existing user** and click **+** button
4. Select **Netbird** and click **Add**
5. Disable **Hide service-accounts** and verify the user is added
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-service-account-details.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-add-user-group.png" alt="Add user to group" className="imagewrapper-big"/>
</p>
## Step 4: Add service account to admin group
In this step, we will add `Netbird` service account to `authentik Admins` group.
### Step 5: Create Device Code Flow
- 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
1. Click **Flows and Stages** on the left menu, then click **Flows** → **Create**
2. Fill in the form:
- **Name**: `default-device-code-flow`
- **Title**: `Device Code Flow`
- **Designation**: `Stage Configuration`
- **Authentication**: `Require authentication`
3. Click **Create**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-add-user-group.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-new-device-flow.png" alt="Create device flow" className="imagewrapper-big"/>
</p>
#### 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`
4. Click **System** on the left menu, then click **Brands**
5. Click edit on **authentik-default**
6. Under **Default flows**, set **Device code flow** to `default-device-code-flow`
7. Click **Update**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-new-device-flow.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-brand-device-flow.png" alt="Configure brand device flow" className="imagewrapper-big"/>
</p>
- 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`
### Step 6: Configure NetBird
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-brand-device-flow.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
Your authority OIDC configuration will be available under:
Your authority OIDC configuration will be available at:
```bash
https://< YOUR_AUTHENTIK_HOST_AND_PORT >/application/o/netbird/.well-known/openid-configuration
https://<YOUR_AUTHENTIK_HOST_AND_PORT>/application/o/netbird/.well-known/openid-configuration
```
<Note>
Double-check if the endpoint returns a JSON response by calling it from your browser.
</Note>
- Set properties in the `setup.env` file:
Set properties in the `setup.env` file:
```shell
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://<YOUR_AUTHENTIK_HOST_AND_PORT>/application/o/netbird/.well-known/openid-configuration"
NETBIRD_USE_AUTH0=false
@@ -146,10 +205,37 @@ 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)
# Needs disabling due to issue with IdP. Learn more: 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](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
### Step 7: Continue with NetBird Setup
You've configured all required resources in Authentik. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
---
## Troubleshooting
### "Invalid redirect URI" error
- Ensure the redirect URI exactly matches what NetBird provides
- For connector setup: Copy the exact URL from the success modal
- For standalone: Use regex pattern `https://<domain>/.*`
### Authentication fails silently
- Verify a signing key is selected in the provider configuration
- Check that the application is linked to the correct provider
### Service account authentication fails
- Ensure you're using the app password, not the account password
- Verify the service account is in the authentik Admins group
---
## Related Resources
- [Authentik Documentation](https://goauthentik.io/docs/)
- [Embedded IdP Overview](/selfhosted/identity-providers/local)

204
src/pages/selfhosted/identity-providers/index.mdx
View File

@@ -1,90 +1,200 @@
import { Note, Button } from '@/components/mdx'
import {Note} from "../../../components/mdx";
# Supported Identity Providers (IdPs)
# Authentication and Identity Providers (IdPs)
NetBird’s self-hosted implementation (Community Edition) uses the OpenID Connect (OIDC) protocol for authentication, an
industry-standard identity layer built on top of OAuth 2.0. OIDC is used both for user authentication to access the
Management Service Dashboard and for user device authorization when accessing internal resources.
<p>
<img src="/docs-static/img/selfhosted/identity-providers/idp-main.png" alt="Identity Providers List" className="imagewrapper-big"/>
</p>
There are several Identity Provider (IdP) options available for running a self-hosted version of NetBird. This document provides
an overview of each option along with links to detailed setup guides.
NetBird's self-hosted implementation uses the OpenID Connect (OIDC) protocol for authentication, an industry-standard
identity layer built on top of OAuth 2.0. OIDC is used both for user authentication to access the Management Service
Dashboard and for user device authorization when accessing internal resources.
## How Authentication Works in NetBird
When a user attempts to access the NetBird dashboard from a web browser or an internal resource from their device,
authentication is handled by the configured identity provider. Upon successful authentication, the identity provider
issues a [JSON Web Token (JWT)](https://en.wikipedia.org/wiki/JSON_Web_Token) containing the user's identity and claims. The Management Service validates this token to
verify the user's identity and grant access.
By default, NetBird does not require an external identity provider. New installations include a built-in authentication
system that lets you create and manage users directly through the Dashboard using local username and password authentication.
External identity providers are entirely optional. Add them when you need SSO integration with Google, Microsoft, Okta, or
self-hosted identity providers like Keycloak or Authentik, and more.
## Local User Management
Refer to the [Local User Management](/selfhosted/identity-providers/local) page for detailed instructions on using local users
authentication.
## External Identity Providers
NetBird supports connecting **multiple external identity providers** [alongside local user management](/selfhosted/identity-providers/local).
This allows users to sign in with their existing accounts from services like Google, Microsoft and your corporate or self-hosted identity
provider, while still maintaining the option for local username/password authentication.
NetBird supports any OIDC-compliant identity providers. Here are some popular providers and their setup instructions:
| Provider | Type | Best For |
|----------|------|----------|
| [**Generic OIDC**](#adding-external-identity-providers) | `oidc` | Any OIDC-compliant provider |
| [**Google**](/selfhosted/identity-providers/managed/google-workspace) | `google` | Google Workspace, personal Google accounts |
| [**Microsoft**](/selfhosted/identity-providers/managed/microsoft-entra-id) | `microsoft` / `entra` | Personal accounts, Azure AD / Entra ID |
| [**Okta**](/selfhosted/identity-providers/managed/okta) | `okta` | Enterprise SSO |
| [**Zitadel**](/selfhosted/identity-providers/zitadel) | `zitadel` | Open-source IAM with multi-tenancy and passwordless auth |
| [**Keycloak**](/selfhosted/identity-providers/keycloak) | `keycloak` | Popular open source IAM with extensive enterprise features |
| [**Authentik**](/selfhosted/identity-providers/authentik) | `authentik` | Flexible open source IdP with SSO, MFA, and policy engine |
| [**Pocket ID**](/selfhosted/identity-providers/pocketid) | `pocketid` | Lightweight OIDC provider with passkey authentication |
<Note>
In addition to OIDC-based authentication, NetBird supports provisioning users and groups through SCIM and the API.
However, this functionality is not available in the open source Community Edition. It is offered only in the cloud-managed
version of NetBird or through a [Commercial License](https://netbird.io/pricing#on-prem) for enterprise self-hosted deployments.
Any identity provider that supports OpenID Connect can be integrated with NetBird. If your provider isn't listed above,
use the generic OIDC configuration.
</Note>
## Our Approach
### Adding an Identity Provider
When a user attempts to access the NetBird network, the Management Service redirects them to your configured Identity Provider for authentication. After successful authentication, the IdP issues a JSON Web Token (JWT) that contains the user's identity and claims. NetBird's Management Service validates this token and uses it to authenticate the user without ever storing passwords or sensitive credentials.
#### Via Dashboard
This approach provides several key benefits: it leverages your existing identity infrastructure, enables Single Sign-On (SSO) across your organization, maintains security through token-based authentication, and allows NetBird to cache user information like names and email addresses without storing sensitive data.
<p>
<img src="/docs-static/img/selfhosted/identity-providers/idp-list.png" alt="Identity Providers List" className="imagewrapper-big"/>
</p>
## Self-hosted IdPs
1. Log in to your NetBird Dashboard
2. Navigate to **Settings** → **Identity Providers**
3. Click **Add Identity Provider**
4. Select your provider type from the dropdown
5. Configure the required fields:
- **Name** - Display name for the login button
- **Client ID** - From your identity provider
- **Client Secret** - From your identity provider
- **Issuer** - From your identity provider
6. Copy the **Redirect URL** and configure it in your identity provider
7. Click **Save**
Self-hosted Identity Providers give you full control over authentication and authorization of your NetBird network. You manage and maintain the IdP infrastructure yourself.
<Note>
Make sure you are creating a confidential OIDC client in your identity provider. The secret will be stored privately in
your NetBird installation and will never be exposed to the public.
</Note>
### Zitadel
<p>
<img src="/docs-static/img/selfhosted/identity-providers/add-idp.png" alt="Identity Providers List" className="imagewrapper-big"/>
</p>
[Zitadel](https://github.com/zitadel/zitadel) is an open-source identity infrastructure platform designed for cloud-native environments. It provides multi-tenancy, customizable branding, passwordless authentication, and supports protocols like OpenID Connect, OAuth2, SAML2, and LDAP. Zitadel offers features such as passkeys (FIDO2), OTP, SCIM 2.0 server, and unlimited audit trails.
#### Via API
<Button href="/selfhosted/identity-providers/zitadel" variant="outline">Setup Zitadel</Button>
```bash
curl -X POST "https://netbird.example.com/api/identity-providers" \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"type": "oidc",
"name": "My SSO Provider",
"client_id": "your-client-id",
"client_secret": "your-client-secret",
"issuer": "https://sso.example.com"
}'
```
### Authentik
For instance setup endpoints, see [Accounts API](/api/resources/accounts). For user creation with embedded IdP, see [Users API](/api/resources/users).
[Authentik](https://github.com/goauthentik/authentik) is an open-source identity provider focused on flexibility and security. It serves as a self-hosted alternative to commercial solutions like Okta and Auth0, providing single sign-on (SSO), multi-factor authentication (MFA), access policies, user management, and support for SAML and OIDC protocols. Authentik includes audit logging, password policies, and full API access for automation.
### Managing Identity Providers via API
<Button href="/selfhosted/identity-providers/authentik" variant="outline">Setup Authentik</Button>
```bash
# List configured identity providers
curl "https://netbird.example.com/api/identity-providers" \
-H "Authorization: Bearer ${TOKEN}"
### Keycloak
# Update an identity provider
curl -X PUT "https://netbird.example.com/api/identity-providers/{id}" \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"name": "Updated Name"
}'
[Keycloak](https://github.com/keycloak/keycloak) is an open-source Identity and Access Management solution aimed at modern applications and services. It's one of the most popular self-hosted IdP solutions with extensive documentation and community support. Keycloak provides single sign-on, social login, user federation, fine-grained authorization, and supports OpenID Connect, OAuth 2.0, and SAML 2.0 protocols.
# Delete an identity providers
curl -X DELETE "https://netbird.example.com/api/identity-providers/{id}" \
-H "Authorization: Bearer ${TOKEN}"
```
<Button href="/selfhosted/identity-providers/keycloak" variant="outline">Setup Keycloak</Button>
### How It Works
### PocketID
1. User clicks the provider button on the login page
2. User is redirected to the identity provider to authenticate
3. After successful authentication, user is redirected back to NetBird
4. NetBird validates the token and creates/updates the user account
5. User is logged in and can access the Dashboard
[PocketID](https://pocket-id.org/) is a simplified identity management solution designed for self-hosted environments. It provides authentication and authorization services with a focus on security and effectiveness, making it a lightweight and easy-to-deploy option for organizations seeking a straightforward identity management solution.
Users who authenticate via an external identity provider appear in your Users list with a badge showing their identity provider.
<Button href="/selfhosted/identity-providers/pocketid" variant="outline">Setup PocketID</Button>
<p>
<img src="/docs-static/img/selfhosted/identity-providers/user-list.png" alt="Identity Providers List" className="imagewrapper-big"/>
</p>
## Managed IdPs
### Multiple Identity Providers
Managed Identity Providers are third-party cloud services that handle the infrastructure and maintenance of your identity provider. These are ideal if you don't want to manage an IdP instance yourself.
You can configure **multiple identity providers simultaneously**:
### Microsoft Entra ID
- All configured providers appear as buttons on the login page
- "Continue with Email" (local authentication) is always available first
- Users can authenticate with any configured provider
- Each user's provider is tracked and displayed in the Dashboard
[Microsoft Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id) (formerly Azure AD) is an enterprise identity service that provides single sign-on and multifactor authentication to your applications. It's a managed service that integrates seamlessly with Microsoft's ecosystem, offering conditional access policies, identity protection, and privileged identity management. Ideal for organizations already using Microsoft services.
This allows you to support different authentication methods for different user groups.
<Button href="/selfhosted/identity-providers/managed/microsoft-entra-id" variant="outline">Setup Microsoft Entra ID</Button>
<p>
<img src="/docs-static/img/selfhosted/identity-providers/idp-login.png" alt="Multiple Identity Providers" className="imagewrapper"/>
</p>
### Okta
### Best Practices
[Okta](https://www.okta.com/) is a cloud-based identity and access management service designed for enterprise use. It provides single sign-on, multifactor authentication, user management, and lifecycle management capabilities. Okta offers extensive integration options with thousands of pre-built connectors, adaptive authentication, and comprehensive API access management.
1. **Start simple** - Begin with local users, add external providers as needed
2. **Test thoroughly** - Verify the provider works before announcing to users
3. **Communicate changes** - Let users know about new login options
4. **Keep a fallback** - Local authentication remains available if an external provider has issues
<Button href="/selfhosted/identity-providers/managed/okta" variant="outline">Setup Okta</Button>
### Troubleshooting
### Google Workspace
#### Provider not appearing on login page
[Google Workspace](https://workspace.google.com/) (formerly G Suite) provides identity management through Google's cloud infrastructure. It offers single sign-on capabilities, multi-factor authentication, and seamless integration with Google services. It's an excellent choice for organizations already using Google Workspace for their business operations, providing unified identity across Google and third-party applications.
- Verify the provider was saved successfully in Settings → Identity Providers
- Check that the provider is enabled
- Clear browser cache and reload the login page
<Button href="/selfhosted/identity-providers/managed/google-workspace" variant="outline">Setup Google Workspace</Button>
#### "Invalid redirect URI" error
### JumpCloud
- Copy the exact Redirect URL from NetBird after creating the provider
- Ensure no trailing slashes or typos
- Some providers are case-sensitive
[JumpCloud](https://jumpcloud.com/) is a cloud-based directory platform that provides identity, access, and device management in a unified solution. It offers single sign-on, multi-factor authentication, directory services, device management, and network access control. JumpCloud provides a comprehensive approach to managing users, devices, and applications from a single platform.
#### Authentication succeeds but user not created
<Button href="/selfhosted/identity-providers/managed/jumpcloud" variant="outline">Setup JumpCloud</Button>
- Check Management service logs for errors
- Verify the token contains required claims (email, name)
- Ensure the user's email domain is not blocked by any policies in your IdP. Some providers like Pocket ID block all users by default unless you unrestrict groups in the OIDC client configuration.
### Keycloak (Managed)
#### External connector not working
[Keycloak](https://www.keycloak.org/) can also be deployed as a managed service through various cloud providers, providing the same open-source features with the convenience of cloud hosting and management. This option offers the flexibility and features of Keycloak without the operational overhead of self-hosting.
1. Verify Client ID and Secret are correct
2. Check redirect URIs are properly configured in the external IdP
3. Review Management logs for OIDC/SAML errors
<Button href="/selfhosted/identity-providers/managed/keycloak" variant="outline">Setup Keycloak</Button>
For provider-specific troubleshooting, see the individual provider pages.
### Auth0
## User Provisioning (SCIM)
[Auth0](https://auth0.com/) is a flexible, drop-in solution to add authentication and authorization services to your applications. It's a managed service that's ideal if you don't want to manage an Identity Provider instance on your own. Auth0 offers extensive customization options, developer-friendly APIs, universal login, social identity providers, and advanced security features like anomaly detection and breached password detection.
In addition to OIDC-based authentication, NetBird supports provisioning users and groups through SCIM.
However, this functionality is not available in the open source Community Edition. It is offered only in the cloud-managed version of NetBird or through a [Commercial License](https://netbird.io/pricing#on-prem) for enterprise self-hosted deployments.
<Button href="/selfhosted/identity-providers/managed/auth0" variant="outline">Setup Auth0</Button>
## Migration Guide and Backwards Compatibility
If you have an existing NetBird deployment using a standalone IdP (like Zitadel from the previous quickstart), you have several options:
1. **Keep using your standalone IdP** - No changes required, your setup continues to work
2. **Add your IdP as an external provider** - Keep your IdP but add it as an OIDC provider alongside local users.
This option requires a migration as user IDs have a different format. See below.
<Note>
We are working on a migration tool to automate the process of switching from standalone IdPs to external providers.
Please contact us at [](mailto:support@netbird.io) if you are interested in this feature.
</Note>

376
src/pages/selfhosted/identity-providers/keycloak.mdx
View File

@@ -1,265 +1,323 @@
import {Note} from "@/components/mdx";
# Keycloak with NetBird Self-Hosted
# Keycloak
This guide is a part of the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide) and explains how to integrate
**self-hosted** NetBird with [Keycloak](https://www.keycloak.org/).
[Keycloak](https://www.keycloak.org/) is an open-source Identity and Access Management solution maintained by Red Hat. It provides single sign-on, social login, user federation, fine-grained authorization, and supports OpenID Connect, OAuth 2.0, and SAML 2.0 protocols.
Keycloak is an open source software product to allow single sign-on with Identity and Access Management aimed at modern applications and services.
## Connector Setup (Recommended)
Add Keycloak 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
- Keycloak instance running with SSL
### Step 1: Create Client in Keycloak
1. Open the Keycloak Admin Console
2. Select your realm (or create a new one, e.g., `netbird`)
3. Click **Clients** → **Create client**
4. Fill in the form:
- **Client type**: `OpenID Connect`
- **Client ID**: `netbird`
5. Click **Next**
6. On Capability config:
- Enable **Client authentication**
7. Click **Next**
8. On Login settings:
- Leave redirect URIs empty for now
9. Click **Save**
10. Go to the **Credentials** tab and copy the **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 | Keycloak (or your preferred display name) |
| Client ID | `netbird` (from Step 1) |
| Client Secret | From Keycloak Credentials tab |
| Issuer | `https://keycloak.example.com/realms/your-realm` |
5. Click **Save**
### Step 3: Configure Redirect URI
After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your Keycloak client:
1. Return to Keycloak Admin Console
2. Go to your client → **Settings** tab
3. Under **Valid redirect URIs**, add the redirect URL from NetBird
4. Click **Save**
### Step 4: Test the Connection
1. Log out of NetBird Dashboard
2. On the login page, you should see a "Keycloak" button
3. Click it and authenticate with your Keycloak credentials
4. You should be redirected back to NetBird and logged in
<Note>
If you prefer not to self-host an Identity and Access Management solution, then you could use a managed alternative like
[Auth0](/selfhosted/identity-providers#auth0).
Users who authenticate via Keycloak will appear in your NetBird Users list with a Keycloak badge next to their name.
</Note>
The following guide is an adapted version of the original
[Keycloak on Docker](https://www.keycloak.org/getting-started/getting-started-docker) guide from the official website.
---
## Expected Result
## Standalone Setup (Advanced)
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](/get-started/install#running-net-bird-with-sso-login)
over Keycloak.
Use Keycloak 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 Keycloak administrators as it also requires additional setup and ongoing maintenance.
For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) 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.
<Note>
If you prefer not to self-host an Identity and Access Management solution, you could use a managed alternative like [Auth0](/selfhosted/identity-providers/managed/auth0).
</Note>
### Expected Result
After completing this guide, you can log in to your self-hosted NetBird Dashboard and add machines to your network using the [Interactive SSO Login feature](/get-started/install#running-net-bird-with-sso-login) over Keycloak.
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-auth-grant.gif" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-auth-grant.gif" alt="Keycloak auth flow" className="imagewrapper-big"/>
</p>
## Step 1: Check your Keycloak Instance
### Prerequisites
For this guide, you need a fully configured Keycloak instance running with SSL.
- Keycloak instance running with SSL
- Docker and Docker Compose for NetBird
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.
### Step 1: Check Your Keycloak Instance
Most of the OIDC software requires SSL for production use.
We encourage you to comply with this requirement to make the world more secure 😊.
Ensure your Keycloak instance is available at `https://YOUR-KEYCLOAK-HOST-AND-PORT` with SSL enabled.
## Step 2: Create a realm
### 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`
1. Open the Keycloak Admin Console
2. Hover over the dropdown in the top-left corner where it says `Master`
3. Click **Create Realm**
4. Fill in:
- **Realm name**: `netbird`
5. Click **Create**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-create-realm.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-create-realm.png" alt="Create realm" className="imagewrapper-big"/>
</p>
### Step 3: Create a User
## 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`
1. Make sure the selected realm is `netbird`
2. Click **Users** (left-hand menu)
3. Click **Create new user**
4. Fill in:
- **Username**: `netbird`
5. Click **Create**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-create-user.png" alt="high-level-dia" className="imagewrapper"/>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-create-user.png" alt="Create user" className="imagewrapper"/>
</p>
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`
6. Click **Credentials** tab
7. Click **Set password**
8. Fill in the password and set **Temporary** to `Off`
9. Click **Save**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-set-password.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-set-password.png" alt="Set password" className="imagewrapper-big"/>
</p>
## Step 4: Create a NetBird client
### Step 4: Create 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`
1. Click **Clients** → **Create client**
2. Fill in:
- **Client Type**: `OpenID Connect`
- **Client ID**: `netbird-client`
3. Click **Next**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-create-client.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-create-client.png" alt="Create client" className="imagewrapper-big"/>
</p>
- Check the checkboxes as on the screenshot below and click Save
4. Enable the authentication options as shown:
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-enable-auth.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-enable-auth.png" alt="Enable auth" className="imagewrapper-big"/>
</p>
## Step 5: Adjust NetBird client access settings
5. Click **Save**
In this step we will configure NetBird application client access with the NetBird URLs.
### Step 5: Configure Client Access Settings
- 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`
1. Go to **Clients** → **netbird-client**
2. In **Access Settings**, fill in:
- **Root URL**: `https://YOUR_DOMAIN/`
- **Valid redirect URIs**: `https://YOUR_DOMAIN/*` and `http://localhost:53000`
- **Valid post logout redirect URIs**: `https://YOUR_DOMAIN/*`
- **Web origins**: `+`
3. Click **Save**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-access-settings.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-access-settings.png" alt="Access settings" className="imagewrapper-big"/>
</p>
## Step 6: Create a NetBird client scope
### Step 6: Create 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`
1. Click **Client scopes** (left-hand menu)
2. Click **Create client scope**
3. Fill in:
- **Name**: `api`
- **Type**: `Default`
- **Protocol**: `OpenID Connect`
4. Click **Save**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-create-client-scope.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-create-client-scope.png" alt="Create client scope" className="imagewrapper-big"/>
</p>
- While in the newly created Client Scope, switch to the `Mappers` tab
- Click `Configure a new mapper`
- Choose the `Audience` mapping
5. Switch to the **Mappers** tab
6. Click **Configure a new mapper**
7. Choose **Audience** mapping
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-configure-audience-mapper.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-configure-audience-mapper.png" alt="Configure audience mapper" className="imagewrapper-big"/>
</p>
- 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`
8. Fill in:
- **Name**: `Audience for NetBird Management API`
- **Included Client Audience**: `netbird-client`
- **Add to access token**: `On`
9. Click **Save**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-configure-audience-mapper-2.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-configure-audience-mapper-2.png" alt="Audience mapper config" className="imagewrapper-big"/>
</p>
## Step 7: Add client scope to NetBird client
### 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
1. Go to **Clients** → **netbird-client**
2. Switch to **Client scopes** tab
3. Click **Add client scope**
4. Choose `api`
5. Click **Add** choosing `Default`
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-add-client-scope.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-add-client-scope.png" alt="Add client scope" className="imagewrapper-big"/>
</p>
## Step 8: Create a NetBird-Backend client
### Step 8: Create 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`
1. Click **Clients** → **Create client**
2. Fill in:
- **Client Type**: `OpenID Connect`
- **Client ID**: `netbird-backend`
3. Click **Next**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-create-backend-client.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-create-backend-client.png" alt="Create backend client" className="imagewrapper-big"/>
</p>
- Check the checkboxes as on the screenshot below and click Save
4. Enable authentication as shown:
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-backend-client-auth.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-backend-client-auth.png" alt="Backend client auth" className="imagewrapper-big"/>
</p>
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`
5. Click **Save**
6. Go to **Credentials** tab
7. Copy the **Client secret**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-backend-client-credentials.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-backend-client-credentials.png" alt="Backend client credentials" className="imagewrapper-big"/>
</p>
## Step 9: Add view-users role to netbird-backend
### Step 9: Add View-Users Role
- 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`
1. Go to **Clients** → **netbird-backend**
2. Switch to **Service accounts roles** tab
3. Click **Assign roles**
4. Select **Filter by clients** and search for `view-users`
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-service-account-role.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-service-account-role.png" alt="Service account role" className="imagewrapper-big"/>
</p>
- Check the role checkbox and click assign
5. Check the role checkbox and click **Assign**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-add-role.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-add-role.png" alt="Add role" className="imagewrapper-big"/>
</p>
<Note>
Optional
NetBird offers the ability to automatically delete a user from the Keycloak 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 `manage-users` role to the `netbird-backend` following the steps outlined above.
**Optional**: To enable automatic user deletion from Keycloak when deleted from NetBird, add the `--user-delete-from-idp` flag to the management startup command and assign the `manage-users` role instead.
</Note>
Your authority OIDC configuration will be available under:
### Step 10: Configure NetBird
Your authority OIDC configuration will be available at:
```bash
https://<YOUR_KEYCLOAK_HOST_AND_PORT>/realms/netbird/.well-known/openid-configuration
```
<Note>
Double-check if the endpoint returns a JSON response by calling it from your browser.
Double-check if the endpoint returns a JSON response by calling it from your browser.
</Note>
- Set properties in the `setup.env` file:
```shell
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`
Set properties in the `setup.env` file:
NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID=`netbird-client`
NETBIRD_AUTH_DEVICE_AUTH_AUDIENCE=`netbird-client`
```shell
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_AUTH_DEVICE_AUTH_AUDIENCE="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"
```
<Note>
Make sure that your Keycloak instance use HTTPS. Otherwise, the setup won't work.
Make sure your Keycloak instance uses HTTPS. Otherwise, the setup won't work.
</Note>
#### 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](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
### Step 11: Continue with NetBird Setup
You've configured all required resources in Keycloak. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
---
## Troubleshooting
### "Invalid redirect URI" error
- Ensure the redirect URI matches exactly what's configured
- For connector: Use the exact URL from the NetBird success modal
- For standalone: Include both `https://YOUR_DOMAIN/*` and `http://localhost:53000`
### "Invalid token" errors
- Verify the issuer URL includes `/realms/your-realm`
- Ensure the client ID matches in both Keycloak and NetBird
- Check clock synchronization between servers
### Users not appearing in NetBird
- For connector: Users appear after their first successful login
- For standalone: Verify the backend client has `view-users` role
---
## Related Resources
- [Keycloak Documentation](https://www.keycloak.org/documentation)
- [Embedded IdP Overview](/selfhosted/identity-providers/local)

292
src/pages/selfhosted/identity-providers/local.mdx Normal file
View File

@@ -0,0 +1,292 @@
# Local User Management
NetBird's Management service includes built-in user management, allowing you to create and manage local users directly without requiring an external identity provider. This functionality is powered by an embedded [Dex](https://dexidp.io/) server.
Starting with version 0.62, NetBird **no longer requires an external identity provider**. The Management service now supports creating and managing local users directly, so you can get started without setting up Zitadel, Keycloak, or any other IdP.
With local user management, you can:
- **Create local users** directly from the NetBird Dashboard
- **Add external identity providers** (Google, Microsoft, Okta, etc.) through the Dashboard UI
- **Configure multiple IdPs** simultaneously, users see all providers as login options
- **Simplify your deployment** with fewer containers and reduced resource requirements
- **Get started faster** with no additional IdP setup required
<Note>
Local user management is powered by an embedded [Dex](https://dexidp.io/) server running within the NetBird Management service, requiring no additional containers or databases.
</Note>
[Get Started →](/selfhosted/selfhosted-quickstart)
## When to Use Local Users
Local user management is ideal for:
| Use Case | Why Local Users Work |
|----------|----------------------|
| **Homelabs** | Simple setup, minimal resources, no external dependencies |
| **Small teams** | Easy user management, quick onboarding |
| **Proof of concept** | Get started in minutes, upgrade path available |
| **Air-gapped environments** | No external service dependencies |
| **Development/testing** | Fast iteration, simple reset |
Consider a [standalone external IdP](/selfhosted/selfhosted-guide#step-3-configure-identity-provider-idp) if you need:
- SCIM user provisioning (Enterprise feature)
- Complex user lifecycle management
- Integration with existing enterprise SSO infrastructure
- Specific IdP features not available via OIDC connectors
## Configuration
### Enabling Embedded IdP
The embedded IdP is enabled by default when using the new [`getting-started.sh`](/selfhosted/selfhosted-quickstart) quickstart script. For manual configuration, update your `management.json`:
```json
{
"EmbeddedIdP": {
"Enabled": true,
"DataDir": "/var/lib/netbird/idp"
},
"EncryptionKey": "<auto-generated-base64-key>"
}
```
### Configuration Options
| Option | Description | Default |
|--------|-------------|---------|
| `EmbeddedIdP.Enabled` | Enable/disable the embedded IdP | `true` (quickstart) |
| `EmbeddedIdP.DataDir` | Directory for IdP data storage | `/var/lib/netbird/idp` |
| `EncryptionKey` | Base64-encoded AES-256 key for encrypting user data | Auto-generated |
### Environment Variables
When using docker-compose, you can configure these via environment variables:
```yaml
environment:
- NETBIRD_EMBEDDED_IDP_ENABLED=true
- NETBIRD_EMBEDDED_IDP_DATA_DIR=/var/lib/netbird/idp
- NETBIRD_ENCRYPTION_KEY=${ENCRYPTION_KEY}
```
### Generating an Encryption Key
If you need to generate an encryption key manually:
```bash
openssl rand -base64 32
```
<Note>
Store your encryption key securely. If lost, encrypted user data (emails, names) cannot be recovered. Include it in your backup procedures.
</Note>
## User Management
### Creating Users via Dashboard
When embedded IdP is enabled, the Dashboard shows a **"Create User"** button (instead of "Invite User" shown for cloud-hosted NetBird):
1. Navigate to **Team** → **Users**
2. Click **Create User**
3. Fill in the user details:
- **Email** (required) - User's email address for login
- **Name** (required) - Display name
- **Groups** (optional) - Auto-assign to groups
4. Click **Create**
After creation, a modal displays with:
- The **generated password** with a copy button
- Warning: *"This password will only be shown once. Please copy it now."*
- **Copy & Close** button to copy password and dismiss
<Note>
The generated password is only shown once at creation time. It cannot be retrieved later. Make sure to copy it and share it securely with the user.
</Note>
### User IdP Badges
In the Users table, each user shows a badge indicating their identity provider:
- Users created locally show no badge (or "Local" badge)
- Users who authenticated via an external connector show that provider's icon (Google, Microsoft, etc.)
- The badge links to the `idp_id` field in the user record
### Creating Users via API
```bash
curl -X POST "https://netbird.example.com/api/users" \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"name": "New User",
"auto_groups": ["group-id-1"]
}'
```
Response includes the generated password:
```json
{
"id": "user-abc123",
"email": "user@example.com",
"name": "New User",
"role": "user",
"status": "active",
"password": "generated-password-here"
}
```
<Note>
The `password` field is only included when creating users with embedded IdP. Store it immediately—it won't be returned in subsequent API calls.
</Note>
### User Roles
Users created through the embedded IdP can be assigned roles:
| Role | Permissions |
|------|-------------|
| **Owner** | Full administrative access, cannot be demoted |
| **Admin** | Manage users, peers, policies, and settings |
| **User** | Connect devices, view assigned resources |
## Instance Setup (First Run)
When NetBird starts with the embedded IdP and no existing accounts, the Dashboard redirects to the `/setup` route and displays the **Instance Setup Wizard**:
1. The Dashboard checks `GET /instance` for `setup_required: true`
2. If setup is required, users are redirected to `/setup`
3. The wizard collects:
- **Email address** (required)
- **Password** (required, minimum 8 characters)
- **Name** (optional)
4. On submit, the owner account is created via `POST /instance/setup`
5. User is redirected to login with the credentials they just created
<Note>
The `/setup` route is unauthenticated and only accessible when `setup_required` is true. Once setup is complete, accessing `/setup` returns a 412 error and redirects to login.
</Note>
### Setup API
For automated deployments, you can complete setup via API:
```bash
# Check if setup is required
curl "https://netbird.example.com/api/instance"
# Response when setup is needed:
{
"setup_required": true
}
# Complete setup
curl -X POST "https://netbird.example.com/api/instance/setup" \
-H "Content-Type: application/json" \
-d '{
"email": "admin@example.com",
"password": "securepassword123",
"name": "Admin User"
}'
# Response:
{
"user_id": "user-abc123",
"account_id": "account-xyz789"
}
```
## Data Encryption
The embedded IdP encrypts sensitive user data at rest:
| Field | Encryption |
|-------|------------|
| Email | AES-256-GCM |
| Name | AES-256-GCM |
| Password | bcrypt hash (via Dex) |
The encryption key is configured in `management.json` and should be:
- Generated using a cryptographically secure random generator
- Stored securely (not in version control)
- Included in backup procedures
- Rotated according to your security policies
## Security Considerations
### Password Requirements
Default password requirements for local users:
- Minimum 8 characters
- No specific complexity requirements (consider your security policy)
### Session Management
- JWT tokens are issued upon successful authentication
- Token expiration follows OIDC best practices
- Device authorization flow available for CLI clients
### Audit Logging
User authentication events are logged in the activity log:
- Login attempts (successful and failed)
- User creation/deletion
- Connector configuration changes
## Troubleshooting
### "Embedded IdP not available" error
Ensure `EmbeddedIdP.Enabled` is `true` in `management.json` and the Management service has been restarted.
### Users can't log in
1. Check Management service logs: `docker compose logs management`
2. Verify the encryption key hasn't changed
3. Confirm the user exists: Check **Team** → **Users** in Dashboard
## Comparison with External IdP
| Feature | Embedded IdP | External IdP |
|---------|--------------|--------------|
| Setup complexity | Minimal | Moderate to High |
| Resource requirements | Low (~1GB RAM) | Higher (2-4GB+ RAM) |
| Additional containers | None | IdP + Database |
| User management | Dashboard/API | External IdP console |
| External SSO | Via connectors | Native |
| SCIM provisioning | Not available | Available (Enterprise) |
| MFA | Via external connectors | Native IdP feature |
| Backup complexity | Single database | Multiple databases |
## Disabling Embedded IdP
To switch from embedded IdP to an external IdP:
1. Configure your external IdP following the [Advanced guide](/selfhosted/selfhosted-guide)
2. Update `management.json`:
```json
{
"EmbeddedIdP": {
"Enabled": false
},
"HttpConfig": {
"OIDCConfigEndpoint": "https://your-idp.example.com/.well-known/openid-configuration"
}
}
```
3. Restart the Management service
4. Users will need to re-authenticate with the new IdP
<Note>
Disabling the embedded IdP will invalidate all local user accounts. Ensure users have accounts in the external IdP before switching.
</Note>

242
src/pages/selfhosted/identity-providers/managed/auth0.mdx
View File

@@ -1,22 +1,85 @@
import {Note} from "@/components/mdx";
# Auth0 with NetBird Self-Hosted
# Auth0
This guide is a part of the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide) and explains how to integrate **self-hosted** NetBird with [Auth0](https://auth0.com/).
[Auth0](https://auth0.com/) is a flexible, drop-in solution to add authentication and authorization services to your applications. It's a managed service that handles identity infrastructure so you don't have to.
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.
## Connector Setup (Recommended)
Add Auth0 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
- Auth0 account (sign up at https://auth0.com/)
### Step 1: Create Application in Auth0
1. Log in to your Auth0 dashboard at https://manage.auth0.com/
2. Go to **Applications** → **Applications**
3. Click **Create Application**
4. Fill in:
- **Name**: `NetBird`
- **Application type**: `Regular Web Application`
5. Click **Create**
6. Go to **Settings** tab
7. Note the **Client ID** and **Client Secret**
8. Note the **Domain** (e.g., `your-tenant.auth0.com`)
### 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 | Auth0 (or your preferred display name) |
| Client ID | From Auth0 application |
| Client Secret | From Auth0 application |
| Issuer | `https://your-tenant.auth0.com` |
5. Click **Save**
### Step 3: Configure Redirect URI
After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your Auth0 application:
1. Return to Auth0 Dashboard → **Applications** → **NetBird**
2. Go to **Settings** tab
3. Under **Allowed Callback URLs**, add the redirect URL from NetBird
4. Click **Save Changes**
### Step 4: Test the Connection
1. Log out of NetBird Dashboard
2. On the login page, you should see an "Auth0" button
3. Click it and authenticate
4. You should be redirected back to NetBird and logged in
---
## Standalone Setup (Advanced)
Use Auth0 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 Auth0 administrators as it also requires additional setup and ongoing maintenance.
For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) 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.
<Note>
If you prefer to have full control over authentication and authorization of your NetBird network, there are good
self-hosted alternatives to the managed Auth0 service like [Keycloak](/selfhosted/identity-providers#keycloak).
If you prefer to have full control over authentication, consider self-hosted alternatives like [Keycloak](/selfhosted/identity-providers/keycloak).
</Note>
## Step 1: Create Auth0 account
To create an Auth0 account, sign up at [https://auth0.com](https://auth0.com/).
### Prerequisites
- Auth0 account (sign up at https://auth0.com/)
- Docker and Docker Compose for NetBird
### Configuration Properties
You will configure these properties in `setup.env`:
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`
@@ -27,115 +90,113 @@ There are multiple properties of the **`setup.env`** file that we will configure
- `NETBIRD_IDP_MGMT_CLIENT_SECRET`
- `NETBIRD_IDP_MGMT_EXTRA_AUDIENCE`
## Step 2: Create and configure Auth0 application
### Step 1: Create Dashboard Application
This Auth0 application will be used to authorize access to NetBird Dashboard (Web UI).
This application authorizes access to NetBird Dashboard.
1. Follow the [Auth0 React SDK Guide](https://auth0.com/docs/quickstart/spa/react/01-login#configure-auth0) up to "Install the Auth0 React SDK"
2. Set **Allowed Callback URLs**: `https://YOUR_DOMAIN` and `http://localhost:53000`
3. Set **Allowed Logout URLs**, **Allowed Web Origins**, **Allowed Origins (CORS)**: `https://YOUR_DOMAIN` and `http://localhost`
- Follow the steps in the [Auth0 React SDK Guide](https://auth0.com/docs/quickstart/spa/react/01-login#configure-auth0)
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)`
<Note>
Make sure that **`Token Endpoint Authentication Method`** is set to **`None`**.
Ensure **Token Endpoint Authentication Method** is set to **None**.
</Note>
- 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:
4. Use **Client ID** for `NETBIRD_AUTH_CLIENT_ID`
5. Use **Domain** to configure `NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT`:
```bash
https://<DOMAIN>/.well-known/openid-configuration
https://<DOMAIN>/.well-known/openid-configuration
```
<Note>
Double-check if the endpoint returns a JSON response by calling it from your browser.
Double-check if the endpoint returns a JSON response by calling it from your browser.
</Note>
#### Step 3: Create and configure Auth0 API
### Step 2: Create API
This Auth0 API will be used to access NetBird Management Service API.
This API is used to access NetBird Management Service.
- Follow the steps in the [Auth0 Create An API](https://auth0.com/docs/quickstart/backend/golang#create-an-api).
- Use API **`Identifier`** to set ```NETBIRD_AUTH_AUDIENCE``` property in the `setup.env` file.
- Set ```NETBIRD_USE_AUTH0``` to `true`in the `setup.env` file.
1. Follow the [Auth0 Create An API](https://auth0.com/docs/quickstart/backend/golang#create-an-api) guide
2. Use the API **Identifier** for `NETBIRD_AUTH_AUDIENCE`
3. Set `NETBIRD_USE_AUTH0=true`
## Step 4: Enable Interactive SSO Login (Optional)
### Step 3: Enable Interactive SSO Login (Optional)
The [Interactive SSO Login feature](/get-started/install#running-net-bird-with-sso-login) allows for machine
authorization with your Identity Provider. This feature can be used as an alternative to [setup keys](/manage/peers/register-machines-using-setup-keys)
and is optional.
This enables machine authorization via your Identity Provider as an alternative to [setup keys](/manage/peers/register-machines-using-setup-keys).
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`
1. Go to **Applications**
2. Click **Create Application**
3. Fill in:
- **Name**: `Interactive Login`
- **Application type**: `Native`
4. Click **Create**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-create-interactive-login-app.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-create-interactive-login-app.png" alt="Create interactive login app" className="imagewrapper-big"/>
</p>
- Click `Settings` tab
- Copy **`Client ID`** to `NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID` in the `setup.env` file
5. Click **Settings** tab
6. Copy **Client ID** to `NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID`
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-interactive-login-settings.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-interactive-login-settings.png" alt="Interactive login settings" className="imagewrapper-big"/>
</p>
- Scroll down to the `Advanced Settings` section
- Enable **`Device Code`**
- Click `Save Changes`
7. Scroll to **Advanced Settings**
8. Enable **Device Code**
9. Click **Save Changes**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-grant-types.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-grant-types.png" alt="Grant types" className="imagewrapper-big"/>
</p>
## Step 5: Create and configuire Machine to Machine application.
This application will be used to authorize access to Auth0 Management API.
### Step 4: Create Machine to Machine Application
- 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`
This application authorizes access to Auth0 Management API.
1. Go to **Applications**
2. Click **Create Application**
3. Fill in:
- **Name**: `Netbird API`
- **Application type**: `Machine to Machine Applications`
4. Click **Create**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-create-machine-app.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-create-machine-app.png" alt="Create machine app" className="imagewrapper-big"/>
</p>
- 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`
5. Configure:
- **API**: `Auth0 Management API`
- **Permissions**: `read:users`, `update:users`, `create:users`, `read:users_app_metadata`, `update:users_app_metadata`, `create:users_app_metadata`
6. Click **Authorize**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-machine-authorization.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-machine-authorization.png" alt="Machine authorization" className="imagewrapper-big"/>
</p>
<Note>
Optional
NetBird offers the ability to automatically delete a user from the Auth0 side when the user is deleted from the associated account.
To enable this functionality, 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 `delete:users` permission following the steps outlined above.
**Optional**: To enable automatic user deletion from Auth0 when deleted from NetBird, add the `--user-delete-from-idp` flag to the management startup command and assign the `delete:users` permission.
</Note>
- 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
7. Click **Settings** tab
8. Copy values:
- **Client ID** → `NETBIRD_IDP_MGMT_CLIENT_ID`
- **Client Secret** → `NETBIRD_IDP_MGMT_CLIENT_SECRET`
- **Domain** → `NETBIRD_IDP_MGMT_EXTRA_AUDIENCE` (format: `https://<DOMAIN>/api/v2/`)
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-machine-settings.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-machine-settings.png" alt="Machine settings" className="imagewrapper-big"/>
</p>
- Set properties in the `setup.env` file:
### Step 5: Configure NetBird
Set properties in the `setup.env` file:
```shell
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://<DOMAIN>/.well-known/openid-configuration"
NETBIRD_USE_AUTH0=true
NETBIRD_AUTH_CLIENT_ID="<Client_ID>"
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>"
@@ -146,6 +207,39 @@ NETBIRD_IDP_MGMT_CLIENT_SECRET="<NETBIRD_API_CLIENT_SECRET>"
NETBIRD_IDP_MGMT_EXTRA_AUDIENCE="https://<DOMAIN>/api/v2/"
```
### Step 6: Continue with NetBird Setup
## 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](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
You've configured all required resources in Auth0. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
---
## Troubleshooting
### "Invalid redirect URI" error
- Ensure all callback URLs are configured in Auth0
- Check for trailing slashes
- Verify URLs match exactly
### "Unauthorized" errors for Management API
- Verify the Machine to Machine application has correct permissions
- Check that `NETBIRD_IDP_MGMT_EXTRA_AUDIENCE` includes `/api/v2/`
### Device authorization not working
- Ensure Device Code grant is enabled in Advanced Settings
- Verify the native application Client ID is used
### Token validation errors
- Verify `NETBIRD_USE_AUTH0=true` is set
- Check the audience matches the API identifier
---
## Related Resources
- [Auth0 Documentation](https://auth0.com/docs/)
- [Auth0 Dashboard](https://manage.auth0.com/)
- [Embedded IdP Overview](/selfhosted/identity-providers/local)

351
src/pages/selfhosted/identity-providers/managed/google-workspace.mdx
View File

@@ -1,127 +1,239 @@
import {Note} from "@/components/mdx";
# Google Workspace with NetBird Self-Hosted
# Google Workspace
This guide is a part of the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide) and explains how to integrate
**self-hosted** NetBird with [Google Workspace](https://workspace.google.com/).
Use Google accounts for authentication with NetBird. This supports both personal Google accounts and Google Workspace (formerly G Suite) organizations.
## Connector Setup (Recommended)
Add Google 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
- Access to [Google Cloud Console](https://console.cloud.google.com/)
### Step 1: Create OAuth Credentials
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Select or create a project
3. Navigate to **APIs & Services** → **Credentials**
4. Click **Create Credentials** → **OAuth client ID**
5. If prompted, configure the OAuth consent screen first:
- Choose **Internal** (for Workspace) or **External** (for any Google account)
- Fill in required fields (app name, support email)
- Add scopes: `email`, `profile`, `openid`
- Save and continue
6. Back in Credentials, create the OAuth client:
- **Application type**: `Web application`
- **Name**: `NetBird`
- Leave redirect URIs empty for now
7. Click **Create**
8. 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 | Google |
| Name | Google (or your preferred display name) |
| Client ID | From Google Cloud Console |
| Client Secret | From Google Cloud Console |
<Note>
Beginning with NetBird version v0.23.6 and onwards, the Google Workspace IdP manager no longer requires the creation of a custom admin role called `User and Schema Management`.
Instead, we are transitioning towards a more tailored role explicitly designed for managing read-only user information.
Consequently, you have the option to remove the previously established custom admin role and refer to the documentation to configure the admin role scope for read-only access correctly.
Google connectors don't require an Issuer field—it's determined automatically.
</Note>
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.
5. Click **Save**
## Step 1: Configure OAuth consent screen
- Navigate to [OAuth consent](https://console.cloud.google.com/apis/credentials/consent) page
- Select `Internal` User Type and click create
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-consent-screen-type.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
### Step 3: Configure Redirect URI
- 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`
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-consent-screen-scopes.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
- 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`
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-consent-screen-summary.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your Google OAuth client:
## Step 2: Create OAuth 2.0 credentials
- Navigate to [API Credentials](https://console.cloud.google.com/apis/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`
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-oauth-client.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
- Take note of `Client ID` and `Client Secret` and click `OK`
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-oauth-client-created.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
1. Return to Google Cloud Console → **Credentials**
2. Click on your OAuth client
3. Under **Authorized redirect URIs**, click **Add URI**
4. Paste the redirect URL from NetBird
5. Click **Save**
## Step 3: Create service account
- Navigate to [API Credentials](https://console.cloud.google.com/apis/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`
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-service-account-create.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
### Step 4: Test the Connection
## Step 4: Create service account keys
- Navigate to [API Credentials](https://console.cloud.google.com/apis/credentials) page
- Under `Service Accounts` click the `netbird` to edit the service account
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-edit-service-account.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
- 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`
1. Log out of NetBird Dashboard
2. On the login page, you should see a "Google" button
3. Click it and sign in with your Google account
4. You should be redirected back to NetBird and logged in
### Restricting to Google Workspace Domains
To limit authentication to specific Google Workspace domains:
1. Go to **APIs & Services** → **OAuth consent screen**
2. Under **User type**, select **Internal** (Workspace only)
3. For external apps, verify your domain to restrict access
<Note>
When you create a service account key by using the Google Cloud console, most browsers immediately download the new key and save it in a download folder on your computer.
Read how to manage and secure your service keys [here](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys#temp-locations)
Domain restrictions are configured in Google Cloud Console, not in NetBird.
</Note>
- Open downloaded json file and take note of `client_id` will be used later as `Service Account Client ID`
---
## Standalone Setup (Advanced)
Use Google Workspace 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 Google Workspace administrators as it also requires additional setup and ongoing maintenance.
For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) 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.
<Note>
Beginning with NetBird version v0.23.6 and onwards, the Google Workspace IdP manager no longer requires the custom admin role called `User and Schema Management`. We now use a read-only role for user information.
</Note>
### Prerequisites
- A Google Workspace account (not just personal Google)
- Admin permissions in Google Workspace
- A project in [Google Cloud Console](https://console.cloud.google.com)
- Enable **Admin SDK API** for your project at https://console.cloud.google.com/apis/library/admin.googleapis.com
### Step 1: Configure OAuth Consent Screen
1. Navigate to [OAuth consent](https://console.cloud.google.com/apis/credentials/consent)
2. Select **Internal** User Type and click **Create**
## Step 5: Grant user management admin role to service account
- Navigate to [Admin Console](https://admin.google.com/ac/home) 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`
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-new-role-info.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-consent-screen-type.png" alt="Consent screen type" className="imagewrapper-big"/>
</p>
- Scroll down to `Admin API privileges` and add the following privileges
- Users: `Read`
- Click `CONTINUE`
3. Fill in the form:
- **App name**: `Netbird`
- **User support email**: `<administrator email>`
- **Authorized domain**: `<your netbird domain>`
- **Developer contact information**: `<developer email>`
4. Click **SAVE AND CONTINUE**
5. Click **ADD OR REMOVE SCOPES**
6. Select `/auth/userinfo.email`, `/auth/userinfo.profile`, and `openid`
7. Click **UPDATE**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-privileges-review.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
- 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`
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-assign-role.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
- Click `ASSIGN ROLE` to assign service account to `User Management ReadOnly` role
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-service-account-privileges.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-consent-screen-scopes.png" alt="Consent screen scopes" className="imagewrapper-big"/>
</p>
- Navigate to [Account Settings](https://admin.google.com/ac/accountsettings/profile?hl=en_US) page and take note of `Customer ID`
8. Click **SAVE AND CONTINUE**
9. Review the summary and click **BACK TO DASHBOARD**
- Encode service account json key into base64 format
```sh
base64 -i <SERVICE_ACCOUNT_KEY_PATH>
```
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-consent-screen-summary.png" alt="Consent screen summary" className="imagewrapper-big"/>
</p>
- Set properties in the `setup.env` file:
```json
### Step 2: Create OAuth 2.0 Credentials
1. Navigate to [API Credentials](https://console.cloud.google.com/apis/credentials)
2. Click **CREATE CREDENTIALS** → **OAuth client ID**
3. Fill in:
- **Application type**: `Web application`
- **Name**: `netbird`
- **Authorized JavaScript origins**: `https://<your domain>` and `http://localhost`
- **Authorized redirect URIs**:
- `https://<your domain>/auth`
- `https://<your domain>/silent-auth`
- `http://localhost:53000`
4. Click **CREATE**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-oauth-client.png" alt="OAuth client" className="imagewrapper-big"/>
</p>
5. Note **Client ID** and **Client Secret**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-oauth-client-created.png" alt="OAuth client created" className="imagewrapper-big"/>
</p>
### Step 3: Create Service Account
1. Navigate to [API Credentials](https://console.cloud.google.com/apis/credentials)
2. Click **CREATE CREDENTIALS** → **Service account**
3. Fill in:
- **Service account name**: `netbird`
- **Service account ID**: `netbird`
4. Note the service account email address
5. Click **DONE**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-service-account-create.png" alt="Create service account" className="imagewrapper-big"/>
</p>
### Step 4: Create Service Account Keys
1. Navigate to [API Credentials](https://console.cloud.google.com/apis/credentials)
2. Under **Service Accounts**, click **netbird** to edit
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-edit-service-account.png" alt="Edit service account" className="imagewrapper-big"/>
</p>
3. Click the **Keys** tab
4. Click **Add key** → **Create new key**
5. Select **JSON** and click **Create**
<Note>
The key file downloads automatically. Store it securely. Read about [managing service account keys](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys#temp-locations).
</Note>
6. Open the downloaded JSON file and note the `client_id` (Service Account Client ID)
### Step 5: Grant User Management Admin Role
1. Navigate to [Admin Console](https://admin.google.com/ac/home)
2. Select **Account** → **Admin Roles**
3. Click **Create new role**
4. Fill in:
- **Name**: `User Management ReadOnly`
- **Description**: `User Management ReadOnly`
5. Click **CONTINUE**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-new-role-info.png" alt="New role info" className="imagewrapper-big"/>
</p>
6. Scroll to **Admin API privileges** and add:
- **Users**: `Read`
7. Click **CONTINUE**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-privileges-review.png" alt="Privileges review" className="imagewrapper-big"/>
</p>
8. Click **CREATE ROLE**
9. Click **Assign service accounts**
10. Add the service account email address
11. Click **ADD** then **ASSIGN ROLE**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-assign-role.png" alt="Assign role" className="imagewrapper-big"/>
</p>
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-service-account-privileges.png" alt="Service account privileges" className="imagewrapper-big"/>
</p>
12. Navigate to [Account Settings](https://admin.google.com/ac/accountsettings/profile) and note the **Customer ID**
### Step 6: Encode Service Account Key
```bash
base64 -i <SERVICE_ACCOUNT_KEY_PATH>
```
### Step 7: Configure NetBird
Set properties in the `setup.env` file:
```shell
NETBIRD_DOMAIN="<YOUR_DOMAIN>"
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://accounts.google.com/.well-known/openid-configuration"
NETBIRD_USE_AUTH0=false
@@ -141,5 +253,42 @@ 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](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
### Step 8: Continue with NetBird Setup
You've configured all required resources in Google Workspace. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
---
## Troubleshooting
### "Access blocked" error
- Ensure OAuth consent screen is configured correctly
- For external apps, you may need to submit for verification or add test users
- Check that required scopes are added
### "Invalid redirect URI" error
- Verify the redirect URI exactly matches what's in Google Cloud Console
- Check for trailing slashes or HTTP vs HTTPS mismatches
- Google is case-sensitive for redirect URIs
### Users from wrong domain signing in
- For Workspace, use **Internal** user type in OAuth consent screen
- Verify domain restrictions in consent screen settings
### Service account not syncing users
- Verify Admin SDK API is enabled
- Check that the service account has the User Management ReadOnly role
- Ensure the Customer ID is correct
---
## Related Resources
- [Google Cloud Console](https://console.cloud.google.com/)
- [Google OAuth 2.0 Documentation](https://developers.google.com/identity/protocols/oauth2)
- [Google Workspace Admin Console](https://admin.google.com/)
- [Embedded IdP Overview](/selfhosted/identity-providers/local)

297
src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx
View File

@@ -1,105 +1,204 @@
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 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) 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-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 +216,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/local)

278
src/pages/selfhosted/identity-providers/managed/microsoft-entra-id.mdx
View File

@@ -1,133 +1,224 @@
import {Note} from "@/components/mdx";
# Microsoft Entra ID with NetBird Self-Hosted
# Microsoft Entra ID
This guide is a part of the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide) and explains how to integrate **self-hosted** NetBird with [Azure AD](https://azure.microsoft.com/en-us/products/active-directory/).
Use Microsoft accounts for authentication with NetBird. This supports both personal Microsoft accounts and Microsoft Entra ID (formerly Azure AD) for work and school accounts.
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.
## Connector Setup (Recommended)
Add Microsoft as a connector to the embedded IdP. Choose the appropriate connector type based on your needs:
| Connector Type | Use Case |
|---------------|----------|
| **Microsoft** (`microsoft`) | Personal Microsoft accounts |
| **Microsoft Entra ID** (`entra`) | Work/school accounts via Azure AD |
### Prerequisites
- NetBird self-hosted with embedded IdP enabled
- Access to [Azure Portal](https://portal.azure.com/) or [Entra Admin Center](https://entra.microsoft.com/)
### Step 1: Create App Registration
1. Navigate to [Azure Portal](https://portal.azure.com/) → **Azure Active Directory** (or [Entra Admin Center](https://entra.microsoft.com/))
2. Click **App registrations** → **New registration**
3. Fill in:
- **Name**: `NetBird`
- **Supported account types**: Choose based on your needs:
- *Personal accounts only*: `Personal Microsoft accounts only`
- *Work/school only*: `Accounts in this organizational directory only`
- *Both*: `Accounts in any organizational directory and personal Microsoft accounts`
- **Redirect URI**: Leave empty for now
4. Click **Register**
5. Note the **Application (client) ID** and **Directory (tenant) ID**
### Step 2: Create Client Secret
1. Go to **Certificates & secrets**
2. Click **New client secret**
3. Add a description and expiration
4. Click **Add**
5. Copy the **Value** immediately (it won't be shown again)
### Step 3: 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:
**For Personal Microsoft Accounts:**
| Field | Value |
|-------|-------|
| Type | Microsoft |
| Name | Microsoft (or your preferred display name) |
| Client ID | Application (client) ID from Azure |
| Client Secret | Secret value from Azure |
**For Microsoft Entra ID (Work/School):**
| Field | Value |
|-------|-------|
| Type | Microsoft Entra ID |
| Name | Microsoft Work (or your preferred display name) |
| Client ID | Application (client) ID from Azure |
| Client Secret | Secret value from Azure |
| Tenant ID | Directory (tenant) ID from Azure |
5. Click **Save**
### Step 4: Configure Redirect URI
After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your Azure app:
1. Return to Azure Portal → Your app registration
2. Go to **Authentication**
3. Click **Add a platform** → **Single-page application**
4. Add the redirect URL from NetBird
5. Click **Configure**
### Step 5: Test the Connection
1. Log out of NetBird Dashboard
2. On the login page, you should see the Microsoft button
3. Click it and sign in with your Microsoft account
4. You should be redirected back to NetBird and logged in
---
## Standalone Setup (Advanced)
Use Microsoft Entra ID 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 Microsoft Entra ID administrators as it also requires additional setup and ongoing maintenance.
For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) 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.
<Note>
If you prefer to have full control over authentication and authorization of your NetBird network, there are good
self-hosted alternatives to the managed Auth0 service like [Keycloak](/selfhosted/identity-providers#keycloak).
If you prefer to have full control over authentication, consider self-hosted alternatives like [Keycloak](/selfhosted/identity-providers/keycloak).
</Note>
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/.
### Prerequisites
- 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.
- An Azure account with appropriate permissions
- Docker and Docker Compose for NetBird
### Step 1: Create and Configure Azure AD Application
## 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](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview)
- 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`
1. Navigate to [Azure Active Directory](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview)
2. Click **App Registrations** → **+ New registration**
3. Fill in:
- **Name**: `Netbird`
- **Supported account types**: `Accounts in this organizational directory only (Single tenant)`
- **Redirect URI**: Select `Single-page application (SPA)` and enter `https://<yournetbirddomain.com>/silent-auth`
4. Click **Register**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-new-application.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-new-application.png" alt="New application" className="imagewrapper-big"/>
</p>
#### Step 2. Platform configurations
- Click `Authentication` on the left side menu
- Under the `Single-page application` Section, add another URI `https://<yournetbirddomain.com>/auth`
### Step 2: Configure Platform Settings
1. Click **Authentication** on the left menu
2. Under **Single-page application**, add another URI: `https://<yournetbirddomain.com>/auth`
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-spa-uri-setup.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-spa-uri-setup.png" alt="SPA URI setup" className="imagewrapper-big"/>
</p>
- Scroll down and setup other options as on the screenshot below and click Save
3. Scroll down and configure options as shown:
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-flows-setup.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-flows-setup.png" alt="Flows setup" className="imagewrapper-big"/>
</p>
- 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`
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-spa-uri-setup.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
4. Click **Add a Platform** → **Mobile and desktop applications**
5. Add custom redirect URI: `http://localhost:53000`
6. Click **Configure**
## 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`
### Step 3: Create Application Scope
1. Click **Expose an API** on the left menu
2. Under **Application ID URI**, click **Set** then **Save**
3. Click **+ Add a Scope**
4. Fill in:
- **Scope name**: `api`
5. Click **Add scope**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-add-scope.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-add-scope.png" alt="Add scope" className="imagewrapper-big"/>
</p>
- 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://`
6. Under **Authorized client applications**, click **+ Add a client application**
7. Enter your **Client ID** (same as Application ID URI minus `api://`)
8. Click **Add application**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-add-application-scope.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-add-application-scope.png" alt="Add application scope" className="imagewrapper-big"/>
</p>
### Step 4: Add API Permissions
## 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`.
1. Click **API permissions** on the left menu
2. Click **Add a permission**
3. Select **My APIs** tab → **Netbird** → check `api` permission → **Add permissions**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-netbird-api-permisssions.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-netbird-api-permisssions.png" alt="NetBird API permissions" className="imagewrapper-big"/>
</p>
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`
4. Click **Add a permission** again
5. Select **Microsoft Graph** → **Application permissions**
6. Search for `User.Read` and select `User.Read.All`
7. Click **Add permissions**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-openid-permissions.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-openid-permissions.png" alt="OpenID permissions" className="imagewrapper-big"/>
</p>
- Click `Grant admin consent for Default Directory` and click `Yes`
8. Click **Grant admin consent for Default Directory** → **Yes**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-grant-admin-conset.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-grant-admin-conset.png" alt="Grant admin consent" className="imagewrapper-big"/>
</p>
## Step 5. Update token version
- Click `Manifest` on left menu
- Search for `accessTokenAcceptedVersion` and change the value from `null` to `2`
- Click `Save`
### Step 5: Update Token Version
## 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.
1. Click **Manifest** on the left menu
2. Find `accessTokenAcceptedVersion` and change from `null` to `2`
3. Click **Save**
### Step 6: Generate Client Secret
1. Click **Certificates & secrets** on the left menu
2. Click **New client secret**
3. Fill in:
- **Description**: `Netbird`
4. Click **Add**
5. Copy the **Value** immediately
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-client-secret.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-client-secret.png" alt="Client secret" className="imagewrapper-big"/>
</p>
- Click `Overview` on left menu and take note of `Application (client) ID`, `Object ID` and `Directory (tenant) ID`
will be required in next step.
6. Click **Overview** and note:
- **Application (client) ID**
- **Object ID**
- **Directory (tenant) ID**
### Step 7: Configure NetBird
Your authority OIDC configuration will be available at:
Your authority OIDC configuration will be available under:
```bash
https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0/.well-known/openid-configuration
```
<Note>
Double-check if the endpoint returns a JSON response by calling it from your browser.
Double-check if the endpoint returns a JSON response by calling it from your browser.
</Note>
- Set properties in the `setup.env` file:
Set properties in the `setup.env` file:
```shell
NETBIRD_DOMAIN="<YOUR_DOMAIN>"
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0/.well-known/openid-configuration"
@@ -147,8 +238,43 @@ 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](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
### Step 8: Continue with NetBird Setup
You've configured all required resources in Azure AD. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
---
## Troubleshooting
### "AADSTS50011: The redirect URI specified in the request does not match"
- Ensure the redirect URI in Azure exactly matches what NetBird provides
- Check platform type (SPA vs Mobile/Desktop)
- Verify no trailing slashes
### "AADSTS700016: Application not found"
- Verify the Application (client) ID is correct
- Check tenant ID for single-tenant apps
- Ensure the app registration is in the correct directory
### Users from wrong tenant signing in
- Use single-tenant configuration for organization-only access
- Verify "Supported account types" setting in app registration
### Token validation errors
- Ensure `accessTokenAcceptedVersion` is set to `2` in the manifest
- Verify all scopes are properly configured
- Check that admin consent was granted
---
## Related Resources
- [Microsoft Identity Platform Documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/)
- [Azure Portal](https://portal.azure.com/)
- [Embedded IdP Overview](/selfhosted/identity-providers/local)

243
src/pages/selfhosted/identity-providers/managed/okta.mdx
View File

@@ -1,115 +1,185 @@
import {Note} from "@/components/mdx";
# Okta with NetBird Self-Hosted
# Okta
This guide is a part of the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide) and explains how to integrate
**self-hosted** NetBird with [Okta](https://www.okta.com/).
[Okta](https://www.okta.com/) is a cloud-based identity and access management service for enterprise use, providing single sign-on, multi-factor authentication, and lifecycle management.
## Connector Setup (Recommended)
Add Okta 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
- Okta Workforce Identity Cloud account
### Step 1: Create OIDC Application in Okta
1. Navigate to Okta Admin Dashboard
2. Click **Applications** → **Applications**
3. Click **Create App Integration**
4. Select:
- **Sign-in method**: `OIDC - OpenID Connect`
- **Application type**: `Web Application`
5. Click **Next**
6. Fill in:
- **App integration name**: `NetBird`
- **Grant type**: `Authorization Code`
- Leave redirect URIs empty for now
7. Click **Save**
8. 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 | Okta |
| Name | Okta (or your preferred display name) |
| Client ID | From Okta application |
| Client Secret | From Okta application |
| Issuer | Your Okta URL (e.g., `https://your-org.okta.com`) |
5. Click **Save**
### Step 3: Configure Redirect URI
After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your Okta application:
1. Return to Okta Admin → **Applications** → **NetBird**
2. Click **Edit** in the General Settings
3. Add the redirect URL from NetBird to **Sign-in redirect URIs**
4. Click **Save**
### Step 4: Test the Connection
1. Log out of NetBird Dashboard
2. On the login page, you should see an "Okta" button
3. Click it and authenticate with your Okta credentials
4. You should be redirected back to NetBird and logged in
---
## Standalone Setup (Advanced)
Use Okta 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 Okta administrators as it also requires additional setup and ongoing maintenance.
For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) 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.
<Note>
If you prefer to have full control over authentication and authorization of your NetBird network, there are good self-hosted alternatives to the managed Okta service like [Keycloak](/selfhosted/identity-providers#keycloak).
If you prefer to have full control over authentication, consider self-hosted alternatives like [Keycloak](/selfhosted/identity-providers/keycloak).
</Note>
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/.
### Prerequisites
## 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`
- Okta Workforce Identity Cloud account (sign up at https://www.okta.com/free-trial/)
- Docker and Docker Compose for NetBird
### Step 1: Create Single-Page Application
1. Navigate to Okta Admin Dashboard
2. Click **Applications** → **Applications**
3. Click **Create App Integration**
4. Select:
- **Sign-in method**: `OIDC - OpenID Connect`
- **Application type**: `Single-Page Application`
5. Click **Next**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-new-single-page-application.png" alt="high-level-dia" className="imagewrapper"/>
<img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-new-single-page-application.png" alt="New SPA application" className="imagewrapper"/>
</p>
- 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`
6. Fill in:
- **App integration name**: `Netbird`
- **Grant type**: `Authorization Code` and `Refresh Token`
- **Sign-in redirect URIs**:
- `https://<yournetbirddomain.com>/auth`
- `https://<yournetbirddomain.com>/silent-auth`
- `http://localhost:53000`
- **Sign-out redirect URIs**: `https://<yournetbirddomain.com>/`
7. Click **Save**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-single-page-application.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-single-page-application.png" alt="SPA application config" className="imagewrapper-big"/>
</p>
- 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`
8. Note the **Client ID**
9. Click **Sign On** tab
10. Under **OpenID Connect ID Token**, click **Edit** and set **Issuer** to use the `Okta URL`
11. Click **Save**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-single-sign-on-configuration.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-single-sign-on-configuration.png" alt="Sign-on configuration" className="imagewrapper-big"/>
</p>
## 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`
### Step 2: Create Native Application (for Device Auth)
1. Click **Applications** → **Applications**
2. Click **Create App Integration**
3. Select:
- **Sign-in method**: `OIDC - OpenID Connect`
- **Application type**: `Native Application`
4. Click **Next**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-new-native-application.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-new-native-application.png" alt="New native application" className="imagewrapper-big"/>
</p>
- Fill in the form with the following values and click `Save`
- App integration name: `Netbird Native App`
- Grant type: `Device Authorization`
- Click `Save`
5. Fill in:
- **App integration name**: `Netbird Native App`
- **Grant type**: `Device Authorization`
6. Click **Save**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-native-application.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-native-application.png" alt="Native application config" className="imagewrapper-big"/>
</p>
- 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`
7. Note the **Client ID** (for device auth)
8. Click **Sign On** tab
9. Under **OpenID Connect ID Token**, set **Issuer** to use the `Okta URL`
10. Click **Save**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-native-sign-on-configuration.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-native-sign-on-configuration.png" alt="Native sign-on configuration" className="imagewrapper-big"/>
</p>
### Step 3: Generate API Token
## 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`
1. Click **Security** → **API**
2. Click **Tokens** tab
3. Click **Create token**
4. Enter:
- **Name**: `Netbird`
5. Click **Create token**
6. Copy the token value and click **OK, got it**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-generate-token.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-generate-token.png" alt="Generate token" className="imagewrapper-big"/>
</p>
### Step 4: Configure NetBird
Your authority OIDC configuration will be available at:
Your authority OIDC configuration will be available under:
```bash
https://<YOUR_OKTA_ORGANIZATION_URL>/.well-known/openid-configuration
```
<Note>
Double-check if the endpoint returns a JSON response by calling it from your browser.
Double-check if the endpoint returns a JSON response by calling it from your browser.
</Note>
- Set properties in the `setup.env` file:
```json
Set properties in the `setup.env` file:
```shell
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_AUDIENCE="<NETBIRD_CLIENT_ID>"
NETBIRD_AUTH_CLIENT_ID="<NETBIRD_CLIENT_ID>"
NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email"
NETBIRD_AUTH_REDIRECT_URI="/auth"
@@ -117,13 +187,48 @@ 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_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>"
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](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
### Step 5: Continue with NetBird Setup
You've configured all required resources in Okta. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
---
## Troubleshooting
### "Invalid redirect URI" error
- Ensure all redirect URIs are configured in Okta
- Check for trailing slashes
- Verify the application type matches the use case
### "Invalid issuer" error
- Ensure the issuer is set to use the Okta URL (not dynamic)
- Verify the OIDC configuration endpoint returns valid JSON
### Device authorization not working
- Ensure the native application has "Device Authorization" grant type
- Verify the native client ID is used for device auth settings
### Users not syncing
- Verify the API token is valid and not expired
- Check that the token has appropriate permissions
---
## Related Resources
- [Okta Developer Documentation](https://developer.okta.com/docs/)
- [Okta Admin Console](https://help.okta.com/en/prod/Content/Topics/Apps/Apps_App_Integration_Wizard_OIDC.htm)
- [Embedded IdP Overview](/selfhosted/identity-providers/local)

178
src/pages/selfhosted/identity-providers/pocketid.mdx
View File

@@ -1,72 +1,134 @@
import {Note} from "@/components/mdx";
# PocketID with NetBird Self-Hosted
# PocketID
This guide is a part of the [NetBird Self-hosting Guide](/docs/selfhosted/selfhosted-guide) and explains how to integrate
**self-hosted** NetBird with [PocketID](https://pocket-id.org/).
[PocketID](https://pocket-id.org/) is a simplified identity management solution designed for self-hosted environments, offering a lightweight and easy-to-deploy option for authentication.
<Note>
PocketID is a simplified identity management solution designed for self hosted environments.
It is secure and effective, but makes some tradeoffs in terms of features and usability.
Notably, it does not allow scoping the access of API Tokens.
This isn't an issue per se, but it does mean that you should keep careful track of the token used by NetBird for management.
PocketID is secure and effective but makes some tradeoffs in terms of features. Notably, it does not allow scoping the access of API Tokens. Keep careful track of the token used by NetBird for management.
</Note>
## Step 1. Create and configure PocketID application
In this step, we will create and configure NetBird application in pocketid.
## Connector Setup (Recommended)
Create new PocketID OIDC Client
- Navigate to pocketid console
- Click the `Administration` dropdown in the left hand bar, then select `OIDC Clients`
- Fill in the form with the following values and click `Continue`
- Name: `NetBird`
- Client Launch URL: `https://<domain>`
- Callback URL's:
- `http://localhost:53000`
- `https://<domain>/auth`
- `https://<domain>/silent-auth`
- Logout Callback URL: `https://<domain>/`
- Public Client: On
- PKCE: On
- Click `Save`
Add PocketID 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
- PocketID instance with admin access
### Step 1: Create OIDC Client in PocketID
1. Navigate to PocketID console
2. Click the **Administration** dropdown in the left-hand bar
3. Select **OIDC Clients**
4. Click **Add** to create a new client
5. Fill in the form:
- **Name**: `NetBird`
- **Public Client**: Off (for confidential client)
- **PKCE**: Off
6. Click **Save**
7. 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 | PocketID |
| Name | PocketID (or your preferred display name) |
| Client ID | From PocketID |
| Client Secret | From PocketID |
| Issuer | `https://pocketid.example.com` |
5. Click **Save**
### Step 3: Configure Redirect URI
After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your PocketID client:
1. Return to PocketID console → **OIDC Clients**
2. Edit your NetBird client
3. Add the redirect URL to **Callback URLs**
4. Click **Save**
### Step 4: Test the Connection
1. Log out of NetBird Dashboard
2. On the login page, you should see a "PocketID" button
3. Click it and authenticate with your PocketID credentials
4. You should be redirected back to NetBird and logged in
---
## Standalone Setup (Advanced)
Use PocketID 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 PocketID administrators as it also requires additional setup and ongoing maintenance.
For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) 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
- PocketID instance running with SSL
- Docker and Docker Compose for NetBird
### Step 1: Create and Configure PocketID Application
1. Navigate to PocketID console
2. Click the **Administration** dropdown, then select **OIDC Clients**
3. Fill in the form:
- **Name**: `NetBird`
- **Client Launch URL**: `https://<domain>`
- **Callback URLs**:
- `http://localhost:53000`
- `https://<domain>/auth`
- `https://<domain>/silent-auth`
- **Logout Callback URL**: `https://<domain>/`
- **Public Client**: On
- **PKCE**: On
4. Click **Save**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/pocketid-create-oidc-client.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/pocketid-create-oidc-client.png" alt="Create OIDC client" className="imagewrapper-big"/>
</p>
- Copy `Client ID` will be used later in the `setup.env`
5. Copy **Client ID** for later use
## Step 2: Application Token Configuration
### Step 2: Create API Token
To configure the application token you need to:
- Click `Administration` dropdown in the left hand bar, then select `API Keys`
- Click `Add API Key`
- Enter the following values and click `Save`
- Name: 'NetBird Management Token'
- Expires At: Pick a date in the future
- Description: 'NetBird Management Token'
- Click `Save`
1. Click **Administration** dropdown, then select **API Keys**
2. Click **Add API Key**
3. Fill in:
- **Name**: `NetBird Management Token`
- **Expires At**: Pick a date in the future
- **Description**: `NetBird Management Token`
4. Click **Save**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/pocketid-create-api-token.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/pocketid-create-api-token.png" alt="Create API token" className="imagewrapper-big"/>
</p>
- Copy `API Key` will be used later in the `setup.env`
5. Copy **API Key** for later use
### Step 3: Configure NetBird
Your authority OIDC configuration will be available under:
Your authority OIDC configuration will be available at:
```bash
https://<YOUR_POCKETID_HOST_AND_PORT>/.well-known/openid-configuration
```
:::caution
<Note>
Double-check if the endpoint returns a JSON response by calling it from your browser.
:::
</Note>
- Set properties in the `setup.env` file:
```json
Set properties in the `setup.env` file:
```shell
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://<YOUR_POCKETID_HOST_AND_PORT>/.well-known/openid-configuration"
NETBIRD_USE_AUTH0=false
NETBIRD_AUTH_CLIENT_ID="<CLIENT_ID>"
@@ -86,8 +148,34 @@ NETBIRD_MGMT_IDP="pocketid"
NETBIRD_IDP_MGMT_CLIENT_ID="netbird"
NETBIRD_IDP_MGMT_EXTRA_MANAGEMENT_ENDPOINT="https://<YOUR_POCKETID_HOST_AND_PORT>"
NETBIRD_IDP_MGMT_EXTRA_API_TOKEN="<API_TOKEN>"
```
## Step 3: Continue with the NetBird Self-hosting Guide
You've configured all required resources in PocketID. You can now continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
### Step 4: Continue with NetBird Setup
You've configured all required resources in PocketID. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
---
## Troubleshooting
### "Invalid redirect URI" error
- Ensure all callback URLs are properly configured in PocketID
- Include both HTTP (localhost) and HTTPS (domain) variants
### API token not working
- Verify the token hasn't expired
- Ensure the token was created by an admin user
### Device authorization not available
- PocketID has limited device auth support
- Set `NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="none"` if issues persist
---
## Related Resources
- [PocketID Documentation](https://pocket-id.org/docs)
- [Embedded IdP Overview](/selfhosted/identity-providers/local)

322
src/pages/selfhosted/identity-providers/zitadel.mdx
View File

@@ -1,153 +1,215 @@
import {Note} from "@/components/mdx";
# Zitadel with NetBird Self-Hosted
# Zitadel
This guide is a part of the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide) and explains how to integrate
**self-hosted** NetBird with [Zitadel](https://zitadel.com).
[Zitadel](https://zitadel.com) is an open-source identity infrastructure platform designed for cloud-native environments. It provides multi-tenancy, customizable branding, passwordless authentication, and supports protocols like OpenID Connect, OAuth2, SAML2, and LDAP.
<Note>
If you prefer not to self-host an Identity and Access Management solution, then you could use the managed alternative
[Zitadel Cloud](https://zitadel.com/).
Zitadel was previously used in the NetBird quickstart script. If you have an existing Zitadel deployment, you can continue using it as a standalone IdP or migrate to the embedded IdP with Zitadel as a connector.
</Note>
## Step 1. Create and configure Zitadel application
In this step, we will create and configure NetBird application in zitadel.
## Connector Setup (Recommended)
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`
Add Zitadel as a connector to the embedded IdP. This is the simplest approach for new deployments or when migrating from the previous quickstart.
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-new-project.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
### Prerequisites
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`
- NetBird self-hosted with embedded IdP enabled
- Zitadel instance (cloud or self-hosted)
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-new-application.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
### Step 1: Create Application in Zitadel
- Fill in the form with the following values and click `Continue`
- Authentication Method: `PKCE`
1. Log in to your Zitadel Console
2. Navigate to your project (or create one)
3. Click **New** in the **Applications** section
4. Fill in:
- **Name**: `NetBird`
- **Type**: `Web`
5. Click **Continue**
6. Configure authentication:
- **Authentication Method**: `Code` (not PKCE)
7. Leave redirect URIs empty for now
8. Click **Create**
9. Go to **Token Settings** and enable **User Info inside ID Token**
10. Note the **Client ID** and generate a **Client Secret**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-new-application-auth.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
### Step 2: Add Connector in NetBird
- 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 `+`
1. Log in to your NetBird Dashboard
2. Navigate to **Settings** → **Identity Providers**
3. Click **Add Identity Provider**
4. Fill in the fields:
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-new-application-uri.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
| Field | Value |
|-------|-------|
| Type | Zitadel |
| Name | Zitadel (or your preferred display name) |
| Client ID | From Zitadel application |
| Client Secret | From Zitadel application |
| Issuer | Your Zitadel URL (e.g., `https://your-instance.zitadel.cloud`) |
- Verify applications details and Click `Create` and then click `Close`
- Under `Grant Types` select `Authorization Code`, `Device Code` and `Refresh Token` and click `save`
5. Click **Save**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-new-application-overview.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
### Step 3: Configure Redirect URI
- Copy `Client ID` will be used later in the `setup.env`
After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your Zitadel application:
## Step 2: Application Token Configuration
1. Return to Zitadel Console
2. Go to your application → **Redirect Settings**
3. Add the redirect URL from NetBird to **Redirect URIs**
4. Click **Save**
To configure `netbird` application token you need to:
### Step 4: Test the Connection
- 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`
1. Log out of NetBird Dashboard
2. On the login page, you should see a "Zitadel" button
3. Click it and authenticate with your Zitadel credentials
4. You should be redirected back to NetBird and logged in
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-token-settings.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
---
## Step 3: Application Redirect Configuration
## Standalone Setup (Advanced)
Use Zitadel 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 Zitadel administrators as it also requires additional setup and ongoing maintenance.
For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) 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.
<Note>
This step is intended for setup running in development mode with no SSL
If you prefer not to self-host, Zitadel offers a managed cloud option at [zitadel.com](https://zitadel.com/).
</Note>
To configure `netbird` application redirect you need to:
### Prerequisites
- 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`
- Zitadel instance (cloud or self-hosted) with SSL
- Docker and Docker Compose for NetBird
### Step 1: Create and Configure Zitadel Application
1. Navigate to Zitadel console
2. Click **Projects** at the top menu, then click **Create New Project**
3. Fill in:
- **Name**: `NETBIRD`
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-redirect-settings.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-new-project.png" alt="New project" className="imagewrapper-big"/>
</p>
## 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`
4. Click **Projects** and select **NETBIRD** project
5. Click **New** in **Applications** section
6. Fill in:
- **Name**: `netbird`
- **Type of Application**: `User Agent`
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-create-user.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-new-application.png" alt="New application" className="imagewrapper-big"/>
</p>
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`
7. Click **Continue** and set:
- **Authentication Method**: `PKCE`
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-service-user-secret.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-new-application-auth.png" alt="Application auth" className="imagewrapper-big"/>
</p>
## 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`
8. Click **Continue** and configure:
- **Redirect URIs**:
- `https://<domain>/auth`
- `https://<domain>/silent-auth`
- `http://localhost:53000`
- **Post Logout URIs**: `https://<domain>/`
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-service-account-role.png" alt="high-level-dia" className="imagewrapper-big"/>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-new-application-uri.png" alt="Application URIs" className="imagewrapper-big"/>
</p>
Your authority OIDC configuration will be available under:
9. Click **Create** and then **Close**
10. Under **Grant Types**, select `Authorization Code`, `Device Code`, and `Refresh Token`
11. Click **Save**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-new-application-overview.png" alt="Application overview" className="imagewrapper-big"/>
</p>
12. Copy **Client ID** for later use
### Step 2: Configure Token Settings
1. Select the **netbird** application
2. Click **Token Settings** in the left menu
3. Configure:
- **Auth Token Type**: `JWT`
- Check **Add user roles to the access token**
4. Click **Save**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-token-settings.png" alt="Token settings" className="imagewrapper-big"/>
</p>
### Step 3: Configure Redirect Settings (Development Only)
<Note>
This step is only for development mode without SSL.
</Note>
1. Click **Redirect Settings** in the left menu
2. Toggle **Development Mode**
3. Click **Save**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-redirect-settings.png" alt="Redirect settings" className="imagewrapper-big"/>
</p>
### Step 4: Create Service User
1. Click **Users** in the top menu
2. Select **Service Users** tab
3. Click **New**
4. Fill in:
- **User Name**: `netbird`
- **Name**: `netbird`
- **Description**: `Netbird Service User`
- **Access Token Type**: `JWT`
5. Click **Create**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-create-user.png" alt="Create service user" className="imagewrapper-big"/>
</p>
6. Click **Actions** in the top right corner
7. Click **Generate Client Secret**
8. Copy **ClientSecret** for later use
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-service-user-secret.png" alt="Service user secret" className="imagewrapper-big"/>
</p>
### Step 5: Grant User Manager Role
1. Click **Organization** in the top menu
2. Click **+** in the top right corner
3. Search for `netbird` service user
4. Check **Org User Manager** checkbox
5. Click **Add**
<p>
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-service-account-role.png" alt="Service account role" className="imagewrapper-big"/>
</p>
### Step 6: Configure NetBird
Your authority OIDC configuration will be available at:
```bash
https://<YOUR_ZITADEL_HOST_AND_PORT>/.well-known/openid-configuration
```
:::caution
<Note>
Double-check if the endpoint returns a JSON response by calling it from your browser.
:::
</Note>
- Set properties in the `setup.env` file:
```json
Set properties in the `setup.env` file:
```shell
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>"
@@ -165,9 +227,63 @@ 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](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
### Step 7: Continue with NetBird Setup
You've configured all required resources in Zitadel. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
---
## Migrating from Zitadel Quickstart
If you deployed NetBird using the previous quickstart script with Zitadel:
**Option A - Keep using Zitadel standalone**: Continue with your existing setup. No changes needed.
**Option B - Add Zitadel as connector to embedded IdP**:
1. Deploy new NetBird version with embedded IdP
2. Add your existing Zitadel as a connector (follow connector setup above)
3. Users can continue logging in with Zitadel
4. Optionally create local user accounts as fallback
**Option C - Migrate fully to embedded IdP**:
1. Export user list from Zitadel
2. Deploy new NetBird version with embedded IdP
3. Recreate users in NetBird Dashboard
4. Decommission Zitadel when ready
---
## Troubleshooting
### "Invalid redirect URI" error
- Verify the redirect URI exactly matches what's configured
- Check for trailing slashes
- Ensure the application type is correct (User Agent for Dashboard)
### "Token validation failed" error
- Verify the issuer URL is correct
- Ensure **User Info inside ID Token** is enabled
- Check that the audience matches your client ID
### Service user authentication fails
- Verify the client secret was copied correctly
- Ensure the service user has **Org User Manager** role
### Device auth not working
- Ensure **Device Code** grant type is enabled
- Verify PKCE is configured for the application
---
## Related Resources
- [Zitadel Documentation](https://zitadel.com/docs)
- [Zitadel GitHub](https://github.com/zitadel/zitadel)
- [Embedded IdP Overview](/selfhosted/identity-providers/local)
- [Migration Guide](/selfhosted/identity-providers#migration-guide)

37
src/pages/selfhosted/self-hosted-vs-cloud-netbird.mdx
View File

@@ -18,6 +18,19 @@ peer-to-peer connectivity, fallback relayed connections through a network of geo
and overall system reliability and availability. It is not an easy task to deploy and maintain such infrastructure in
a reliable manner. NetBird is not just one VPN server. You can read more about how NetBird works [here](/about-netbird/how-netbird-works).
## What's New: No External IdP Required
Starting with version 0.62, self-hosting NetBird has become significantly easier. Previously, self-hosting required setting up and maintaining a separate identity provider (like Zitadel, Keycloak, or Auth0). Now, the Management service supports **local user management** directly, which means:
- **No external IdP required** - Create and manage users directly in NetBird
- **Fewer containers** to deploy and maintain (4-5 vs 7+ previously)
- **Lower resource requirements** (~1GB RAM vs 2-4GB previously)
- **User management directly in the Dashboard**
- **Optional external IdPs** - Connect Google, Microsoft, Okta, etc. if you want SSO
- **Multiple IdPs supported** - Configure multiple OIDC providers simultaneously
This makes self-hosting a more viable option for homelabs, small teams, and proof-of-concept deployments.
## Installation and Maintenance
NetBird platform is a combination of [multiple components](/about-netbird/how-netbird-works) that make it possible for
@@ -25,7 +38,8 @@ machines to establish direct point-to-point connections and for network administ
e.g., control network access.
When running the self-hosted version, you are responsible for installing and maintaining all the components as well as backing up
and securing the data.
and securing the data. With local user management built into the Management service, this burden is significantly reduced—you no longer need to maintain separate identity provider infrastructure.
The cloud-hosted NetBird only requires you to install the client software (NetBird agent) on your machines and log them in to the network.
The cloud-hosted version is more suitable for organizations that want a hassle-free solution that is easy to set up and maintain.
@@ -42,6 +56,10 @@ some additional features that are targeted at business customers and help with n
- **[User invites](/manage/team/add-users-to-your-network#direct-user-invites)**.
- **[MSP functionality](/manage/for-partners/msp-portal)** for managing multiple tenant networks from a single account.
<Note>
SCIM provisioning and some enterprise features require a [Commercial License](https://netbird.io/pricing#on-prem) for self-hosted deployments.
</Note>
## Geo Distributed Relay Servers
NetBird uses relay servers to establish connections between machines when a direct point-to-point connections isn't possible.
@@ -57,12 +75,27 @@ maintenance effort.
When using the cloud-hosted version, you benefit from highly available control plane servers (Management) providing stability for
your critical network infrastructure.
## Quick Comparison
| Aspect | Self-Hosted | Cloud-Hosted |
|--------|-------------|--------------|
| **Setup time** | ~5 minutes with local users | Instant |
| **Infrastructure** | You manage | We manage |
| **Identity provider** | Built-in local users (+ optional external IdPs) | Managed |
| **Multiple IdPs** | Yes, OIDC-compatible | Yes |
| **Relay servers** | Single instance (or DIY geo-distribution) | Geo-distributed globally |
| **High availability** | DIY | Included |
| **SCIM provisioning** | Enterprise license | Included (Business+) |
| **Cost** | Your infrastructure costs | Subscription |
| **Best for** | Homelabs, air-gapped networks, compliance requirements | Teams wanting hassle-free setup |
## Get started
<p float="center" >
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
</p>
- [Self-hosting Quickstart](/selfhosted/selfhosted-quickstart) - Get started with self-hosted NetBird in 5 minutes
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on X](https://x.com/netbird)
- Join our [Slack Channel](/slack-url)
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub

54
src/pages/selfhosted/selfhosted-guide.mdx
View File

@@ -8,12 +8,24 @@ a 3rd party open-source STUN/TURN service [Coturn](https://github.com/coturn/cot
If you would like to learn more about the architecture please refer to the [architecture section](/about-netbird/how-netbird-works).
<Note>
It might be a good idea to try NetBird before self-hosting on your servers.
We run NetBird in the cloud, and it will take a few clicks to get started with our managed version. [Check it out!](https://netbird.io/pricing)
**New to self-hosting?** The [Quickstart guide](/selfhosted/selfhosted-quickstart) uses the built-in identity provider and is the fastest way to get started. This advanced guide is for users who need to integrate with an existing IdP or have specific enterprise requirements.
</Note>
If you are looking for a quick way of trying self-hosted NetBird, please refer to [this guide](/about-netbird/how-netbird-works). Otherwise, continue here to set up
NetBird with custom IdPs.
<Note>
It might be a good idea to try NetBird before self-hosting on your servers.
We run NetBird in the cloud, and it will take a few clicks to get started with our managed version. [Check it out!](https://netbird.io/pricing)
</Note>
## When to use this guide
Use this advanced guide if you:
- Need to integrate with an **existing identity provider** (Okta, Azure AD, Auth0, etc.)
- Require **SCIM provisioning** for user/group sync (Enterprise)
- Have **compliance requirements** that mandate a specific IdP
- Want **full control** over the authentication infrastructure
For simpler deployments, the [Quickstart with embedded IdP](/selfhosted/selfhosted-quickstart) is recommended.
## Advanced self-hosting guide with a custom identity provider
@@ -123,18 +135,24 @@ NetBird supports generic OpenID (OIDC) protocol allowing integration with any ID
NetBird's management service integrates with some of the most popular IDP APIs, allowing the service to cache and display user names and email addresses without storing sensitive data.
Pick the one that suits your needs, follow the steps, and continue with this guide:
Pick the one that suits your needs, follow the **Standalone Setup (Advanced)** section in each guide, and continue with this guide:
**Self-hosted options**
- Continue with [Zitadel](/selfhosted/identity-providers#zitadel).
- Continue with [Keycloak](/selfhosted/identity-providers#keycloak).
- Continue with [Authentik](/selfhosted/identity-providers#authentik).
- [Zitadel](/selfhosted/identity-providers/zitadel) - Previously used in the quickstart script
- [Keycloak](/selfhosted/identity-providers/keycloak) - Popular open-source IAM
- [Authentik](/selfhosted/identity-providers/authentik) - Flexible open-source IdP
- [PocketID](/selfhosted/identity-providers/pocketid) - Lightweight self-hosted option
**Managed options**
- Continue with [Azure AD](/selfhosted/identity-providers#azure-ad-microsoft-entra-id).
- Continue with [Google Workspace](/selfhosted/identity-providers#google-workspace).
- Continue with [Okta](/selfhosted/identity-providers#okta).
- Continue with [Auth0](/selfhosted/identity-providers#auth0).
- [Microsoft Entra ID](/selfhosted/identity-providers/managed/microsoft-entra-id) - Azure AD / Microsoft 365
- [Google Workspace](/selfhosted/identity-providers/managed/google-workspace) - Google accounts
- [Okta](/selfhosted/identity-providers/managed/okta) - Enterprise SSO
- [Auth0](/selfhosted/identity-providers/managed/auth0) - Flexible auth platform
- [JumpCloud](/selfhosted/identity-providers/managed/jumpcloud) - Cloud directory
<Note>
Each provider page includes both "Connector Setup" (for use with embedded IdP) and "Standalone Setup (Advanced)" sections. For this guide, follow the **Standalone Setup** section.
</Note>
### Step 4: Disable single account mode (optional)
@@ -283,10 +301,20 @@ To upgrade NetBird to the latest version, you need to review the [release notes]
docker compose up -d --force-recreate
```
## Migrating to Embedded IdP
If you've deployed NetBird using this advanced guide and want to simplify your setup by migrating to the embedded IdP:
1. Your existing IdP can be added as a **connector** to the embedded IdP
2. Users can continue logging in with their existing credentials
3. You can gradually transition to local user management
See the [Migration Guide](/selfhosted/identity-providers#migration-guide) for detailed instructions.
## Get in touch
Feel free to ping us on [Slack](/slack-url) if you have any questions
- NetBird managed version: [https://app.netbird.io](https://app.netbird.io)
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on X](https://x.com/netbird)
- Follow us [on X](https://x.com/netbird)

268
src/pages/selfhosted/selfhosted-quickstart.mdx
View File

@@ -1,24 +1,17 @@
# Self-hosting quickstart guide (5 min)
NetBird is open-source and can be self-hosted on your servers.
NetBird is open source and can be self-hosted on your servers.
It relies on components developed by NetBird Authors [Management Service](https://github.com/netbirdio/netbird/tree/main/management), [Management UI Dashboard](https://github.com/netbirdio/dashboard), [Signal Service](https://github.com/netbirdio/netbird/tree/main/signal),
a 3rd party open-source STUN/TURN service [Coturn](https://github.com/coturn/coturn), and an identity provider (available options will be listed later in this guide).
and a 3rd party open-source STUN/TURN service [Coturn](https://github.com/coturn/coturn).
If you would like to learn more about the architecture please refer to the [Architecture section](/about-netbird/how-netbird-works).
<Note>
It might be a good idea to try NetBird before self-hosting on your servers.
We run NetBird in the cloud, and it will take a few clicks to get started with our managed version. [Check it out!](https://netbird.io/pricing)
</Note>
## Quick self-hosting with Zitadel IdP
In this guide, we will guide you through deploying NetBird with [Zitadel](https://zitadel.com/)
as the identity provider for user management using a single-line setup script and docker containers.
## Quick self-hosting
<Note>
This is the quickest way to try self-hosted NetBird. It should take around 5 minutes to get started if you already have a public domain and a VM.
Follow the [Advanced guide with a custom identity provider](/selfhosted/selfhosted-guide#advanced-self-hosting-guide-with-a-custom-identity-provider) for installations with different IDPs.
This is the quickest way to try self-hosted NetBird. It should take around 5 minutes to get started if you already have a public domain and a VM.
For advanced setups, see the [Advanced guide](/selfhosted/selfhosted-guide).
</Note>
### Requirements
@@ -30,19 +23,186 @@ as the identity provider for user management using a single-line setup script an
**Software requirements:**
- Docker installed on the VM with the docker compose plugin ([Docker installation guide](https://docs.docker.com/engine/install/)) or docker with docker-compose in version 2 or higher.
- [jq](https://jqlang.github.io/jq/) installed. In most distributions
Usually available in the official repositories and can be installed with `sudo apt install jq` or `sudo yum install jq`
- [curl](https://curl.se/) installed.
Usually available in the official repositories and can be installed with `sudo apt install curl` or `sudo yum install curl`
- [jq](https://jqlang.github.io/jq/) installed. In most distributions usually available in the official repositories and can be installed with `sudo apt install jq` or `sudo yum install jq`
- [curl](https://curl.se/) installed. Usually available in the official repositories and can be installed with `sudo apt install curl` or `sudo yum install curl`
### Download and run the script
Download and run the installation script in a single line:
```bash
export NETBIRD_DOMAIN=netbird.example.com; curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started-with-zitadel.sh | bash
export NETBIRD_DOMAIN=netbird.example.com; curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash
```
If you want to check the script before running it, you can download it and run it locally:
```bash
curl -sSLO https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh
# check the script
cat getting-started.sh
# run the script
export NETBIRD_DOMAIN=netbird.example.com
bash getting-started.sh
```
<Note>
Replace `netbird.example.com` with your domain name.
</Note>
An example output of the script:
```bash
root@selfhosted-1:~/netbird# bash getting-started.sh
Rendering initial files...
Starting NetBird services
WARN[0000] No services to build
[+] up 9/9
✔ Network netbird-selfhosted-3_netbird Created 0.1s
✔ Volume netbird-selfhosted-3_netbird_caddy_data Created 0.0s
✔ Volume netbird-selfhosted-3_netbird_management Created 0.0s
✔ Container netbird-caddy Created 0.2s
✔ Container netbird-dashboard Created 0.2s
✔ Container netbird-management Created 0.2s
✔ Container netbird-relay Created 0.2s
✔ Container netbird-coturn Created 0.2s
✔ Container netbird-signal Created 0.2s
Waiting for Management server to become ready . . done
Done!
You can access the NetBird dashboard at https://netbird.example.com
Follow the onboarding steps to set up your NetBird instance.
```
### Initial setup (Onboarding)
The script deploys NetBird **without any users**. Once complete, you'll need to create your first user:
<p>
<img src="/docs-static/img/selfhosted/quickstart/setup.png" alt="NetBird setup page" width="600"/>
</p>
1. Open your browser and navigate to `https://netbird.example.com`
2. You'll be redirected to the setup page (`/setup`)
3. Create your admin account:
- Enter your email address
- Enter your name
- Enter a password
- Click **Create Account**
You can then log in with your email and password.
<Note>
The `/setup` page is only accessible when no users exist. After creating the first user, it redirects to the regular login page.
</Note>
### Add more users
#### Local users
You can add users directly from the NetBird Dashboard:
<p>
<img src="/docs-static/img/selfhosted/quickstart/create-user.png" alt="Add user" width="600"/>
</p>
1. Navigate to **Team** → **Users**
2. Click **Create User**
3. Enter the user's email and name
4. Click **Create**
A password will be generated and displayed once. Share this securely with the user—it cannot be retrieved later.
#### Via Identity Provider (Optional)
If you want users to sign in with their existing accounts from Google, Microsoft, Okta, or other providers, you can connect external identity providers:
1. Navigate to **Settings** → **Identity Providers**
2. Click **Add Identity Provider**
3. Select your provider type (Google, Microsoft, Okta, or generic OIDC)
4. Enter the OAuth client credentials from your provider
5. Click **Save**
You can add multiple identity providers. Users will see all configured providers as login options.
For detailed setup guides, see [Identity Providers](/selfhosted/identity-providers).
### Backup
To backup your NetBird installation, you need to copy the configuration files and the Management service databases.
The configuration files are located in the folder where you ran the installation script. To backup, copy the files to a backup location:
```bash
mkdir backup
cp docker-compose.yml Caddyfile dashboard.env turnserver.conf management.json relay.env backup/
```
To save the Management service databases, you need to stop the Management service and copy the files from the store directory using a docker compose command as follows:
```bash
docker compose stop management
docker compose cp -a management:/var/lib/netbird/ backup/
docker compose start management
```
### Upgrade
To upgrade NetBird to the latest version:
1. Run the backup steps described in the [backup](#backup) section.
2. Review the [release notes](https://github.com/netbirdio/netbird/releases) for any breaking changes.
3. Pull the latest NetBird docker images:
```bash
docker compose pull management dashboard signal relay
```
4. Restart the NetBird containers with the new images:
```bash
docker compose up -d --force-recreate management dashboard signal relay
```
<Note>
For upgrades from older versions (pre-v0.26.0), see the [Legacy upgrade notes](#legacy-self-hosting-with-zitadel-idp).
</Note>
### Remove
To remove the NetBird installation and all related data from your server, run these commands from the folder where you installed NetBird:
```bash
# remove all NetBird-related containers and volumes (data)
docker compose down --volumes
# remove downloaded and generated config files
rm -f docker-compose.yml Caddyfile dashboard.env turnserver.conf management.json relay.env
```
### Troubleshoot
- **I can't access the `/setup` page**
The setup page is only available when no users exist. If you've already created a user, go to the main login page instead.
- **I forgot my admin password**
You can create a new user via the API using a PAT (Personal Access Token) from an existing admin, or reset the database to start fresh.
- **SSO provider not appearing on login page**
Check that the connector is properly configured in **Settings** → **Identity Providers**. Ensure the redirect URL is correctly configured in your IdP.
For more troubleshooting help, see the [Troubleshooting guide](/selfhosted/troubleshooting).
---
## Legacy: Self-hosting with Zitadel IdP
<Note>
**Deprecated**: This method is no longer recommended for new installations. It is preserved as a reference for users who deployed NetBird using the Zitadel quickstart script prior to version 0.62. For new installations, use the [quickstart approach](#quick-self-hosting) above.
</Note>
The following instructions apply to deployments using the `getting-started-with-zitadel.sh` script, which bundled Zitadel as an external identity provider.
### Download and run the script
```bash
export NETBIRD_DOMAIN=netbird.example.com; curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started-with-zitadel.sh | bash
```
If you want to check the script before running it:
```bash
curl -sSLO https://github.com/netbirdio/netbird/releases/latest/download/getting-started-with-zitadel.sh
# check the script
cat getting-started-with-zitadel.sh
@@ -50,62 +210,30 @@ cat getting-started-with-zitadel.sh
export NETBIRD_DOMAIN=netbird.example.com
bash getting-started-with-zitadel.sh
```
<Note>
Replace `netbird.example.com` with your domain name.
</Note>
Once the script execution is complete, you can access your netbird instance via the URL `https://netbird.example.com` using the credentials displayed in your terminal.
### Add users
If you want to add additional users, you can access Zitadel's management console via the URL `https://netbird.example.com/ui/console` with the same credentials. Follow the [Users guide](https://zitadel.com/docs/guides/manage/console/users)
from Zitadel to add additional local users or integrate Zitadel with your existing identity provider by following the guide [Configure identity providers](https://zitadel.com/docs/guides/integrate/identity-providers).
Once the script execution is complete, you can access your NetBird instance via `https://netbird.example.com` using the credentials displayed in your terminal.
### Backup
To backup your NetBird installation, you need to copy the configuration files, the Management service databases, and Zitadel's database.
### Add users (Zitadel)
To add additional users, access Zitadel's management console via `https://netbird.example.com/ui/console` with the same credentials. Follow the [Users guide](https://zitadel.com/docs/guides/manage/console/users) from Zitadel to add additional local users or integrate Zitadel with your existing identity provider by following the guide [Configure identity providers](https://zitadel.com/docs/guides/integrate/identity-providers).
### Backup (Zitadel)
To backup your NetBird installation with Zitadel, you need to copy the configuration files, the Management service databases, and Zitadel's database.
The configuration files are located in the folder where you ran the installation script. To backup, copy the files to a backup location:
```bash
mkdir backup
cp docker-compose.yml Caddyfile zitadel.env dashboard.env turnserver.conf management.json relay.env zdb.env backup/
```
To save the Management service databases, you need to stop the Management service and copy the files from the store directory using a docker compose command as follows:
To save the Management service databases:
```bash
docker compose stop management
docker compose cp -a management:/var/lib/netbird/ backup/
docker compose start management
```
You can follow the [Cockroach backup guide](https://www.cockroachlabs.com/docs/stable/backup) to backup Zitadel's database, which holds user information.
### Upgrade
<Note>
The users with management on version < [v0.15.3](https://github.com/netbirdio/netbird/releases/tag/v0.15.3)
should first upgrade their systems to [v0.25.9](https://github.com/netbirdio/netbird/releases/tag/v0.25.9),
run management to properly migrate rules to policies, and then upgrade to **0.26.0+**.
</Note>
To upgrade NetBird to the latest version, you need to review the [release notes](https://github.com/netbirdio/netbird/releases) for any breaking changes and follow the upgrade steps below:
1. Run the backup steps described in the [backup](#backup) section.
2. Pull the latest NetBird docker images:
```bash
docker compose pull management dashboard signal relay
```
3. Restart the NetBird containers with the new images:
```bash
docker compose up -d --force-recreate management dashboard signal relay
```
### Support browser clients
If you deployed NetBird before version **0.59.0** and want to use browser clients, you need to update your Signal, Management, Dashboard and Relay services, see [Upgrade](#upgrade), then you need to edit the `Caddyfile` file to enable support for browser clients by adding the following lines to the `Caddyfile`:
```
reverse_proxy /ws-proxy/management* management:80
reverse_proxy /ws-proxy/signal* signal:80
```
Then restart the Caddy service to apply the changes:
```bash
docker compose restart caddy
```
### Remove
To remove the NetBird installation and all related data from your server, run these commands from the folder where you installed NetBird:
### Remove (Zitadel)
```bash
# remove all NetBird-related containers and volumes (data)
docker compose down --volumes
@@ -113,12 +241,24 @@ docker compose down --volumes
rm -f docker-compose.yml Caddyfile zitadel.env dashboard.env machinekey/zitadel-admin-sa.token turnserver.conf management.json
```
### Troubleshoot
### Migrating from Zitadel to Local Users
- I'm trying to register a user but I didn't receive a verification code. What's the problem?
If you have an existing Zitadel deployment and want to migrate:
The NetBird quickstart script generates a user name and a password for the administrator. This should be enough to login and manage your network.
If you want to register a new user and invite them via email, you need to configure a SMTP server in Zitadel. See [this guide](https://zitadel.com/docs/guides/manage/console/instance-settings#smtp) or details.
1. **Option A**: Keep Zitadel as an external provider—add it as an identity provider in Settings
2. **Option B**: Recreate users as local users and decommission Zitadel
See the [Migration Guide](/selfhosted/identity-providers#migration-guide) for detailed steps.
### Upgrade (Legacy)
<Note>
If upgrading from management version < [v0.15.3](https://github.com/netbirdio/netbird/releases/tag/v0.15.3),
first upgrade to [v0.25.9](https://github.com/netbirdio/netbird/releases/tag/v0.25.9),
run management to migrate rules to policies, then upgrade to **0.26.0+**.
</Note>
---
## Get in touch
@@ -126,4 +266,4 @@ Feel free to ping us on [Slack](/slack-url) if you have any questions
- NetBird managed version: [https://app.netbird.io](https://app.netbird.io)
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on X](https://x.com/netbird)
- Follow us [on X](https://x.com/netbird)

162
src/pages/selfhosted/troubleshooting.mdx
View File

@@ -1,5 +1,70 @@
# Troubleshooting
This page will help with various issues when self-hosting NetBird.
## Embedded IdP Issues
### Setup page not accessible
**Problem**: You can't access the `/setup` page to create the first user.
**Solutions**:
- The `/setup` page is only available when no users exist. If you've already created a user, use the regular login page.
- Check that the embedded IdP is enabled in your configuration.
- Verify the Management service is running: `docker compose logs management`
### "Setup already completed" error (HTTP 412)
**Problem**: The setup endpoint returns a 412 error.
**Solution**: Setup has already been completed. The first user was already created. Use the regular login page to sign in.
### Password not working after user creation
**Problem**: You created a user but the password doesn't work.
**Solutions**:
- Passwords are shown only once during user creation. If you didn't save it, you'll need to delete and recreate the user.
- Via API, you can create a new user with a new password.
- For the owner account, you may need to reset the database if no other admins exist.
### SSO connector not appearing on login page
**Problem**: You configured an identity provider but it doesn't show on the login page.
**Solutions**:
1. Verify the connector was saved: Go to **Settings** → **Identity Providers**
2. Check that the redirect URL is correctly configured in your IdP
3. Review Management service logs for configuration errors: `docker compose logs management`
4. Ensure the IdP application has the correct redirect URI from NetBird
### "Invalid redirect URI" error from IdP
**Problem**: When clicking an SSO button, the IdP returns an invalid redirect URI error.
**Solutions**:
1. Copy the exact redirect URL from NetBird (shown after saving the connector)
2. Add it to your IdP's allowed redirect URIs
3. Check for trailing slashes or typos
4. Some IdPs are case-sensitive
### Identity Providers tab not visible
**Problem**: You don't see the Identity Providers tab in Settings.
**Solution**: This tab is only visible when the embedded IdP is enabled. Check your deployment configuration:
- For quickstart deployments, the embedded IdP should be enabled by default
- For advanced deployments, ensure `EmbeddedIdP.Enabled` is set to `true` in management.json
### Users not syncing from SSO provider
**Problem**: Users who authenticate via SSO don't appear in the user list.
**Solutions**:
- Users appear after their first successful login, not immediately after connector configuration
- Check that the SSO flow completes successfully (user should land on Dashboard)
- Review Management logs for any token validation errors
## Debugging TURN connections
In the case that the peer-to-peer connection is not an option then the peer will use the TURN server for the secure connection establishment. If the connection is not possible even with TURN (Relay),
@@ -21,3 +86,100 @@ You should see an output similar to the following:
</p>
Where you have the following types: `host` (local address), `srflx` (STUN reflexive address), `relay`
(TURN relay address). If `srflx` and `relay` are not present then the TURN server is not working or not accessible and you should review the required ports in the [requirements section](/selfhosted/selfhosted-guide#requirements).
## Dashboard Issues
### Dashboard shows blank page
**Problem**: The Dashboard loads but shows a blank page or errors.
**Solutions**:
1. Check browser console for JavaScript errors (F12 → Console)
2. Verify the Dashboard can reach the Management API
3. Check CORS configuration if running behind a custom reverse proxy
4. Clear browser cache and try again
### "Unauthorized" or "403" errors
**Problem**: API calls return unauthorized or forbidden errors.
**Solutions**:
1. Verify your authentication token is valid
2. Check that the user has appropriate permissions
3. For API access, ensure you're using a valid Personal Access Token (PAT)
4. Review Management service logs for detailed error information
## Certificate Issues
### Let's Encrypt certificate not renewing
**Problem**: SSL certificate expires and doesn't auto-renew.
**Solutions**:
1. Ensure port 80 is accessible for ACME challenge
2. Check Caddy logs: `docker compose logs caddy`
3. Verify the domain points to the correct IP
4. Manually trigger renewal: `docker compose exec caddy caddy reload`
### Certificate errors with custom reverse proxy
**Problem**: SSL errors when using your own reverse proxy.
**Solutions**:
1. Ensure your reverse proxy terminates SSL correctly
2. Set `NETBIRD_DISABLE_LETSENCRYPT=true` in your configuration
3. Configure proper headers (X-Forwarded-For, X-Forwarded-Proto)
4. Verify HTTP/2 support is enabled for gRPC endpoints
## Connection Issues
### Peers can't connect to each other
**Problem**: Peers are registered but can't establish connections.
**Solutions**:
1. Check that UDP port 3478 is accessible (STUN/TURN)
2. Verify the TURN server is working (see [TURN debugging](#debugging-turn-connections))
3. Check firewall rules on both peers
4. Review peer logs: `netbird status -d`
### Management service unreachable
**Problem**: Clients can't connect to the Management service.
**Solutions**:
1. Verify port 443 is accessible
2. Check DNS resolution for your domain
3. Review Management logs: `docker compose logs management`
4. Test with curl: `curl -v https://your-domain.com/api/health`
## Database Issues
### Management service won't start after upgrade
**Problem**: After upgrading, the Management service fails to start.
**Solutions**:
1. Check logs for migration errors: `docker compose logs management`
2. Ensure you followed the [upgrade path](/selfhosted/selfhosted-quickstart#upgrade) for your version
3. Restore from backup if needed
4. For major version jumps, you may need intermediate upgrades
### Data corruption after power loss
**Problem**: Services don't start properly after unexpected shutdown.
**Solutions**:
1. Check for database lock files
2. Review all service logs
3. Consider restoring from backup
4. For SQLite databases, you may need to run integrity checks
## Getting Help
If you're still experiencing issues:
1. **Check logs**: `docker compose logs` for all services
2. **Search existing issues**: [GitHub Issues](https://github.com/netbirdio/netbird/issues)
3. **Join our community**: [Slack Channel](/slack-url)
4. **Open an issue**: Include logs, configuration (without secrets), and steps to reproduce