diff --git a/docs/getting-started/self-hosting.md b/docs/getting-started/self-hosting.md index f71158be..3656ca7b 100644 --- a/docs/getting-started/self-hosting.md +++ b/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 diff --git a/docs/integrations/identity-providers/self-hosted/auth0.md b/docs/integrations/identity-providers/self-hosted/auth0.md index 70f3bb2b..fc860008 100644 --- a/docs/integrations/identity-providers/self-hosted/auth0.md +++ b/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). \ No newline at end of file diff --git a/docs/integrations/identity-providers/self-hosted/introduction.md b/docs/integrations/identity-providers/self-hosted/available-integrations.md similarity index 56% rename from docs/integrations/identity-providers/self-hosted/introduction.md rename to docs/integrations/identity-providers/self-hosted/available-integrations.md index f7fe698e..d9a30adc 100644 --- a/docs/integrations/identity-providers/self-hosted/introduction.md +++ b/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). \ No newline at end of file +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) \ 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 4ca35be8..90761e36 100644 --- a/docs/integrations/identity-providers/self-hosted/keycloak.md +++ b/docs/integrations/identity-providers/self-hosted/keycloak.md @@ -10,4 +10,162 @@ tags: - how-to --- -TODO \ No newline at end of file +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. +::: \ No newline at end of file diff --git a/static/img/integrations/identity-providers/self-hosted/keycloack-add-client-scope.png b/static/img/integrations/identity-providers/self-hosted/keycloack-add-client-scope.png new file mode 100644 index 00000000..79001777 Binary files /dev/null and b/static/img/integrations/identity-providers/self-hosted/keycloack-add-client-scope.png differ diff --git a/static/img/integrations/identity-providers/self-hosted/keycloak-access-settings.png b/static/img/integrations/identity-providers/self-hosted/keycloak-access-settings.png new file mode 100644 index 00000000..e788a554 Binary files /dev/null and b/static/img/integrations/identity-providers/self-hosted/keycloak-access-settings.png differ diff --git a/static/img/integrations/identity-providers/self-hosted/keycloak-configure-audience-mapper-2.png b/static/img/integrations/identity-providers/self-hosted/keycloak-configure-audience-mapper-2.png new file mode 100644 index 00000000..dce65781 Binary files /dev/null and b/static/img/integrations/identity-providers/self-hosted/keycloak-configure-audience-mapper-2.png differ diff --git a/static/img/integrations/identity-providers/self-hosted/keycloak-configure-audience-mapper.png b/static/img/integrations/identity-providers/self-hosted/keycloak-configure-audience-mapper.png new file mode 100644 index 00000000..9a54c13c Binary files /dev/null and b/static/img/integrations/identity-providers/self-hosted/keycloak-configure-audience-mapper.png differ diff --git a/static/img/integrations/identity-providers/self-hosted/keycloak-create-client-scope.png b/static/img/integrations/identity-providers/self-hosted/keycloak-create-client-scope.png new file mode 100644 index 00000000..bdef79ac Binary files /dev/null and b/static/img/integrations/identity-providers/self-hosted/keycloak-create-client-scope.png differ diff --git a/static/img/integrations/identity-providers/self-hosted/keycloak-create-client.png b/static/img/integrations/identity-providers/self-hosted/keycloak-create-client.png new file mode 100644 index 00000000..2dbf841d Binary files /dev/null and b/static/img/integrations/identity-providers/self-hosted/keycloak-create-client.png differ diff --git a/static/img/integrations/identity-providers/self-hosted/keycloak-create-realm.png b/static/img/integrations/identity-providers/self-hosted/keycloak-create-realm.png new file mode 100644 index 00000000..29a36b2d Binary files /dev/null and b/static/img/integrations/identity-providers/self-hosted/keycloak-create-realm.png differ diff --git a/static/img/integrations/identity-providers/self-hosted/keycloak-create-user.png b/static/img/integrations/identity-providers/self-hosted/keycloak-create-user.png new file mode 100644 index 00000000..c6f20772 Binary files /dev/null and b/static/img/integrations/identity-providers/self-hosted/keycloak-create-user.png differ diff --git a/static/img/integrations/identity-providers/self-hosted/keycloak-enable-auth.png b/static/img/integrations/identity-providers/self-hosted/keycloak-enable-auth.png new file mode 100644 index 00000000..a512ba69 Binary files /dev/null and b/static/img/integrations/identity-providers/self-hosted/keycloak-enable-auth.png differ diff --git a/static/img/integrations/identity-providers/self-hosted/keycloak-set-password.png b/static/img/integrations/identity-providers/self-hosted/keycloak-set-password.png new file mode 100644 index 00000000..6ddf65d6 Binary files /dev/null and b/static/img/integrations/identity-providers/self-hosted/keycloak-set-password.png differ