Keycloak user management
:::warning Beta This feature is in beta and still incomplete. It is usable for evaluation on a Keycloak-backed white label, but expect gaps and change: the screen manages a subset of what Keycloak itself offers, there is no audit trail on the actions performed from it, and both the UI and the configuration may change in a future release without a deprecation cycle. Do not enable it for production tenants without agreeing the scope first. :::
Where an organization's users live in Keycloak rather than in Harmoney, the FSP management area can expose those Keycloak users instead of Harmoney's own partner list. Managers then invite and manage their colleagues from inside Harmoney, without a second admin console.
What it replaces​
The FINANCIAL_SP_MANAGEMENT module normally shows a Users tab listing Harmoney partner users.
Setting userManagement to KEYCLOAK replaces that tab with a Keycloak users tab. The two are
mutually exclusive — an FSP shows one or the other, never both.
Settings Configuration
Examples
Leaving the setting out keeps the built-in user management, so existing FSP definitions are unaffected.
The administrator's FSP detail page follows the same setting: it shows either the Users tab or the Keycloak users tab for an FSP, never both.
How it authenticates​
The screen talks to Keycloak directly, with its own session, entirely separate from the Harmoney session:
- Harmoney decides whether the user may open the tab, through the ACL derived from this module.
- Keycloak decides what the user may do there: the manager group in the token's
organizationclaim determines which organizations they can administer, and every request to the admin service carries the Keycloak bearer token only.
A user therefore needs both: access to FSP management in Harmoney, and membership of the manager group in Keycloak. Connecting or disconnecting from Keycloak on this screen never touches the Harmoney session, and a failure there is reported on the card instead of logging the user out.
What a manager can do​
- See the organization's users and its sub-groups with their members
- Add a user by email address — an existing Keycloak user is added back to the organization, a new one is created
- Change a user's sub-group membership
- Reset a user's password, optionally as a temporary one the user must change on next sign-in
- Update a user's email address
- Remove a user from the organization — the Keycloak account itself is kept
Actions that cannot apply to a row are not offered: a manager cannot change their own group membership or remove their own account.
Deployment prerequisite​
Beyond the module setting, the environment must point the front end at the Keycloak realm and the admin service. Without that configuration block the tab stays hidden regardless of the module setting, which is the safe default for environments where the admin service is not deployed.
| Key | Description |
|---|---|
keycloakUrl | Base URL of the Keycloak instance. |
realm | Realm holding the organizations and users. |
clientId | Public client used for the interactive login from this screen (PKCE). |
adminApiUrl | Host of the admin service backing the screen. Defaults to https when no scheme is given. |
managerGroup | Group that grants administration of an organization. Defaults to /managers. |
Because the tab is gated on this block being present, it is deployed per environment rather than configured per FSP — coordinate enabling it with the team that owns the environment. These settings can be set via environment variables.
Related​
- Keycloak SSO provider — signing in to Harmoney with Keycloak and mapping organizations and groups onto FSPs and roles. That is a separate concern from this screen: SSO covers logging in, this covers administering the users.
- Modules — the full list of FSP modules and their settings.