The current documentation provides information on user provisioning and catalog ingestion, but it does not clearly explain the user experience implications when Keycloak is federated to OpenShift—especially during the first-time login flow.

In environments where authentication is delegated from Keycloak to OpenShift, users are provisioned into Keycloak only on their first login. However, because RHDH requires users to exist in the catalog, the background synchronization may not have completed at the time of login. This results in a poor user experience where users receive an initial error message stating that they are not part of the catalog, which resolves only after the sync finishes.

Documentation gaps to address:

• Provide clearer guidance on how the user provisioning flow works when using OpenShift identity through Keycloak federation.
• Highlight the requirement for RHDH to ingest users and groups into the catalog before granting access.
• Add a best-practice note advising RHDH administrators to validate user and group ingestion before making RHDH available in production.
• Explain the limitations and considerations for large enterprise environments where pre-provisioning all users may not be feasible.
• Improve visibility of this information through a minor reorganization of the relevant conceptual and configuration sections.

Goal:
Reduce first-login errors and improve admin understanding of user provisioning workflows in federated authentication setups.