Skip to main content

Integrate with NetBird

Support level: Community

What is NetBird​

NetBird is an open source, zero trust networking platform that allows you to create secure private networks for your organization or home.

-- https://netbird.io

Preparation​

The following placeholders are used in this guide:

  • netbird.company is the FQDN of the NetBird installation.
  • authentik.company is the FQDN of the authentik installation.
info

This documentation lists only the settings that you need to change from their default values. Be aware that any changes other than those explicitly mentioned in this guide could cause issues accessing your application.

Configuration methods​

NetBird can use authentik in two ways:

  • Management setup: add authentik as an external identity provider while keeping NetBird's embedded IdP and local users.
  • Standalone setup: replace NetBird's embedded IdP with authentik.

authentik configuration​

To support adding authentik as an external identity provider in NetBird, you need to create an application/provider pair and application entitlements in authentik.

Create an application and provider in authentik​

  1. Log in to authentik as an administrator and open the authentik Admin interface.

  2. Navigate to Applications > Applications and click New Application to open the application wizard.

    • Application: provide a descriptive name, an optional group for the type of application, the policy engine mode, and optional UI settings. Note the Slug value because it will be required later.
    • Choose a Provider type: select OAuth2/OpenID Connect as the provider type.
    • Configure the Provider: provide a name (or accept the auto-provided name), the authorization flow to use for this provider, and the following required configurations.
      • Note the Client ID and Client Secret values because they will be required later.
      • Leave Redirect URIs/Origins empty. NetBird generates the redirect URI in a later step.
      • Under Advanced protocol settings > Selected Scopes, add authentik default OAuth Mapping: OpenID 'entitlements'.
    • Configure Bindings (optional): you can create a binding (policy, group, or user) to manage the listing and access to applications on a user's My applications page.

  3. Click Submit to save the new application and provider.

Create application entitlements​

Use application entitlements to define which NetBird groups can be assigned to authentik users.

  1. Open the NetBird application in authentik.
  2. Click the Application entitlements tab.
  3. Create one entitlement for each NetBird group you want to assign to users.
  4. Open each entitlement and bind the users or groups that should receive it.

Name each entitlement exactly as the NetBird group value that NetBird should sync. This keeps NetBird-specific authorization scoped to the NetBird application instead of relying on global authentik group names.

NetBird configuration​

  1. Log in to the NetBird Management Dashboard as an administrator.
  2. Navigate to Settings > Identity Providers and click Add Identity Provider.
  3. Configure the following settings:
    • Type: select authentik if available; otherwise select Generic OIDC.
    • Name: authentik
    • Client ID: enter the client ID from authentik.
    • Client Secret: enter the client secret from authentik.
    • Issuer: https://authentik.company/application/o/<application_slug>/
  4. Copy the redirect URL shown by NetBird. Do not complete the provider setup yet.
  5. Return to authentik, navigate to Applications > Providers, and edit the NetBird provider.
  6. Under Redirect URIs/Origins, add the redirect URL from NetBird as a Strict redirect.
  7. Click Update.
  8. Return to NetBird and complete the identity provider setup.

Configure entitlement sync​

NetBird can sync group membership from a JWT claim. Use the entitlements claim so NetBird receives the application entitlements assigned to the user.

  1. In authentik, edit the NetBird provider.
  2. Under Advanced protocol settings, enable Include claims in id_token.
  3. Ensure the entitlements scope is selected.
  4. In NetBird, enable JWT group sync and set the JWT claim to entitlements.

Configuration verification​

To confirm that authentik is properly configured with NetBird, log out and log back in via authentik.

Troubleshooting​

When accessing NetBird through a reverse proxy, you might encounter a loop where the /peers URL continuously reloads. To resolve this, set the following variables accordingly:

setup.env
NETBIRD_MGMT_API_PORT=443
NETBIRD_SIGNAL_PORT=443

Run the configure.sh script for the change to take effect.

Resources​