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

id, title, sidebar_position, tags

id	title	sidebar_position	tags
using-netbird-with-keycloak	Using NetBird with Keycloak	3	integrations idp keycloak oidc how-to

This guide is a part of the NetBird Self-hosting Guide and explains how to integrate self-hosted NetBird with Keycloak.

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. :::

The following guide is an adapted version of the original Keycloak on Docker guide from the official website.

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. 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.

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: 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.

:::note Make sure that your Keycloak instance and NETBIRD_AUTH_AUTHORITY use HTTPS. Otherwise, the setup won't work. :::