Keycloak with NetBird Self-Hosted

Keycloak is an open-source Identity and Access Management solution maintained by Red Hat. It provides single sign-on, social login, user federation, fine-grained authorization, and supports OpenID Connect, OAuth 2.0, and SAML 2.0 protocols.

Management Setup (Recommended)

Add Keycloak as an external IdP directly in the NetBird Management Dashboard. This is the simplest approach and recommended for most deployments.

Prerequisites

• NetBird self-hosted with embedded IdP enabled
• Keycloak instance running with SSL

Step 1: Create Realm in Keycloak

1. Open the Keycloak Admin Console
2. Hover over the realm dropdown in the top-left corner (where it shows Master or your current realm)
3. Click Create Realm

4. Fill in:
   • Realm name: netbird

5. Click Create
6. Verify that netbird is now selected in the realm dropdown

Step 2: Create User in Keycloak

1. Make sure the netbird realm is selected
2. Click Users (left-hand menu)
3. Click Create new user

4. Fill in:
   • Username: netbird (or your preferred username)
   • Email: Your email address
5. Click Create
6. Click the Credentials tab
7. Click Set password
8. Fill in the password and set Temporary to Off
9. Click Save

Step 3: Start Creating Client in Keycloak

1. Click Clients → Create client

2. Fill in the form:
   • Client type: OpenID Connect
   • Client ID: netbird

3. Click Next
4. On Capability config:
   • Enable Client authentication

5. Click Next
6. On Login settings page, don't click Save yet — you'll add the redirect URI in Step 4

Step 4: 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. Select Keycloak (or choose Generic OIDC if Keycloak is not listed)
5. Fill in the fields (you can leave Client Secret empty for now):

6. NetBird will display a Redirect URL — copy this URL (but don't click Add Provider yet)

Step 5: Complete Client Configuration in Keycloak

1. Return to the Keycloak Admin Console tab
2. On the Login settings page:
   • Under Valid redirect URIs, paste the redirect URL you copied from NetBird
3. Click Save
4. Go to the Credentials tab and copy the Client secret — you'll need this for Step 6

Step 6: Complete NetBird Setup

1. Return to the NetBird tab
2. In the identity provider form, paste the Client secret you copied from Step 5
3. Click Add Provider

Step 7: Test the Connection

1. Log out of NetBird Dashboard
2. On the login page, you should see a "Keycloak" button
3. Click it and authenticate with the user credentials you created in Step 2
4. You should be redirected back to NetBird and logged in

Configuring JWT 'groups' Claim

To sync Keycloak groups with NetBird, you need to create a client scope with a group membership mapper.

Step 1: Create Groups Client Scope

1. In Keycloak Admin Console, ensure the netbird realm is selected
2. Go to Client scopes → Create client scope
3. Fill in:
   • Name: groups
   • Type: Default
   • Include in token scope: On
4. Click Save

Step 2: Add Group Membership Mapper

1. In the newly created groups client scope, go to the Mappers tab
2. Click Configure a new mapper
3. Select Group Membership
4. Configure the mapper:
   • Name: groups
   • Token Claim Name: groups
   • Full group path: Off (recommended for cleaner group names)
   • Add to ID token: On
   • Add to access token: On
   • Add to userinfo: On
   • Add to token introspection: Off
5. Click Save

Step 3: Add Client Scope to NetBird Client

1. Go to Clients → netbird (your client)
2. Go to the Client scopes tab
3. Click Add client scope
4. Select groups and add it as Default

Step 4: Create Groups and Assign Users

1. Go to Groups → Create group
2. Create groups as needed (e.g., admins, developers)
3. Go to Users → select a user → Groups tab
4. Click Join Group and assign users to groups

Step 5: 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 Keycloak 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 Keycloak 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 Keycloak SSO with NetBird Self-Hosted (Advanced) documentation.

Troubleshooting

"Invalid redirect URI" error

• Ensure the redirect URI matches exactly what's configured
• Use the exact URL from the NetBird success modal

"Invalid token" errors

• Verify the issuer URL includes /realms/netbird (or your realm name)
• Ensure the client ID matches in both Keycloak and NetBird
• Check clock synchronization between servers

Users not appearing in NetBird

• Users appear after their first successful login

Related Resources

• Keycloak Documentation
• Embedded IdP Overview