diff --git a/src/pages/selfhosted/identity-providers/dex.mdx b/src/pages/selfhosted/identity-providers/dex.mdx new file mode 100644 index 00000000..804dd157 --- /dev/null +++ b/src/pages/selfhosted/identity-providers/dex.mdx @@ -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). + + + 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. + + +## 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:///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: + redirectURIs: + - https:///nb-auth + - https:///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@" + hash: "" + username: "admin" + userID: "admin-user-id-001" +``` + + +Generate a bcrypt hash for the password using: +```bash +htpasswd -bnBC 10 "" "your-password" | tr -d ':\n' +``` + + +## 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:///dex/.well-known/openid-configuration" +NETBIRD_USE_AUTH0=false +NETBIRD_AUTH_CLIENT_ID="netbird-dashboard" +NETBIRD_AUTH_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:///dex", + "AuthAudience": "netbird-dashboard", + "OIDCConfigEndpoint": "https:///dex/.well-known/openid-configuration" + }, + "IdpManagerConfig": { + "ManagerType": "dex", + "ClientConfig": { + "Issuer": "https:///dex" + }, + "ExtraConfig": { + "GRPCAddr": "dex:5557" + } + }, + "DeviceAuthorizationFlow": { + "Provider": "hosted", + "ProviderConfig": { + "Audience": "netbird-cli", + "ClientID": "netbird-cli", + "Scope": "openid profile email offline_access", + "DeviceAuthEndpoint": "https:///dex/device/code", + "TokenEndpoint": "https:///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:// +NETBIRD_MGMT_GRPC_API_ENDPOINT=https:// +AUTH_AUDIENCE=netbird-dashboard +AUTH_CLIENT_ID=netbird-dashboard +AUTH_CLIENT_SECRET= +AUTH_AUTHORITY=https:///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:///dex/callback +``` + + +See the [Dex connectors documentation](https://dexidp.io/docs/connectors/) for all available connector types. + + +## 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:///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). \ No newline at end of file diff --git a/src/pages/selfhosted/identity-providers/index.mdx b/src/pages/selfhosted/identity-providers/index.mdx index c383f83b..0dfc6c50 100644 --- a/src/pages/selfhosted/identity-providers/index.mdx +++ b/src/pages/selfhosted/identity-providers/index.mdx @@ -49,6 +49,12 @@ Self-hosted Identity Providers give you full control over authentication and aut +### 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. + + + ## 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. diff --git a/src/pages/selfhosted/selfhosted-quickstart-dex.mdx b/src/pages/selfhosted/selfhosted-quickstart-dex.mdx new file mode 100644 index 00000000..c4008fd4 --- /dev/null +++ b/src/pages/selfhosted/selfhosted-quickstart-dex.mdx @@ -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). + + + 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/) + + +## 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. + + + 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. + + +### 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 +``` + + Replace `netbird.example.com` with your domain name. + +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 +``` + + + 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. + + +### 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 + +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+**. + + +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) \ No newline at end of file diff --git a/src/pages/selfhosted/selfhosted-quickstart.mdx b/src/pages/selfhosted/selfhosted-quickstart.mdx index be55b194..cc48b843 100644 --- a/src/pages/selfhosted/selfhosted-quickstart.mdx +++ b/src/pages/selfhosted/selfhosted-quickstart.mdx @@ -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). - 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) + Want to try NetBird functionality before self-hosting? Our managed cloud version gets you started in just a few clicks, no + infrastructure required. [Try it free!](https://app.netbird.io/) ## 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. + + For a lightweight alternative to Zitadel that may be better suited for a home lab, see the [Dex quickstart](/selfhosted/selfhosted-quickstart-dex). + + ### Requirements **Infrastructure requirements:**