From cbdfceda564115b768b0bcb3e7bf914ab9dc967d Mon Sep 17 00:00:00 2001 From: Heena Manwani Date: Wed, 4 Dec 2024 19:08:22 +0530 Subject: [PATCH 1/3] RHBK v24 support for RHDH 1.4 --- artifacts/attributes.adoc | 2 ++ .../assembly-authenticating-with-rhbk.adoc | 13 +++++++++ .../assembly-authenticating-with-rhsso.adoc | 13 --------- .../assembly-enabling-authentication.adoc | 2 +- ...rs-from-rhbk-to-the-software-catalog.adoc} | 14 +++++----- ...oc-enabling-authentication-with-rhbk.adoc} | 28 +++++++++---------- ...rs-from-rhbk-to-the-software-catalog.adoc} | 16 +++++------ 7 files changed, 45 insertions(+), 43 deletions(-) create mode 100644 assemblies/assembly-authenticating-with-rhbk.adoc delete mode 100644 assemblies/assembly-authenticating-with-rhsso.adoc rename modules/authentication/{proc-creating-a-custom-transformer-to-provision-users-from-rhsso-to-the-software-catalog.adoc => proc-creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog.adoc} (81%) rename modules/authentication/{proc-enabling-authentication-with-rhsso.adoc => proc-enabling-authentication-with-rhbk.adoc} (76%) rename modules/authentication/{proc-provisioning-users-from-rhsso-to-the-software-catalog.adoc => proc-provisioning-users-from-rhbk-to-the-software-catalog.adoc} (79%) diff --git a/artifacts/attributes.adoc b/artifacts/attributes.adoc index d711562489..f0a5abef18 100644 --- a/artifacts/attributes.adoc +++ b/artifacts/attributes.adoc @@ -35,6 +35,8 @@ :openshift-cli: pass:quotes[OpenShift CLI (`oc`)] :rhsso-brand-name: Red Hat Single-Sign On :rhsso: RHSSO +:rhbk-brand-name: Red Hat Build of Keycloak +:rhbk: RHBK // Partner Platforms :aws-brand-name: Amazon Web Services diff --git a/assemblies/assembly-authenticating-with-rhbk.adoc b/assemblies/assembly-authenticating-with-rhbk.adoc new file mode 100644 index 0000000000..6b124ba27d --- /dev/null +++ b/assemblies/assembly-authenticating-with-rhbk.adoc @@ -0,0 +1,13 @@ +[id="assembly-authenticating-with-rhbk"] += Authenticating with {rhbk-brand-name} ({rhbk}) + +To authenticate users with {rhbk-brand-name} ({rhbk}): + +. xref:enabling-authentication-with-rhbk[Enable the OpenID Connect (OIDC) authentication provider in RHDH]. +. xref:provisioning-users-from-rhbk-to-the-software-catalog[Provision users from {rhbk-brand-name} ({rhbk}) to the software catalog]. + +include::modules/authentication/proc-enabling-authentication-with-rhbk.adoc[leveloffset=+1] + +include::modules/authentication/proc-provisioning-users-from-rhbk-to-the-software-catalog.adoc[leveloffset=+1] + +include::modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog.adoc[leveloffset=+1] diff --git a/assemblies/assembly-authenticating-with-rhsso.adoc b/assemblies/assembly-authenticating-with-rhsso.adoc deleted file mode 100644 index d3d5b1c95c..0000000000 --- a/assemblies/assembly-authenticating-with-rhsso.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[id="assembly-authenticating-with-rhsso"] -= Authenticating with Red Hat Single Sign-On (RHSSO) - -To authenticate users with Red Hat Single Sign-On (RHSSO): - -. xref:enabling-authentication-with-rhsso[Enable the OpenID Connect (OIDC) authentication provider in RHDH]. -. xref:provisioning-users-from-rhsso-to-the-software-catalog[Provision users from Red Hat Single-Sign On (RHSSO) to the software catalog]. - -include::modules/authentication/proc-enabling-authentication-with-rhsso.adoc[leveloffset=+1] - -include::modules/authentication/proc-provisioning-users-from-rhsso-to-the-software-catalog.adoc[leveloffset=+1] - -include::modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhsso-to-the-software-catalog.adoc[leveloffset=+1] diff --git a/assemblies/assembly-enabling-authentication.adoc b/assemblies/assembly-enabling-authentication.adoc index 7d5308b51d..d9100a0bde 100644 --- a/assemblies/assembly-enabling-authentication.adoc +++ b/assemblies/assembly-enabling-authentication.adoc @@ -53,7 +53,7 @@ Therefore, deleting users and groups by using {product-short} Web UI or REST API include::assembly-authenticating-with-the-guest-user.adoc[leveloffset=+1] -include::assembly-authenticating-with-rhsso.adoc[leveloffset=+1] +include::assembly-authenticating-with-rhbk.adoc[leveloffset=+1] include::assembly-authenticating-with-github.adoc[leveloffset=+1] diff --git a/modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhsso-to-the-software-catalog.adoc b/modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog.adoc similarity index 81% rename from modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhsso-to-the-software-catalog.adoc rename to modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog.adoc index 802be18d07..272b7d8a91 100644 --- a/modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhsso-to-the-software-catalog.adoc +++ b/modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog.adoc @@ -1,10 +1,10 @@ -[id="creating-a-custom-transformer-to-provision-users-from-rhsso-to-the-software-catalog"] -= Creating a custom transformer to provision users from {rhsso-brand-name} ({rhsso}) to the software catalog +[id="creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog"] += Creating a custom transformer to provision users from {rhbk-brand-name} ({rhbk}) to the software catalog -To customize how {rhsso} users and groups are mapped to {product} entities, you can create a backend module that uses the `keycloakTransformerExtensionPoint` to provide custom user and group transformers for the Keycloak backend. +To customize how {rhbk} users and groups are mapped to {product} entities, you can create a backend module that uses the `keycloakTransformerExtensionPoint` to provide custom user and group transformers for the Keycloak backend. .Prerequisites -* You have xref:provisioning-users-from-rhsso-to-the-software-catalog[enabled provisioning users from {rhsso-brand-name} ({rhsso}) to the software catalog]. +* You have xref:provisioning-users-from-rhbk-to-the-software-catalog[enabled provisioning users from {rhbk-brand-name} ({rhbk}) to the software catalog]. .Procedure . Create a new backend module with the `yarn new` command. @@ -85,8 +85,8 @@ Check the console logs to verify that the synchronization is completed. * After the first import is complete, navigate to the *Catalog* page and select **User** to view the list of users. -* When you select a user, you see the information imported from {rhsso}. +* When you select a user, you see the information imported from {rhbk}. -* You can select a group, view the list, and access or review the information imported from {rhsso}. +* You can select a group, view the list, and access or review the information imported from {rhbk}. -* You can log in with an {rhsso} account. +* You can log in with an {rhbk} account. diff --git a/modules/authentication/proc-enabling-authentication-with-rhsso.adoc b/modules/authentication/proc-enabling-authentication-with-rhbk.adoc similarity index 76% rename from modules/authentication/proc-enabling-authentication-with-rhsso.adoc rename to modules/authentication/proc-enabling-authentication-with-rhbk.adoc index 4f8d17d46d..ac24f1a970 100644 --- a/modules/authentication/proc-enabling-authentication-with-rhsso.adoc +++ b/modules/authentication/proc-enabling-authentication-with-rhbk.adoc @@ -1,21 +1,21 @@ -[id="enabling-authentication-with-rhsso"] -= Enabling authentication with {rhsso-brand-name} ({rhsso}) +[id="enabling-authentication-with-rhbk"] += Enabling authentication with {rhbk-brand-name} ({rhbk}) -To authenticate users with Red Hat Single Sign-On ({rhsso}), enable the OpenID Connect (OIDC) authentication provider in {product}. +To authenticate users with {rhbk-brand-name} ({rhbk}), enable the OpenID Connect (OIDC) authentication provider in {product}. .Prerequisites * You link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html/administration_guide_for_red_hat_developer_hub/assembly-add-custom-app-file-openshift_admin-rhdh[added a custom {product-short} application configuration], and have sufficient permissions to modify it. -* You have sufficient permissions in {rhsso} to create and manage a realm. +* You have sufficient permissions in {rhbk} to create and manage a realm. .Procedure -. To allow {product-short} to authenticate with {rhsso}, complete the steps in {rhsso}, to link:https://docs.redhat.com/en/documentation/red_hat_single_sign-on/7.6/html-single/getting_started_guide/index#realms-apps_[create a realm and a user] and link:https://docs.redhat.com/en/documentation/red_hat_single_sign-on/7.6/html-single/getting_started_guide/index#registering-app_[register the {product-short} application]: +. To allow {product-short} to authenticate with {rhbk}, complete the steps in {rhbk}, to link:https://docs.redhat.com/en/documentation/red_hat_single_sign-on/7.6/html-single/getting_started_guide/index#realms-apps_[create a realm and a user] and link:https://docs.redhat.com/en/documentation/red_hat_single_sign-on/7.6/html-single/getting_started_guide/index#registering-app_[register the {product-short} application]: .. Use an existing realm, or link:https://docs.redhat.com/en/documentation/red_hat_single_sign-on/7.6/html-single/getting_started_guide/index#create-realm_[create a realm], with a distinctive **Name** such as ____. Save the value for the next step: -* **{rhsso} realm base URL**, such as: ____/auth/realms/____. +* **{rhbk} realm base URL**, such as: ____/realms/____. -.. To register your {product-short} in {rhsso}, in the created realm, link:https://docs.redhat.com/en/documentation/red_hat_single_sign-on/7.6/html-single/getting_started_guide/index#registering-app_[create a Client ID], with: +.. To register your {product-short} in {rhbk}, in the created realm, link:https://docs.redhat.com/en/documentation/red_hat_single_sign-on/7.6/html-single/getting_started_guide/index#registering-app_[create a Client ID], with: ... **Client ID**: A distinctive client ID, such as __<{product-very-short}>__. ... **Valid redirect URIs**: Set to the OIDC handler URL: `https://____/api/auth/oidc/handler/frame`. ... Navigate to the **Credentials** tab and copy the **Client secret**. @@ -23,23 +23,23 @@ Save the value for the next step: * **Client ID** * **Client Secret** -.. Configure your {rhsso} realm for performance and security: +.. Configure your {rhbk} realm for performance and security: ... Navigate to the **Configure** > **Realm Settings**. ... Set the **Access Token Lifespan** to a value greater than five minutes (preferably 10 or 15 minutes) to prevent performance issues from frequent refresh token requests for every API call. ... Enable the **Revoke Refresh Token** option to improve security by enabling the refresh token rotation strategy. .. To prepare for the verification steps, in the same realm, get the credential information for an existing user or link:https://docs.redhat.com/en/documentation/red_hat_single_sign-on/7.6/html-single/getting_started_guide/index#create-user_[create a user]. Save the user credential information for the verification steps. -. To add your {rhsso} credentials to your {product-short} secrets, edit your {product-short} secrets, such as `secrets-rhdh`, and add the following key/value pairs: +. To add your {rhbk} credentials to your {product-short} secrets, edit your {product-short} secrets, such as `secrets-rhdh`, and add the following key/value pairs: + `AUTH_OIDC_CLIENT_ID`:: Enter the saved **Client ID**. `AUTH_OIDC_CLIENT_SECRET`:: Enter the saved **Client Secret**. -`AUTH_OIDC_METADATA_URL`:: Enter the saved **{rhsso} realm base URL**. +`AUTH_OIDC_METADATA_URL`:: Enter the saved **{rhbk} realm base URL**. -. To set up the {rhsso} authentication provider in your {product-short} custom configuration, edit your custom {product-short} ConfigMap such as `app-config-rhdh`, and add the following lines to the `app-config-rhdh.yaml` content: +. To set up the {rhbk} authentication provider in your {product-short} custom configuration, edit your custom {product-short} ConfigMap such as `app-config-rhdh`, and add the following lines to the `app-config-rhdh.yaml` content: + -- -.`app-config-rhdh.yaml` fragment with mandatory fields to enable authentication with {rhsso} +.`app-config-rhdh.yaml` fragment with mandatory fields to enable authentication with {rhbk} [source,yaml] ---- auth: @@ -90,7 +90,7 @@ dangerouslyAllowSignInWithoutUserInCatalog: true `callbackUrl`:: -- -{rhsso} callback URL. +{rhbk} callback URL. .`app-config-rhdh.yaml` fragment with optional `callbackURL` field [source,yaml] @@ -135,7 +135,7 @@ auth: `scope`:: -- -{rhsso} scope. +{rhbk} scope. .`app-config-rhdh.yaml` fragment with optional `scope` field [source,yaml] diff --git a/modules/authentication/proc-provisioning-users-from-rhsso-to-the-software-catalog.adoc b/modules/authentication/proc-provisioning-users-from-rhbk-to-the-software-catalog.adoc similarity index 79% rename from modules/authentication/proc-provisioning-users-from-rhsso-to-the-software-catalog.adoc rename to modules/authentication/proc-provisioning-users-from-rhbk-to-the-software-catalog.adoc index ca4c10ad08..0dd9cab6c3 100644 --- a/modules/authentication/proc-provisioning-users-from-rhsso-to-the-software-catalog.adoc +++ b/modules/authentication/proc-provisioning-users-from-rhbk-to-the-software-catalog.adoc @@ -1,12 +1,12 @@ -[id="provisioning-users-from-rhsso-to-the-software-catalog"] -= Provisioning users from {rhsso-brand-name} ({rhsso}) to the software catalog +[id="provisioning-users-from-rhbk-to-the-software-catalog"] += Provisioning users from {rhbk-brand-name} ({rhbk}) to the software catalog .Prerequisites -* You xref:enabling-authentication-with-rhsso[enabled authentication with {rhsso}]. +* You xref:enabling-authentication-with-rhbk[enabled authentication with {rhbk}]. .Procedure -* To enable {rhsso} member discovery, edit your custom {product-short} ConfigMap, such as `app-config-rhdh`, and add the following lines to the `app-config-rhdh.yaml` content: +* To enable {rhbk} member discovery, edit your custom {product-short} ConfigMap, such as `app-config-rhdh`, and add the following lines to the `app-config-rhdh.yaml` content: + -- [id=keycloakOrgProviderId] @@ -27,13 +27,13 @@ catalog: Allow authentication only for users present in the {product-short} software catalog. `baseUrl`:: -Your {rhsso} server URL, defined when xref:enabling-authentication-with-rhsso[enabling authentication with {rhsso}]. +Your {rhbk} server URL, defined when xref:enabling-authentication-with-rhbk[enabling authentication with {rhbk}]. `clientId`:: -Your {product-short} application client ID in {rhsso}, defined when xref:enabling-authentication-with-rhsso[enabling authentication with {rhsso}]. +Your {product-short} application client ID in {rhbk}, defined when xref:enabling-authentication-with-rhbk[enabling authentication with {rhbk}]. `clientSecret`:: -Your {product-short} application client secret in {rhsso}, defined when xref:enabling-authentication-with-rhsso[enabling authentication with {rhsso}]. +Your {product-short} application client secret in {rhbk}, defined when xref:enabling-authentication-with-rhbk[enabling authentication with {rhbk}]. Optional: Consider adding the following optional fields: @@ -150,4 +150,4 @@ catalog: {"class":"KeycloakOrgEntityProvider","level":"info","message":"Committed 3 Keycloak users and 2 Keycloak groups in 0.0 seconds.","plugin":"catalog","service":"backstage","taskId":"KeycloakOrgEntityProvider:default:refresh","taskInstanceId":"bf0467ff-8ac4-4702-911c-380270e44dea","timestamp":"2024-09-25 13:58:04"} ---- -. Log in with an {rhsso} account. +. Log in with an {rhbk} account. From 32cad03d0412db2a5c9e0e9e2d3a77166440bb60 Mon Sep 17 00:00:00 2001 From: Heena Manwani Date: Thu, 5 Dec 2024 12:32:37 +0530 Subject: [PATCH 2/3] Added note --- assemblies/assembly-authenticating-with-rhbk.adoc | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/assemblies/assembly-authenticating-with-rhbk.adoc b/assemblies/assembly-authenticating-with-rhbk.adoc index 6b124ba27d..fd2439dbda 100644 --- a/assemblies/assembly-authenticating-with-rhbk.adoc +++ b/assemblies/assembly-authenticating-with-rhbk.adoc @@ -1,6 +1,11 @@ [id="assembly-authenticating-with-rhbk"] = Authenticating with {rhbk-brand-name} ({rhbk}) +[NOTE] +==== +{rhsso} 7.6 is deprecated as an authentication provider. You can continue using {rhsso} until the end of its maintenance support. For more information, see link:https://access.redhat.com/support/policy/updates/jboss_notes#p_sso[{rhsso} lifecycle dates]. As an alternative, consider migrating to {rhbk-brand-name} ({rhbk}). +==== + To authenticate users with {rhbk-brand-name} ({rhbk}): . xref:enabling-authentication-with-rhbk[Enable the OpenID Connect (OIDC) authentication provider in RHDH]. From ea105a397d837752cc6c1715adfe4e35a5225df3 Mon Sep 17 00:00:00 2001 From: Heena Manwani Date: Mon, 9 Dec 2024 12:09:58 +0530 Subject: [PATCH 3/3] review suggestions incorporated --- .../proc-enabling-authentication-with-rhbk.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/authentication/proc-enabling-authentication-with-rhbk.adoc b/modules/authentication/proc-enabling-authentication-with-rhbk.adoc index ac24f1a970..6c104fe1ae 100644 --- a/modules/authentication/proc-enabling-authentication-with-rhbk.adoc +++ b/modules/authentication/proc-enabling-authentication-with-rhbk.adoc @@ -9,13 +9,13 @@ To authenticate users with {rhbk-brand-name} ({rhbk}), enable the OpenID Connect * You have sufficient permissions in {rhbk} to create and manage a realm. .Procedure -. To allow {product-short} to authenticate with {rhbk}, complete the steps in {rhbk}, to link:https://docs.redhat.com/en/documentation/red_hat_single_sign-on/7.6/html-single/getting_started_guide/index#realms-apps_[create a realm and a user] and link:https://docs.redhat.com/en/documentation/red_hat_single_sign-on/7.6/html-single/getting_started_guide/index#registering-app_[register the {product-short} application]: +. To allow {product-short} to authenticate with {rhbk}, complete the steps in {rhbk}, to link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/24.0/html/getting_started_guide/getting-started-zip-#getting-started-zip-create-a-realm[create a realm and a user] and link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/24.0/html/getting_started_guide/getting-started-zip-#getting-started-zip-secure-the-first-application[secure the first application]: -.. Use an existing realm, or link:https://docs.redhat.com/en/documentation/red_hat_single_sign-on/7.6/html-single/getting_started_guide/index#create-realm_[create a realm], with a distinctive **Name** such as ____. +.. Use an existing realm, or link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/24.0/html/getting_started_guide/getting-started-zip-#getting-started-zip-create-a-realm[create a realm], with a distinctive **Name** such as ____. Save the value for the next step: * **{rhbk} realm base URL**, such as: ____/realms/____. -.. To register your {product-short} in {rhbk}, in the created realm, link:https://docs.redhat.com/en/documentation/red_hat_single_sign-on/7.6/html-single/getting_started_guide/index#registering-app_[create a Client ID], with: +.. To register your {product-short} in {rhbk}, in the created realm, link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/24.0/html-single/getting_started_guide/index#getting-started-zip-secure-the-first-application[secure the first application], with: ... **Client ID**: A distinctive client ID, such as __<{product-very-short}>__. ... **Valid redirect URIs**: Set to the OIDC handler URL: `https://____/api/auth/oidc/handler/frame`. ... Navigate to the **Credentials** tab and copy the **Client secret**. @@ -28,7 +28,7 @@ Save the value for the next step: ... Set the **Access Token Lifespan** to a value greater than five minutes (preferably 10 or 15 minutes) to prevent performance issues from frequent refresh token requests for every API call. ... Enable the **Revoke Refresh Token** option to improve security by enabling the refresh token rotation strategy. -.. To prepare for the verification steps, in the same realm, get the credential information for an existing user or link:https://docs.redhat.com/en/documentation/red_hat_single_sign-on/7.6/html-single/getting_started_guide/index#create-user_[create a user]. Save the user credential information for the verification steps. +.. To prepare for the verification steps, in the same realm, get the credential information for an existing user or link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/24.0/html-single/getting_started_guide/index#getting-started-zip-create-a-user[create a user]. Save the user credential information for the verification steps. . To add your {rhbk} credentials to your {product-short} secrets, edit your {product-short} secrets, such as `secrets-rhdh`, and add the following key/value pairs: +