Add docs for running NetBird with Keycloak

docs/getting-started/self-hosting.md

@@ -53,16 +53,21 @@ To simplify the setup we have prepared a script to substitute required propertie
 The [setup.env.example](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/setup.env.example) file contains multiple properties that have to be filled. You need to copy the example file to `setup.env` before updating it.
 
 ```bash
+## example file, you can copy this file to setup.env and update its values
+##
 # Dashboard domain. e.g. app.mydomain.com
 NETBIRD_DOMAIN=""
-# e.g. dev-24vkclam.us.auth0.com
-NETBIRD_AUTH0_DOMAIN=""
-# e.g. 61u3JMXRO0oOevc7gCkZLCwePQvT4lL0
-NETBIRD_AUTH0_CLIENT_ID=""
-# e.g. https://app.mydomain.com/ or https://app.mydomain.com,
-# Make sure you used the exact same value for Identifier
-# you used when creating your Auth0 API
-NETBIRD_AUTH0_AUDIENCE=""
+# e.g. https://dev-24vkclam.us.auth0.com/ or https://YOUR-KEYCLOAK-HOST:8080/realms/netbird
+NETBIRD_AUTH_AUTHORITY=""
+# 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=""
 # e.g. hello@mydomain.com
 NETBIRD_LETSENCRYPT_EMAIL=""
 ```
@@ -79,9 +84,10 @@ Let's Encrypt will notify you via this email when certificates are about to expi
 ### Step 3: Configure Identity Provider
 
 NetBird supports generic OpenID (OIDC) protocol allowing for the integration with any IDP that follows the specification.
+Pick the one that suits your needs, follow the steps, and continue with this guide:
 
-Check out the [Available Integrations](/integrations/identity-providers/self-hosted/available-idp-integrations) section,
-pick the one that suits your needs, follow the steps, and continue with this guide.
+- Continue with [Auth0](/integrations/identity-providers/self-hosted/using-netbird-with-auth0) (managed service).
+- Continue with [Keycloak](/integrations/identity-providers/self-hosted/using-netbird-with-keycloak).
 
 ### Step 4: Run configuration script
 Make sure all the required properties set in the ```setup.env``` file and run:
@@ -99,12 +105,12 @@ docker-compose up -d
 ```
 ### Step 5: Check docker logs (Optional)
 
-     ```bash
-     docker-compose logs signal
-     docker-compose logs management
-     docker-compose logs coturn
-     docker-compose logs dashboard
-    ```
+ ```bash
+ docker-compose logs signal
+ docker-compose logs management
+ docker-compose logs coturn
+ docker-compose logs dashboard
+```
 
 ### Get in touch
 

docs/integrations/identity-providers/self-hosted/auth0.md

@@ -25,17 +25,21 @@ self-hosted alternatives to the managed Auth0 service like [Keycloak](/integrati
 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_AUTH0_DOMAIN``` and ```NETBIRD_AUTH0_CLIENT_ID``` properties.
+1. Configure ```NETBIRD_AUTH_AUTHORITY``` and ```NETBIRD_AUTH_CLIENT_ID``` properties.
 
-    * To obtain these, please use [Auth0 React SDK Guide](https://auth0.com/docs/quickstart/spa/react/01-login#configure-auth0) up until "Install the Auth0 React SDK".
+    * 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".
 
       > Use ```https://YOUR DOMAIN``` as ````Allowed Callback URLs````, ```Allowed Logout URLs```, ```Allowed Web Origins``` and ```Allowed Origins (CORS)```
-    * set the variables in the ```setup.env```
+    * 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_AUTH0_AUDIENCE``` property.
+2. Configure ```NETBIRD_AUTH_AUDIENCE``` property.
 
     * 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`
+  
 ### Step 3: 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).

docs/integrations/identity-providers/self-hosted/available-integrations.md

@@ -10,5 +10,6 @@ There are a few Identity Provider options that you can choose to run a self-host
 NetBird supports generic OpenID (OIDC) protocol allowing for the integration with any IDP that follows the specification.
 :::
 
-This section describes steps to integrate with self-hosted IDPs like [Keycloak](/integrations/identity-providers/self-hosted/using-netbird-with-keycloak)
-or cloud-managed like [Auth0](/integrations/identity-providers/self-hosted/using-netbird-with-auth0).
+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)

docs/integrations/identity-providers/self-hosted/keycloak.md

@@ -10,4 +10,162 @@ tags:
 - how-to
 ---
 
-TODO
+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.
+
+### Step 1: Check your Keycloak Instance
+
+For this guide, you need a fully configured Keycloak instance running with configured SSL.
+
+We assume that your Keycloak instance is available at https://YOUR-KEYCLOAK-HOST:443. 
+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`
+- 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
+
+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`
+
+![](/img/integrations/identity-providers/self-hosted/keycloak-create-user.png)
+
+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`
+
+![](/img/integrations/identity-providers/self-hosted/keycloak-set-password.png)
+
+### 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`
+
+![](/img/integrations/identity-providers/self-hosted/keycloak-create-client.png)
+
+- Check the checkboxes as on the screenshot below and click Save
+
+![](/img/integrations/identity-providers/self-hosted/keycloak-enable-auth.png)
+
+### 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`
+
+![](/img/integrations/identity-providers/self-hosted/keycloak-access-settings.png)
+
+### 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`
+
+![](/img/integrations/identity-providers/self-hosted/keycloak-create-client-scope.png)
+
+- While in the newly created Client Scope, switch to the `Mappers` tab
+- Click `Configure a new mapper`
+- Choose the `Audience` mapping
+
+![](/img/integrations/identity-providers/self-hosted/keycloak-configure-audience-mapper.png)
+
+- 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`
+
+![](/img/integrations/identity-providers/self-hosted/keycloak-configure-audience-mapper-2.png)
+
+### 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 
+
+![](/img/integrations/identity-providers/self-hosted/keycloack-add-client-scope.png)
+
+### Step 8: Continue with the self-hosting guide
+
+Your authority configuration will be available under:
+```
+https://YOUR-KEYCLOAK-HOST:443/realms/netbird/.well-known/openid-configuration
+```
+
+- 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_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`
+
+- 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.
+:::