some file

Keycloak

Keycloak is an open-source Identity and Access Management solution maintained by Red Hat. It provides single sign-on, social login, user federation, fine-grained authorization, and supports OpenID Connect, OAuth 2.0, and SAML 2.0 protocols.

Add Keycloak as a connector to the embedded IdP. This is the simplest approach and recommended for most deployments.

Prerequisites

  • NetBird self-hosted with embedded IdP enabled
  • Keycloak instance running with SSL

Step 1: Create Client in Keycloak

  1. Open the Keycloak Admin Console
  2. Select your realm (or create a new one, e.g., netbird)
  3. Click Clients → Create client
  4. Fill in the form:
    • Client type: OpenID Connect
    • Client ID: netbird
  5. Click Next
  6. On Capability config:
    • Enable Client authentication
  7. Click Next
  8. On Login settings:
    • Leave redirect URIs empty for now
  9. Click Save
  10. Go to the Credentials tab and copy the Client secret

Step 2: Add Connector in NetBird

  1. Log in to your NetBird Dashboard
  2. Navigate to Settings → Identity Providers
  3. Click Add Identity Provider
  4. Fill in the fields:
FieldValue
TypeGeneric OIDC
NameKeycloak (or your preferred display name)
Client IDnetbird (from Step 1)
Client SecretFrom Keycloak Credentials tab
Issuerhttps://keycloak.example.com/realms/your-realm
  1. Click Save

Step 3: Configure Redirect URI

After saving, NetBird displays the Redirect URL. Copy this URL and add it to your Keycloak client:

  1. Return to Keycloak Admin Console
  2. Go to your client → Settings tab
  3. Under Valid redirect URIs, add the redirect URL from NetBird
  4. Click Save

Step 4: Test the Connection

  1. Log out of NetBird Dashboard
  2. On the login page, you should see a "Keycloak" button
  3. Click it and authenticate with your Keycloak credentials
  4. You should be redirected back to NetBird and logged in

Users who authenticate via Keycloak will appear in your NetBird Users list with a Keycloak badge next to their name.

Standalone Setup (Advanced)

Use Keycloak as your primary identity provider instead of NetBird's embedded IdP. This option gives you full control over authentication and user management, is recommended for experienced Keycloak administrators as it also requires additional setup and ongoing maintenance.

For most deployments, the embedded IdP is the simpler choice — it's built into NetBird, fully integrated, and requires minimal configuration to get started. For this implementation, go back up to the Connector Setup (Recommended) section above.

If you prefer not to self-host an Identity and Access Management solution, you could use a managed alternative like Auth0.

Expected Result

After completing this guide, you can log in to your self-hosted NetBird Dashboard and add machines to your network using the Interactive SSO Login feature over Keycloak.

Keycloak auth flow

Prerequisites

  • Keycloak instance running with SSL
  • Docker and Docker Compose for NetBird

Step 1: Check Your Keycloak Instance

Ensure your Keycloak instance is available at https://YOUR-KEYCLOAK-HOST-AND-PORT with SSL enabled.

Step 2: Create a Realm

  1. Open the Keycloak Admin Console
  2. Hover over the dropdown in the top-left corner where it says Master
  3. Click Create Realm
  4. Fill in:
    • Realm name: netbird
  5. Click Create

Create realm

Step 3: Create a User

  1. Make sure the selected realm is netbird
  2. Click Users (left-hand menu)
  3. Click Create new user
  4. Fill in:
    • Username: netbird
  5. Click Create

Create user

  1. Click Credentials tab
  2. Click Set password
  3. Fill in the password and set Temporary to Off
  4. Click Save

Set password

Step 4: Create NetBird Client

  1. Click Clients → Create client
  2. Fill in:
    • Client Type: OpenID Connect
    • Client ID: netbird-client
  3. Click Next

Create client

  1. Enable the authentication options as shown:

Enable auth

  1. Click Save

Step 5: Configure Client Access Settings

  1. Go to Clients → netbird-client
  2. In Access Settings, fill in:
    • Root URL: https://YOUR_DOMAIN/
    • Valid redirect URIs: https://YOUR_DOMAIN/* and http://localhost:53000
    • Valid post logout redirect URIs: https://YOUR_DOMAIN/*
    • Web origins: +
  3. Click Save

Access settings

Step 6: Create Client Scope

  1. Click Client scopes (left-hand menu)
  2. Click Create client scope
  3. Fill in:
    • Name: api
    • Type: Default
    • Protocol: OpenID Connect
  4. Click Save

Create client scope

  1. Switch to the Mappers tab
  2. Click Configure a new mapper
  3. Choose Audience mapping

Configure audience mapper

  1. Fill in:
    • Name: Audience for NetBird Management API
    • Included Client Audience: netbird-client
    • Add to access token: On
  2. Click Save

Audience mapper config

Step 7: Add Client Scope to NetBird Client

  1. Go to Clients → netbird-client
  2. Switch to Client scopes tab
  3. Click Add client scope
  4. Choose api
  5. Click Add choosing Default

Add client scope

Step 8: Create NetBird-Backend Client

  1. Click Clients → Create client
  2. Fill in:
    • Client Type: OpenID Connect
    • Client ID: netbird-backend
  3. Click Next

Create backend client

  1. Enable authentication as shown:

Backend client auth

  1. Click Save
  2. Go to Credentials tab
  3. Copy the Client secret

Backend client credentials

Step 9: Add View-Users Role

  1. Go to Clients → netbird-backend
  2. Switch to Service accounts roles tab
  3. Click Assign roles
  4. Select Filter by clients and search for view-users

Service account role

  1. Check the role checkbox and click Assign

Add role

Optional: To enable automatic user deletion from Keycloak when deleted from NetBird, add the --user-delete-from-idp flag to the management startup command and assign the manage-users role instead.

Step 10: Configure NetBird

Your authority OIDC configuration will be available at:

https://<YOUR_KEYCLOAK_HOST_AND_PORT>/realms/netbird/.well-known/openid-configuration

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_USE_AUTH0=false
NETBIRD_AUTH_CLIENT_ID="netbird-client"
NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access api"
NETBIRD_AUTH_AUDIENCE="netbird-client"

NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID="netbird-client"
NETBIRD_AUTH_DEVICE_AUTH_AUDIENCE="netbird-client"

NETBIRD_MGMT_IDP="keycloak"
NETBIRD_IDP_MGMT_CLIENT_ID="netbird-backend"
NETBIRD_IDP_MGMT_CLIENT_SECRET="<NETBIRD_BACKEND_CLIENT_SECRET>"
NETBIRD_IDP_MGMT_EXTRA_ADMIN_ENDPOINT="https://<YOUR_KEYCLOAK_HOST_AND_PORT>/admin/realms/netbird"

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

Step 11: Continue with NetBird Setup

You've configured all required resources in Keycloak. Continue with the NetBird Self-hosting Guide.

Troubleshooting

"Invalid redirect URI" error

  • Ensure the redirect URI matches exactly what's configured
  • For connector: Use the exact URL from the NetBird success modal
  • For standalone: Include both https://YOUR_DOMAIN/* and http://localhost:53000

"Invalid token" errors

  • Verify the issuer URL includes /realms/your-realm
  • Ensure the client ID matches in both Keycloak and NetBird
  • Check clock synchronization between servers

Users not appearing in NetBird

  • For connector: Users appear after their first successful login
  • For standalone: Verify the backend client has view-users role