User object names in the OpenShift cluster

Problem

We need to define an identifier which we use to name users which are synchronized from Keycloak to the OpenShift cluster.

The identifier should have the following properties:

  • It should be stable for the lifetime of the user in Keycloak.

  • It must be suitable for use as an OpenShift resource name (namely for the OpenShift User resource)

  • It must be used to configure OpenShift Group membership when synchronizing groups from Keycloak.

In the implementation, this identifier is selected by providing an appropriate attribute name for the OpenID claim preferred_username in the OpenShift OpenID Connect identity provider configuration. Please note that regardless of the choice of identifier for preferred_username, the user’s identity in the OpenShift cluster is always tied to their Keycloak user’s ID property. This is because Openshift’s OpenID Connect identity provider uses the OpenID claim sub to establish the user’s identity, see the OpenShift documentation. The OpenID claim sub is mapped to the Keycloak user’s ID by default.

Proposals

  1. Use the Username property of Keycloak user objects

    With this approach, oc whoami shows users the Username they chose when registering their APPUiO Cloud user. However, Users can’t change their Username after registration, as the OpenShift User and Identity objects (which are created when the users first logs in) aren’t updated when users change their Username in Keycloak.

  2. Use the ID property of Keycloak user objects

    With this approach, users can freely change their Username in Keycloak. However, their Username doesn’t appear anywhere in the OpenShift cluster with this approach and the output of oc whoami is the Keycloak user’s ID.

  3. Use the Email property of Keycloak user objects

    With this approach, users can’t change their E-Mail address after signing up, for the same reasons as they can’t change their Username property when using that property (see first proposal).

Decision

Use the Username property of Keycloak user objects

Rationale

For all described proposals, Keycloak can be configured to require that the property must be unique per realm. Therefore, we don’t risk having OpenShift User objects which are associated with multiple Keycloak users with any of the described proposals.

We decide to use the Username property as the identifier used for the OpenShift User object. This choice provides the best trade-off in our eyes, as it allows users to change their E-Mail address at any time and it shows users a human-verifiable output when running oc whoami.