RHIDP-3878 Authenticating with RHSSO (redhat-developer#480)

* RHIDP-3878 Authenticating with RHSSO Signed-off-by: Fabrice Flore-Thébault <[email protected]> * Update modules/auth/proc-enabling-authentication-with-rhsso.adoc * Update modules/auth/proc-enabling-authentication-with-rhsso.adoc * Update modules/auth/proc-enabling-authentication-with-rhsso.adoc * Update modules/auth/proc-enabling-authentication-with-rhsso.adoc * Update modules/auth/proc-enabling-authentication-with-rhsso.adoc * Update modules/auth/proc-enabling-authentication-with-rhsso.adoc * Update modules/auth/proc-enabling-authentication-with-rhsso.adoc * Update modules/auth/proc-enabling-authentication-with-rhsso.adoc * Update modules/auth/proc-enabling-authentication-with-rhsso.adoc * Update modules/auth/proc-enabling-authentication-with-rhsso.adoc * Update modules/auth/proc-enabling-authentication-with-rhsso.adoc * Update modules/auth/proc-enabling-authentication-with-rhsso.adoc * Update modules/auth/proc-enabling-authentication-with-rhsso.adoc * Update modules/auth/proc-enabling-authentication-with-rhsso.adoc * Update modules/auth/proc-enabling-authentication-with-rhsso.adoc * Update modules/auth/proc-enabling-authentication-with-rhsso.adoc * Update modules/auth/proc-enabling-authentication-with-rhsso.adoc * Update modules/auth/proc-enabling-authentication-with-rhsso.adoc * Update modules/auth/proc-enabling-authentication-with-rhsso.adoc * Update modules/auth/proc-enabling-authentication-with-rhsso.adoc * Update modules/auth/proc-enabling-authentication-with-rhsso.adoc * Update modules/auth/proc-enabling-authentication-with-rhsso.adoc * Update modules/auth/proc-enabling-authentication-with-rhsso.adoc * Update modules/auth/proc-enabling-authentication-with-rhsso.adoc * Apply suggestions from code review * Update modules/auth/proc-enabling-authentication-with-rhsso.adoc * Apply suggestions from code review * Update modules/auth/proc-enabling-authentication-with-rhsso.adoc * Apply suggestions from code review * Update modules/auth/proc-enabling-authentication-with-rhsso.adoc Co-authored-by: Kim Tsao <[email protected]> * docs: added procedure Signed-off-by: Fabrice Flore-Thébault <[email protected]> * docs: added procedure Signed-off-by: Fabrice Flore-Thébault <[email protected]> * docs: added procedure Signed-off-by: Fabrice Flore-Thébault <[email protected]> * docs: added procedure Signed-off-by: Fabrice Flore-Thébault <[email protected]> * Update modules/authentication/proc-provisioning-users-from-rhsso-to-the-software-catalog.adoc * Update assemblies/assembly-authenticating-with-rhsso.adoc * Update assemblies/assembly-authenticating-with-rhsso.adoc * Update assemblies/assembly-authenticating-with-rhsso.adoc * Update modules/authentication/proc-provisioning-users-from-rhsso-to-the-software-catalog.adoc Co-authored-by: Kim Tsao <[email protected]> * Apply suggestions from code review Co-authored-by: Heena Manwani <[email protected]> --------- Signed-off-by: Fabrice Flore-Thébault <[email protected]> Co-authored-by: Kim Tsao <[email protected]> Co-authored-by: Heena Manwani <[email protected]>
themr0c · Oct 8, 2024 · 7fe92fa · 7fe92fa
1 parent a23c431
commit 7fe92fa
Show file tree

Hide file tree

Showing 8 changed files with 338 additions and 191 deletions.
diff --git a/assemblies/assembly-auth-provider-oidc.adoc b/assemblies/assembly-auth-provider-oidc.adoc
diff --git a/assemblies/assembly-authenticating-with-rhsso.adoc b/assemblies/assembly-authenticating-with-rhsso.adoc
@@ -0,0 +1,11 @@
+[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]
diff --git a/assemblies/assembly-enabling-authentication.adoc b/assemblies/assembly-enabling-authentication.adoc
@@ -53,11 +53,11 @@ Therefore, deleting users and groups by using {product-short} Web UI or REST API
 include::assembly-authenticationg-with-the-guest-user.adoc[leveloffset=+1]
 
 
-include::modules/auth/proc-adding-azure-as-an-authentication-provider.adoc[leveloffset=+1]
+include::assembly-authenticating-with-rhsso.adoc[leveloffset=+1]
 
 
 include::assembly-auth-provider-github.adoc[leveloffset=+1]
 
 
-include::assembly-auth-provider-oidc.adoc[leveloffset=+1]
+include::modules/auth/proc-adding-azure-as-an-authentication-provider.adoc[leveloffset=+1]
 
diff --git a/modules/authentication/proc-enabling-authentication-with-rhsso.adoc b/modules/authentication/proc-enabling-authentication-with-rhsso.adoc
@@ -0,0 +1,172 @@
+[id="enabling-authentication-with-rhsso"]
+= Enabling authentication with Red Hat Single-Sign On (RHSSO)
+
+To authenticate users with Red Hat Single Sign-On (RHSSO), 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.
+
+.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]:
+
+.. 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 __<my_realm>__.
+Save the value for the next step:
+* **RHSSO realm base URL**, such as: __<your_rhsso_URL>__/auth/realms/__<your_realm>__.
+
+.. 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:
+... **Client ID**: A distinctive client ID, such as __<{product-very-short}>__.
+... **Valid redirect URIs**: Set to the OIDC handler URL: `https://__<RHDH_URL>__/api/auth/oidc/handler/frame`.
+... Navigate to the **Credentials** tab and copy the **Client secret**.
+... Save the values for the next step:
+* **Client ID**
+* **Client Secret**
+
+.. 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:
++
+`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**.
+
+. 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:
++
+--
+.`app-config-rhdh.yaml` fragment with mandatory fields to enable authentication with RHSSO
+[source,yaml]
+----
+auth:
+  environment: production
+  providers:
+    oidc:
+      production:
+        metadataUrl: ${AUTH_OIDC_METADATA_URL}
+        clientId: ${AUTH_OIDC_CLIENT_ID}
+        clientSecret: ${AUTH_OIDC_CLIENT_SECRET}
+signInPage: oidc
+----
+
+`environment: production`::
+Mark the environment as `production` to hide the Guest login in the {product-short} home page.
+
+`metadataUrl`, `clientId`, `clientSecret`::
+To configure the OIDC provider with your secrets.
+
+`sigInPage: oidc`::
+To enable the OIDC provider as default sign-in provider.
+
+
+Optional: Consider adding the following optional fields:
+
+`dangerouslyAllowSignInWithoutUserInCatalog: true`::
++
+--
+To enable authentication without requiring to provision users in the {product-short} software catalog.
++
+WARNING: Use this option to explore {product-short} features, but do not use it in production.
++
+.`app-config-rhdh.yaml` fragment with optional field to allow authenticating users absent from the software catalog
+[source,yaml]
+----
+auth:
+  environment: production
+  providers:
+    oidc:
+      production:
+        metadataUrl: ${AUTH_OIDC_METADATA_URL}
+        clientId: ${AUTH_OIDC_CLIENT_ID}
+        clientSecret: ${AUTH_OIDC_CLIENT_SECRET}
+signInPage: oidc
+dangerouslyAllowSignInWithoutUserInCatalog: true
+----
+--
+
+`callbackUrl`::
+--
+RHSSO callback URL.
+
+.`app-config-rhdh.yaml` fragment with optional `callbackURL` field
+[source,yaml]
+----
+auth:
+  providers:
+    oidc:
+      production:
+        callbackUrl: ${AUTH_OIDC_CALLBACK_URL}
+----
+--
+
+`tokenEndpointAuthMethod`::
+--
+Token endpoint authentication method.
+
+.`app-config-rhdh.yaml` fragment with optional `tokenEndpointAuthMethod` field
+[source,yaml]
+----
+auth:
+  providers:
+    oidc:
+      production:
+        tokenEndpointAuthMethod: ${AUTH_OIDC_TOKEN_ENDPOINT_METHOD}
+----
+--
+
+`tokenSignedResponseAlg`::
+--
+Token signed response algorithm.
+
+.`app-config-rhdh.yaml` fragment with optional `tokenSignedResponseAlg` field
+[source,yaml]
+----
+auth:
+  providers:
+    oidc:
+      production:
+        tokenSignedResponseAlg: ${AUTH_OIDC_SIGNED_RESPONSE_ALG}
+----
+--
+
+`scope`::
+--
+RHSSO scope.
+
+.`app-config-rhdh.yaml` fragment with optional `scope` field
+[source,yaml]
+----
+auth:
+  providers:
+    oidc:
+      production:
+        scope: ${AUTH_OIDC_SCOPE}
+----
+--
+
+`signIn.resolvers`::
+--
+Declarative resolvers to override the default resolver: `emailLocalPartMatchingUserEntityName`.
+The authentication provider tries each sign-in resolver until it succeeds, and fails if none succeed.
+
+.`app-config-rhdh.yaml` fragment with optional `callbackURL` field
+[source,yaml]
+----
+auth:
+  providers:
+    oidc:
+      production:
+        signIn:
+          resolvers:
+            - resolver: preferredUsernameMatchingUserEntityName
+            - resolver: emailMatchingUserEntityProfileEmail
+            - resolver: emailLocalPartMatchingUserEntityName
+----
+--
+
+--
+
+.Verification
+. Go to the {product-short} login page.
+. Your {product-short} sign-in page displays *Sign in using OIDC* and the Guest user sign-in is disabled.
+. Log in with OIDC by using the saved **Username** and **Password** values.
+
diff --git a/.../authentication/proc-provisioning-users-from-rhsso-to-the-software-catalog.adoc b/.../authentication/proc-provisioning-users-from-rhsso-to-the-software-catalog.adoc
@@ -0,0 +1,153 @@
+[id="provisioning-users-from-rhsso-to-the-software-catalog"]
+= Provisioning users from Red Hat Single-Sign On (RHSSO) to the software catalog
+
+.Prerequisites
+* You xref:enabling-authentication-with-rhsso[enabled authentication with RHSSO].
+
+.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:
++
+--
+[id=keycloakOrgProviderId]
+.`app-config.yaml` fragment with mandatory `keycloakOrg` fields
+[source,yaml]
+----
+dangerouslyAllowSignInWithoutUserInCatalog: false
+catalog:
+  providers:
+    keycloakOrg:
+      default:
+        baseUrl: ${AUTH_OIDC_METADATA_URL}
+        clientId: ${AUTH_OIDC_CLIENT_ID}
+        clientSecret: ${AUTH_OIDC_CLIENT_SECRET}
+----
+
+`dangerouslyAllowSignInWithoutUserInCatalog: false`::
+ 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].
+
+`clientId`::
+Your {product-short} application client ID in RHSSO, defined when xref:enabling-authentication-with-rhsso[enabling authentication with RHSSO].
+
+`clientSecret`::
+Your {product-short} application client secret in RHSSO, defined when xref:enabling-authentication-with-rhsso[enabling authentication with RHSSO].
+
+Optional: Consider adding the following optional fields:
+
+`realm`::
+Realm to synchronize.
+Default value: `master`.
++
+.`app-config.yaml` fragment with optional `realm` field
+[source,yaml]
+----
+catalog:
+  providers:
+    keycloakOrg:
+      default:
+        realm: master
+----
+
+`loginRealm`::
+Realm used to authenticate.
+Default value: `master`.
++
+.`app-config.yaml` fragment with optional `loginRealm` field
+[source,yaml]
+----
+catalog:
+  providers:
+    keycloakOrg:
+      default:
+        loginRealm: master
+----
+
+`userQuerySize`::
+User number to query simultaneously.
+Default value: `100`.
++
+.`app-config.yaml` fragment with optional `userQuerySize` field
+[source,yaml]
+----
+catalog:
+  providers:
+    keycloakOrg:
+      default:
+        userQuerySize: 100
+----
+
+`groupQuerySize`::
+Group number to query simultaneously.
+Default value: `100`.
++
+.`app-config.yaml` fragment with optional `groupQuerySize` field
+[source,yaml]
+----
+catalog:
+  providers:
+    keycloakOrg:
+      default:
+        groupQuerySize: 100
+----
+
+`schedule.frequency`::
+To specify custom schedule frequency.
+Supports cron, ISO duration, and "human duration" as used in code.
++
+.`app-config.yaml` fragment with optional `schedule.frequency` field
+[source,yaml]
+----
+catalog:
+  providers:
+    keycloakOrg:
+      default:
+        schedule:
+          frequency: { hours: 1 }
+----
+
+`schedule.timeout`::
+To specify custom timeout.
+Supports ISO duration and "human duration" as used in code.
++
+.`app-config.yaml` fragment with optional `schedule.timeout` field
+[source,yaml]
+----
+catalog:
+  providers:
+    keycloakOrg:
+      default:
+        schedule:
+          timeout: { minutes: 50 }
+----
+
+`schedule.initialDelay`::
+To specify custom initial delay.
+Supports ISO duration and "human duration" as used in code.
++
+.`app-config.yaml` fragment with optional `schedule.initialDelay` field
+[source,yaml]
+----
+catalog:
+  providers:
+    keycloakOrg:
+      default:
+        schedule:
+          initialDelay: { seconds: 15}
+----
+--
+
+.Verification
+
+. Check the console logs to verify that the synchronization is completed.
++
+.Successful synchronization example:
+[source,json]
+----
+{"class":"KeycloakOrgEntityProvider","level":"info","message":"Read 3 Keycloak users and 2 Keycloak groups in 1.5 seconds. Committing...","plugin":"catalog","service":"backstage","taskId":"KeycloakOrgEntityProvider:default:refresh","taskInstanceId":"bf0467ff-8ac4-4702-911c-380270e44dea","timestamp":"2024-09-25 13:58:04"}
+{"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.
diff --git a/modules/getting-started/con-oidc-overview.adoc b/modules/getting-started/con-oidc-overview.adoc