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: Deploy Keycloak (Optional)

If you have a running instance of Keycloak, you can skip this step; run the Keycloak container on your server otherwise:

docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:latest start-dev

:::caution We recommend setting the KEYCLOAK_ADMIN to something different than admin and choosing a secure password. :::

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
  • First Name: Your first name
  • Last Name: Your last name
• 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

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
  • Name: NetBird Application Client

• 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: +

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: netbird-client-audience
  • Type: Default
  • Type: OpenID Connect
• Click Save

• 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 netbird-client-audience
• CLick Add choosing Default

Step 8: Continue with the self-hosting guide

Set properties in the setup.env file

You can now continue with the NetBird Self-hosting Guide.