"
```
-### Step 4: Continue with the NetBird Self-hosting Guide
+#### 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).
-## Google Workspace
+### Google Workspace
This guide is a part of the [NetBird Self-hosting Guide](/getting-started/self-hosting) and explains how to integrate
**self-hosted** NetBird with [Google Workspace](https://workspace.google.com/).
@@ -985,7 +848,7 @@ Before you start creating and configuring an Google Workspace application, ensur
- Create new `Netbird` project in Google cloud console https://console.cloud.google.com.
- Enable `Admin SDK API` for `Netbird` project at https://console.cloud.google.com/apis/library/admin.googleapis.com.
-### Step 1: Configure OAuth consent screen
+#### 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
@@ -1008,7 +871,7 @@ Before you start creating and configuring an Google Workspace application, ensur
-### Step 2: Create OAuth 2.0 credentials
+#### 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`
@@ -1024,7 +887,7 @@ Before you start creating and configuring an Google Workspace application, ensur
-### Step 3: Create service account
+#### 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`
@@ -1036,7 +899,7 @@ Before you start creating and configuring an Google Workspace application, ensur
-### Step 4: Create service account keys
+#### 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
@@ -1053,7 +916,7 @@ Read how to manage and secure your service keys [here](https://cloud.google.com/
- Open downloaded json file and take note of `client_id` will be used later as `Service Account Client ID`
-### Step 5: Grant user and schema management admin role to service account
+#### Step 5: Grant user and schema 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`
@@ -1082,7 +945,7 @@ Read how to manage and secure your service keys [here](https://cloud.google.com/
-### Step 6: Granting service account access to organization data
+#### Step 6: Granting service account access to organization data
- Navigate to [Admin Console](https://admin.google.com/ac/home) page
- Select `Security` > `Access and data control` > `API controls` and then click `MANAGE DOMAIN WIDE DELEGATION`
- Click `Add new`
@@ -1124,5 +987,147 @@ NETBIRD_IDP_MGMT_EXTRA_SERVICE_ACCOUNT_KEY=""
NETBIRD_IDP_MGMT_EXTRA_CUSTOMER_ID=""
```
-### Step 7: 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).
\ No newline at end of file
+#### Step 7: 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).
+
+### 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 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.
+
+
+ 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](/integrations/identity-providers/self-hosted/using-netbird-with-keycloak).
+
+
+#### Step 1: Create Auth0 account
+To create an Auth0 account, sign up at [https://auth0.com](https://auth0.com/).
+
+There are multiple properties of the **`setup.env`** file that we will configure in this guide:
+- `NETBIRD_AUTH_CLIENT_ID`
+- `NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT`
+- `NETBIRD_USE_AUTH0`
+- `NETBIRD_AUTH_AUDIENCE`
+- `NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID` (Optional)
+- `NETBIRD_MGMT_IDP`
+- `NETBIRD_IDP_MGMT_CLIENT_ID`
+- `NETBIRD_IDP_MGMT_CLIENT_SECRET`
+- `NETBIRD_IDP_MGMT_EXTRA_AUDIENCE`
+
+#### Step 2: Create and configure Auth0 application
+
+This Auth0 application will be used to authorize access to NetBird Dashboard (Web UI).
+
+- Follow the steps in the [Auth0 React SDK Guide](https://auth0.com/docs/quickstart/spa/react/01-login#configure-auth0)
+up until "Install the Auth0 React SDK".
+- Use **`https://YOUR DOMAIN`** as: `Allowed Callback URLs`, `Allowed Logout URLs`, `Allowed Web Origins`, `Allowed Origins (CORS)`
+
+ Make sure that **`Token Endpoint Authentication Method`** is set to **`None`**.
+
+
+- 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:
+
+```bash
+ https:///.well-known/openid-configuration
+```
+
+ Double-check if the endpoint returns a JSON response by calling it from your browser.
+
+
+#### Step 3: Create and configure Auth0 API
+
+This Auth0 API will be used to access NetBird Management Service API.
+
+- Follow the steps in the [Auth0 Create An API](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.
+
+#### Step 4: Enable Interactive SSO Login (Optional)
+
+The [Interactive SSO Login feature](/how-to/installation#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](/how-to/register-machines-using-setup-keys)
+and is optional.
+
+You can enable it by following these steps:
+- Log in to your Auth0 account https://manage.auth0.com/
+- Go to `Applications` (left-hand menu)
+- Click `Create Application` button (top right)
+- Fill in the form with the following values:
+ - Name: `Interactive Login`
+ - Application type: `Native`
+- Click `Create`
+
+
+ 
+
+
+- Click `Settings` tab
+- Copy **`Client ID`** to `NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID` in the `setup.env` file
+
+
+ 
+
+
+- Scroll down to the `Advanced Settings` section
+- Enable **`Device Code`**
+- Click `Save Changes`
+
+
+ 
+
+
+#### Step 5: Create and configuire Machine to Machine application.
+This application will be used to authorize access to Auth0 Management API.
+
+- Log in to your Auth0 account https://manage.auth0.com/
+- Go to `Applications` (left-hand menu)
+- Click `Create Application` button (top right)
+- Fill in the form with the following values:
+ - Name: `Netbird API`
+ - Application type: `Machine to Machine Applications`
+- Click `Create`
+
+
+ 
+
+
+- Fill the form with the following values:
+ - API: `Auth0 Management API`
+ - Permissions: `read:users`, `update:users`, `create:users`, `read:users_app_metadata`, `update:users_app_metadata`, `create:users_app_metadata`
+ - Click `Authorize`
+
+
+ 
+
+
+- Click `Settings` tab
+- Copy **`Client ID`** to `NETBIRD_IDP_MGMT_CLIENT_ID` in the `setup.env` file
+- Copy **`Client SECRET`** to `NETBIRD_IDP_MGMT_CLIENT_SECRET` in the `setup.env` file
+- Copy **`DOMAIN`** to `NETBIRD_IDP_MGMT_EXTRA_AUDIENCE` in the `setup.env` file
+
+
+ 
+
+
+- Set properties in the `setup.env` file:
+```shell
+NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https:///.well-known/openid-configuration"
+NETBIRD_USE_AUTH0=true
+NETBIRD_AUTH_CLIENT_ID=""
+NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access api email_verified"
+NETBIRD_AUTH_AUDIENCE=""
+NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID=""
+
+NETBIRD_MGMT_IDP="auth0"
+NETBIRD_IDP_MGMT_CLIENT_ID=""
+NETBIRD_IDP_MGMT_CLIENT_SECRET=""
+NETBIRD_IDP_MGMT_EXTRA_AUDIENCE="https:///api/v2/"
+```
+
+
+#### Step 6: Continue with the NetBird Self-hosting Guide
+You've configured all required resources in Auth0. You can now continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
diff --git a/src/pages/selfhosted/selfhosted-guide.mdx b/src/pages/selfhosted/selfhosted-guide.mdx
index 738e8071..8163d7b5 100644
--- a/src/pages/selfhosted/selfhosted-guide.mdx
+++ b/src/pages/selfhosted/selfhosted-guide.mdx
@@ -13,7 +13,58 @@ If you would like to learn more about the architecture please refer to the [Arch
We run NetBird in the cloud, and it will take less than 5 minutes to get started with our managed version. [Check it out!](https://netbird.io/pricing)
-## Requirements
+
+## Getting started with NetBird and Zitadel
+In this guide, we will guide you through deploying NetBird with [Zitadel](https://zitadel.com/)
+as the identity provider for user management using a getting started setup script and docker containers.
+
+
+ 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](#advanced-guide-with-a-custom-identity-provider) for installations with different IDPs.
+
+
+### Requirements
+
+**Infrastructure requirements:**
+- A Linux VM with at least **1CPU** and **2GB** of memory.
+- The VM should be publicly accessible on TCP ports **80** and **443** and UDP ports: **3478**, **49152-65535**.
+- **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-zitadel.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-zitadel.sh
+# check the script
+cat getting-started-with-zitadel.sh
+# run the script
+export NETBIRD_DOMAIN=netbird.example.com
+bash getting-started-with-zitadel.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.
+
+### Creating 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).
+
+## Advanced guide with a custom identity provider
+This guide will walk you through deploying NetBird with a custom identity provider for user management.
+
+### Requirements
- Virtual machine offered by any cloud provider (e.g., AWS, DigitalOcean, Hetzner, Google Cloud, Azure ...).
- Any Linux OS.
@@ -25,7 +76,7 @@ If you would like to learn more about the architecture please refer to the [Arch
For this tutorial we will be using domain ```demo.netbird.io``` which points to our Ubuntu 22.04 machine hosted at Hetzner.
-## Step 1: Get the latest stable NetBird code
+### Step 1: Get the latest stable NetBird code
```bash
#!/bin/bash
@@ -43,7 +94,7 @@ Then switch to the infra folder that contains docker-compose file:
```bash
cd netbird/infrastructure_files/
```
-## Step 2: Prepare configuration files
+### Step 2: Prepare configuration files
To simplify the setup we have prepared a script to substitute required properties in the [docker-compose.yml.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/docker-compose.yml.tmpl) and [management.json.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/management.json.tmpl) files.
@@ -80,7 +131,7 @@ This can be any email address. [Let's Encrypt](https://letsencrypt.org/) will cr
If you want to setup netbird with your own reverse-Proxy and without using the integrated letsencrypt, follow [this step here instead](#advanced-running-netbird-behind-an-existing-reverse-proxy).
-## Step 3: Configure Identity Provider (IDP)
+### Step 3: Configure Identity Provider (IDP)
NetBird supports generic OpenID (OIDC) protocol allowing integration with any IDP following the specification.
@@ -99,7 +150,7 @@ Pick the one that suits your needs, follow the steps, and continue with this gui
- Continue with [Okta](/selfhosted/identity-providers#okta).
- Continue with [Auth0](/selfhosted/identity-providers#auth0).
-## Step 4: Disable single account mode (optional)
+### Step 4: Disable single account mode (optional)
NetBird Management service runs in a single account mode by default since version v0.10.1.
Management service was creating a separate account for each registered user before v0.10.1.
@@ -110,7 +161,7 @@ If you want to disable the single-account mode, set `--disable-single-account-mo
[docker-compose.yml.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/docker-compose.yml.tmpl)
`command` section of the `management` service.
-## Step 5: Run configuration script
+### Step 5: Run configuration script
Make sure all the required properties set in the ```setup.env``` file and run:
```bash
@@ -119,12 +170,12 @@ Make sure all the required properties set in the ```setup.env``` file and run:
This will export all the properties as environment variables and generate ```docker-compose.yml``` and ```management.json``` files substituting required variables.
-## Step 6: Run docker compose:
+### Step 6: Run docker compose:
```bash
docker-compose up -d
```
-## Step 7: Check docker logs (Optional)
+### Step 7: Check docker logs (Optional)
```bash
docker-compose logs signal
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-### Step 3: Application Redirect Configuration
+#### Step 3: Application Redirect Configuration
-### Step 4: Create a Service User
+#### Step 4: Create a Service User
In this step we will create a `netbird` service user.
@@ -680,7 +131,7 @@ In this step we will generate `ClientSecret` for the `netbird` service user.
-### Step 5: Grant manage-users role to netbird service user
+#### Step 5: Grant manage-users role to netbird service user
In this step we will grant `Org User Manager` role to `netbird` service user.
@@ -726,10 +177,266 @@ NETBIRD_IDP_MGMT_EXTRA_MANAGEMENT_ENDPOINT="https://
-### Step 2: Create external applications
+#### Step 2: Create external applications
In this step, we will create external applications in Authentik.
- Navigate to authentik admin interface
@@ -783,7 +490,7 @@ In this step, we will create external applications in Authentik.
-### Step 3: Create service account
+#### Step 3: Create service account
In this step, we will create service account.
- Navigate to authentik admin interface
@@ -803,7 +510,7 @@ In this step, we will create service account.
-### Step 4: Add service account to admin group
+#### Step 4: Add service account to admin group
In this step, we will add `Netbird` service account to `authentik Admins` group.
- Navigate to authentik admin interface
@@ -843,10 +550,166 @@ NETBIRD_IDP_MGMT_EXTRA_USERNAME="Netbird"
NETBIRD_IDP_MGMT_EXTRA_PASSWORD="
-### Step 2. Create and configure Okta native application
+#### 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`
@@ -926,7 +789,7 @@ In this step, we will create and configure Netbird native application in okta.
-### 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
@@ -971,10 +834,10 @@ NETBIRD_AUTH_DEVICE_AUTH_USE_ID_TOKEN=true
NETBIRD_MGMT_IDP="okta"
NETBIRD_IDP_MGMT_EXTRA_API_TOKEN="