Connecting NetBird to Authentik or Keycloak

Want remote access with your own identity provider? WZ-IT plans and operates NetBird together with Authentik or Keycloak - identities, groups and policies from one team, GDPR-compliant inside the EU. See managed secure access

NetBird checks neither passwords nor second factors. It relies on an identity provider having done that. The security gain of the whole model hangs on exactly this - which makes IdP integration not a configuration detail but the core of the setup. This article shows how integration with Authentik and Keycloak works, where the two differ, and what is not included in the Community Edition. As of July 2026.

Table of contents

• Why the IdP is the actual lever
• The three integration levels
• Connecting Authentik
• Connecting Keycloak
• Authentik or Keycloak
• Where MFA is actually enforced
• Pitfalls from practice

Why the IdP is the actual lever

In a classic VPN, identity is a certificate or a local account on the appliance. Both live in exactly one system and have to be maintained there separately. With an identity-based overlay this reverses: the identity provider is the leading source, and NetBird merely consumes its verdict.

In practice that means:

• Joining and leaving happen in one place. Anyone deactivated in the IdP gets in nowhere - including the network.
• Groups are modelled once and then drive access policies without having to be mirrored inside NetBird.
• MFA is enforced once and applies to every connected application.

How the overlay underneath works is explained in What is NetBird?. Why the identity route beats the other MFA retrofit paths is covered in Retrofitting MFA for VPN.

The three integration levels

Integration is not all-or-nothing. There are three levels building on each other (documentation):

Level 1 - login via OIDC. Any identity provider that speaks OpenID Connect can be connected. Users log in through the IdP and NetBird works with the issued token. That is the minimum scope and already covers SSO and MFA completely.

Level 2 - group sync via JWT claim. NetBird can read a user's group memberships from the token when JWT group sync is enabled and the claim name is configured. IdP groups then drive access policies directly. Worth noting: this requires no access to the IdP's management API, the claim inside the token is enough.

Level 3 - SCIM provisioning. Automatic creation and deactivation of users and groups. This one deserves a close read: SCIM is not part of the open-source Community Edition. When self-hosting it starts with the Commercial Starter at EUR 2,000 per year (up to 50 users and 500 devices), which also includes high availability and device approvals (pricing overview, as of July 2026).

What matters for the assessment: levels 1 and 2 are fully included in the free Community Edition - SSO and MFA via your own identity provider therefore cost nothing. SCIM automates creating and deactivating accounts; anyone maintaining users in the IdP anyway and delivering groups via the JWT claim gets by without it in most mid-sized setups. It should simply be settled before the architecture decision, not after.

Connecting Authentik

In Authentik you create an OAuth2/OpenID Provider. The relevant values (documentation):

• Client type: Confidential
• Authorization flow: default-provider-authorization-explicit-consent
• Signing key: any available certificate, for example Authentik's self-signed one
• Redirect URI: the URL shown by NetBird, in Strict mode rather than Regex. Optionally add the logout callback https://netbird.example.com/oauth2/logout/callback

On the NetBird side you add an entry of type Generic OIDC under Settings → Identity Providers, with the client ID and secret from Authentik plus the issuer in the form https://authentik.example.com/application/o/netbird/.

For group sync Authentik has the advantage: it provides a groups claim already through the profile scope. Only two things are needed - enable "Include claims in id_token" in the provider's advanced settings, and make sure the profile and groups scopes are selected. In NetBird you then switch on JWT group sync with the claim name groups.

Connecting Keycloak

With Keycloak the basic setup runs similarly: a realm (the documentation uses netbird), inside it an OpenID Connect client with client authentication enabled, the redirect URI from the NetBird settings entered under "Valid redirect URIs", then the client secret carried over. The issuer takes the form https://keycloak.example.com/realms/netbird (documentation).

The difference is groups: Keycloak does not provide them by default. You need a dedicated client scope, usually named groups, with a group membership mapper whose token claim name is set to groups. That scope is assigned to the NetBird client as a default scope.

This is the most common reason a Keycloak integration works but all peers end up in the wrong group: login succeeds, the token just carries no groups.

Authentik or Keycloak

Both are open source, self-hostable and entirely suitable for this purpose. The decision comes down to the surrounding environment rather than to NetBird:

Anyone not yet running an IdP and starting with remote access will get there faster with Authentik. Anyone already using Keycloak for other applications connects NetBird there - a second IdP would be exactly the sprawl this model is meant to remove.

Where MFA is actually enforced

One point regularly misplaced in concepts: NetBird does not verify a second factor. There is no "enforce MFA" switch in NetBird. The rule belongs in the identity provider - in Authentik in the authentication flow, in Keycloak in the realm's authentication flow.

That is not a shortcoming but the actual gain: the factor rule is defined once and applies to every connected application. Tightening it for remote access automatically tightens it for everything else behind the same IdP. Background in SSO & MFA for the remote access portal.

Pitfalls from practice

• Groups missing from the token. The classic with Keycloak, see above. Verify the claim actually arrives before building policies on it.
• Redirect URI defined too loosely. For Authentik the documentation explicitly calls for Strict mode. Regex entries are convenient and open unnecessary room.
• Planning for SCIM without licensing it. Anyone making automatic deprovisioning a base assumption should clarify the licensing situation up front.
• Placing the IdP behind the network it protects. If login is only reachable through the remote access it is supposed to enable, you create a dependency that gets expensive during an incident.
• Building the group structure afterwards. It determines every later access rule. Modelling it before rollout saves more time than it costs - the sequence is laid out in Migrate FortiGate SSL-VPN to NetBird.