some file

Auth0 SSO with NetBird Self-Hosted (Legacy)

Auth0 is a flexible, drop-in solution to add authentication and authorization services to your applications. It's a managed service that handles identity infrastructure so you don't have to.

Standalone Setup (Advanced)

NetBird includes built-in local user management powered by an embedded IdP, allowing you to create and manage users directly without requiring an external identity provider. You can also add multiple external identity providers alongside local users, giving users multiple login options.

We highly recommend using the simpler setup that adds Auth0 as an external IdP directly in the NetBird Management Dashboard. This approach requires minimal configuration, works alongside local users, and doesn't require replacing your embedded IdP. See the Management Setup (Recommended) section in the main Auth0 documentation.

The standalone setup below replaces your embedded IdP entirely and is only recommended for experienced Auth0 administrators who need full control over authentication and user management.

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

If you prefer to have full control over authentication, consider self-hosted alternatives like PocketID.

Prerequisites

Configuration Properties

You will configure these properties in setup.env:

  • NETBIRD_AUTH_CLIENT_ID
  • NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT
  • NETBIRD_USE_AUTH0
  • NETBIRD_AUTH_AUDIENCE
  • NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID (Optional)
  • NETBIRD_MGMT_IDP
  • NETBIRD_IDP_MGMT_CLIENT_ID
  • NETBIRD_IDP_MGMT_CLIENT_SECRET
  • NETBIRD_IDP_MGMT_EXTRA_AUDIENCE

Step 1: Create Dashboard Application

This application authorizes access to NetBird Dashboard.

  1. Follow the Auth0 React SDK Guide up to "Install the Auth0 React SDK"
  2. Set Allowed Callback URLs: https://YOUR_DOMAIN and http://localhost:53000
  3. Set Allowed Logout URLs, Allowed Web Origins, Allowed Origins (CORS): https://YOUR_DOMAIN and http://localhost

Ensure Token Endpoint Authentication Method is set to None.

  1. Use Client ID for NETBIRD_AUTH_CLIENT_ID
  2. Use Domain to configure NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT:
https://<DOMAIN>/.well-known/openid-configuration

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

Step 2: Create API

This API is used to access NetBird Management Service.

  1. Follow the Auth0 Create An API guide
  2. Use the API Identifier for NETBIRD_AUTH_AUDIENCE
  3. Set NETBIRD_USE_AUTH0=true

Step 3: Enable Interactive SSO Login (Optional)

This enables machine authorization via your Identity Provider as an alternative to setup keys.

  1. Go to Applications
  2. Click Create Application
  3. Fill in:
    • Name: Interactive Login
    • Application type: Native
  4. Click Create

Create interactive login app

  1. Click Settings tab
  2. Copy Client ID to NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID

Interactive login settings

  1. Scroll to Advanced Settings
  2. Enable Device Code
  3. Click Save Changes

Grant types

Step 4: Create Machine to Machine Application

This application authorizes access to Auth0 Management API.

  1. Go to Applications
  2. Click Create Application
  3. Fill in:
    • Name: Netbird API
    • Application type: Machine to Machine Applications
  4. Click Create

Create machine app

  1. Configure:
    • API: Auth0 Management API
    • Permissions: read:users, update:users, create:users, read:users_app_metadata, update:users_app_metadata, create:users_app_metadata
  2. Click Authorize

Machine authorization

Optional: To enable automatic user deletion from Auth0 when deleted from NetBird, add the --user-delete-from-idp flag to the management startup command and assign the delete:users permission.

  1. Click Settings tab
  2. Copy values:
    • Client ID → NETBIRD_IDP_MGMT_CLIENT_ID
    • Client Secret → NETBIRD_IDP_MGMT_CLIENT_SECRET
    • Domain → NETBIRD_IDP_MGMT_EXTRA_AUDIENCE (format: https://<DOMAIN>/api/v2/)

Machine settings

Step 5: Configure NetBird

Set properties in the setup.env file:

NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://<DOMAIN>/.well-known/openid-configuration"
NETBIRD_USE_AUTH0=true
NETBIRD_AUTH_CLIENT_ID="<CLIENT_ID>"
NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access api email_verified"
NETBIRD_AUTH_AUDIENCE="<IDENTIFIER>"
NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID="<INTERACTIVE_CLIENT_ID>"

NETBIRD_MGMT_IDP="auth0"
NETBIRD_IDP_MGMT_CLIENT_ID="<NETBIRD_API_CLIENT_ID>"
NETBIRD_IDP_MGMT_CLIENT_SECRET="<NETBIRD_API_CLIENT_SECRET>"
NETBIRD_IDP_MGMT_EXTRA_AUDIENCE="https://<DOMAIN>/api/v2/"

Step 6: Continue with NetBird Setup

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

Troubleshooting

"Invalid redirect URI" error

  • Ensure all callback URLs are configured in Auth0
  • Check for trailing slashes
  • Verify URLs match exactly

"Unauthorized" errors for Management API

  • Verify the Machine to Machine application has correct permissions
  • Check that NETBIRD_IDP_MGMT_EXTRA_AUDIENCE includes /api/v2/

Device authorization not working

  • Ensure Device Code grant is enabled in Advanced Settings
  • Verify the native application Client ID is used

Token validation errors

  • Verify NETBIRD_USE_AUTH0=true is set
  • Check the audience matches the API identifier

NetBird includes built-in local user management powered by an embedded IdP, allowing you to create and manage users directly without requiring an external identity provider. You can also add multiple external identity providers alongside local users, giving users multiple login options.

We highly recommend using the simpler setup that adds Auth0 as an external IdP directly in the NetBird Management Dashboard. This approach requires minimal configuration, works alongside local users, and doesn't require replacing your embedded IdP. See the Management Setup (Recommended) section in the main Auth0 documentation.