openZro

Keycloak SSO with openZro Self-Hosted (Advanced)

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.

Standalone Setup (Advanced)

This guide wires Keycloak as openZro's only identity provider — Dex is disabled and the management daemon talks directly to Keycloak for both token validation and user lifecycle. Choose this path only if all three apply:

  1. Keycloak is the source of truth for user lifecycle. You want openZro to call Keycloak's admin API to list, invite, and delete users — so deleting a user in openZro removes them from Keycloak too. The recommended setup (Management Setup) only consumes tokens; it cannot write back.
  2. You need just one IdP, and it's Keycloak. This path doesn't support multiple upstreams — there's no Dex to aggregate them.
  3. You're willing to give up the bootstrap admin fallback. No embedded local user store. If Keycloak is down or misconfigured, nobody can log into the dashboard.

For everyone else — multi-IdP shops, anyone wanting a static admin fallback, or operators who only need authentication (not user lifecycle writeback) — use the Management Setup (Recommended) in the main Keycloak documentation instead.

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

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: openzro
  5. Click Create

Create realm

Step 3: Create a User

  1. Make sure the selected realm is openzro
  2. Click Users (left-hand menu)
  3. Click Create new user
  4. Fill in:
    • Username: openzro
  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 openZro Client

  1. Click Clients → Create client
  2. Fill in:
    • Client Type: OpenID Connect
    • Client ID: openzro-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 → openzro-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 openZro Management API
    • Included Client Audience: openzro-client
    • Add to access token: On
  2. Click Save

Audience mapper config

Step 7: Add Client Scope to openZro Client

  1. Go to Clients → openzro-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 openZro-Backend Client

  1. Click Clients → Create client
  2. Fill in:
    • Client Type: OpenID Connect
    • Client ID: openzro-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 → openzro-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 openZro, add the --user-delete-from-idp flag to the management startup command and assign the manage-users role instead.

Step 10: Configure openZro

Your authority OIDC configuration will be available at:

https://<YOUR_KEYCLOAK_HOST_AND_PORT>/realms/openzro/.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:

OPENZRO_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://<YOUR_KEYCLOAK_HOST_AND_PORT>/realms/openzro/.well-known/openid-configuration"
OPENZRO_USE_AUTH0=false
OPENZRO_AUTH_CLIENT_ID="openzro-client"
OPENZRO_AUTH_SUPPORTED_SCOPES="openid profile email offline_access api"
OPENZRO_AUTH_AUDIENCE="openzro-client"

OPENZRO_AUTH_DEVICE_AUTH_CLIENT_ID="openzro-client"
OPENZRO_AUTH_DEVICE_AUTH_AUDIENCE="openzro-client"

OPENZRO_MGMT_IDP="keycloak"
OPENZRO_IDP_MGMT_CLIENT_ID="openzro-backend"
OPENZRO_IDP_MGMT_CLIENT_SECRET="<OPENZRO_BACKEND_CLIENT_SECRET>"
OPENZRO_IDP_MGMT_EXTRA_ADMIN_ENDPOINT="https://<YOUR_KEYCLOAK_HOST_AND_PORT>/admin/realms/openzro"

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

Step 11: Continue with openZro Setup

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

Troubleshooting

"Invalid token" errors

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

Users not appearing in openZro

  • Verify the backend client has view-users role