Keycloak with NetBird Self-Hosted
Updated
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
- The NetBird server can reach Keycloak's issuer URL (for example
https://keycloak.example.com/realms/netbird) and trusts Keycloak's certificate. If your organization's own certificate authority issued that certificate, see Keycloak with a certificate from an internal CA.
Step 1: Create Realm in Keycloak
- Open the Keycloak Admin Console
- Hover over the realm dropdown in the top-left corner (where it shows
Masteror your current realm) - Click Create Realm

- Fill in:
- Realm name:
netbird
- Realm name:

- Click Create
- Verify that
netbirdis now selected in the realm dropdown
Step 2: Create User in Keycloak
- Make sure the
netbirdrealm is selected - Click Users (left-hand menu)
- Click Create new user

- Fill in:
- Username:
netbird(or your preferred username) - Email: Your email address
- Username:
- Click Create
- Click the Credentials tab
- Click Set password
- Fill in the password and set Temporary to
Off - Click Save

Step 3: Start Creating Client in Keycloak
- Click Clients → Create client

- Fill in the form:
- Client type:
OpenID Connect - Client ID:
netbird
- Client type:

- Click Next
- On Capability config:
- Enable Client authentication

- Click Next
- 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
- Open a new tab or window and log in to your NetBird Dashboard
- Navigate to Settings → Identity Providers
- Click Add Identity Provider
- Select Keycloak (or choose Generic OIDC if Keycloak is not listed)
- Fill in the fields (you can leave Client Secret empty for now):
| Field | Value |
|---|---|
| Type | Generic OIDC (if not already selected) |
| Name | Keycloak (or your preferred display name) |
| Client ID | netbird (from Step 3) |
| Client Secret | Leave empty for now |
| Issuer | https://keycloak.example.com/realms/netbird |
- NetBird will display a Redirect URL — copy this URL (but don't click Add Provider yet)

Step 5: Complete Client Configuration in Keycloak
- Return to the Keycloak Admin Console tab
- On the Login settings page:
- Under Valid redirect URIs, paste the redirect URL you copied from NetBird
- (Optional) Under Valid post logout redirect URIs, add
https://netbird.example.com/oauth2/logout/callback(replacenetbird.example.comwith your NetBird dashboard domain) so logout redirects back to NetBird cleanly
- Click Save
- Go to the Credentials tab and copy the Client secret — you'll need this for Step 6

Step 6: Complete NetBird Setup
- Return to the NetBird tab
- In the identity provider form, paste the Client secret you copied from Step 5
- Click Add Provider

Step 7: Test the Connection
- Log out of NetBird Dashboard
- On the login page, you should see a "Keycloak" button
- Click it and authenticate with the user credentials you created in Step 2
- You should be redirected back to NetBird and logged in

Users who authenticate via Keycloak will appear in your NetBird Users list with a Keycloak badge next to their name.
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
- In Keycloak Admin Console, ensure the
netbirdrealm is selected - Go to Client scopes → Create client scope
- Fill in:
- Name:
groups - Type:
Default - Include in token scope:
On
- Name:
- Click Save

Step 2: Add Group Membership Mapper
- In the newly created
groupsclient scope, go to the Mappers tab - Click Configure a new mapper
- Select Group Membership
- 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
- Name:
- Click Save

Step 3: Add Client Scope to NetBird Client
- Go to Clients → netbird (your client)
- Go to the Client scopes tab
- Click Add client scope
- Select groups and add it as Default

Step 4: Create Groups and Assign Users
- Go to Groups → Create group
- Create groups as needed (e.g.,
admins,developers) - Go to Users → select a user → Groups tab
- Click Join Group and assign users to groups
Step 5: Enable JWT Group Sync in NetBird
- In NetBird Dashboard, go to Settings → Groups
- Enable JWT group sync
- Set JWT claim to
groups - Optionally configure JWT allow groups to restrict access
If Full group path is enabled, group names will include the path (e.g., /admins or /parent/child). Disable it for cleaner names like admins.
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.
If you prefer not to self-host an Identity and Access Management solution, you could use a managed alternative like Auth0.
Keycloak with a certificate from an internal CA
When you add Keycloak, and again every time the NetBird server starts, the server fetches Keycloak's OpenID configuration from the issuer URL, not through your browser. If your organization's own certificate authority (an internal CA) issued Keycloak's certificate, the server does not trust that certificate, even when every browser in your organization does. You then see one of these errors:
- Adding Keycloak fails with
identity provider issuer is unreachable: … x509: certificate signed by unknown authority. - A provider that worked before shows
Connector failed to initializewhen you click its button on the login page. This happens when thenetbird-servercontainer is recreated without the CA mount, for example afterdocker-compose.ymlwas replaced.
Only the netbird-server container needs your CA file; the dashboard and the other containers do not. The CA file adds to the public CAs the server already trusts, so connections to public services, such as the license check on a commercial license, keep working.
-
On the NetBird host, check which certificates Keycloak sends:
openssl s_client -connect keycloak.example.com:443 -servername keycloak.example.com -showcerts </dev/null 2>/dev/null | grep -E '^ *[0-9] s:'Lines
0 s:,1 s:and so on are the certificates Keycloak sends, its own first; only0 s:means it sends no intermediate CA. The CA file needs only your root CA certificate if Keycloak sends every intermediate CA between its certificate and the root, or if your root CA signed Keycloak's certificate directly. Otherwise, either configure Keycloak with a certificate chain file of its own certificate followed by every intermediate CA (preferred; the CA file then holds only the root), or add each intermediate CA certificate that Keycloak does not send to the CA file, after the root. -
Save the CA file in PEM format on the NetBird host, for example as
/etc/netbird/certs/internal-ca.pem. -
In
docker-compose.override.yml, in the same directory asdocker-compose.yml(create it if it does not exist), mount the CA file into/etc/ssl/certs/ofnetbird-server. Docker Compose reads the override file automatically, so the mount stays in place when you replacedocker-compose.yml; if you rundocker compose -f, also pass-f docker-compose.override.yml. If the override file already has anetbird-serverservice, add the line under itsvolumes:key:services: netbird-server: volumes: - /etc/netbird/certs/internal-ca.pem:/etc/ssl/certs/internal-ca.pem:ro -
Recreate the container with
docker compose up -d netbird-server. Then add Keycloak again if adding it failed, or sign in with the Keycloak button if an existing provider stopped working.
Mounting the CA file into /usr/local/share/ca-certificates/ has no effect: the container does not run update-ca-certificates.
Troubleshooting
"identity provider issuer is unreachable" or "Connector failed to initialize" error
Connector failed to initializeon the login page: the server could not load Keycloak's OpenID configuration. It tries again each time you click the button, so a fix outside the NetBird host, such as a firewall rule, needs no restart. The cause is in the latestfailed to open connectorline ofdocker compose logs netbird-server.- If that line, or the error when adding Keycloak, includes
x509: certificate signed by unknown authority: the NetBird server does not trust Keycloak's certificate. See Keycloak with a certificate from an internal CA. - If that line or the error includes
context deadline exceeded: the NetBird server cannot reach Keycloak's issuer URL. Allow HTTPS from the NetBird host to Keycloak's host name and port.
"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

