mirror of
https://github.com/netbirdio/docs.git
synced 2026-04-19 00:46:35 +00:00
67d2b0fa94
* Refactor NavigationDocs component and update documentation structure - Improved formatting and organization of the NavigationDocs component for better readability. - Updated the docsNavigation structure to include detailed sections for managing peers, access control, networks, and integrations. - Removed the identity providers documentation file as part of the restructuring effort. - Enhanced the overall navigation experience by ensuring all links are properly formatted and accessible. * Update NavigationDocs to include new SSO links and remove outdated documentation - Added links for Authentik, Keycloak, Auth0, and JumpCloud under the Single Sign-On section in NavigationDocs. - Removed the single-sign-on.mdx file as part of the documentation cleanup effort. * Add more info about self-hosted IdP support * Update Single Sign-On documentation and NavigationDocs - Updated titles and added introductory text for Auth0, Authentik, JumpCloud, and Keycloak pages to clarify their use as Identity Providers with NetBird. - Commented out the links section in NavigationDocs for Single Sign-On to reflect the current documentation state. Didn't make sense to have those and didn't want to confuse people thinking those are the only supported providers. - Enhanced the index page to include detailed descriptions and setup buttons for Okta ans each OIDC Identity Provider. * Update paths in structure and documentation for Auth0, Authentik, Keycloak, Microsoft Entra ID, Google Workspace, and JumpCloud. This cleanup enhances clarity and ensures all references point to the correct resources. --------- Co-authored-by: braginini <bangvalo@gmail.com>
151 lines
6.6 KiB
Plaintext
151 lines
6.6 KiB
Plaintext
import {Note} from "@/components/mdx";
|
|
|
|
# Auth0 with NetBird Self-Hosted
|
|
|
|
This guide is a part of the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide) and explains how to integrate **self-hosted** NetBird with [Auth0](https://auth0.com/).
|
|
|
|
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.
|
|
|
|
<Note>
|
|
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](/selfhosted/identity-providers#keycloak).
|
|
</Note>
|
|
|
|
## Step 1: Create Auth0 account
|
|
To create an Auth0 account, sign up at [https://auth0.com](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](https://auth0.com/docs/quickstart/spa/react/01-login#configure-auth0)
|
|
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)`
|
|
<Note>
|
|
Make sure that **`Token Endpoint Authentication Method`** is set to **`None`**.
|
|
</Note>
|
|
|
|
- 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:
|
|
|
|
```bash
|
|
https://<DOMAIN>/.well-known/openid-configuration
|
|
```
|
|
<Note>
|
|
Double-check if the endpoint returns a JSON response by calling it from your browser.
|
|
</Note>
|
|
|
|
#### 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](https://auth0.com/docs/quickstart/backend/golang#create-an-api).
|
|
- Use API **`Identifier`** to set ```NETBIRD_AUTH_AUDIENCE``` property in the `setup.env` file.
|
|
- Set ```NETBIRD_USE_AUTH0``` to `true`in the `setup.env` file.
|
|
|
|
## Step 4: Enable Interactive SSO Login (Optional)
|
|
|
|
The [Interactive SSO Login feature](/get-started/install#running-net-bird-with-sso-login) allows for machine
|
|
authorization with your Identity Provider. This feature can be used as an alternative to [setup keys](/manage/peers/register-machines-using-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`
|
|
|
|
<p>
|
|
<img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-create-interactive-login-app.png" alt="high-level-dia" className="imagewrapper-big"/>
|
|
</p>
|
|
|
|
- Click `Settings` tab
|
|
- Copy **`Client ID`** to `NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID` in the `setup.env` file
|
|
|
|
<p>
|
|
<img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-interactive-login-settings.png" alt="high-level-dia" className="imagewrapper-big"/>
|
|
</p>
|
|
|
|
- Scroll down to the `Advanced Settings` section
|
|
- Enable **`Device Code`**
|
|
- Click `Save Changes`
|
|
|
|
<p>
|
|
<img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-grant-types.png" alt="high-level-dia" className="imagewrapper-big"/>
|
|
</p>
|
|
|
|
## 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`
|
|
|
|
<p>
|
|
<img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-create-machine-app.png" alt="high-level-dia" className="imagewrapper-big"/>
|
|
</p>
|
|
|
|
- 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`
|
|
|
|
<p>
|
|
<img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-machine-authorization.png" alt="high-level-dia" className="imagewrapper-big"/>
|
|
</p>
|
|
|
|
<Note>
|
|
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.
|
|
</Note>
|
|
|
|
- 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
|
|
|
|
<p>
|
|
<img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-machine-settings.png" alt="high-level-dia" className="imagewrapper-big"/>
|
|
</p>
|
|
|
|
- Set properties in the `setup.env` file:
|
|
```shell
|
|
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](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional). |