How to pass UCS group memberships as SAML attributes via Keycloak

Knowledge Base Community
, , ,
1

Problem

An external software system shall be integrated with UCS using Single Sign-On (SSO) via SAML and UCS’ built-in Keycloak Identity Provider.
Currently, there are five groups in UCS, e.g. “RUDEL roles”.

The requirement is that, during a SAML login, the group membership must be transferred to the Service Provider (SP) as an attribute – exactly as it is stored in UCS.

The question is:

Is it possible to configure UCS Keycloak so that group memberships from UCS are passed as SAML attributes to the external SP?
If yes, how?

Solution

In the UCS-integrated Keycloak, group memberships from the UCS LDAP directory can be synchronized and used within Keycloak. However, the default SAML mappers in UCS’ Keycloak provide only limited flexibility:

  • You can expose all group memberships of a user as SAML attributes.
  • You can filter by a group name or path and only forward those groups.
  • You cannot, with the stock UCS Keycloak, dynamically translate a group membership into an arbitrary custom attribute/value pair (e.g. “if user is member of RUDEL roles → send RUDELrolle=superuser”) without manual user attribute maintenance.

Practical options

  1. Send group names as-is

    • Use a SAML Group Mapper in the Keycloak IdP configuration.
    • Configure the Group attribute name and Friendly Name according to the SP requirements.
    • The Service Provider will then receive the UCS group memberships directly in the assertion.

  2. Restrict to selected groups

    • Configure the mapper to only forward specific groups (e.g. only RUDEL roles).
    • This works when the SP accepts the group name itself as the attribute value.

  3. Custom attribute/value mappings

    • If you need different claim names or custom attribute values (e.g. RUDELrolle=superuser instead of roles=RUDEL_superuser), this is not possible out of the box in the UCS-delivered Keycloak.
    • To achieve this, you would need one of the following:
      • A custom Keycloak extension (Java provider), or
      • A Script Mapper, which is not included in UCS’ Keycloak builds, or
      • An external claim translation layer, such as:
        • oauth2-proxy
        • Apache with mod_auth_mellon and attribute rewriting

Conclusion

  • :white_check_mark: UCS Keycloak can expose UCS group memberships as SAML attributes.
  • :white_check_mark: You can filter and forward only specific groups (such as RUDEL roles).
  • :x: UCS Keycloak (as shipped) cannot dynamically map a UCS group into a custom attribute/value pair without either manual user attributes or a custom extension.

If the Service Provider accepts UCS group names directly, the standard Group Mapper is sufficient.
If a translation into custom attributes is required, a custom extension or external translation layer must be implemented.

keywords: [ucs, keycloak, saml, sso, groups, attributes, mapping]