some file

Auth0 with NetBird Self-Hosted

This guide is a part of the NetBird Self-hosting Guide and explains how to integrate self-hosted NetBird with Auth0.

Auth0 is a flexible, drop-in solution to add authentication and authorization services to your applications. It is a 3rd party managed service and can't be self-hosted. Auth0 is the right choice if you don't want to manage an Identity Provider (IDP) instance on your own.

If you prefer to have full control over authentication and authorization of your NetBird network, there are good self-hosted alternatives to the managed Auth0 service like Keycloak.

Step 1: Create Auth0 account

To create an Auth0 account, sign up at https://auth0.com.

There are multiple properties of the setup.env file that we will configure in this guide:

  • 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 2: Create and configure Auth0 application

This Auth0 application will be used to authorize access to NetBird Dashboard (Web UI).

  • Follow the steps in the Auth0 React SDK Guide up until "Install the Auth0 React SDK".
  • Use https://YOUR DOMAIN and http://localhost:53000 as: Allowed Callback URLs,
  • Use https://YOUR DOMAIN and http://localhost as: Allowed Logout URLs, Allowed Web Origins, Allowed Origins (CORS)

Make sure that Token Endpoint Authentication Method is set to None.

  • Use Client ID to set NETBIRD_AUTH_CLIENT_ID property in the setup.env file.
  • Use Domain to configure NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT property in the setup.env file like so:
 https://<DOMAIN>/.well-known/openid-configuration

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

Step 3: Create and configure Auth0 API

This Auth0 API will be used to access NetBird Management Service API.

  • Follow the steps in the Auth0 Create An API.
  • Use API Identifier to set NETBIRD_AUTH_AUDIENCE property in the setup.env file.
  • Set NETBIRD_USE_AUTH0 to truein the setup.env file.

Step 4: Enable Interactive SSO Login (Optional)

The Interactive SSO Login feature allows for machine authorization with your Identity Provider. This feature can be used as an alternative to setup keys and is optional.

You can enable it by following these steps:

  • Log in to your Auth0 account https://manage.auth0.com/
  • Go to Applications (left-hand menu)
  • Click Create Application button (top right)
  • Fill in the form with the following values:
    • Name: Interactive Login
    • Application type: Native
  • Click Create

high-level-dia

  • Click Settings tab
  • Copy Client ID to NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID in the setup.env file

high-level-dia

  • Scroll down to the Advanced Settings section
  • Enable Device Code
  • Click Save Changes

high-level-dia

Step 5: Create and configuire Machine to Machine application.

This application will be used to authorize access to Auth0 Management API.

  • Log in to your Auth0 account https://manage.auth0.com/
  • Go to Applications (left-hand menu)
  • Click Create Application button (top right)
  • Fill in the form with the following values:
    • Name: Netbird API
    • Application type: Machine to Machine Applications
  • Click Create

high-level-dia

  • Fill the form with the following values:
    • API: Auth0 Management API
    • Permissions: read:users, update:users, create:users, read:users_app_metadata, update:users_app_metadata, create:users_app_metadata
    • Click Authorize

high-level-dia

Optional

NetBird offers the ability to automatically delete a user from the Auth0 side when the user is deleted from the associated account. To enable this functionality, include the --user-delete-from-idp flag in the management startup command within your Docker Compose configuration. If you choose to enable this feature, please ensure that you assign the delete:users permission following the steps outlined above.

  • Click Settings tab
  • Copy Client ID to NETBIRD_IDP_MGMT_CLIENT_ID in the setup.env file
  • Copy Client SECRET to NETBIRD_IDP_MGMT_CLIENT_SECRET in the setup.env file
  • Copy DOMAIN to NETBIRD_IDP_MGMT_EXTRA_AUDIENCE in the setup.env file

high-level-dia

  • 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 the NetBird Self-hosting Guide

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