Zitadel with NetBird Self-Hosted

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.

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 a Project in Zitadel

1. Log in to your Zitadel Console
2. If you don't have a project yet, click New Project (or navigate to an existing project)

3. Fill in the project details:
   • Name: NetBird (or your preferred name)

4. Click Create

Step 2: Create Application in Zitadel

1. Make sure you're in your project (select it from the project dropdown if needed)
2. Click New in the Applications section

3. Fill in:
   • Name: NetBird
   • Type: Web

4. Click Continue
5. Configure authentication:
   • Authentication Method: Code (not PKCE)

6. Don't click Create yet — you'll add the redirect URI in Step 4

Step 3: Get Redirect URL from NetBird

1. Open a new tab or window and log in to your NetBird Dashboard
2. Navigate to Settings → Identity Providers
3. Click Add Identity Provider
4. Fill in the fields (you can leave Client ID and Secret empty for now):

5. NetBird will display a Redirect URL — copy this URL (but don't click Save yet)

Step 4: Complete Application Configuration in Zitadel

1. Return to the Zitadel Console tab
2. In the redirect URIs field, paste the redirect URL you copied from NetBird

3. Click Create

4. Now you will have the Client ID and Secret displayed.

Step 5: Complete NetBird Setup

1. Return to the NetBird tab
2. In the identity provider form, paste the Client ID and Secret you displayed in Step 4
3. Click Save

Step 6: Configure Token Settings in Zitadel

1. Return to the Zitadel Console tab
2. Navigate to your NetBird application → Token Settings
3. Enable:
   • Include user's profile info in the ID Token
   • User roles inside ID Token (if group mapping is needed)

4. Click Save

Step 7: 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

Configuring JWT 'groups' Claim

Zitadel uses roles instead of groups. By default, Zitadel's role claims use a nested JSON object format, but NetBird expects a flat array of strings. You'll need to create a Zitadel Action to transform roles into a groups claim.

Step 1: Create the Groups Action

1. In Zitadel Console, go to Actions
2. Click New
3. Fill in:
   • Name: groupsClaim
4. Add the following script:

function groupsClaim(ctx, api) {
  if (ctx.v1.user.grants == undefined || ctx.v1.user.grants.count == 0) {
    return;
  }
  let groups = [];
  ctx.v1.user.grants.grants.forEach(claim => {
    claim.roles.forEach(role => {
      groups.push(role);
    });
  });
  api.v1.claims.setClaim('groups', groups);
}

5. Click Add

Step 2: Configure Action Triggers

1. Go to Actions → Flows
2. Select Complement Token
3. Add triggers for the groupsClaim action:
   • Pre Userinfo creation
   • Pre access token creation

Step 3: Assign Roles to Users

1. Go to your Project in Zitadel
2. Navigate to Roles and create roles (e.g., admin, developer)
3. Go to Authorizations and assign roles to users

Step 4: Enable JWT Group Sync in NetBird

1. In NetBird Dashboard, go to Settings → Groups
2. Enable JWT group sync
3. Set JWT claim to groups
4. Optionally configure JWT allow groups to restrict access

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 Management Setup (Recommended) section above.

For detailed instructions on the standalone setup, see the Zitadel SSO with NetBird Self-Hosted (Advanced) documentation.

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)

Related Resources

• Zitadel Documentation
• Zitadel GitHub
• Embedded IdP Overview
• Migration Guide