IdP Group membership Mapping


Normal users can login via Keycloak to any APPUiO Zone and deploy workloads. However, certain groups are destined to be cluster administrators and require the permissions to perform privileged operations.

With Keycloak being the only IdP frontend for any APPUiO Zone, group memberships need to be synchronized in a way that OpenShift is able to distinguish special organizations. Especially with brokered IdPs where the actual source of truth regarding group memberships of users is outside of APPUiO IdP this is a technical challenge around authorization that impacts the architecture.

The problem ultimately asks the questions:

  • How does APPUiO IdP know which organization is privileged if the organization is brokered through another IdP?

  • How does APPUiO IdP determine if a user, whose login is brokered though another IdP, belongs to such an organization?

Relevant requirements

Relevant decisions


  1. External group syncing via API

    An extra component connects to the brokered IdP via API, collects the groups and group memberships, adapts and then pushes to APPUiO IdP also via API. This method allows different implementations for various brokered IdPs, for example there could be an implementation for Keycloak-to-Keycloak, or GitHub-to-Keycloak.

    Such a component would regularly pull and push the group memberships (or event-driven if supported) and is provided by APPUiO Cloud developers.

  2. Group mapping via claims

    With OIDC protocol, custom fields in the user token payload called "Claims" allow additional information to be included. In this proposal, if the brokered IdP is also Keycloak, the group memberships can be easily added to those claims. The APPUiO IdP is then able to read and create or join the given groups on-the-fly.

    Unfortunately there is no built-in mechanism in Keycloak that allows to dynamically manage group memberships coming from brokered claims. There is a GitHub project that implements this approach as a Keycloak extension written in Java, but it seems to be unmaintained.


Group mapping via claims


A mapping via claims basically allows to delegate the desire and support of group memberships to the implementation of the brokered IdP. In other words, if the foreign IdP provides the group membership in the claims, then APPUiO IdP can sync the groups.

On all APPUiO Zones, once the groups have been synchronized to OpenShift, a static configuration allows a certain group to become cluster-admin via RBAC rules.

The mentioned GitHub project will be used as inspiration, but there will be an APPUiO repository that is generally used for extending Keycloak, which includes group mapping. A proof-of-concept has already been tested and was successful.