Zitadel

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.

Connector Setup (Recommended)

Add Zitadel as a connector to the embedded IdP. 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 Connector 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:

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

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

4. Click Projects and select NETBIRD project
5. Click New in Applications section
6. Fill in:
   • Name: netbird
   • Type of Application: User Agent

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

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

9. Click Create and then Close
10. Under Grant Types, select Authorization Code, Device Code, and Refresh Token
11. Click Save

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

Step 3: Configure Redirect Settings (Development Only)

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

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

6. Click Actions in the top right corner
7. Click Generate Client Secret
8. Copy ClientSecret for later use

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

Step 6: Configure NetBird

Your authority OIDC configuration will be available at:

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

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 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
• Zitadel GitHub
• Embedded IdP Overview
• Migration Guide