some file

Auth0 SSO with NetBird Self-Hosted

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.

Add Auth0 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
  • Auth0 account (sign up at https://auth0.com/)

Step 1: Start Creating Application in Auth0

  1. Log in to your Auth0 dashboard at https://manage.auth0.com/
  2. Go to Applications → Applications
  3. Click Create Application

Create application

  1. Fill in:
    • Name: NetBird
    • Application type: Regular Web Application

Create web application

  1. Click Create

Step 2: 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
NameAuth0 (or your preferred display name)
Client IDFrom Auth0 application (will fill after Step 3)
Client SecretFrom Auth0 application (will fill after Step 3)
Issuerhttps://your-tenant.auth0.com/ (must include trailing slash) (will fill after Step 3)
  1. Copy the Redirect URL that NetBird displays (but don't click Add Provider yet)

Step 3: Complete Auth0 Application Setup

  1. Return to the Auth0 tab
  2. Go to Settings tab
  3. Under Allowed Callback URLs, add the redirect URL you copied from NetBird
  4. Click Save Changes

Add and save callback URL

  1. Note the Client ID, Client Secret, and Domain (e.g., your-tenant.auth0.com) at the top of the setting tab — you'll need these for Step 4

Copy client secret and IDs

Step 4: Complete NetBird Setup

  1. Return to the NetBird tab
  2. Fill in the Client ID and Client Secret from Step 3
  3. Update the Issuer field with your Auth0 domain if needed (e.g., https://your-tenant.auth0.com/)

NetBird IdP configuration

  1. Click Add Provider

Step 5: Test the Connection

  1. Log out of NetBird Dashboard
  2. On the login page, you should see an "Auth0" button
  3. Click it and authenticate
  4. You should be redirected back to NetBird and logged in. Unless your user approval setting were changed you will need to log back into your local admin account to approve the user.

Standalone Setup (Advanced)

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 Keycloak.

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