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

Add Dex identity provider documentation and quickstart guide

Browse Source 
Add comprehensive documentation for using Dex as a lightweight identity
provider alternative for self-hosted NetBird deployments. Includes a
quickstart guide with one-line installation script and detailed manual
configuration instructions. Also improves managed version notes across
quickstart guides with clearer calls-to-action.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
braginini
2025-12-18 17:42:06 -05:00
parent 3d21a987a8
commit 556efd777b
4 changed files with 443 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

243
src/pages/selfhosted/identity-providers/dex.mdx Normal file
View File

@@ -0,0 +1,243 @@
import {Note} from "@/components/mdx";
# Dex with NetBird Self-Hosted
This guide is a part of the [NetBird Self-hosting Guide](/docs/selfhosted/selfhosted-guide) and explains how to integrate
**self-hosted** NetBird with [Dex](https://dexidp.io).
<Note>
For the quickest setup with Dex, use our [one-line installation script](/selfhosted/selfhosted-quickstart-dex).
This guide is for users who want to manually configure Dex with an existing NetBird installation.
</Note>
## Overview
[Dex](https://dexidp.io) is a lightweight, open-source OIDC identity provider that acts as a portal to other identity providers.
It's ideal for self-hosted NetBird deployments where you want:
- Minimal resource usage (~50MB memory)
- Simple static user configuration
- Optional integration with external identity providers (LDAP, GitHub, Google, SAML, etc.)
## Step 1: Configure Dex
Create a `dex.yaml` configuration file:
```yaml
issuer: https://<YOUR_NETBIRD_DOMAIN>/dex
storage:
type: sqlite3
config:
file: /var/dex/dex.db
web:
http: 0.0.0.0:5556
# gRPC API for user management (used by NetBird IDP manager)
grpc:
addr: 0.0.0.0:5557
oauth2:
skipApprovalScreen: true
# Static OAuth2 clients for NetBird
staticClients:
# Dashboard client
- id: netbird-dashboard
name: NetBird Dashboard
secret: <GENERATE_A_RANDOM_SECRET>
redirectURIs:
- https://<YOUR_NETBIRD_DOMAIN>/nb-auth
- https://<YOUR_NETBIRD_DOMAIN>/nb-silent-auth
# CLI client (public - uses PKCE)
- id: netbird-cli
name: NetBird CLI
public: true
redirectURIs:
- http://localhost:53000/
- http://localhost:54000/
# Enable password database for static users
enablePasswordDB: true
# Static users - add more users here as needed
staticPasswords:
- email: "admin@<YOUR_NETBIRD_DOMAIN>"
hash: "<BCRYPT_HASH_OF_PASSWORD>"
username: "admin"
userID: "admin-user-id-001"
```
<Note>
Generate a bcrypt hash for the password using:
```bash
htpasswd -bnBC 10 "" "your-password" | tr -d ':\n'
```
</Note>
## Step 2: Add Dex to Docker Compose
Add the Dex service to your `docker-compose.yml`:
```yaml
services:
dex:
image: ghcr.io/dexidp/dex:v2.38.0
container_name: netbird-dex
restart: unless-stopped
networks: [netbird]
volumes:
- ./dex.yaml:/etc/dex/config.docker.yaml:ro
- netbird_dex_data:/var/dex
command: ["dex", "serve", "/etc/dex/config.docker.yaml"]
logging:
driver: "json-file"
options:
max-size: "500m"
max-file: "2"
volumes:
netbird_dex_data:
```
## Step 3: Configure Caddy reverse proxy
Add Dex routing to your `Caddyfile`:
```
# Dex
reverse_proxy /dex/* dex:5556
```
## Step 4: Configure NetBird Management
Set properties in the `setup.env` file:
```shell
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://<YOUR_NETBIRD_DOMAIN>/dex/.well-known/openid-configuration"
NETBIRD_USE_AUTH0=false
NETBIRD_AUTH_CLIENT_ID="netbird-dashboard"
NETBIRD_AUTH_CLIENT_SECRET="<YOUR_DEX_DASHBOARD_CLIENT_SECRET>"
NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access"
NETBIRD_AUTH_AUDIENCE="netbird-dashboard"
NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID="netbird-cli"
NETBIRD_AUTH_DEVICE_AUTH_AUDIENCE="netbird-cli"
NETBIRD_AUTH_REDIRECT_URI="/nb-auth"
NETBIRD_AUTH_SILENT_REDIRECT_URI="/nb-silent-auth"
NETBIRD_MGMT_IDP="dex"
```
Or configure directly in `management.json`:
```json
{
"HttpConfig": {
"AuthIssuer": "https://<YOUR_NETBIRD_DOMAIN>/dex",
"AuthAudience": "netbird-dashboard",
"OIDCConfigEndpoint": "https://<YOUR_NETBIRD_DOMAIN>/dex/.well-known/openid-configuration"
},
"IdpManagerConfig": {
"ManagerType": "dex",
"ClientConfig": {
"Issuer": "https://<YOUR_NETBIRD_DOMAIN>/dex"
},
"ExtraConfig": {
"GRPCAddr": "dex:5557"
}
},
"DeviceAuthorizationFlow": {
"Provider": "hosted",
"ProviderConfig": {
"Audience": "netbird-cli",
"ClientID": "netbird-cli",
"Scope": "openid profile email offline_access",
"DeviceAuthEndpoint": "https://<YOUR_NETBIRD_DOMAIN>/dex/device/code",
"TokenEndpoint": "https://<YOUR_NETBIRD_DOMAIN>/dex/token"
}
},
"PKCEAuthorizationFlow": {
"ProviderConfig": {
"Audience": "netbird-cli",
"ClientID": "netbird-cli",
"Scope": "openid profile email offline_access",
"RedirectURLs": ["http://localhost:53000/", "http://localhost:54000/"]
}
}
}
```
## Step 5: Configure Dashboard
Set properties in `dashboard.env`:
```shell
NETBIRD_MGMT_API_ENDPOINT=https://<YOUR_NETBIRD_DOMAIN>
NETBIRD_MGMT_GRPC_API_ENDPOINT=https://<YOUR_NETBIRD_DOMAIN>
AUTH_AUDIENCE=netbird-dashboard
AUTH_CLIENT_ID=netbird-dashboard
AUTH_CLIENT_SECRET=<YOUR_DEX_DASHBOARD_CLIENT_SECRET>
AUTH_AUTHORITY=https://<YOUR_NETBIRD_DOMAIN>/dex
USE_AUTH0=false
AUTH_SUPPORTED_SCOPES=openid profile email offline_access
AUTH_REDIRECT_URI=/nb-auth
AUTH_SILENT_REDIRECT_URI=/nb-silent-auth
```
## Adding External Identity Providers
Dex supports various external identity providers through connectors. Add them to your `dex.yaml`:
### LDAP Example
```yaml
connectors:
- type: ldap
id: ldap
name: LDAP
config:
host: ldap.example.com:636
insecureNoSSL: false
bindDN: cn=admin,dc=example,dc=com
bindPW: admin
userSearch:
baseDN: ou=users,dc=example,dc=com
filter: "(objectClass=person)"
username: uid
idAttr: uid
emailAttr: mail
nameAttr: cn
```
### GitHub Example
```yaml
connectors:
- type: github
id: github
name: GitHub
config:
clientID: $GITHUB_CLIENT_ID
clientSecret: $GITHUB_CLIENT_SECRET
redirectURI: https://<YOUR_NETBIRD_DOMAIN>/dex/callback
```
<Note>
See the [Dex connectors documentation](https://dexidp.io/docs/connectors/) for all available connector types.
</Note>
## Step 6: Start Services
Start Dex and restart NetBird services:
```bash
docker compose up -d dex
docker compose restart management dashboard
```
Verify Dex is running:
```bash
curl -k https://<YOUR_NETBIRD_DOMAIN>/dex/.well-known/openid-configuration
```
## Step 7: Continue with the NetBird Self-hosting Guide
You've configured all required resources in Dex. You can now continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).

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

@@ -49,6 +49,12 @@ Self-hosted Identity Providers give you full control over authentication and aut
<Button href="/selfhosted/identity-providers/pocketid" variant="outline">Setup PocketID</Button> <Button href="/selfhosted/identity-providers/pocketid" variant="outline">Setup PocketID</Button>
### Dex
[Dex](https://dexidp.io/) is a lightweight, open-source OIDC identity provider that acts as a portal to other identity providers. It has minimal resource requirements (~50MB memory), supports static user configuration for simple deployments, and can connect to external identity providers like LDAP, GitHub, Google, and SAML. Dex is ideal for resource-constrained environments or when you need a simple, standalone identity solution.
<Button href="/selfhosted/identity-providers/dex" variant="outline">Setup Dex</Button>
## Managed IdPs ## Managed IdPs
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. 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.

188
src/pages/selfhosted/selfhosted-quickstart-dex.mdx Normal file
View File

@@ -0,0 +1,188 @@
# Self-Hosting Quickstart Guide with Dex (5 min)
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.
This guide uses [Dex](https://dexidp.io/) as the identity provider - a lightweight, open-source OIDC provider that's perfect for simple self-hosted deployments.
If you would like to learn more about the architecture please refer to the [Architecture section](/about-netbird/how-netbird-works).
For more feature-rich identity management, see the [Zitadel quickstart](/selfhosted/selfhosted-quickstart-zitadel) or the [Advanced guide with a custom identity provider](/selfhosted/selfhosted-guide#advanced-self-hosting-guide-with-a-custom-identity-provider).
<Note>
Want to try NetBird without the setup overhead? Our managed cloud version gets you started in just a few clicks—no
infrastructure required. [Try it free!](https://app.netbird.io/)
</Note>
## Quick self-hosting with Dex IdP
In this guide, we will guide you through deploying NetBird with [Dex](https://dexidp.io/)
as the identity provider for user management using a single-line setup script and docker containers.
<Note>
This is the quickest way to try self-hosted NetBird with a minimal footprint. It should take around 5 minutes to get started if you already have a public domain and a VM.
Dex is lighter weight than Zitadel, making it ideal for resource-constrained environments.
</Note>
### Requirements
**Infrastructure requirements:**
- A Linux VM with at least **1CPU** and **1GB** of memory (Dex has lower requirements than Zitadel).
- The VM should be publicly accessible on TCP ports **80 (Let's Encrypt)**, **443 (NetBird control plane)**; and UDP ports: **3478 (STUN)**.
- **Public domain** name pointing to the VM.
**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`
### 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-dex.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-with-dex.sh
# check the script
cat getting-started-with-dex.sh
# run the script
export NETBIRD_DOMAIN=netbird.example.com
bash getting-started-with-dex.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
Dex uses static user configuration by default. To add additional users, you need to edit the `dex.yaml` configuration file.
1. Open the `dex.yaml` file in your favorite editor
2. Add a new entry under `staticPasswords`:
```yaml
staticPasswords:
- email: "admin@netbird.example.com"
hash: "$2a$10$..." # existing admin user
username: "admin"
userID: "admin-user-id-001"
- email: "newuser@netbird.example.com"
hash: "$2a$10$..." # bcrypt hash of the password
username: "newuser"
userID: "new-user-id-002"
```
3. Generate a bcrypt hash for the password using:
```bash
htpasswd -bnBC 10 "" "your-password" | tr -d ':\n'
```
4. Restart Dex to apply changes:
```bash
docker compose restart dex
```
<Note>
For more advanced user management, you can configure Dex to use external identity providers like LDAP, GitHub, Google, or SAML.
See the [Dex connectors documentation](https://dexidp.io/docs/connectors/) for details.
</Note>
### Backup
To backup your NetBird installation, you need to copy the configuration files and the Management service 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 dex.yaml 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
```
To backup the Dex database (which stores user sessions):
```bash
docker compose stop dex
docker compose cp -a dex:/var/dex/ backup/
docker compose start dex
```
### 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:
```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 dex.yaml dashboard.env turnserver.conf management.json relay.env .env
```
### Troubleshoot
- I'm trying to add a user but the password hash doesn't work. What's the problem?
Make sure you're generating a valid bcrypt hash. The hash must start with `$2a$`, `$2b$`, or `$2y$`. You can generate one using:
```bash
htpasswd -bnBC 10 "" "your-password" | tr -d ':\n'
```
If `htpasswd` is not available, you can use Python:
```bash
python3 -c "import bcrypt; print(bcrypt.hashpw(b'your-password', bcrypt.gensalt(rounds=10)).decode())"
```
- Dex is not starting or showing errors in logs
Check the Dex logs for specific error messages:
```bash
docker compose logs dex
```
Common issues include invalid YAML syntax in `dex.yaml` or incorrect file permissions.
## Dex vs Zitadel
| Feature | Dex | Zitadel |
|---------|-----|---------|
| Memory footprint | ~50MB | ~500MB+ |
| User management UI | No (config file) | Yes (web console) |
| External IdP support | Yes (connectors) | Yes |
| SMTP/Email invites | No | Yes |
| Best for | Simple deployments, resource-constrained environments | Full-featured self-hosted IdP |
## 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)

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

@@ -8,8 +8,8 @@ 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). If you would like to learn more about the architecture please refer to the [Architecture section](/about-netbird/how-netbird-works).
<Note> <Note>
It might be a good idea to try NetBird before self-hosting on your servers. Want to try NetBird functionality before self-hosting? Our managed cloud version gets you started in just a few clicks, no
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) infrastructure required. [Try it free!](https://app.netbird.io/)
</Note> </Note>
## Quick self-hosting with Zitadel IdP ## Quick self-hosting with Zitadel IdP
@@ -21,6 +21,10 @@ as the identity provider for user management using a single-line setup script an
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. 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.
</Note> </Note>
<Note>
For a lightweight alternative to Zitadel that may be better suited for a home lab, see the [Dex quickstart](/selfhosted/selfhosted-quickstart-dex).
</Note>
### Requirements ### Requirements
**Infrastructure requirements:** **Infrastructure requirements:**