[RHDHBUGS-2722]: Restructure authentication title to JTBD outline (#2049)

* feat: create new JTBD outline shell for authentication title

Establish the new section structure: share secrets, import users,
enable auth, external services. Existing content temporarily parked
under the auth section pending per-IdP splits.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: split RHBK auth procedure into secret, import, and auth modules

Extract secrets sharing, user import, and auth config from the
monolithic RHBK procedure into focused JTBD modules.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: split GitHub auth procedure into secret, import, and auth modules

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: split Azure auth procedure into secret, import, and auth modules

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: split GitLab auth procedure into secret, import, and auth modules

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: extract LDAP secret sharing into dedicated procedure

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: update get-started mandatory-only assembly to use split procedures

Replace old monolithic proc-enable-user-authentication-with-{rhbk,github,microsoft-azure}
wrapper includes with the new split procedures (secret, import, auth) for each IdP.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: remove old monolithic auth procedures, assemblies, and orphaned snippets

Delete 26 files replaced by the new JTBD-structured authentication docs:
- 4 old per-IdP assemblies (RHBK, GitHub, Microsoft Azure, GitLab)
- 3 old monolithic with-optional-steps procedures
- 1 old monolithic GitLab procedure
- 3 old mandatory-only wrapper procedures
- 15 orphaned snippet files

5 snippet files retained (still referenced by new split procedures):
- snip-enabling-user-authentication-with-rhbk-common-prerequisites.adoc
- snip-enabling-user-authentication-with-github-common-prerequisites.adoc
- snip-enabling-user-authentication-with-microsoft-azure-common-prerequisites.adoc
- snip-enable-user-authentication-with-gitlab-common-prerequisites.adoc
- snip-disabling-the-guest-user-step.adoc

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: use secrets-context attribute for cross-assembly xref resolution

Hardcoded xref targets to _share-a-secret-with-your-identity-provider
broke when procedures were included in the mandatory-only assembly
(which uses a different context). Introduce a {secrets-context}
attribute set by each parent assembly to ensure xrefs resolve correctly
in both the auth title and the get-started mandatory-only assembly.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: update broken xrefs in transformer and LDAP procedures

Custom transformer prerequisites referenced old monolithic procedure
IDs. LDAP procedure referenced RHBK auth with {parent-context} which
no longer resolves correctly after the assembly restructure. Hardcode
the correct target contexts for cross-assembly xrefs.

* fix(RHDHBUGS-2722): fix broken xrefs in LDAP and troubleshoot modules

Update xref context suffixes to match the actual assembly contexts:
- LDAP procedure: use enable-authentication-with-your-identity-provider
- Troubleshoot catalog errors: use import-users-and-groups-from-your-identity-provider

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Apply suggestions from code review

Co-authored-by: Jana Vrbkova <jvrbkova@redhat.com>

* Apply suggestions from code review

Co-authored-by: Fabrice Flore-Thébault <ffloreth@redhat.com>

* Apply suggestion from @themr0c

* fix CQA issue

Signed-off-by: Fabrice Flore-Thébault <ffloreth@redhat.com>

* fix CQA issues

Signed-off-by: Fabrice Flore-Thébault <ffloreth@redhat.com>

* Apply suggestions from code review

Co-authored-by: Jana Vrbkova <jvrbkova@redhat.com>

* fix CQA issue

Signed-off-by: Fabrice Flore-Thébault <ffloreth@redhat.com>

---------

Signed-off-by: Fabrice Flore-Thébault <ffloreth@redhat.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Jana Vrbkova <jvrbkova@redhat.com>

Author: 3 people

assemblies/shared/assembly-enable-authentication-in-rhdh-with-mandatory-steps-only.adoc

@@ -6,23 +6,36 @@ ifdef::context[:parent-context: {context}]
 = Enable authentication in {product} (with mandatory steps only)
 
 :context: enable-authentication-in-rhdh-with-mandatory-steps-only
+:secrets-context: enable-authentication-in-rhdh-with-mandatory-steps-only
 
 [role="_abstract"]
-You can enable authentication in {product} to allow users to sign in using credentials from an external identity provider, such as {rhbk}, GitHub, or {azure-brand-name}, and provision user and group data to the software catalog.
+Enable authentication in {product} to allow users to sign in using credentials from an external identity provider, such as {rhbk}, GitHub, or {azure-brand-name}, and provision user and group data to the software catalog.
 
 include::../modules/shared/con-understand-authentication-and-user-provisioning.adoc[leveloffset=+1]
 
 
 include::assembly-enable-or-disable-authentication-with-the-guest-user.adoc[leveloffset=+1]
 
 
-include::../modules/shared/proc-enable-user-authentication-with-rhbk.adoc[leveloffset=+1]
+include::../modules/shared/proc-share-a-secret-with-rhbk.adoc[leveloffset=+1]
 
+include::../modules/shared/proc-import-users-and-groups-from-rhbk.adoc[leveloffset=+1]
 
-include::../modules/shared/proc-enable-user-authentication-with-github.adoc[leveloffset=+1]
+include::../modules/shared/proc-enable-authentication-with-rhbk.adoc[leveloffset=+1]
 
 
-include::../modules/shared/proc-enable-user-authentication-with-microsoft-azure.adoc[leveloffset=+1]
+include::../modules/shared/proc-share-a-secret-with-github.adoc[leveloffset=+1]
+
+include::../modules/shared/proc-import-users-and-groups-from-github.adoc[leveloffset=+1]
+
+include::../modules/shared/proc-enable-authentication-with-github.adoc[leveloffset=+1]
+
+
+include::../modules/shared/proc-share-a-secret-with-microsoft-azure.adoc[leveloffset=+1]
+
+include::../modules/shared/proc-import-users-and-groups-from-microsoft-azure.adoc[leveloffset=+1]
+
+include::../modules/shared/proc-enable-authentication-with-microsoft-azure.adoc[leveloffset=+1]
 
 ifdef::parent-context[:context: {parent-context}]
 ifndef::parent-context[:!context:]

assemblies/shared/assembly-enable-authentication-with-external-services.adoc

@@ -0,0 +1,17 @@
+:_mod-docs-content-type: ASSEMBLY
+ifdef::context[:parent-context: {context}]
+
+[id="enable-authentication-with-external-services_{context}"]
+= Enable authentication with external services
+
+:context: enable-authentication-with-external-services
+
+[role="_abstract"]
+Enable authentication with external services to allow {product} to communicate with secondary identity providers and external APIs.
+
+include::../modules/shared/proc-enable-user-authentication-with-github-as-an-auxiliary-authentication-provider.adoc[leveloffset=+1]
+
+include::assembly-enable-service-to-service-authentication.adoc[leveloffset=+1]
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]

assemblies/shared/assembly-enable-authentication-with-github.adoc

@@ -0,0 +1,22 @@
+:_mod-docs-content-type: ASSEMBLY
+ifdef::context[:parent-context: {context}]
+
+[id="enable-authentication-with-your-identity-provider_{context}"]
+= Enable authentication with your identity provider
+
+:context: enable-authentication-with-your-identity-provider
+:secrets-context: share-a-secret-with-your-identity-provider
+
+[role="_abstract"]
+Enable authentication with your main identity provider to allow users to sign in to {product} using their organizational credentials.
+
+include::../modules/shared/proc-enable-authentication-with-rhbk.adoc[leveloffset=+1]
+
+include::../modules/shared/proc-enable-authentication-with-github.adoc[leveloffset=+1]
+
+include::../modules/shared/proc-enable-authentication-with-microsoft-azure.adoc[leveloffset=+1]
+
+include::../modules/shared/proc-enable-authentication-with-gitlab.adoc[leveloffset=+1]
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]

assemblies/shared/assembly-enable-authentication-with-gitlab.adoc

@@ -0,0 +1,34 @@
+:_mod-docs-content-type: ASSEMBLY
+ifdef::context[:parent-context: {context}]
+
+[id="import-users-and-groups-from-your-identity-provider_{context}"]
+= Import users and groups from your identity provider
+
+:context: import-users-and-groups-from-your-identity-provider
+:secrets-context: share-a-secret-with-your-identity-provider
+
+[role="_abstract"]
+Import users and groups from your identity provider to the {product} software catalog to enable user identity resolution and role-based access control.
+
+include::../modules/shared/proc-import-users-and-groups-from-rhbk.adoc[leveloffset=+1]
+
+include::../modules/shared/proc-create-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog.adoc[leveloffset=+2]
+
+include::../modules/shared/proc-enable-user-provisioning-with-ldap.adoc[leveloffset=+1]
+
+include::../modules/shared/proc-create-a-custom-transformer-to-provision-users-from-ldap-to-the-software-catalog.adoc[leveloffset=+2]
+
+include::../modules/shared/proc-import-users-and-groups-from-github.adoc[leveloffset=+1]
+
+include::../modules/shared/proc-create-a-custom-transformer-to-provision-users-from-github-to-the-software-catalog.adoc[leveloffset=+2]
+
+include::../modules/shared/proc-import-users-and-groups-from-microsoft-azure.adoc[leveloffset=+1]
+
+include::../modules/shared/proc-create-a-custom-transformer-to-provision-users-from-to-the-software-catalog.adoc[leveloffset=+2]
+
+include::../modules/shared/proc-import-users-and-groups-from-gitlab.adoc[leveloffset=+1]
+
+include::../modules/shared/proc-create-a-custom-transformer-to-provision-users-from-gitlab-to-the-software-catalog.adoc[leveloffset=+2]
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]

assemblies/shared/assembly-enable-authentication-with-microsoft-azure.adoc

@@ -0,0 +1,23 @@
+:_mod-docs-content-type: ASSEMBLY
+ifdef::context[:parent-context: {context}]
+
+[id="share-a-secret-with-your-identity-provider_{context}"]
+= Share a secret with your identity provider
+
+:context: share-a-secret-with-your-identity-provider
+
+[role="_abstract"]
+Share credentials between your identity provider and {product} to enable secure communication for authentication and user provisioning.
+
+include::../modules/shared/proc-share-a-secret-with-rhbk.adoc[leveloffset=+1]
+
+include::../modules/shared/proc-share-a-secret-with-ldap.adoc[leveloffset=+1]
+
+include::../modules/shared/proc-share-a-secret-with-github.adoc[leveloffset=+1]
+
+include::../modules/shared/proc-share-a-secret-with-microsoft-azure.adoc[leveloffset=+1]
+
+include::../modules/shared/proc-share-a-secret-with-gitlab.adoc[leveloffset=+1]
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]

assemblies/shared/assembly-enable-authentication-with-rhbk.adoc

@@ -8,7 +8,7 @@ Customize how {product} provisions users and groups to {product-short} software
 by creating a backend module plugin that uses the `githubOrgEntityProviderTransformsExtensionPoint` to offer custom user and group transformers for the GitHub backend.
 
 .Prerequisites
-* You have xref:enable-user-authentication-with-github-with-optional-steps_{context}[enabled provisioning users from GitHub to the software catalog].
+* You have xref:import-users-and-groups-from-github_{context}[imported users and groups from GitHub to the software catalog].
 
 .Procedure
 . Create a new backend module: