mirror of
https://github.com/netbirdio/docs.git
synced 2026-04-27 21:06:38 +00:00
DEX Docs Overall Updates
This commit is contained in:
Brandon Hopkins
@@ -1,153 +1,213 @@
|
||||
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 the embedded IdP. This was the default approach in previous NetBird versions.
|
||||
|
||||
<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 +225,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/embedded-idp)
|
||||
- [Migration Guide](/selfhosted/identity-providers/migration)
|
||||
Reference in New Issue
Block a user