Keycloak with openZro Self-Hosted

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.

Management Setup (Recommended)

Add Keycloak as an external IdP directly in the openZro Management Dashboard. This is the simplest approach and recommended for most deployments.

Prerequisites

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

Step 1: Create Realm in Keycloak

1. Open the Keycloak Admin Console
2. Hover over the realm dropdown in the top-left corner (where it shows Master or your current realm)
3. Click Create Realm

4. Fill in:
   • Realm name: openzro

5. Click Create
6. Verify that openzro is now selected in the realm dropdown

Step 2: Create User in Keycloak

1. Make sure the openzro realm is selected
2. Click Users (left-hand menu)
3. Click Create new user

4. Fill in:
   • Username: openzro (or your preferred username)
   • Email: Your email address
5. Click Create
6. Click the Credentials tab
7. Click Set password
8. Fill in the password and set Temporary to Off
9. Click Save

Step 3: Start Creating Client in Keycloak

1. Click Clients → Create client

2. Fill in the form:
   • Client type: OpenID Connect
   • Client ID: openzro

3. Click Next
4. On Capability config:
   • Enable Client authentication

5. Click Next
6. On Login settings page, don't click Save yet — you'll add the redirect URI in Step 4

Step 4: Get Redirect URL from openZro

1. Open a new tab or window and log in to your openZro Dashboard
2. Navigate to Settings → Identity Providers
3. Click Add Identity Provider
4. Select Keycloak (or choose Generic OIDC if Keycloak is not listed)
5. Fill in the fields (you can leave Client Secret empty for now):

6. openZro will display a Redirect URL — copy this URL (but don't click Add Provider yet)

Step 5: Complete Client Configuration in Keycloak

1. Return to the Keycloak Admin Console tab
2. On the Login settings page:
   • Under Valid redirect URIs, paste the redirect URL you copied from openZro
3. Click Save
4. Go to the Credentials tab and copy the Client secret — you'll need this for Step 6

Step 6: Complete openZro Setup

1. Return to the openZro tab
2. In the identity provider form, paste the Client secret you copied from Step 5
3. Click Add Provider

Step 7: Test the Connection

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

Configuring JWT 'groups' Claim

To sync Keycloak groups with openZro, you need to create a client scope with a group membership mapper.

Step 1: Create Groups Client Scope

1. In Keycloak Admin Console, ensure the openzro realm is selected
2. Go to Client scopes → Create client scope
3. Fill in:
   • Name: groups
   • Type: Default
   • Include in token scope: On
4. Click Save

Step 2: Add Group Membership Mapper

1. In the newly created groups client scope, go to the Mappers tab
2. Click Configure a new mapper
3. Select Group Membership
4. Configure the mapper:
   • Name: groups
   • Token Claim Name: groups
   • Full group path: Off (recommended for cleaner group names)
   • Add to ID token: On
   • Add to access token: On
   • Add to userinfo: On
   • Add to token introspection: Off
5. Click Save

Step 3: Add Client Scope to openZro Client

1. Go to Clients → openzro (your client)
2. Go to the Client scopes tab
3. Click Add client scope
4. Select groups and add it as Default

Step 4: Create Groups and Assign Users

1. Go to Groups → Create group
2. Create groups as needed (e.g., admins, developers)
3. Go to Users → select a user → Groups tab
4. Click Join Group and assign users to groups

Step 5: Enable JWT Group Sync in openZro

1. In openZro Dashboard, go to Settings → Groups
2. Enable JWT group sync
3. Set JWT claim to groups
4. Optionally configure JWT allow groups to restrict access

Step 6: Verify the dashboard requests the groups scope

JWT Group Sync only fires if the JWT actually carries groups. On Kubernetes deployments, the chart's dashboard.env.AUTH_SUPPORTED_SCOPES must include groups and dashboard.env.OPENZRO_TOKEN_SOURCE must be idToken — Dex puts groups in the id_token only, never in the access_token. The Helm Quickstart spells out the four moving parts.

For Docker Compose deploys, set in setup.env:

OPENZRO_AUTH_SUPPORTED_SCOPES="openid profile email offline_access groups"
OPENZRO_TOKEN_SOURCE="idToken"

After updating either, log out + log back in fresh. Browser session caches the old (group-less) token until you re-authenticate.

Troubleshooting: groups visible in Dex log but not in dashboard

Check the Dex pod log on a fresh login. A successful upstream sync looks like:

level=INFO msg="login successful" connector_id=keycloak ...
  groups="[admins developers ...]"

If groups=[] despite Keycloak emitting them in the id_token (verify via a direct password-grant curl against /realms/<realm>/protocol/openid-connect/token), the Dex OIDC connector likely has getUserInfo: true. With that enabled, Dex calls Keycloak's /userinfo endpoint after the token exchange and overwrites the claims — and the userinfo response does not carry groups by default. Set getUserInfo: false and insecureEnableGroups: true on the connector and restart the Dex pods.

If groups appears in the Dex log but not in Team → Groups, the likely missing piece is the dashboard requesting the groups scope (Step 6 above) — without it, Dex omits the claim from the id_token even though the upstream returned them.

Standalone Setup (Advanced)

The standalone setup 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 above only consumes tokens; it cannot write back.
2. You need just one IdP, and it's Keycloak. The standalone 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) — stick with the Management Setup (Recommended) above.

For detailed standalone instructions, see Keycloak SSO with openZro Self-Hosted (Advanced).

Troubleshooting

"Invalid redirect URI" error

• Ensure the redirect URI matches exactly what's configured
• Use the exact URL from the openZro success modal

"Invalid token" errors

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

Users not appearing in openZro

• Users appear after their first successful login

Related Resources

• Keycloak Documentation
• Embedded IdP Overview