RHDHBUGS-2067 - Grouped optional configurations in one example file

assemblies/assembly-authenticating-with-rhbk.adoc

@@ -4,7 +4,7 @@
 = Authenticating with {rhbk-brand-name} ({rhbk})
 
 
-include::modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc[leveloffset=+1]
+include::modules/authentication/proc-enabling-user-authentication-with-rhbk-with-optional-steps.adoc[leveloffset=+1]
 
 
 include::modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog.adoc[leveloffset=+1]

assemblies/assembly-enabling-authentication-with-github.adoc

@@ -4,7 +4,7 @@
 [id='enabling-authentication-with-github']
 = Enabling authentication with GitHub
 
-include::modules/authentication/proc-enabling-user-authentication-with-github.adoc[leveloffset=+1]
+include::modules/authentication/proc-enabling-user-authentication-with-github-with-optional-steps.adoc[leveloffset=+1]
 
 
 include::modules/authentication/proc-enabling-user-authentication-with-github-as-an-auxiliary-authentication-provider.adoc[leveloffset=+1]

assemblies/assembly-enabling-authentication-with-mandatory-steps-only.adoc

@@ -10,11 +10,11 @@ include::modules/authentication/con-understanding-authentication-and-user-provis
 include::assembly-authenticating-with-the-guest-user.adoc[leveloffset=+1]
 
 
-include::modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc[leveloffset=+1]
+include::modules/authentication/proc-enabling-user-authentication-with-rhbk-with-mandatory-steps.adoc[leveloffset=+1]
 
 
-include::modules/authentication/proc-enabling-user-authentication-with-github.adoc[leveloffset=+1]
+include::modules/authentication/proc-enabling-user-authentication-with-github-with-mandatory-steps.adoc[leveloffset=+1]
 
 
-include::modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc[leveloffset=+1]
+include::modules/authentication/proc-enabling-user-authentication-with-microsoft-azure-with-mandatory-steps.adoc[leveloffset=+1]
 

assemblies/assembly-enabling-authentication.adoc

@@ -16,5 +16,5 @@ include::assembly-authenticating-with-rhbk.adoc[leveloffset=+1]
 include::assembly-enabling-authentication-with-github.adoc[leveloffset=+1]
 
 
-include::modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc[leveloffset=+1]
+include::modules/authentication/proc-enabling-user-authentication-with-microsoft-azure-with-optional-steps.adoc[leveloffset=+1]
 

modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog.adoc

@@ -7,7 +7,7 @@ Customize how {product} provisions users and groups to {product} software catalo
 by creating a backend module that uses the `keycloakTransformerExtensionPoint` to offer custom user and group transformers for the Keycloak backend.
 
 .Prerequisites
-* You have xref:enabling-user-authentication-with-rhbk[enabled provisioning users from {rhbk-brand-name} ({rhbk}) to the software catalog].
+* You have xref:enabling-user-authentication-with-rhbk-with-optional-steps[enabled provisioning users from {rhbk-brand-name} ({rhbk}) to the software catalog].
 
 .Procedure
 . Create a new backend module with the `yarn new` command.

modules/authentication/proc-enabling-user-authentication-with-github-as-an-auxiliary-authentication-provider.adoc

@@ -3,14 +3,17 @@
 [id="enabling-user-authentication-with-github-as-an-auxiliary-authentication-provider"]
 = Enabling user authentication with GitHub as an auxiliary authentication provider
 
-To allow users to access GitHub templates or plugins that require GitHub authentication, configure GitHub as an auxiliary authentication provider. This method relies on a primary authentication provider for user identity management, and skips resolving user identity from this provider.
+If your primary authentication provider is not GitHub, users might lack the permissions needed for templates or plugins that require GitHub access. The recommended solution is to configure GitHub as an auxiliary authentication provider. This approach uses the primary provider for user identity management and the auxiliary provider to grant the necessary GitHub permissions, without re-resolving the user's identity.
+
+Give users access to these features by configuring GitHub as an auxiliary authentication provider.
 
 .Prerequisites
-* You have {configuring-book-link}[added a custom {product-short} application configuration] with another authentication provider enabled, and have enough permissions to change it.
+include::snip-enabling-user-authentication-with-github-common-prerequisites.adoc[]
+* You have configured a primary authentication provider to provision user and group identities to the {product} software catalog, and establish {product-short} user sessions.
 
-include::snip-enabling-user-authentication-with-github-common-steps.adoc[]
 
-. To set up the GitHub authentication provider as an auxiliary authentication provider, add the `auth.providers.github` section to your `{my-app-config-file}` file:
+.Procedure
+. Add the `auth.providers.github` section to your `{my-app-config-file}` file:
 +
 [source,yaml]
 ----
@@ -31,11 +34,14 @@ Enter the configured secret variable name: `$\{GITHUB_CLIENT_ID}`.
 Enter the configured secret variable name: `$\{GITHUB_CLIENT_SECRET}`.
 
 `disableIdentityResolution`::
-Enter `true`to skip user identity resolution for this provider to enable sign-in from an auxiliary authentication provider.
+Enter `true` to skip user identity resolution for this provider to enable sign-in from an auxiliary authentication provider.
++
+[WARNING]
+====
 Do not enable this setting on the primary authentication provider you plan on using for sign-in and identity management.
+====
 
 .Verification
-
 . Go to the {product-short} login page.
 . Log in with your primary authentication provider account.
 . In the top user menu, go to *Settings* > *Authentication Providers*.

modules/authentication/proc-enabling-user-authentication-with-github-with-mandatory-steps.adoc

@@ -0,0 +1,14 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="enabling-user-authentication-with-github-with-mandatory-steps"]
+= Enabling user authentication with GitHub
+
+Authenticate users with GitHub by provisioning the users and groups from GitHub to the {product-short} software catalog, and configuring the GitHub authentication provider in {product}.
+
+include::snip-enabling-user-authentication-with-github-common-prerequisites.adoc[]
+
+include::snip-enabling-user-authentication-with-github-common-first-steps.adoc[]
++
+Optional: To configure optional fields, see {configuring-book-link}[{configuring-book-title}].
+
+include::snip-enabling-user-authentication-with-github-common-verification-steps.adoc[]

modules/authentication/proc-enabling-user-authentication-with-github-with-optional-steps.adoc

@@ -0,0 +1,18 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="enabling-user-authentication-with-github-with-optional-steps"]
+= Enabling user authentication with GitHub, with optional steps
+
+Authenticate users with GitHub by provisioning the users and groups from GitHub to the {product-short} software catalog, and configuring the GitHub authentication provider in {product}.
+
+include::snip-enabling-user-authentication-with-github-common-prerequisites.adoc[]
+
+include::snip-enabling-user-authentication-with-github-common-first-steps.adoc[]
+
+. {empty}
++
+--
+include::snip-enabling-user-authentication-with-github-optional-authentication-provider-steps.adoc[]
+--
+
+include::snip-enabling-user-authentication-with-github-common-verification-steps.adoc[]

modules/authentication/proc-enabling-user-authentication-with-microsoft-azure-with-mandatory-steps.adoc

@@ -0,0 +1,14 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="enabling-user-authentication-with-microsoft-azure-with-mandatory-steps"]
+= Enabling user authentication with {azure-brand-name}
+
+include::snip-enabling-user-authentication-with-microsoft-azure-common-first-steps.adoc[]
++
+Optional: To configure optional fields, see {configuring-book-link}[{configuring-book-title}].
+
+include::snip-enabling-user-authentication-with-microsoft-azure-common-authentication-provider-steps.adoc[]
++
+Optional: To configure optional fields, see {configuring-book-link}[{configuring-book-title}].
+
+include::snip-enabling-user-authentication-with-microsoft-azure-common-verification-steps.adoc[]

modules/authentication/proc-enabling-user-authentication-with-microsoft-azure-with-optional-steps.adoc

@@ -0,0 +1,26 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="enabling-user-authentication-with-microsoft-azure-with-optional-steps"]
+= Enabling user authentication with {azure-brand-name}, with optional steps
+
+include::snip-enabling-user-authentication-with-microsoft-azure-common-first-steps.adoc[]
+
+. {empty}
++
+--
+include::snip-enabling-user-authentication-with-microsoft-azure-optional-catalog-provider-steps.adoc[]
+--
+
+. {empty}
++
+--
+include::snip-enabling-user-authentication-with-microsoft-azure-common-authentication-provider-steps.adoc[]
+--
+
+. {empty}
++
+--
+include::snip-enabling-user-authentication-with-microsoft-azure-optional-authentication-provider-steps.adoc[]
+--
+
+include::snip-enabling-user-authentication-with-microsoft-azure-common-verification-steps.adoc[]