mirror of
https://github.com/netbirdio/docs.git
synced 2026-04-18 00:16:36 +00:00
466 lines
19 KiB
Plaintext
466 lines
19 KiB
Plaintext
import {HeroPattern} from "@/components/HeroPattern"; import {Note} from "@/components/mdx";
|
|
|
|
<HeroPattern />
|
|
|
|
# Identity Providers
|
|
|
|
There are a few Identity Provider options that you can choose to run a self-hosted version NetBird.
|
|
|
|
<Note>
|
|
NetBird supports generic OpenID (OIDC) protocol allowing for the integration with any IDP that follows the specification.
|
|
</Note>
|
|
|
|
## Auth0
|
|
|
|
This guide is a part of the [NetBird Self-hosting Guide](/docs/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](/integrations/identity-providers/self-hosted/using-netbird-with-keycloak).
|
|
</Note>
|
|
|
|
### Step 1: Create Auth0 account
|
|
To create an Auth0 account, sign up at [https://auth0.com](https://auth0.com/).
|
|
|
|
There are five 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)
|
|
|
|
### 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`** as: `Allowed Callback URLs`, `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:
|
|
```
|
|
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](/getting-started/installation#running-netbird-with-sso-login) allows for machine
|
|
authorization with your Identity Provider. This feature can be used as an alternative to [setup keys](/docs/how-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`
|
|
|
|
|
|
|
|
- Click `Settings` tab
|
|
- Copy **`Client ID`** to `NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID` in the `setup.env` file
|
|
|
|
|
|
|
|
- Scroll down to the `Advanced Settings` section
|
|
- Enable **`Device Code`**
|
|
- Click `Save Changes`
|
|
|
|
|
|
|
|
|
|
### Step 4: Continue with the self-hosting guide
|
|
You can now continue with the [NetBird Self-hosting Guide](/docs/selfhosted/selfhosted-guide).
|
|
|
|
## Keycloak
|
|
|
|
This guide is a part of the [NetBird Self-hosting Guide](/docs/selfhosted/selfhosted-guide) and explains how to integrate
|
|
**self-hosted** NetBird with [Keycloak](https://www.keycloak.org/).
|
|
|
|
Keycloak is an open source software product to allow single sign-on with Identity and Access Management aimed at modern applications and services.
|
|
|
|
<Note>
|
|
If you prefer not to self-host an Identity and Access Management solution, then you could use a managed alternative like
|
|
[Auth0](/integrations/identity-providers/self-hosted/using-netbird-with-auth0).
|
|
</Note>
|
|
|
|
The following guide is an adapted version of the original
|
|
[Keycloak on Docker](https://www.keycloak.org/getting-started/getting-started-docker) guide from the official website.
|
|
|
|
### Expected Result
|
|
|
|
After completing this guide, you can log in to your self-hosted NetBird Dashboard and add your machines
|
|
to your network using the [Interactive SSO Login feature](/getting-started/installation#running-netbird-with-sso-login)
|
|
over Keycloak.
|
|
|
|
|
|
|
|
### Step 1: Check your Keycloak Instance
|
|
|
|
For this guide, you need a fully configured Keycloak instance running with SSL.
|
|
|
|
We assume that your Keycloak instance is available at **`https://YOUR-KEYCLOAK-HOST-AND_PORT`**.
|
|
Feel free to change the port if you have configured Keycloak with a different one.
|
|
|
|
Most of the OIDC software requires SSL for production use.
|
|
We encourage you to comply with this requirement to make the world more secure 😊.
|
|
|
|
### Step 2: Create a realm
|
|
|
|
To create a realm you need to:
|
|
|
|
- Open the Keycloak Admin Console
|
|
- Hover the mouse over the dropdown in the top-left corner where it says `Master`, then click on `Create Realm`
|
|
- Fill in the form with the following values:
|
|
- Realm name: `netbird`
|
|
- Click `Create`
|
|
-
|
|
|
|
|
|
### Step 3: Create a user
|
|
|
|
In this step we will create a NetBird administrator user.
|
|
|
|
- Open the Keycloak Admin Console
|
|
- Make sure, that the selected realm is `Netbird`
|
|
- Click `Users` (left-hand menu)
|
|
- Click `Create new user`
|
|
- Fill in the form with the following values:
|
|
- Username: `netbird`
|
|
- Click `Create`
|
|
|
|
|
|
|
|
The user will need an initial password set to be able to log in. To do this:
|
|
- Click `Credentials` tab
|
|
- Click `Set password` button
|
|
- Fill in the password form with a password
|
|
- Set the `Temporary` field to `Off` to prevent having to update password on first login
|
|
- Click `Save`
|
|
|
|
|
|
|
|
### Step 4: Create a NetBird client
|
|
|
|
In this step we will create NetBird application client and register with the Keycloak instance.
|
|
|
|
- Open the Keycloak Admin Console
|
|
- Make sure, that the selected realm is `Netbird`
|
|
- Click `Clients`
|
|
- Click `Create client` button
|
|
- Fill in the form with the following values and click Next:
|
|
- Client Type: `OpenID Connect`
|
|
- Client ID: `netbird-client`
|
|
- Your newly client `netbird-client` will be used later to set `NETBIRD_AUTH_CLIENT_ID` in the `setup.env`
|
|
|
|
|
|
|
|
- Check the checkboxes as on the screenshot below and click Save
|
|
|
|
|
|
|
|
### Step 5: Adjust NetBird client access settings
|
|
|
|
In this step we will configure NetBird application client access with the NetBird URLs.
|
|
|
|
- Open the Keycloak Admin Console
|
|
- Make sure, that the selected realm is `Netbird`
|
|
- Click `Clients`
|
|
- Choose `netbird-client` from the list
|
|
- Go to `Access Settings` section
|
|
- Fill in the fields with the following values:
|
|
- Root URL: `https://YOUR DOMAIN/` (this is the NetBird Dashboard root URL)
|
|
- Valid redirect URIs: `https://YOUR DOMAIN/*`
|
|
- Valid post logout redirect URIs: `https://YOUR DOMAIN/*`
|
|
- Web origins: `+`
|
|
- Click `Save`
|
|
|
|
|
|
|
|
### Step 6: Create a NetBird client scope
|
|
|
|
In this step, we will create and configure the NetBird client audience for Keycloak to add it to the generated JWT tokens.
|
|
|
|
- Open the Keycloak Admin Console
|
|
- Make sure, that the selected realm is `Netbird`
|
|
- Click `Client scopes` (left-hand menu)
|
|
- Click `Create client scope` button
|
|
- Fill in the form with the following values:
|
|
- Name: `api`
|
|
- Type: `Default`
|
|
- Protocol: `OpenID Connect`
|
|
- Click `Save`
|
|
|
|
|
|
|
|
- While in the newly created Client Scope, switch to the `Mappers` tab
|
|
- Click `Configure a new mapper`
|
|
- Choose the `Audience` mapping
|
|
|
|
|
|
|
|
- Fill in the form with the following values:
|
|
- Name: `Audience for NetBird Management API`
|
|
- Included Client Audience: `netbird-client`
|
|
- Add to access token: `On`
|
|
- Click `Save`
|
|
|
|
|
|
|
|
### Step 7: Add client scope to NetBird client
|
|
|
|
- Open the Keycloak Admin Console
|
|
- Make sure, that the selected realm is `Netbird`
|
|
- Click `Clients`
|
|
- Choose `netbird-client` from the list
|
|
- Switch to `Client scopes` tab
|
|
- Click `Add client scope` button
|
|
- Choose `api`
|
|
- Click `Add` choosing `Default`
|
|
- The value `netbird-client` will be used as audience
|
|
|
|
|
|
|
|
### Step 8: Create a NetBird-Backend client
|
|
|
|
In this step we will create NetBird backend client and register with the Keycloak instance.
|
|
|
|
- Open the Keycloak Admin Console
|
|
- Make sure, that the selected realm is `Netbird`
|
|
- Click `Clients`
|
|
- Click `Create client` button
|
|
- Fill in the form with the following values and click Next:
|
|
- Client Type: `OpenID Connect`
|
|
- Client ID: `netbird-backend`
|
|
- Your newly client `netbird-backend` will be used later to set `KeycloakClientCredentials` in the `management.json`
|
|
|
|
|
|
|
|
- Check the checkboxes as on the screenshot below and click Save
|
|
|
|
|
|
|
|
The client will need secret to authenticate. To do this:
|
|
- Click `Credentials` tab
|
|
- Copy `client secret` will be used later to set `ClientSecret` in the `management.json`
|
|
|
|
|
|
|
|
### Step 9: Add manage-users role to netbird-backend
|
|
|
|
- Open the Keycloak Admin Console
|
|
- Make sure, that the selected realm is `Netbird`
|
|
- Click `Clients`
|
|
- Choose `netbird-backend` from the list
|
|
- Switch to `Service accounts roles` tab
|
|
- Click `Assign roles` button
|
|
- Select `Filter by clients` and search for `manage-users`
|
|
|
|
|
|
|
|
- Check the role checkbox and click assign
|
|
|
|
|
|
|
|
Your authority OIDC configuration will be available under:
|
|
```
|
|
https://<YOUR-KEYCLOAK-HOST-AND-PORT>/realms/netbird/.well-known/openid-configuration
|
|
```
|
|
<Note>
|
|
Double-check if the endpoint returns a JSON response by calling it from your browser.
|
|
</Note>
|
|
|
|
- Set properties in the `setup.env` file:
|
|
- NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT=`https://<YOUR-KEYCLOAK-HOST-AND-PORT>/realms/netbird/.well-known/openid-configuration`.
|
|
- NETBIRD_AUTH_CLIENT_ID=`netbird-client`
|
|
- NETBIRD_AUTH_AUDIENCE=`netbird-client`
|
|
- NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID=`netbird-client`. Optional,
|
|
it enables the [Interactive SSO Login feature](/getting-started/installation#running-netbird-with-sso-login) (Oauth 2.0 Device Authorization Flow)
|
|
|
|
- You can now continue with the [NetBird Self-hosting Guide](/docs/selfhosted/selfhosted-guide).
|
|
|
|
- Set property `IdpManagerConfig` in the `management.json` file with:
|
|
<Note>
|
|
The file management.json is created automatically. Please refer [here](/getting-started/self-hosting#step-5-run-configuration-script) for more information.
|
|
</Note>
|
|
|
|
```json
|
|
{
|
|
"ManagerType": "keycloak",
|
|
"KeycloakClientCredentials": {
|
|
"ClientID": "netbird-backend",
|
|
"ClientSecret": "<netbird-backend-client-secret>",
|
|
"GrantType": "client_credentials",
|
|
"TokenEndpoint": "https://<YOUR-KEYCLOAK-HOST-AND-PORT>/realms/netbird/protocol/openid-connect/token",
|
|
"AdminEndpoint": "https://<YOUR-KEYCLOAK-HOST-AND-PORT>/admin/realms/netbird"
|
|
}
|
|
}
|
|
```
|
|
|
|
<Note>
|
|
Make sure that your Keycloak instance use HTTPS. Otherwise, the setup won't work.
|
|
</Note>
|
|
|
|
## Azure AD
|
|
|
|
This guide is a part of the [NetBird Self-hosting Guide](/docs/selfhosted/selfhosted-guide) and explains how to integrate **self-hosted** NetBird with [Azure AD](https://azure.microsoft.com/en-us/products/active-directory/).
|
|
|
|
Azure AD is a an enterprise identity service that provides single sign-on and multifactor authentication to your applications.
|
|
It is a 3rd party managed service and can't be self-hosted.
|
|
|
|
<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](/integrations/identity-providers/self-hosted/using-netbird-with-keycloak).
|
|
</Note>
|
|
|
|
Before you start creating and configuring an Azure AD application, ensure that you have the following:
|
|
- An Azure account: To create an Azure AD application, you must have an Azure account. If you don't have one, sign up for a free account at https://azure.microsoft.com/free/.
|
|
|
|
- User account with appropriate permissions: You must have an Azure AD user account with the appropriate permissions to create and manage Azure AD applications. If you don't have the required permissions, ask your Azure AD administrator to grant them to you.
|
|
|
|
|
|
### 1. Create and configure Azure AD application
|
|
In this step, we will create and configure Netbird application in azure AD.
|
|
- Navigate to [Azure Active Directory](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview)
|
|
- Click `App Registrations` in the left menu then click on the `+ New registration` button to create a new application.
|
|
- Fill in the form with the following values and click Register
|
|
- Name: `Netbird`
|
|
- Account Types: `Accounts in this organizational directory only (Default Directory only - Single tenant)`
|
|
- Redirect URI: select `Single-page application (SPA)` and URI as `https://<yournetbirddomain.com>/silent-auth`
|
|
|
|
|
|
|
|
### 2. Platform configurations
|
|
- Click `Authentication` on the left side menu
|
|
- Under the `Single-page application` Section, add another URI `https://<yournetbirddomain.com>/auth`
|
|
|
|
|
|
- Scroll down and setup other options as on the screenshot below and click Save
|
|
|
|
|
|
|
|
### 3. Create a NetBird application scope
|
|
- Click `Expose an API` on the left menu
|
|
- Under `Application ID URI` click `Set` and then `Save`
|
|
- Click `+ Add a Scope`
|
|
- Fill in the form with the following values and click `Add scope`
|
|
- Scope name: `api`
|
|
|
|
|
|
|
|
- Under `Authorized client Applications`, click on `+ add a client application` and enter the following:
|
|
- Fill in the form with the following values and click `Add application`
|
|
- Client ID: same as your Application ID URI minus the `api://`
|
|
|
|
|
|
|
|
|
|
### 4. Add API permissions
|
|
- Add `Netbird` permissions
|
|
- Click `API permissions` on the left menu
|
|
- Click `Add a permission`
|
|
- Click `My APIs` tab, and select `Netbird`. Next check `api` permission checkbox and click `Add permissions`.
|
|
|
|
|
|
|
|
- Add `Delagated permissions` to Microsoft Graph
|
|
- Click `Add a permission`
|
|
- Click `Microsoft Graph` and then click `Delagated permissions` tab and check all permissions under the `OpenId permissions` section and click `Add permissions`
|
|
|
|
|
|
|
|
|
|
- Add `Application permissions` to Microsoft Graph
|
|
- Click `Add a permission`
|
|
- Click `Microsoft Graph` and then click `Application permissions` tab
|
|
- Search for `User.ReadWrite.All` and under `User` sections and check `User.ReadWrite.All` checkbox section
|
|
|
|
|
|
|
|
- Search for `Application.ReadWrite.All` and under `Application` sections and check `Application.ReadWrite.All` checkbox section and click `Add permissions`
|
|
|
|
|
|
|
|
- Click `Grant admin conset for Default Directory` and click `Yes`
|
|
|
|
|
|
|
|
### 4. Update token version
|
|
- Click `Manifest` on left menu
|
|
- Search for `accessTokenAcceptedVersion` and change the value from `null` to `2`
|
|
- Click `Save`
|
|
|
|
### 5. Generate client secret
|
|
- Click `Certificates & secrets` on left menu
|
|
- Click `New client secret`
|
|
- Fill in the form with the following values and click `Add`
|
|
- Description: `Netbird`
|
|
- Copy `Value` and save it as it can be viewed only once after creation.
|
|
|
|
|
|
|
|
Your authority OIDC configuration will be available under:
|
|
```
|
|
https://login.microsoftonline.com/<tenant_id>/v2.0/.well-known/openid-configuration
|
|
```
|
|
<Note>
|
|
Double-check if the endpoint returns a JSON response by calling it from your browser.
|
|
</Note>
|
|
|
|
- Set properties in the `setup.env` file:
|
|
```json
|
|
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://login.microsoftonline.com/<tenant_id>/v2.0/.well-known/openid-configuration"
|
|
NETBIRD_USE_AUTH0=false
|
|
NETBIRD_AUTH_CLIENT_ID="<application_id>"
|
|
NETBIRD_AUTH_AUDIENCE="<application_id>"
|
|
NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID="<application_id>"
|
|
NETBIRD_AUTH_REDIRECT_URI="/auth"
|
|
NETBIRD_AUTH_SILENT_REDIRECT_URI="/silent-auth"
|
|
NETBIRD_AUTH_USER_ID_CLAIM="oid"
|
|
```
|
|
|
|
- You can now continue with the [NetBird Self-hosting Guide](/getting-started/self-hosting#step-3-configure-identity-provider).
|
|
|
|
- Set property `IdpManagerConfig` in the `management.json` file with:
|
|
<Note>
|
|
The file management.json is created automatically. Please refer [here](/getting-started/self-hosting#step-5-run-configuration-script) for more information.
|
|
</Note>
|
|
|
|
```json
|
|
{
|
|
"ManagerType": "azure",
|
|
"AzureClientCredentials": {
|
|
"ClientID": "<application_id>",
|
|
"ClientSecret": "<client_secret>",
|
|
"GrantType": "client_credentials",
|
|
"ObjectID": "<object_id>",
|
|
"TokenEndpoint": "https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token",
|
|
"GraphAPIEndpoint": "https://graph.microsoft.com/v1.0"
|
|
}
|
|
}
|
|
```
|
|
|
|
- Modify the value of the `AUTH_SUPPORTED_SCOPES` environment variable for the dashboard service in the docker-compose.yml file to `openid profile email offline_access api://<application_id>/api`.
|
|
|