How to integrate NetBird with Keycloak for SSO authentication

Why unify NetBird and Keycloak in your infrastructure

As a company grows, managing separate credentials for every tool turns into an operational nightmare. In practice, this means every new employee needs an account for the traditional VPN, another for email, and yet another for the server dashboard. By integrating NetBird, a WireGuard-based private networking technology that draws direct connections between devices, with Keycloak, a centralized identity manager, you solve this problem by creating a single entry point.

Before diving in, it is worth noting that this process complements what we covered in how to set up NetBird from scratch for a secure network. With the foundation ready, the goal now is to take local password control away from users and hand it over to a robust authentication server, where security rules like strong passwords and multi-factor authentication can be applied centrally.

Understanding OpenID Connect and SSO concepts

The core concept behind this integration revolves around OpenID Connect, often called OIDC. It is a communication protocol that allows an application to verify a user's identity based on a login performed on another server, known as an Identity Provider. For those looking for a modern remote access alternative without traditional VPNs, understanding OIDC is the first step to grasping how access tokens travel encrypted between systems.

In practice, when the user opens the NetBird application on their computer, the program redirects them to the Keycloak login screen. After the user enters their credentials and passes multi-factor authentication, Keycloak generates a digital pass called a JWT token. NetBird receives this pass, validates its mathematical signature, and grants network access without ever seeing or storing the user's actual password.

Configuring the OpenID Connect client in Keycloak

The first practical step happens in the administrative panel of your Keycloak server, where we need to create a reserved space so NetBird can talk to it. This space is called an OIDC client. Access your Keycloak dashboard, select the appropriate realm, and create a new client by providing the identifier and redirect URLs that NetBird will supply during the control panel installation process.

In the NetBird dashboard, configure your external provider details by entering Keycloak's base address, the created client ID, and the secret generated in the previous step. It is crucial to ensure the redirection protocol uses HTTPS, as modern identity providers block any attempt to send credentials over unencrypted connections, preventing passwords from being intercepted along the way.

Mapping groups and roles for granular access control

One of the biggest wins of using Keycloak is the ability to organize users into groups that reflect the company's real structure, such as developers, support, or finance. In Keycloak, you create these groups and configure protocol mappers so that membership information travels inside the token generated at login time.

When NetBird receives this token, it reads the group information and automatically applies the access policies you defined. In practice, this means a finance team member will only be able to see and connect to accounting servers, while the rest of the network remains invisible to them, drastically reducing the attack surface if a machine is compromised.

Validating the login flow and testing security

With everything configured, it is time to put the integration to the test. Open the NetBird dashboard in an incognito browser tab and try logging in using your Keycloak-managed corporate account. The system should redirect you to the unified login screen and, after confirmation, return to the dashboard showing your profile successfully connected.

If failures occur, the first place to check is the logs of the Keycloak server and NetBird control panel, where detailed messages usually point to redirection errors or incorrect secret keys. By validating this flow, you ensure that any employee termination in Keycloak will immediately cut off their access to the private network, raising your operation's security posture.

Final considerations on identity and modern networks

Integrating NetBird with Keycloak radically transforms how distributed teams access internal resources, combining the speed of peer-to-peer connections with the rigor of centralized governance. This approach eliminates weak passwords, simplifies the support team's daily routine, and ensures that control over who enters and leaves the network is always in the hands of IT management, without unnecessary bureaucracy.