sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-04-19 08:56: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

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)