some file

Zitadel SSO with NetBird Self-Hosted (Advanced)

Zitadel 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.

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.

Standalone Setup (Advanced)

NetBird includes built-in local user management powered by an embedded IdP, allowing you to create and manage users directly without requiring an external identity provider. You can also add multiple external identity providers alongside local users, giving users multiple login options.

We highly recommend using the simpler setup that adds Zitadel as an external IdP directly in the NetBird Management Dashboard. This approach requires minimal configuration, works alongside local users, and doesn't require replacing your embedded IdP. See the Management Setup (Recommended) section in the main Zitadel documentation.

The standalone setup below replaces your embedded IdP entirely and is only recommended for experienced Zitadel administrators who need full control over authentication and user management.

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 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) section above.

If you prefer not to self-host, Zitadel offers a managed cloud option at zitadel.com.

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

New project

  1. Click Projects and select NETBIRD project
  2. Click New in Applications section
  3. Fill in:
    • Name: netbird
    • Type of Application: User Agent

New application

  1. Click Continue and set:
    • Authentication Method: PKCE

Application auth

  1. Click Continue and configure:
    • Redirect URIs:
      • https://<domain>/auth
      • https://<domain>/silent-auth
      • http://localhost:53000
    • Post Logout URIs: https://<domain>/

Application URIs

  1. Click Create and then Close
  2. Under Grant Types, select Authorization Code, Device Code, and Refresh Token
  3. Click Save

Application overview

  1. 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

Token settings

Step 3: Configure Redirect Settings (Development Only)

This step is only for development mode without SSL.

  1. Click Redirect Settings in the left menu
  2. Toggle Development Mode
  3. Click Save

Redirect settings

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

Create service user

  1. Click Actions in the top right corner
  2. Click Generate Client Secret
  3. Copy ClientSecret for later use

Service user secret

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

Service account role

Step 6: Configure NetBird

Your authority OIDC configuration will be available at:

https://<YOUR_ZITADEL_HOST_AND_PORT>/.well-known/openid-configuration

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

Set properties in the setup.env file:

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.

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

"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