[RHDHBUGS-2722]: Restructure authentication title to JTBD outline

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

@@ -6,6 +6,7 @@ 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.
@@ -16,13 +17,25 @@ include::../modules/shared/con-understand-authentication-and-user-provisioning.a
 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-your-identity-provider.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-import-users-and-groups-from-your-identity-provider.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-share-a-secret-with-your-identity-provider.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:]

modules/shared/proc-create-a-custom-transformer-to-provision-users-from-github-to-the-software-catalog.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:

modules/shared/proc-create-a-custom-transformer-to-provision-users-from-gitlab-to-the-software-catalog.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 `gitlabOrgEntityProviderTransformsExtensionPoint` to offer custom user and group transformers for the GitLab backend.
 
 .Prerequisites
-* You have xref:enable-user-authentication-with-gitlab_{context}[enabled provisioning users from GitLab to the software catalog].
+* You have xref:import-users-and-groups-from-gitlab_{context}[imported users and groups from GitLab to the software catalog].
 
 .Procedure
 . Create a new backend module:

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

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

modules/shared/proc-create-a-custom-transformer-to-provision-users-from-to-the-software-catalog.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 `microsoftGraphOrgEntityProviderTransformExtensionPoint` to offer custom user and group transformers for the {azure-short} backend.
 
 .Prerequisites
-* You have xref:enable-user-authentication-with-microsoft-azure-with-optional-steps_{context}[enabled provisioning users from {azure-short} to the software catalog].
+* You have xref:import-users-and-groups-from-microsoft-azure_{context}[imported users and groups from {azure-brand-name}].
 
 .Procedure
 . Create a new backend module:

modules/shared/snip-enabling-user-authentication-with-github-optional-authentication-provider-steps.adoc → modules/shared/proc-enable-authentication-with-github.adoc

@@ -1,4 +1,41 @@
-:_mod-docs-content-type: SNIPPET
+:_mod-docs-content-type: PROCEDURE
+
+[id="enable-authentication-with-github_{context}"]
+= Enable authentication with GitHub
+
+[role="_abstract"]
+Configure GitHub as your {product} sign-in provider.
+
+.Prerequisites
+* You have xref:share-a-secret-with-github_{secrets-context}[shared a secret with GitHub].
+
+.Procedure
+
+. Enable the GitHub authentication provider, by adding the GitHub authentication provider section to your `{my-app-config-file}` file:
++
+[source,yaml]
+----
+auth:
+  environment: production
+  providers:
+    github:
+      production:
+        clientId: ${GITHUB_CLIENT_ID}
+        clientSecret: ${GITHUB_CLIENT_SECRET}
+signInPage: github
+----
+
+`environment`::
+Enter `production` to disable the Guest login option in the {product-short} login page.
+
+`clientId`::
+Enter the configured secret variable name: `$\{GITHUB_CLIENT_ID}`.
+
+`clientSecret`::
+Enter the configured secret variable name: `$\{GITHUB_CLIENT_SECRET}`.
+
+`signInPage`::
+Enter `github` to enable the GitHub provider as your {product-short} sign-in provider.
 
 . Optional: Add optional fields to the GitHub authentication provider section in your `{my-app-config-file}` file:
 +
@@ -46,14 +83,28 @@ In production mode, configure only one resolver to make sure users are securely
 Enter the sign-in resolver name.
 Available resolvers:
 
-* `usernameMatchingUserEntityName`
-* `emailLocalPartMatchingUserEntityName`
-* `emailMatchingUserEntityProfileEmail`
+. `usernameMatchingUserEntityName`
+. `preferredUsernameMatchingUserEntityName`
+. `emailMatchingUserEntityProfileEmail`
 
 `dangerouslyAllowSignInWithoutUserInCatalog`::::
 Enter `true` to configure the sign-in resolver to bypass the user provisioning requirement in the {product-short} software catalog.
 +
 [WARNING]
 ====
-In production mode, do not enable `dangerouslyAllowSignInWithoutUserInCatalog`.
+In production more, do not enable `dangerouslyAllowSignInWithoutUserInCatalog`.
 ====
+
+. To disable the guest login option, in the `{my-app-config-file}` file, set the authentication environment to `production`:
++
+[source,yaml]
+----
+auth:
+  environment: production
+----
+
+.Verification
+. To verify GitHub authentication:
+.. Go to the {product-short} login page.
+.. Your {product-short} sign-in page displays *Sign in using GitHub* and the Guest user sign-in is disabled.
+.. Log in with a GitHub account.

modules/shared/proc-enable-authentication-with-gitlab.adoc

@@ -0,0 +1,58 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="enable-authentication-with-gitlab_{context}"]
+= Enable authentication with GitLab
+
+[role="_abstract"]
+Configure GitLab as your {product} sign-in provider.
+
+.Prerequisites
+* You have xref:share-a-secret-with-gitlab_{secrets-context}[shared a secret with GitLab].
+
+.Procedure
+
+. Enable the GitLab authentication provider by adding the GitLab authentication provider section to your {product-very-short} `{my-app-config-file}` file:
++
+[source,yaml,subs="+quotes,+attributes"]
+----
+includeTransitiveGroupOwnership: true
+signInPage: gitlab
+auth:
+  environment: production
+  session:
+    secret: _<name_of_secret>_
+  providers:
+    gitlab:
+      production:
+        audience: https://${GITLAB_HOST}
+        clientId: $\{GITLAB_CLIENT_ID}
+        clientSecret: $\{GITLAB_CLIENT_SECRET}
+        callbackUrl: {my-product-url}/api/auth/gitlab/handler/frame
+----
++
+
+`audience`::
+Enter your GitLab instance address: `pass:c,a,q[https://${GITLAB_HOST}]`
+
+`clientId`::
+Enter the configured client ID: `${GITLAB_CLIENT_ID}`.
+
+`clientSecret`::
+Enter the configured secret variable name: `${GITLAB_CLIENT_SECRET}`.
+
+`callbackUrl`::
+Enter your {product-short} authentication backend URL: `pass:c,a,q[{my-product-url}/api/auth/gitlab/handler/frame]`
+
+. To disable the guest login option, in the `{my-app-config-file}` file, set the authentication environment to `production`:
++
+[source,yaml]
+----
+auth:
+  environment: production
+----
+
+.Verification
+. To verify GitLab authentication:
+.. Go to the {product-short} login page.
+.. Your {product-short} sign-in page displays *Sign in using GitLab* and the Guest user sign-in is disabled.
+.. Log in with a GitLab account.