some file

Authentik

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 a connector to the embedded IdP. 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
  4. Select OAuth2/OpenID Provider and click Next

Select provider type

  1. Fill in the form with the following values:

    • Name: NetBird
    • Authentication Flow: default-authentication-flow (Welcome to authentik!)
    • Authorization Flow: default-provider-authorization-explicit-consent (Authorize Application)
    • Client type: Confidential
    • Redirect URIs/Origins: Leave empty for now (you'll add this after creating the connector in NetBird)
    • Signing Key: Select any cert present, e.g., authentik Self-signed Certificate

  2. Click Finish

  3. Note the Client ID and Client Secret

Step 2: Create Application in Authentik

  1. Click Applications on the left menu, then click Applications
  2. Click Create to create a new application
  3. Fill in the form:
    • Name: NetBird
    • Slug: netbird
    • Provider: Select the NetBird provider you created
  4. Click Create

Create application

Step 3: Add Connector in NetBird

  1. 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
Client SecretFrom Authentik provider
Issuerhttps://authentik.example.com/application/o/netbird/
  1. Click Save

Step 4: Configure Redirect URI

After saving, NetBird displays the Redirect URL. Copy this URL and add it to your Authentik provider:

  1. Return to Authentik admin → Providers → NetBird
  2. Click Edit
  3. Under Redirect URIs/Origins, add the redirect URL from NetBird
  4. Click Update

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

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 Connector Setup (Recommended) section above.

If you prefer not to self-host an Identity and Access Management solution, you could use a managed alternative like Auth0.

Prerequisites

  • Authentik instance running with SSL
  • Docker and Docker Compose installed for NetBird

Step 1: Create OAuth2/OpenID Provider

Follow steps 1-2 from the connector setup above, but configure the provider as follows:

  • Client type: Public
  • Redirect URIs/Origins (RegEx):
    • Regex: https://<domain>/.*
    • Strict: http://localhost:53000
  • Advanced protocol settings:
    • Access code validity: minutes=10
    • Subject mode: Based on the User's ID

Provider configuration

Take note of Client ID for later use.

Step 2: Create Application

Follow step 2 from the connector setup to create the NetBird application.

Step 3: Create Service Account

  1. Navigate to Authentik admin interface
  2. Click Directory on the left menu, then click Users
  3. Click Create Service Account
  4. Fill in the form:
    • Username: Netbird
    • Create Group: Disable
  5. Click Create

Create service account

  1. Note the service account username
  2. Create an app password: Go to Directory → Tokens and App passwords
  3. Create a new app password, selecting the NetBird service account as the User
  4. Save the app password for later use

Step 4: Add Service Account to Admin Group

  1. Click Directory on the left menu, then click Groups
  2. Click authentik Admins from the list and select Users tab
  3. Click Add existing user and click + button
  4. Select Netbird and click Add
  5. Disable Hide service-accounts and verify the user is added

Add user to group

Step 5: Create Device Code Flow

  1. Click Flows and Stages on the left menu, then click Flows → Create
  2. Fill in the form:
    • Name: default-device-code-flow
    • Title: Device Code Flow
    • Designation: Stage Configuration
    • Authentication: Require authentication
  3. Click Create

Create device flow

  1. Click System on the left menu, then click Brands
  2. Click edit on authentik-default
  3. Under Default flows, set Device code flow to default-device-code-flow
  4. Click Update

Configure brand device flow

Step 6: Configure NetBird

Your authority OIDC configuration will be available at:

https://<YOUR_AUTHENTIK_HOST_AND_PORT>/application/o/netbird/.well-known/openid-configuration

Double-check if the endpoint returns a JSON response by calling it from your browser.

Set properties in the setup.env file:

NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://<YOUR_AUTHENTIK_HOST_AND_PORT>/application/o/netbird/.well-known/openid-configuration"
NETBIRD_USE_AUTH0=false
NETBIRD_AUTH_CLIENT_ID="<PROVIDER_CLIENT_ID>"
NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access api"
NETBIRD_AUTH_AUDIENCE="<PROVIDER_CLIENT_ID>"
NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID="<PROVIDER_CLIENT_ID>"
NETBIRD_AUTH_DEVICE_AUTH_AUDIENCE="<PROVIDER_CLIENT_ID>"
NETBIRD_AUTH_REDIRECT_URI="/auth"
NETBIRD_AUTH_SILENT_REDIRECT_URI="/silent-auth"

NETBIRD_MGMT_IDP="authentik"
NETBIRD_IDP_MGMT_CLIENT_ID="<PROVIDER_CLIENT_ID>"
NETBIRD_IDP_MGMT_EXTRA_USERNAME="Netbird"
NETBIRD_IDP_MGMT_EXTRA_PASSWORD="<SERVICE_ACCOUNT_PASSWORD>"

# Needs disabling due to issue with IdP. Learn more: https://github.com/netbirdio/netbird/issues/3654
NETBIRD_AUTH_PKCE_DISABLE_PROMPT_LOGIN=true

Step 7: Continue with NetBird Setup

You've configured all required resources in Authentik. Continue with the NetBird Self-hosting Guide.

Troubleshooting

"Invalid redirect URI" error

  • Ensure the redirect URI exactly matches what NetBird provides
  • For connector setup: Copy the exact URL from the success modal
  • For standalone: Use regex pattern https://<domain>/.*

Authentication fails silently

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

Service account authentication fails

  • Ensure you're using the app password, not the account password
  • Verify the service account is in the authentik Admins group