applied suggestions

Signed-off-by: Fabrice Flore-Thébault <[email protected]>

Author: themr0c

modules/authentication/proc-authenticationg-with-the-guest-user-on-an-operator-based-installation.adoc

@@ -6,7 +6,7 @@ After an Operator-based installation, you can configure {product-short} to log i
 
 .Prerequisites
 * You link:[installed {product-short} by using the Operator].
-* You link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/administration_guide_for_red_hat_developer_hub/index#proc-add-custom-app-config-file-ocp-operator_admin-rhdh[added a custom {product-short} application configuration], and have sufficient permissions to modify it.
+* You link:{configuring-book-url}[added a custom {product-short} application configuration], and have sufficient permissions to modify it.
 
 .Procedure
 * To enable the guest user in your {product-short} custom configuration, link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/administration_guide_for_red_hat_developer_hub/index#proc-add-custom-app-config-file-ocp-operator_admin-rhdh[edit your {product-short} application configuration] with following content:

modules/authentication/proc-enabling-authentication-with-github.adoc

@@ -4,7 +4,7 @@
 To authenticate users with GitHub, enable the GitHub authentication provider in {product}.
 
 .Prerequisites
-* You have 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 link:{configuring-book-url}[added a custom {product-short} application configuration], and have sufficient permissions to modify it.
 * You have sufficient permissions in GitHub to create and manage a link:https://docs.github.com/en/apps/overview[GitHub App].
 
 .Procedure

modules/authentication/proc-enabling-authentication-with-microsoft-azure.adoc

@@ -5,7 +5,7 @@
 
 .Prerequisites
 . You have the permission to register an application in Microsoft Azure.
-. You link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/administration_guide_for_red_hat_developer_hub/index#assembly-add-custom-app-file-openshift_admin-rhdh[added a custom {product-short} application configuration].
+* You link:{configuring-book-url}[added a custom {product-short} application configuration], and have sufficient permissions to modify it.
 
 .Procedure
 . To allow {product-short} to authenticate with Microsoft Azure, link:https://learn.microsoft.com/en-us/entra/identity-platform/scenario-web-app-sign-user-app-registration?tabs=aspnetcore#register-an-app-by-using-the-azure-portal[create an OAuth application in Microsoft Azure].

modules/authentication/proc-enabling-authentication-with-rhbk.adoc

@@ -5,8 +5,8 @@ To authenticate users with {rhbk-brand-name} ({rhbk}), enable the OpenID Connect
 
 
 .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 {rhbk} to create and manage a realm.
+* You link:{configuring-book-url}[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 {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]:

modules/configuring/proc-provisioning-your-custom-configuration.adoc

@@ -15,75 +15,20 @@ Your changes on this configuration might get reverted on {product-short} restart
 .Procedure
 . Author your custom `{my-product-secrets}.txt` file to provision your secrets as environment variables values in an {ocp-short} secret, rather than in clear text in your configuration files.
 It contains one secret per line in `KEY=value` form.
-
-.. To define the {product-short} backend secret, add the `BACKEND_SECRET` environment variable with a base64 encoded string.
-Use a unique value for each {product-short} instance.
-+
-[source,terminal,subs="+attributes"]
-----
-$ echo > {my-product-secrets}.txt "BACKEND_SECRET=$(node -p 'require("crypto").randomBytes(24).toString("base64")')"
-----
 +
-.`{my-product-secrets}.txt` example
-====
-----
-BACKEND_SECRET=3E2/rIPuZNFCtYHoxVP8wjriffnN1q/z
-----
-====
-
-.. link:{authentication-book-url}[Add your authentication secrets].
+* link:{authentication-book-url}[Enter your authentication secrets].
 
 . Author your custom `{my-app-config-file}` file.
 This is the main {product-short} configuration file.
 +
-.Minimal `{my-app-config-file}` example
-====
-[source,yaml,subs="+attributes,+quotes"]
-----
-backend:
-  auth:
-    externalAccess:
-      - type: legacy
-        options:
-          subject: legacy-default-config
-          secret: "${BACKEND_SECRET}"
-----
-====
-
-Mandatory fields::
-
-`backend.auth.externalAccess`:::
-Enter the mandatory backend authentication key configuration.
-
-Optional fields::
-
-`app.title`:::
-Optionally, enter your {product-short} instance display name, such as _<{product}>_.
-See link:{customizing-book-url}#customizing-your-product-title[Customizing your {product-short} title].
-
-`app.baseURL`, `backend.baseURL` and `backend.cors.origin`:::
-Optionally, enter your {product-short} external URL, such as pass:c,a,q[{my-product-url}].
-See link:{customizing-book-url}#customizing-your-product-base-url[Customizing your {product-short} base URL].
-
-`app.branding`:::
-Optionally, enter your appearance customization configuration.
-See link:{customizing-book-url}#customizing-appearance[Customizing the appearance].
-
-`backend.auth`:::
-Optionally, enter your authentication configuration.
-See link:{authentication-book-url}[{authentication-book-title}].
-
-`catalog`:::
-Optionally, configure the {product-short} catalog.
-See link:{authentication-book-url}[{authorization-book-title}] and xref:proc-configuring-an-rhdh-instance-with-tls-in-kubernetes_running-behind-a-proxy[].
-
-`kubernetes`:::
-Optionally, configure the {ocp-short} integration.
-See xref:proc-configuring-an-rhdh-instance-with-tls-in-kubernetes_running-behind-a-proxy[].
+You can start with an empty file to use the default configuration.
++
+Optionally, enter your configuration such as:
 
-`permission`:::
-Optionally, configure authorization.
-See link:{authorization-book-url}[{authorization-book-title}].
+* link:{authentication-book-url}[{authentication-book-title}].
+* link:{authorization-book-url}[{authorization-book-title}].
+* link:{customizing-book-url}[Customization].
+* xref:proc-configuring-an-rhdh-instance-with-tls-in-kubernetes_running-behind-a-proxy[Configure your {ocp-short} integration].
 
 . Provision your custom configuration files to your {ocp-short} cluster.
 

modules/customizing/proc-customizing-the-backend-secret.adoc

@@ -0,0 +1,40 @@
+[id='customizing-the-backend-secret']
+= Customizing {product} backend secret
+
+The default {product} configuration defines the {product-short} backend secret for service to service authentication.
+
+You can define your custom {product-short} backend secret.
+
+.Prerequisites
+* You link:{configuring-book-url}[added a custom {product-short} application configuration], and have sufficient permissions to modify it.
+
+.Procedure
+
+. To define the {product-short} backend secret,
+add to your custom `{my-product-secrets}.txt` file the `BACKEND_SECRET` environment variable with a base64 encoded string.
+Use a unique value for each {product-short} instance.
++
+[source,terminal,subs="+attributes"]
+----
+$ echo > {my-product-secrets}.txt "BACKEND_SECRET=$(node -p 'require("crypto").randomBytes(24).toString("base64")')"
+----
++
+.`{my-product-secrets}.txt` example
+----
+BACKEND_SECRET=3E2/rIPuZNFCtYHoxVP8wjriffnN1q/z
+----
+
+. Add your backend secret to  your custom `{my-app-config-file}` file.
++
+.`{my-app-config-file}` excerpt defining the backend secret
+[source,yaml,subs="+attributes,+quotes"]
+----
+backend:
+  auth:
+    externalAccess:
+      - type: legacy
+        options:
+          subject: legacy-default-config
+          secret: "${BACKEND_SECRET}"
+----
+

titles/customizing/master.adoc

@@ -10,8 +10,13 @@ include::artifacts/attributes.adoc[]
 
 include::modules/customizing/proc-customizing-your-product-title.adoc[leveloffset=+1]
 
+
 include::modules/customizing/proc-customizing-your-product-base-url.adoc[leveloffset=+1]
 
+
+include::modules/customizing/proc-customizing-the-backend-secret.adoc[leveloffest=+1]
+
+
 include::assemblies/assembly-configuring-templates.adoc[leveloffset=+1]