some file

Authentik with NetBird Self-Hosted

Authentik is an open-source identity provider focused on flexibility and security. It serves as a self-hosted alternative to commercial solutions like Okta and Auth0, providing single sign-on (SSO), multi-factor authentication (MFA), access policies, user management, and support for SAML and OIDC protocols.

Add Authentik 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
  • Authentik instance with admin access

Step 1: Create OAuth2/OpenID Provider in Authentik

  1. Navigate to Authentik admin interface
  2. Click Applications on the left menu, then click Providers
  3. Click Create to create a new provider

Create provider

  1. Select OAuth2/OpenID Provider and click Next

Select OAuth2/OpenID Provider type

  1. Fill in the form with the following values:
    • Name: NetBird
    • Authorization Flow: default-provider-authorization-explicit-consent (Authorize Application)
    • Client type: Confidential
    • Redirect URIs/Origins: Leave empty for now (you'll add this in Step 5)
    • Signing Key: Select any cert present, e.g., authentik Self-signed Certificate

Provider configuration with authorization flow

  1. Click Finish
  2. Note the Client ID and Client Secret — you'll need these for Step 3

Step 2: Create Application in Authentik

  1. Click Applications on the left menu, then click Applications
  2. Click Create to create a new application

Create application

  1. Fill in the form:
    • Name: NetBird
    • Slug: netbird
    • Provider: Select the NetBird provider you created in Step 1

Application name and slug

  1. Click Create

Step 3: 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. Fill in the fields:
FieldValue
TypeGeneric OIDC
NameAuthentik (or your preferred display name)
Client IDFrom Authentik provider (from Step 1)
Client SecretFrom Authentik provider (from Step 1)
Issuerhttps://authentik.example.com/application/o/netbird/
  1. Copy the Redirect URL that NetBird displays (but don't click Add Provider yet)

NetBird configuration and copy redirect URL

Step 4: Configure Redirect URI in Authentik

  1. Return to Authentik admin → Providers → NetBird
  2. Click Edit

Edit provider redirect URIs

  1. Under Redirect URIs/Origins, add the redirect URL you copied from NetBird
  2. Select Strict (not Regex) to match the exact URL from NetBird

Add redirect URI in Strict mode

  1. Click Update

Step 5: Complete NetBird Setup

  1. Return to the NetBird tab
  2. Click Add Provider

Step 6: Test the Connection

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

Configuring JWT 'groups' Claim

Authentik includes a groups claim in the ID token by default through the profile scope. However, you may need to verify the configuration and ensure groups are included in the token.

Step 1: Verify Scope Mappings

  1. In Authentik admin, go to Customization → Property Mappings
  2. Find and click on authentik default OAuth Mapping: OpenID 'profile'
  3. Verify it includes group information, or create a custom mapping

Step 2: Configure Provider to Include Claims in ID Token

  1. Go to Applications → Providers
  2. Edit your NetBird provider
  3. Under Advanced protocol settings, enable Include claims in id_token
  4. Ensure the profile and groups scopes are selected
  5. Click Update

Step 3: 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

Authentik returns group names (not IDs) in the groups claim. Groups are synced based on the user's group membership in Authentik.

Standalone Setup (Advanced)

Use Authentik 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 Authentik 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 Authentik 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.

Troubleshooting

"Invalid redirect URI" error

  • Ensure the redirect URI exactly matches what NetBird provides
  • Copy the exact URL from the success modal

Authentication fails silently

  • Verify a signing key is selected in the provider configuration
  • Check that the application is linked to the correct provider