diff --git a/docs/getting-started/self-hosting.md b/docs/getting-started/self-hosting.md index 920c4297..e772d2ec 100644 --- a/docs/getting-started/self-hosting.md +++ b/docs/getting-started/self-hosting.md @@ -57,17 +57,16 @@ The [setup.env.example](https://github.com/netbirdio/netbird/tree/main/infrastru ## # Dashboard domain. e.g. app.mydomain.com NETBIRD_DOMAIN="" -# e.g. https://dev-24vkclam.us.auth0.com/ or https://YOUR-KEYCLOAK-HOST:8080/realms/netbird -NETBIRD_AUTH_AUTHORITY="" +# OIDC configuration e.g., https://example.eu.auth0.com/.well-known/openid-configuration +NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="" +NETBIRD_AUTH_AUDIENCE="" # e.g. netbird-client NETBIRD_AUTH_CLIENT_ID="" # indicates whether to use Auth0 or not: true or false -NETBIRD_USE_AUTH0="" -# a list of scopes supported e.g. `openid profile email` for keycloak or `openid profile email api offline_access email_verified` for Auth0 -NETBIRD_AUTH_SUPPORTED_SCOPES="" -NETBIRD_AUTH_AUDIENCE="" -# URL of the JWT certificates e.g. https://dev-24vkclam.us.auth0.com/.well-known/jwks.json -NETBIRD_AUTH_JWT_CERTS="" +NETBIRD_USE_AUTH0="false" +NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="none" +# enables Interactive SSO Login feature (Oauth 2.0 Device Authorization Flow) +NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID="" # e.g. hello@mydomain.com NETBIRD_LETSENCRYPT_EMAIL="" ``` diff --git a/docs/integrations/identity-providers/self-hosted/auth0.md b/docs/integrations/identity-providers/self-hosted/auth0.md index fc860008..53c0e9c2 100644 --- a/docs/integrations/identity-providers/self-hosted/auth0.md +++ b/docs/integrations/identity-providers/self-hosted/auth0.md @@ -24,22 +24,68 @@ self-hosted alternatives to the managed Auth0 service like [Keycloak](/integrati ### Step 1: Create Auth0 account To create an Auth0 account, sign up at [https://auth0.com](https://auth0.com/). -### Step 2: Configure Auth0 properties in the setup.env file -1. Configure ```NETBIRD_AUTH_AUTHORITY``` and ```NETBIRD_AUTH_CLIENT_ID``` properties. +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) - * To obtain these, use [Auth0 React SDK Guide](https://auth0.com/docs/quickstart/spa/react/01-login#configure-auth0) up until "Install the Auth0 React SDK". +### Step 2: Create and configure Auth0 application - > Use ```https://YOUR DOMAIN``` as ````Allowed Callback URLs````, ```Allowed Logout URLs```, ```Allowed Web Origins``` and ```Allowed Origins (CORS)``` - * use Auth0 Client ID to set `NETBIRD_AUTH_CLIENT_ID` e.g., `LBRMAgqIZ7hvpVCaHpQLCJvTzkYYIXJt` - * use Auth0 Domain to set `NETBIRD_AUTH_AUTHORITY` to `https://your-auth0-domain.com/`. Pay attention to the `https://` prefix and the trailing slash `/` - * :warning: Make sure that `Token Endpoint Authentication Method` is set to `None` in your Auth0 Default Application -2. Configure ```NETBIRD_AUTH_AUDIENCE``` property. +This Auth0 application will be used to authorize access to NetBird Dashboard (Web UI). - * Check [Auth0 Create An API](https://auth0.com/docs/quickstart/backend/golang#create-an-api) section to obtain AuthAudience. - * set the property in the ```setup.env``` file. -3. Set `NETBIRD_USE_AUTH0` to `true`. -4. Set `NETBIRD_AUTH_SUPPORTED_SCOPES` to `openid profile email api offline_access email_verified` -5. Set `NETBIRD_AUTH_JWT_CERTS` to `https://your-auth0-domain.com/.well-known/jwks.json` +- 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:///.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 3: Continue with the self-hosting guide +### 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` + +![](/img/integrations/identity-providers/self-hosted/auth0-create-interactive-login-app.png) + +- Click `Settings` tab +- Copy **`Client ID`** to `NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID` in the `setup.env` file + +![](/img/integrations/identity-providers/self-hosted/auth0-interactive-login-settings.png) + +- Scroll down to the `Advanced Settings` section +- Enable **`Device Code`** +- Click `Save Changes` + +![](/img/integrations/identity-providers/self-hosted/auth0-grant-types.png) + +### 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). \ No newline at end of file diff --git a/docs/integrations/identity-providers/self-hosted/keycloak.md b/docs/integrations/identity-providers/self-hosted/keycloak.md index c3067b52..42fa6d93 100644 --- a/docs/integrations/identity-providers/self-hosted/keycloak.md +++ b/docs/integrations/identity-providers/self-hosted/keycloak.md @@ -23,11 +23,19 @@ If you prefer not to self-host an Identity and Access Management solution, then 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. + +![](/img/integrations/identity-providers/self-hosted/keycloak-auth-grant.gif) + ### 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:443. +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. @@ -42,8 +50,7 @@ To create a realm you need to: - Fill in the form with the following values: - Realm name: `netbird` - Click `Create` -- Your newly created realm `https://YOUR-KEYCLOAK-HOST:443/realms/netbird` will be used later to set `NETBIRD_AUTH_AUTHORITY` in the `setup.env` file. - +- ![](/img/integrations/identity-providers/self-hosted/keycloak-create-realm.png) ### Step 3: Create a user @@ -152,20 +159,23 @@ In this step, we will create and configure the NetBird client audience for Keycl ### Step 8: Continue with the self-hosting guide -Your authority configuration will be available under: +Your authority OIDC configuration will be available under: ``` -https://YOUR-KEYCLOAK-HOST:443/realms/netbird/.well-known/openid-configuration +https:///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_AUTHORITY=`https://YOUR-KEYCLOAK-HOST-AND-PORT/realms/netbird`. This is the `issuer` field of the openid-configuration. + - NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT=`https:///realms/netbird/.well-known/openid-configuration`. - NETBIRD_AUTH_CLIENT_ID=`netbird-client` - NETBIRD_AUTH_AUDIENCE=`netbird-client` - - NETBIRD_AUTH_SUPPORTED_SCOPES=`openid profile email offline_access api`. Use the fields specified in the `scopes_supported` field of the openid-configuration. - - NETBIRD_AUTH_JWT_CERTS=`https://YOUR-KEYCLOAK-HOST-AND-PORT/realms/netbird/protocol/openid-connect/certs`. Use `jwks_uri` from the openid-configuration to set `NETBIRD_AUTH_JWT_CERTS` + - 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). :::note -Make sure that your Keycloak instance and `NETBIRD_AUTH_AUTHORITY` use HTTPS. Otherwise, the setup won't work. +Make sure that your Keycloak instance use HTTPS. Otherwise, the setup won't work. ::: \ No newline at end of file diff --git a/static/img/integrations/identity-providers/self-hosted/auth0-create-interactive-login-app.png b/static/img/integrations/identity-providers/self-hosted/auth0-create-interactive-login-app.png new file mode 100644 index 00000000..14d5fbb4 Binary files /dev/null and b/static/img/integrations/identity-providers/self-hosted/auth0-create-interactive-login-app.png differ diff --git a/static/img/integrations/identity-providers/self-hosted/auth0-grant-types.png b/static/img/integrations/identity-providers/self-hosted/auth0-grant-types.png new file mode 100644 index 00000000..938e2c9a Binary files /dev/null and b/static/img/integrations/identity-providers/self-hosted/auth0-grant-types.png differ diff --git a/static/img/integrations/identity-providers/self-hosted/auth0-interactive-login-settings.png b/static/img/integrations/identity-providers/self-hosted/auth0-interactive-login-settings.png new file mode 100644 index 00000000..da5628e8 Binary files /dev/null and b/static/img/integrations/identity-providers/self-hosted/auth0-interactive-login-settings.png differ diff --git a/static/img/integrations/identity-providers/self-hosted/keycloak-auth-grant.gif b/static/img/integrations/identity-providers/self-hosted/keycloak-auth-grant.gif new file mode 100644 index 00000000..50d883d4 Binary files /dev/null and b/static/img/integrations/identity-providers/self-hosted/keycloak-auth-grant.gif differ