mirror of
https://github.com/netbirdio/docs.git
synced 2026-04-15 23:16:36 +00:00
add first version of tailwind docs
This commit is contained in:
Pascal Fischer
@@ -1,4 +0,0 @@
|
||||
{
|
||||
"label": "Self-Hosted NetBird",
|
||||
"position": 4
|
||||
}
|
||||
@@ -1,91 +0,0 @@
|
||||
---
|
||||
id: using-netbird-with-auth0
|
||||
title: Using NetBird with Auth0
|
||||
sidebar_position: 2
|
||||
tags:
|
||||
- integrations
|
||||
- idp
|
||||
- auth0
|
||||
- oidc
|
||||
- how-to
|
||||
---
|
||||
|
||||
This guide is a part of the [NetBird Self-hosting Guide](/getting-started/self-hosting) 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.
|
||||
|
||||
:::tip self-hosted idp
|
||||
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).
|
||||
:::
|
||||
|
||||
### 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)`
|
||||
:::caution
|
||||
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
|
||||
```
|
||||
:::caution
|
||||
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](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](/overview/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](/getting-started/self-hosting#step-3-configure-identity-provider).
|
||||
@@ -1,15 +0,0 @@
|
||||
---
|
||||
id: available-idp-integrations
|
||||
title: Available IDP Integrations
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
There are a few Identity Provider options that you can choose to run a self-hosted version NetBird.
|
||||
|
||||
:::tip OpenID
|
||||
NetBird supports generic OpenID (OIDC) protocol allowing for the integration with any IDP that follows the specification.
|
||||
:::
|
||||
|
||||
List of available guides:
|
||||
- [Auth0](/integrations/identity-providers/self-hosted/using-netbird-with-auth0) (managed service)
|
||||
- [Keycloak](/integrations/identity-providers/self-hosted/using-netbird-with-keycloak)
|
||||
@@ -1,88 +0,0 @@
|
||||
---
|
||||
id: using-netbird-with-azure-sso
|
||||
title: Using NetBird with Azure SSO
|
||||
sidebar_position: 4
|
||||
tags:
|
||||
- integrations
|
||||
- idp
|
||||
- azure
|
||||
- oidc
|
||||
- how-to
|
||||
---
|
||||
|
||||
This guide is a part of the [NetBird Self-hosting Guide](/getting-started/self-hosting) and explains how to integrate
|
||||
**self-hosted** NetBird with [Azure SSO](https://azure.microsoft.com/en-us/solutions/active-directory-sso/#overview).
|
||||
|
||||
This is an organized collection of instructions gathered from the [Netbird Slack](https://netbirdio.slack.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`
|
||||
- `NETBIRD_AUTH_DEVICE_AUTH_PROVIDER`
|
||||
- `NETBIRD_AUTH_REDIRECT_URI`
|
||||
- `NETBIRD_AUTH_SILENT_REDIRECT_URI`
|
||||
|
||||
|
||||
In Azure, Navigate to **Azure Active Directory**, and click on **App Registrations** in the left hand menu. Once there, Click on **New registration** across the top menu bar.
|
||||
- Write a name for your application and choose who can access your application.
|
||||
- For Redirect URI, Choose Single-page Application(SPA). for the next box, type your netbird.domainname + auth. E.g `https://netbird.mydomainname.com/auth`. Keep the `auth` in mind as this will be your value for `NETBIRD_AUTH_REDIRECT_URI`
|
||||
- On this next page, copy the `Application (client) ID`. This will be the value for the following:
|
||||
- `NETBIRD_AUTH_AUDIENCE`
|
||||
- `NETBIRD_AUTH_CLIENT_ID`
|
||||
- `NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID`
|
||||
|
||||
|
||||
### 1. Authentication
|
||||
Within the same section (App Registrations), navigate to **Authentication** via the left hand menu. Once there, perform the following:
|
||||
- Under the Single-page Application Section, Add another URI with the following value: `https://yournetbirddomain.com/silent-auth`. The `silent-auth` section of the url is the value for `NETBIRD_AUTH_SILENT_REDIRECT_URI`
|
||||
- You should have two URI's listed similar to these:
|
||||
- `https://yournetbirddomain.com/auth`
|
||||
- `https://yournetbirddomain.com/silent-auth`
|
||||
- Scroll down and check off the following two boxes:
|
||||
- `Access tokens (used for implicit flows)`
|
||||
- `ID tokens (used for implicit and hybrid flows)`
|
||||
|
||||
|
||||
### 2. Expose API
|
||||
Next, on the left hand menu, click on **Expose an API**. Next, set an `Application ID URI`. You can choose the default value as is, or set your own. Click on **Add a Scope**, and enter the following:
|
||||
- **Scope Name:** `api`
|
||||
- The rest you can choose as your work requires it.
|
||||
|
||||
Next under **Authorized client Applications**, click on **add a client application** and enter the following:
|
||||
- **Client ID**: This is the same as your Application ID URI minus the `api://`. See the picture below as a reference
|
||||
- **Authorized Scopes:** The correct scope will contain your **Client ID** used in the above step. The correct Authorized Scope will be similar to `api://YOUR_CLIENT_ID/api` (api is the value of the name of the scope we defined before.)
|
||||
|
||||
|
||||
|
||||
|
||||
### 3. API permissions
|
||||
Under **API Permissions**, click on **Add a permission**. On the next screen that pops up, click on **My APIs**, and select the API that matches with your **Application Client ID**. Next Select the scope we created in the earlier steps.
|
||||
|
||||
### 4. Manifest
|
||||
On the left hand Menu, click on **Manifest**. On the next page, search for `accessTokenAcceptedVersion` and change the value from `null` to `2`.
|
||||
|
||||
### 5. Continue with the self-hosting guide
|
||||
Your authority OIDC configuration will be available under:
|
||||
```
|
||||
https://login.microsoftonline.com/YOUR-DIRECTORY(TENANT)-ID/v2.0/.well-known/openid-configuration
|
||||
```
|
||||
:::caution
|
||||
Double-check if the endpoint returns a JSON response by calling it from your browser.
|
||||
:::
|
||||
|
||||
- Set properties in the `setup.env` file:
|
||||
- NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT=`https://login.microsoftonline.com/YOUR-DIRECTORY(TENANT)-ID/v2.0/.well-known/openid-configuration`
|
||||
- this can be grabbed by clicking on `Endpoints` in your App's **App Registration* Over Page.
|
||||
- NETBIRD_AUTH_CLIENT_ID=**YOUR APPLICATION (client) ID**
|
||||
- This can be grabbed from your App's **App Registration** Overview page
|
||||
- NETBIRD_AUTH_AUDIENCE=**YOUR APPLICATION (client) ID**
|
||||
- NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID=**YOUR Application (client) ID**. Optional,
|
||||
- NETBIRD_USE_AUTH0=`false`
|
||||
- NETBIRD_AUTH_DEVICE_AUTH_PROVIDER=`hosted`
|
||||
- NETBIRD_AUTH_REDIRECT_URI=`/auth`
|
||||
- NETBIRD_AUTH_SILENT_REDIRECT_URI=`/silent-auth`
|
||||
- You can now continue with the [NetBird Self-hosting Guide](/getting-started/self-hosting#step-3-configure-identity-provider).
|
||||
|
||||
@@ -1,238 +0,0 @@
|
||||
---
|
||||
id: using-netbird-with-keycloak
|
||||
title: Using NetBird with Keycloak
|
||||
sidebar_position: 3
|
||||
tags:
|
||||
- integrations
|
||||
- idp
|
||||
- keycloak
|
||||
- oidc
|
||||
- how-to
|
||||
---
|
||||
|
||||
This guide is a part of the [NetBird Self-hosting Guide](/getting-started/self-hosting) 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.
|
||||
|
||||
:::tip managed idp
|
||||
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).
|
||||
:::
|
||||
|
||||
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
|
||||
```
|
||||
:::caution
|
||||
Double-check if the endpoint returns a JSON response by calling it from your browser.
|
||||
:::
|
||||
|
||||
- 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](/getting-started/self-hosting#step-3-configure-identity-provider).
|
||||
|
||||
- Set property `IdpManagerConfig` in the `management.json` file with:
|
||||
:::caution
|
||||
The file management.json is created automatically. Please refer [here](/getting-started/self-hosting#step-5-run-configuration-script) for more information.
|
||||
:::
|
||||
|
||||
```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.
|
||||
:::
|
||||
Reference in New Issue
Block a user