Update /auth context path requirements for Keycloak

[aneta-petrova]

What changes are you introducing?

We need to update the procedures for configuring Keycloak as an authentication source for Foreman to reflect changes in keycloak-httpd-client-install version 1.3.

This PR reshuffles existing prerequisites for the setup (to better enable adding the new information) and then on top of that explains which steps users need to take depending on whether 1.3 or 1.2 is installed on their Foreman server.

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

Existing procedures for configuring Quarkus-based Keycloak as an authentication source currently contain a workaround because they are based on the fact that keycloak-httpd-client-install requires the Keycloak server to be initialized with --http-relative-path=/auth. That is no longer the case because with version 1.3, keycloak-httpd-client-install has been updated. Notable commits:

• latchset/keycloak-httpd-client-install@67a05be removes /auth from URLs
• latchset/keycloak-httpd-client-install@ef7df4e autodetects whether /auth is needed

Therefore, the support matrix that we are dealing with now involves two versions of Keycloak (one based on the Quarkus application server, the other based on the deprecated Wildfly server) and two versions of the keycloak-httpd-client-install utility (1.2 and 1.3).

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

Thanks to @ekohl for investigating the situation and recording his findings in https://issues.redhat.com/browse/SAT-29434.

Checklists

• I am okay with my commits getting squashed when you merge this PR.
• I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

• Foreman 3.13/Katello 4.15
• Foreman 3.12/Katello 4.14 (Satellite 6.16)
• Foreman 3.11/Katello 4.13 (orcharhino 6.11 on EL8 only; orcharhino 7.0 on EL8+EL9)
• Foreman 3.10/Katello 4.12
• Foreman 3.9/Katello 4.11 (Satellite 6.15; orcharhino 6.8/6.9/6.10)
• Foreman 3.8/Katello 4.10
• Foreman 3.7/Katello 4.9 (Satellite 6.14)
• We do not accept PRs for Foreman older than 3.7.

[github-actions]

The PR preview for 583f5c5 is available at theforeman-foreman-documentation-preview-pr-3550.surge.sh

The following output files are affected by this PR:

• Configuring_User_Authentication/index-foreman-deb.html
• Configuring_User_Authentication/index-foreman-el.html
• Configuring_User_Authentication/index-katello.html
• Configuring_User_Authentication/index-orcharhino.html
• Configuring_User_Authentication/index-satellite.html

show diff

show diff as HTML

[aneta-petrova]

Hi @lhellebr, this PR takes the Keycloak setup notes recorded in https://issues.redhat.com/browse/SAT-29434 and applies them to the Quarkus-based Keycloak procedure, to differentiate between how keycloak-httpd-client-install behaves with versions 1.2 and 1.3. Can you please test the new steps?

Hi @ekohl, can you please review as well? Note that based on your notes in https://issues.redhat.com/browse/SAT-29434, it looks like for Wildfly-based Keycloak, existing steps work with either 1.2 or 1.3 version of keycloak-httpd-client-install so I only added the version-dependent steps to the Quarkus-based setup.