RHIDP-7975 Enabling authentication procedures with mandatory steps only

.vale-styles/config/vocabularies/RHDH/accept.txt

@@ -1 +1,6 @@
+cron
+Entra
+IdP
+Operator
+MSGraph
 scaffolder

.vale.ini

@@ -23,3 +23,4 @@ BasedOnStyles = RedHat,DeveloperHub,AsciiDocDITA
 AsciiDocDITA.AttributeReference = NO
 AsciiDocDITA.ShortDescription = NO
 AsciiDocDITA.CrossReference = NO
+AsciiDocDITA.ConditionalCode = NO

assemblies/assembly-authenticating-with-the-guest-user.adoc

@@ -3,8 +3,7 @@
 [id="authenticating-with-the-guest-user_{context}"]
 = Authenticating with the Guest user
 
-To explore {product-short} features, you can skip configuring authentication and authorization.
-You can configure {product-short} to log in as a Guest user and access {product-short} features.
+For trial or non-production environments, you can enable guest access to skip configuring authentication and authorization and explore {product-short} features.
 
 include::modules/authentication/proc-authenticationg-with-the-guest-user-on-an-operator-based-installation.adoc[leveloffset=+1]
 

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

@@ -0,0 +1,20 @@
+:_mod-docs-content-type: ASSEMBLY
+:optional-steps: disable
+
+[id='enabling-authentication-with-mandatory-steps-only']
+= Enabling authentication in {product} (with mandatory steps only)
+
+include::modules/authentication/con-understanding-authentication-and-user-provisioning.adoc[leveloffset=+1]
+
+
+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-github.adoc[leveloffset=+1]
+
+
+include::modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc[leveloffset=+1]
+

assemblies/assembly-enabling-authentication.adoc

@@ -1,11 +1,9 @@
 :_mod-docs-content-type: ASSEMBLY
+:optional-steps: enable
 
 [id='enabling-authentication']
 = Enabling authentication in {product}
 
-
-
-
 include::modules/authentication/con-understanding-authentication-and-user-provisioning.adoc[leveloffset=+1]
 
 

modules/authentication/con-understanding-authentication-and-user-provisioning.adoc

@@ -2,8 +2,7 @@
 
 = Understanding authentication and user provisioning
 
-This module provides an overview of how authentication and user provisioning function within {product}.
-Learn about the process from creating user and group entities in the software catalog to user sign-in, and how authentication and catalog plugins enable each step.
+Learn about the authentication process from creating user and group entities in the software catalog to user sign-in, and how authentication and catalog plugins enable each step.
 Understanding this process is essential for successfully configuring your {product-short} instance, securing access through authorization, and enabling features that rely on synchronized user and group data.
 
 To fully enable catalog features, provision user and group data from the Identity Provider to the {product-short} software catalog.
@@ -18,21 +17,29 @@ On successful authentication, the {product-short} authentication plugin, configu
 
 Configuring authentication and user provisioning is critical for several reasons.
 
-* It secures your {product-short} instance by ensuring only authenticated users can gain access.
-* It enables authorization by allowing you to define access controls based on user and group memberships synchronized from your IdP.
+* Securing your {product-short} instance by ensuring only authenticated users can gain access.
+* Enabling authorization by allowing you to define access controls based on user and group memberships synchronized from your IdP.
 * Provisioning user and group data to the catalog is necessary for various catalog features that rely on understanding entity ownership and relationships between users, groups, and software components.
-Without this provisioning step, features like displaying who owns a component in the catalog may not function correctly.
++
+[IMPORTANT]
+====
+Without this provisioning step, features such as displaying who owns a catalog entity might not function correctly.
+====
 
 [TIP]
 ====
 To explore {product-short} features in a non-production environment, you can:
 
 * To use {product-short} without external IdP, enable the guest user to skip configuring authentication and authorization, log in as the guest user, and access all {product-short} features.
 
-* To use {product-short} without authorization policies and features relying on the software catalog, you can enable the `dangerouslyAllowSignInWithoutUserInCatalog` resolver option. This setting bypasses the check requiring a user to be in the catalog but still enforces authentication.
+* To use {product-short} without authorization policies and features relying on the software catalog, you can enable the `dangerouslyAllowSignInWithoutUserInCatalog` resolver option.
+This setting bypasses the check requiring a user to be in the catalog but still enforces authentication.
 ====
 
 [IMPORTANT]
 ====
-{product-short} uses a one-way synchronization model, where user and group data flow from your Identity Provider to the {product-short} software catalog. As a result, deleting users or groups manually through the {product-short} Web UI or REST API might be ineffective or cause inconsistencies, since those entities will be recreated during the next ingestion.
+{product-short} uses a one-way synchronization model, where user and group data flow from your Identity Provider to the {product-short} software catalog.
+As a result,
+deleting users or groups manually through the {product-short} Web UI or REST API might be ineffective or cause inconsistencies,
+since {product-short} will create those entities again during the next import.
 ====

modules/authentication/proc-authenticationg-with-the-guest-user-on-a-helm-based-installation.adoc

@@ -3,16 +3,15 @@
 [id="authenticating-with-the-guest-user-on-a-helm-based-installation_{context}"]
 = Authenticating with the Guest user on a Helm-based installation
 
-On a Helm-based installation, you can configure {product-short} to log in as a Guest user and access {product-short} features.
+For trial or non-production environments installed by using the {product} Helm chart, you can enable guest access to skip configuring authentication and authorization and explore {product-short} features.
 
 .Prerequisites
-* You {configuring-book-link}[added a custom {product-short} application configuration], and have sufficient permissions to modify it.
+* You {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it.
 * You {configuring-book-link}#using-the-helm-chart-to-run-rhdh-with-your-custom-configuration[use the {product} Helm chart to run {product-short}].
 
 .Procedure
-* To enable the guest user in your {product-short} custom configuration, {configuring-book-link}#using-the-helm-chart-to-run-rhdh-with-your-custom-configuration[configure your {product} Helm Chart] with following content:
+* Add following content to your {product} Helm Chart:
 +
-.{product} Helm Chart configuration fragment
 [source,yaml]
 ----
 upstream:

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

@@ -3,16 +3,15 @@
 [id="authenticating-with-the-guest-user-on-an-operator-based-installation_{context}"]
 = Authenticating with the Guest user on an Operator-based installation
 
-After an Operator-based installation, you can configure {product-short} to log in as a Guest user and access {product-short} features.
+For trial or non-production environments installed by using the {product} Operator, you can enable guest access to skip configuring authentication and authorization and explore {product-short} features.
 
 .Prerequisites
-* You {configuring-book-link}[added a custom {product-short} application configuration], and have sufficient permissions to modify it.
+* You {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it.
 * You {configuring-book-link}#using-the-operator-to-run-rhdh-with-your-custom-configurationn[use the {product} Operator to run {product-short}].
 
 .Procedure
-* To enable the guest user in your {product-short} custom configuration, {configuring-book-link}#provisioning-your-custom-configuration[edit your {product-short} application configuration] with following content:
+* Add the following content to the `{my-app-config-file}` file:
 +
-.`{my-app-config-file}` fragment
 [source,yaml]
 ----
 auth:

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

@@ -3,7 +3,8 @@
 [id="creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog"]
 = Creating a custom transformer to provision users from {rhbk-brand-name} ({rhbk}) to the software catalog
 
-To customize how {rhbk} users and groups are mapped to {product} entities, you can create a backend module that uses the `keycloakTransformerExtensionPoint` to provide custom user and group transformers for the Keycloak backend.
+Customize how {product} provisions users and groups to {product} software catalog entities,
+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].
@@ -14,9 +15,8 @@ To customize how {rhbk} users and groups are mapped to {product} entities, you c
 . Add your custom user and group transformers to the `keycloakTransformerExtensionPoint`.
 
 +
-The following is an example of how the backend module can be defined:
+The following is an example `plugins/__<module_name>__/src/module.ts` file defining the backend module:
 +
-.`plugins/__<module-name>__/src/module.ts`
 [source,javascript]
 ----
 import {
@@ -63,7 +63,7 @@ export const keycloakBackendModuleTransformer = createBackendModule({
 +
 [IMPORTANT]
 ====
-The module's `pluginId` must be set to `catalog` to match the `pluginId` of the `keycloak-backend`; otherwise, the module fails to initialize.
+Set the module's `pluginId` to `catalog` to match the `pluginId` of the `keycloak-backend`; otherwise, the module fails to initialize.
 ====
 
 . Install this new backend module into your {product-short} backend.
@@ -76,16 +76,17 @@ backend.add(import(backstage-plugin-catalog-backend-module-keycloak-transformer)
 .Verification
 
 * {product-short} imports the users and groups each time when started.
-Check the console logs to verify that the synchronization is completed.
+Check the console logs to verify the synchronization result.
++
+Successful synchronization example:
 +
-.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"}
 ----
 
-* After the first import is complete, navigate to the *Catalog* page and select **User** to view the list of users.
+* After the first import is complete, go to the *Catalog* page and select **User** to view the list of users.
 
 * When you select a user, you see the information imported from {rhbk}.
 

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

@@ -3,12 +3,12 @@
 [id="enabling-user-authentication-with-github"]
 = Enabling user authentication with GitHub
 
-To authenticate users with GitHub, configure the GitHub authentication provider in {product} and provision the users and groups from GitHub to the {product-short} software catalog.
+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}.
 
 .Prerequisites
-* You {configuring-book-link}[added a custom {product-short} application configuration], and have sufficient permissions to modify it.
+* You {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it.
 
-* You have sufficient permissions in GitHub to create and manage a link:https://docs.github.com/en/apps/overview[GitHub App].
+* You have enough permissions in GitHub to create and manage a link:https://docs.github.com/en/apps/overview[GitHub App].
 Alternatively, you can ask your GitHub administrator to prepare the required GitHub App.
 
 .Procedure
@@ -45,44 +45,43 @@ Select `Only on this account`.
 * **Client secret**
 
 . To add your GitHub credentials to {product-short}, add the following key/value pairs to {configuring-book-link}#provisioning-your-custom-configuration[your {product-short} secrets].
-You can use these secrets in the {product-short} configuration files by using their respective environment variable name.
+You can use these secrets in the {product-short} configuration files by using their environment variable name.
 
-`AUTHENTICATION_GITHUB_CLIENT_ID`::
+`GITHUB_CLIENT_ID`::
 Enter the saved **Client ID**.
 
-`AUTHENTICATION_GITHUB_CLIENT_SECRET`::
+`GITHUB_CLIENT_SECRET`::
 Enter the saved **Client Secret**.
 
-`AUTHENTICATION_GITHUB_HOST_DOMAIN`::
+`GITHUB_URL`::
 Enter the GitHub host domain: `github.com`.
 
-`AUTHENTICATION_GITHUB_ORGANIZATION`::
+`GITHUB_ORG`::
 Enter your GitHub organization name, such as `__<your_github_organization_name>__`.
 
 . Enable the GitHub organization provisioning plugin (`backstage-plugin-catalog-backend-module-github-org`).
-This plugin ingests GitHub users and groups to the {product-short} software catalog.
+This plugin imports GitHub users and groups to the {product-short} software catalog.
++
+`dynamic-plugins.yaml` file fragment:
 +
-.`dynamic-plugins.yaml` file fragment
 [source,yaml]
 ----
 plugins:
   - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-org'
     disabled: false
 ----
 
-. To provision GitHub users and groups to the {product-short} software catalog, add the `catalog.providers.githubOrg` section to your custom {product-short} `{my-app-config-file}` configuration file:
+. Provision GitHub users and groups to the {product-short} software catalog by adding the `catalog.providers.githubOrg` section to your custom {product-short} `{my-app-config-file}` configuration file:
 +
---
 [id=githubProviderId]
-.`{my-app-config-file}` fragment with mandatory `catalog.providers.githubOrg` fields
 [source,yaml]
 ----
 catalog:
   providers:
     githubOrg:
       id: githuborg
-      githubUrl: "${AUTHENTICATION_GITHUB_HOST_DOMAIN}"
-      orgs: [ "${AUTHENTICATION_GITHUB_ORGANIZATION}" ]
+      githubUrl: "${GITHUB_URL}"
+      orgs: [ "${GITHUB_ORG}" ]
       schedule:
         frequency:
           minutes: 30
@@ -94,13 +93,13 @@ catalog:
 
 `id`::
 Enter a stable identifier for this provider, such as `githuborg`.
-Entities from this provider are associated with this identifier, therefore you must take care not to change it over time since that might lead to orphaned entities and/or conflicts.
+Entities from this provider are associated with this identifier, therefore you must take care not to change it over time since that might lead to orphaned entities or conflicts.
 
 `githubUrl`::
-Enter the configured secret variable name: `${AUTHENTICATION_GITHUB_HOST_DOMAIN}`.
+Enter the configured secret variable name: `$\{GITHUB_URL}`.
 
 `orgs`::
-Enter the configured secret variable name: `${AUTHENTICATION_GITHUB_ORGANIZATION}`.
+Enter the configured secret variable name: `$\{GITHUB_ORG}`.
 
 `schedule.frequency`::
 Enter your schedule frequency, in the cron, ISO duration, or "human duration" format.
@@ -110,48 +109,47 @@ Enter your schedule timeout, in the ISO duration or "human duration" format.
 
 `schedule.initialDelay`::
 Enter your schedule initial delay, in the ISO duration or "human duration" format.
---
 
-. To set up the GitHub authentication provider, add the `auth.providers.github` section to the `{my-app-config-file}` file content:
+. To set up the GitHub authentication provider, add the `auth.providers.github` section to your `{my-app-config-file}` file:
 +
---
-.`{my-app-config-file}` file fragment with mandatory fields to enable authentication with GitHub
 [source,yaml]
 ----
 auth:
   environment: production
   providers:
     github:
       production:
-        clientId: ${AUTHENTICATION_GITHUB_CLIENT_ID}
-        clientSecret: ${AUTHENTICATION_GITHUB_CLIENT_SECRET}
+        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: `${AUTHENTICATION_GITHUB_CLIENT_ID}`.
+Enter the configured secret variable name: `$\{GITHUB_CLIENT_ID}`.
 
 `clientSecret`::
-Enter the configured secret variable name: `${AUTHENTICATION_GITHUB_CLIENT_SECRET}`.
+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: Consider adding the following optional fields:
-
-.`{my-app-config-file}` file fragment including optional fields to enable authentication with GitHub
++
+Optional: Consider adding optional fields.
+ifeval::["{optional-steps}" == "disable"]
+See {configuring-book-link}[{configuring-book-title}].
+endif::[]
+ifeval::["{optional-steps}" == "enable"]
 [source,yaml,subs="+quotes"]
 ----
 auth:
   environment: production
   providers:
     github:
       production:
-        clientId: ${AUTHENTICATION_GITHUB_CLIENT_ID}
-        clientSecret: ${AUTHENTICATION_GITHUB_CLIENT_SECRET}
+        clientId: ${GITHUB_CLIENT_ID}
+        clientSecret: ${GITHUB_CLIENT_SECRET}
         callbackUrl: __<your_intermediate_service_url/handler>__
         sessionDuration: { hours: 24 }
         signIn:
@@ -178,7 +176,10 @@ Enter the resolver list to override the default resolver: `usernameMatchingUserE
 +
 The authentication provider tries each sign-in resolver in order until it succeeds, and fails if none succeed.
 +
-WARNING: In production mode, only configure one resolver to ensure users are securely matched.
+[WARNING]
+====
+Make sure users are securely matched in production mode, by configuring only one resolver.
+====
 
 `resolver`::::
 Enter the sign-in resolver name.
@@ -191,13 +192,17 @@ Available resolvers:
 `dangerouslyAllowSignInWithoutUserInCatalog: true`::::
 Configure the sign-in resolver to bypass the user provisioning requirement in the {product-short} software catalog.
 +
-WARNING: Use `dangerouslyAllowSignInWithoutUserInCatalog` to explore {product-short} features, but do not use it in production.
---
+[WARNING]
+====
+Do not use `dangerouslyAllowSignInWithoutUserInCatalog` in production. Use this configuration only to explore {product-short} features.
+====
+endif::[]
 
 .Verification
-. To verify user and group provisioning, check the console logs.
+. Verify user and group provisioning by checking the console logs.
++
+Successful synchronization example:
 +
-.Successful synchronization example:
 [source,json]
 ----
 {"class":"GithubMultiOrgEntityProvider","level":"info","message":"Reading GitHub users and teams for org: rhdh-dast","plugin":"catalog","service":"backstage","target":"https://github.com","taskId":"GithubMultiOrgEntityProvider:githuborg:refresh","taskInstanceId":"801b3c6c-167f-473b-b43e-e0b4b780c384","timestamp":"2024-09-09 23:55:58"}
@@ -210,6 +215,5 @@ WARNING: Use `dangerouslyAllowSignInWithoutUserInCatalog` to explore {product-sh
 .. Log in with a GitHub account.
 
 .Additional resources
-
 * {integrating-with-github-book-link}[{integrating-with-github-book-title}]