Skip to main content
Version: 19

Keycloak SSO provider

🎯 Functional documentation​

The Keycloak SSO provider extends the OAuth2 OpenID SSO provider, so all of its settings apply here too. It adds one thing: one Keycloak organization is one Harmoney FSP, so who works for which FSP is decided in Keycloak instead of in Harmoney.

How access is granted​

  • Create a user in the Keycloak realm.
  • Add the user to a Keycloak organization and add them in one or more groups within the organization.
  • When logging in in Harmoney:
    • The Keycloak organization is mapped to a Harmoney FSP by matching the organization alias to the field SSO_FSP_REFERENCE_SOURCE names — the FSP's external reference by default, or its identifier.
    • The Keycloak groups are translated to Harmoney roles via the SSO_ROLE_MAPPING settings. Note: it's possible to specify the fspExtRef in SSO_ROLE_MAPPING. If you specify an FSP there, it will take precedence over the organization alias. This allows to either do the organization -> FSP mapping using Keycloak or statically in the settings. That value is read from the same field as the alias.

⚙️ Configuration​

Implementation class​

  • eu.myharmoney.app.providers.sso.implementations.keycloak.KeycloakSSOProvider

What to configure​

  • One Keycloak organization per FSP, its alias exactly the FSP field SSO_FSP_REFERENCE_SOURCE names. It defaults to the external reference; alias on the identifier when the FSP naming is self-managed rather than the client's to change.
  • authorizeUri must carry the whole query string including organization:* — the provider substitutes only <client-id> and <redirect-uri>. Without that scope the organization claim arrives empty or not at all.
https://<keycloak-host>/realms/<realm>/protocol/openid-connect/auth?client_id=<client-id>&response_type=code&response_mode=query&scope=openid%20profile%20email%20organization%3A*&redirect_uri=<redirect-uri>
  • SSO_ROLE_MAPPING (required): maps SSO roles to Harmoney roles. When an fspExtRef is specified in this mapping, it has precedence over the FSP derived from the Keycloak organization alias. It is read from the same field as the alias, so both follow SSO_FSP_REFERENCE_SOURCE.
  • On the realm: Organizations enabled, the organization client scope on the client, the organization mapper on whichever token SSO_USER_INFO_CLAIMS_SOURCE names, and every environment's redirect URI registered.
  • On the white label: list the provider as a PROVIDER authentication method, or it stays inert — see whitelabel authentication settings.

:::warning jwtSettings is what verifies the token With SSO_USER_INFO_CLAIMS_SOURCE on ACCESS_TOKEN or ID_TOKEN, the claims come from a token jwtSettings verifies, so configure jwksUri, expectedJwtIssuer and expectedJwtAudience before setting state to ACTIVE. Never use skipJwtSignatureVerification or skipJwtDefaultAudienceVerification to get a realm working: they make the provider accept any unsigned, wrong-audience token as a valid identity. :::

Settings​

Exactly the same as the base SSO Provider configuration and the OAuth2 OpenID SSO provider configuration.

Settings Configuration

Examples