netbird-docs/src/pages/selfhosted/identity-providers/zitadel.mdx

import {Note} from "@/components/mdx";

# Zitadel

[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>
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 an external IdP directly in the NetBird Management Dashboard.
</Note>

## Management Setup (Recommended)

Add Zitadel as an external IdP directly in the NetBird Management Dashboard. This is the simplest approach for new deployments or when migrating from the previous quickstart.

### Prerequisites

- NetBird self-hosted with embedded IdP enabled
- Zitadel instance (cloud or self-hosted)

### Step 1: Create Application in Zitadel

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**

### Step 2: Add Identity Provider in NetBird

1. Log in to your NetBird Dashboard
2. Navigate to **Settings** → **Identity Providers**
3. Click **Add Identity Provider**
4. Fill in the fields:

| 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`) |

5. Click **Save**

### Step 3: Configure Redirect URI

After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your Zitadel application:

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**

### Step 4: Test the Connection

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

---

## 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 [Management Setup (Recommended)](#management-setup-recommended) section above.

<Note>
If you prefer not to self-host, Zitadel offers a managed cloud option at [zitadel.com](https://zitadel.com/).
</Note>

### Prerequisites

- 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-new-project.png" alt="New project" className="imagewrapper-big"/>
</p>

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-new-application.png" alt="New application" className="imagewrapper-big"/>
</p>

7. Click **Continue** and set:
   - **Authentication Method**: `PKCE`

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-new-application-auth.png" alt="Application auth" className="imagewrapper-big"/>
</p>

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-new-application-uri.png" alt="Application URIs" className="imagewrapper-big"/>
</p>

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
```

<Note>
Double-check if the endpoint returns a JSON response by calling it from your browser.
</Note>

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>"
NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access api"
NETBIRD_AUTH_AUDIENCE="<CLIENT_ID>"
NETBIRD_AUTH_REDIRECT_URI="/auth"
NETBIRD_AUTH_SILENT_REDIRECT_URI="/silent-auth"

NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="hosted"
NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID="<CLIENT_ID>"
NETBIRD_AUTH_DEVICE_AUTH_AUDIENCE="<CLIENT_ID>"

NETBIRD_MGMT_IDP="zitadel"
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 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 external IdP directly in NetBird Management Dashboard**:
1. Deploy new NetBird version with embedded IdP
2. Add your existing Zitadel as an external IdP directly in the NetBird Management Dashboard (follow Management 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)