Skip to main content

Using NetBird with Keycloak

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.

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.

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

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

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 OIDC configuration will be available under:

https://<YOUR-KEYCLOAK-HOST-AND-PORT>/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_OIDC_CONFIGURATION_ENDPOINT=https://<YOUR-KEYCLOAK-HOST-AND-PORT>/realms/netbird/.well-known/openid-configuration.
    • NETBIRD_AUTH_CLIENT_ID=netbird-client
    • NETBIRD_AUTH_AUDIENCE=netbird-client
    • NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID=netbird-client. Optional, it enables the Interactive SSO Login feature (Oauth 2.0 Device Authorization Flow)

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

note

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