Apply suggestions from code review

themr0c · deerskindoll · themr0c · commit d8e0ef4da86d · 2025-10-15T19:08:48.000+02:00
Co-authored-by: Jana Vrbkova &lt;jvrbkova@redhat.com&gt;
Signed-off-by: Fabrice Flore-Thébault &lt;ffloreth@redhat.com&gt;
diff --git a/modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog.adoc b/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.
diff --git a/modules/authentication/proc-enabling-user-authentication-with-github-as-an-auxiliary-authentication-provider.adoc b/modules/authentication/proc-enabling-user-authentication-with-github-as-an-auxiliary-authentication-provider.adoc
@@ -3,16 +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.
+When you are using a primary authentication provider other than GitHub to provision user and group identities to the {product} software catalog, and establish {product-short} user sessions, and this authentication provider is not configured to give access to GitHub, users might miss permissions to access GitHub templates or plugins that require GitHub authentication.
 
-.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.
+Allow users to access these features by configuring GitHub as an auxiliary authentication provider.
 
+.Prerequisites
 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.
+
 
 .Procedure
-. 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:
+. Add the `auth.providers.github` section to your `{my-app-config-file}` file:
 +
 [source,yaml]
 ----
@@ -33,8 +34,12 @@ 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.
diff --git a/modules/authentication/proc-enabling-user-authentication-with-github-with-mandatory-steps.adoc b/modules/authentication/proc-enabling-user-authentication-with-github-with-mandatory-steps.adoc
@@ -1,15 +1,14 @@
 :_mod-docs-content-type: PROCEDURE
 
-[id="enabling-user-authentication-with-github"]
+[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}.
 
-.Prerequisites
-* You {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it.
+include::snip-enabling-user-authentication-with-github-common-prerequisites.adoc[]
+
 include::snip-enabling-user-authentication-with-github-common-first-steps.adoc[]
 +
-Optional: Consider adding optional fields.
-See {configuring-book-link}[{configuring-book-title}].
+Optional: To configure optional fields, see {configuring-book-link}[{configuring-book-title}].
 
 include::snip-enabling-user-authentication-with-github-common-verification-steps.adoc[]
diff --git a/modules/authentication/proc-enabling-user-authentication-with-github-with-optional-steps.adoc b/modules/authentication/proc-enabling-user-authentication-with-github-with-optional-steps.adoc
@@ -1,12 +1,10 @@
 :_mod-docs-content-type: PROCEDURE
 
-[id="enabling-user-authentication-with-github"]
-= Enabling user authentication with GitHub
+[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}.
 
-.Prerequisites
-* You {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it.
 include::snip-enabling-user-authentication-with-github-common-prerequisites.adoc[]
 
 include::snip-enabling-user-authentication-with-github-common-first-steps.adoc[]
diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure-with-mandatory-steps.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure-with-mandatory-steps.adoc
@@ -1,16 +1,14 @@
 :_mod-docs-content-type: PROCEDURE
 
-[id="enabling-user-authentication-with-microsoft-azure"]
+[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: Add optional fields.
-See {configuring-book-link}[{configuring-book-title}].
+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: Add optional fields.
-See {configuring-book-link}[{configuring-book-title}].
+Optional: To configure optional fields, see {configuring-book-link}[{configuring-book-title}].
 
 include::snip-enabling-user-authentication-with-microsoft-azure-common-verification-steps.adoc[]
diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure-with-optional-steps.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure-with-optional-steps.adoc
@@ -1,7 +1,7 @@
 :_mod-docs-content-type: PROCEDURE
 
-[id="enabling-user-authentication-with-microsoft-azure"]
-= Enabling user authentication with {azure-brand-name}
+[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[]
 
diff --git a/modules/authentication/proc-enabling-user-authentication-with-rhbk-with-mandatory-steps.adoc b/modules/authentication/proc-enabling-user-authentication-with-rhbk-with-mandatory-steps.adoc
@@ -1,15 +1,18 @@
 :_mod-docs-content-type: PROCEDURE
-[id="enabling-user-authentication-with-rhbk"]
+[id="enabling-user-authentication-with-rhbk-with-mandatory-steps"]
 = Enabling user authentication with {rhbk-brand-name} ({rhbk})
 
+
 include::snip-enabling-user-authentication-with-rhbk-common-first-steps.adoc[]
 +
-Optional: Add optional fields.
-See {configuring-book-link}[{configuring-book-title}].
+Optional: To configure optional fields, see {configuring-book-link}[{configuring-book-title}].
 
+. {empty}
++
+--
 include::snip-enabling-user-authentication-with-rhbk-common-authentication-provider-steps.adoc[]
 +
-Optional: Add optional fields.
-See {configuring-book-link}[{configuring-book-title}].
+Optional: To configure optional fields, see {configuring-book-link}[{configuring-book-title}].
+--
 
 include::snip-enabling-user-authentication-with-rhbk-verification-steps.adoc[]
diff --git a/modules/authentication/proc-enabling-user-authentication-with-rhbk-with-optional-steps.adoc b/modules/authentication/proc-enabling-user-authentication-with-rhbk-with-optional-steps.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: PROCEDURE
-[id="enabling-user-authentication-with-rhbk"]
-= Enabling user authentication with {rhbk-brand-name} ({rhbk})
+[id="enabling-user-authentication-with-rhbk-with-optional-steps"]
+= Enabling user authentication with {rhbk-brand-name} ({rhbk}), with optional steps
 
 include::snip-enabling-user-authentication-with-rhbk-common-first-steps.adoc[]
 
diff --git a/modules/authentication/snip-enabling-user-authentication-with-github-common-first-steps.adoc b/modules/authentication/snip-enabling-user-authentication-with-github-common-first-steps.adoc
@@ -1,15 +1,8 @@
 :_mod-docs-content-type: SNIPPET
-
-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 enough permissions to change it.
-* 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
-. To allow {product-short} to authenticate with GitHub, create a GitHub App.
-Opt for a GitHub App instead of an OAuth app to use fine-grained permissions, use short-lived tokens, scale with the number of installations by avoiding rate limits, and have a more transparent integration by avoiding to request user input.
+. Allow {product-short} to authenticate with GitHub, by creating a GitHub App.
++
+Use a GitHub App instead of an OAuth app to use fine-grained permissions, use short-lived tokens, scale with the number of installations by avoiding rate limits, and have a more transparent integration by avoiding to request user input.
 
 .. link:https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app[Register a GitHub App] with the following configuration:
 
@@ -55,19 +48,17 @@ Enter the GitHub host domain: `github.com`.
 `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`).
+. Enable the GitHub catalog provider plugin in your `dynamic-plugins.yaml` file.
 This plugin imports GitHub users and groups to the {product-short} software catalog.
 +
-`dynamic-plugins.yaml` file fragment:
-+
 [source,yaml]
 ----
 plugins:
   - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-org'
     disabled: false
 ----
 
-. 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:
+. Enable provisioning GitHub users and groups to the {product-short} software catalog, by adding the GitHub catalog provider section to your `{my-app-config-file}` file:
 +
 [id=githubProviderId]
 [source,yaml]
@@ -89,7 +80,11 @@ 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 or conflicts.
+[WARNING]
+====
+Entities from this provider are associated with this identifier. 
+Therefore, do not to change it over time since that might lead to orphaned entities or conflicts.
+====
 
 `githubUrl`::
 Enter the configured secret variable name: `$\{GITHUB_URL}`.
@@ -106,7 +101,7 @@ 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 your `{my-app-config-file}` file:
+. Enable the GitHub authentication provider, by adding the GitHub authentication provider section to your `{my-app-config-file}` file:
 +
 [source,yaml]
 ----
diff --git a/modules/authentication/snip-enabling-user-authentication-with-github-common-prerequisites.adoc b/modules/authentication/snip-enabling-user-authentication-with-github-common-prerequisites.adoc
@@ -1,3 +1,9 @@
 :_mod-docs-content-type: SNIPPET
+.Prerequisites
 * 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.
++
+[TIP]
+====
+Alternatively, ask your GitHub administrator to prepare the required GitHub App.
+====
+* You have {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it.
diff --git a/modules/authentication/snip-enabling-user-authentication-with-github-optional-authentication-provider-steps.adoc b/modules/authentication/snip-enabling-user-authentication-with-github-optional-authentication-provider-steps.adoc
@@ -1,5 +1,5 @@
 :_mod-docs-content-type: SNIPPET
-Optional: Consider adding optional fields to the `auth.providers.github` section in your `{my-app-config-file}` file:
+Optional: Add optional fields to the GitHub authentication provider section in your `{my-app-config-file}` file:
 
 [source,yaml,subs="+quotes"]
 ----
@@ -30,15 +30,15 @@ Enter the user session lifespan, in `ms` library format (such as '24h', '2 days'
 
 `resolvers`:::
 After successful authentication, {product-short} resolves the user signing in to an existing user in the {product-short} catalog.
-To best match users securely for your use case, consider configuring a specific resolver.
+Configure a specific resolver to best match users securely for your use case..
 +
 Enter the resolver list to override the default resolver: `usernameMatchingUserEntityName`.
 +
-The authentication provider tries each sign-in resolver in order until it succeeds, and fails if none succeed.
+The authentication provider tries each sign-in resolver in order until it succeeds. If none of the attempts succeed, the sign-in fails.
 +
 [WARNING]
 ====
-Make sure users are securely matched in production mode, by configuring only one resolver.
+In production mode, configure only one resolver to make sure users are securely matched.
 ====
 
 `resolver`::::
@@ -49,11 +49,10 @@ Available resolvers:
 * `preferredUsernameMatchingUserEntityName`
 * `emailMatchingUserEntityProfileEmail`
 
-`dangerouslyAllowSignInWithoutUserInCatalog: true`::::
-Configure the sign-in resolver to bypass the user provisioning requirement in the {product-short} software catalog.
+`dangerouslyAllowSignInWithoutUserInCatalog`::::
+Enter `true` to configure the sign-in resolver to bypass the user provisioning requirement in the {product-short} software catalog.
 +
 [WARNING]
 ====
-Do not use `dangerouslyAllowSignInWithoutUserInCatalog` in production.
-Use this configuration only to explore {product-short} features.
+In production more, do not enable `dangerouslyAllowSignInWithoutUserInCatalog` in production.
 ====
diff --git a/modules/authentication/snip-enabling-user-authentication-with-microsoft-azure-common-authentication-provider-steps.adoc b/modules/authentication/snip-enabling-user-authentication-with-microsoft-azure-common-authentication-provider-steps.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: SNIPPET
 
-To set up the {azure-short} authentication provider, add the `auth.providers.microsoft` section to your `{my-app-config-file}` file content:
+Enable {azure-short} authentication, by adding the Microsoft authentication provider to your `{my-app-config-file}` file content:
 
 [source,yaml,subs="+quotes,+attributes"]
 ----
diff --git a/modules/authentication/snip-enabling-user-authentication-with-microsoft-azure-common-first-steps.adoc b/modules/authentication/snip-enabling-user-authentication-with-microsoft-azure-common-first-steps.adoc
@@ -4,7 +4,11 @@ Authenticate users with {azure-brand-name} by provisioning the users and groups
 
 .Prerequisites
 * You have the permission to register an application in {azure-short}.
-Alternatively, you can ask your {azure-short} administrator to prepare the required {azure-short} application.
++
+[TIP]
+====
+Alternatively, ask your {azure-short} administrator to prepare the required {azure-short} application.
+====
 
 * You {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it.
 
@@ -18,11 +22,11 @@ The server for retrieving organization data, including user and group data, to i
 
 .Procedure
 :my-product-app-name-in-azure: <Authenticating with {product-short}>
-. To allow {product-short} to authenticate with {azure-short}, 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[Register an app by using the {azure-short} portal].
+. Register your {product-short} app in {azure-short}, 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[by using the {azure-short} portal].
 
 .. Sign in to the link:https://entra.microsoft.com/[Microsoft Entra admin center].
 
-.. Optional: If you have access to many tenants, use the *Settings* icon in the top menu to switch to the tenant in which you want to register the application from the *Directories + subscriptions* menu.
+.. Optional: If you have access to multiple tenants, use the *Settings* icon in the top menu to switch to the tenant in which you want to register the application from the *Directories + subscriptions* menu.
 
 .. Browse to *Applications > App registrations*, and create a **New registration** with the configuration:
 
@@ -67,7 +71,7 @@ Optional: Enter optional custom scopes for the Microsoft Graph API that you defi
 - **Application (client) ID**
 - **Application (client) Secret ID**
 
-. To add your {azure-short} credentials to {product-short}, add the following key/value pairs to {configuring-book-link}#provisioning-your-custom-configuration[your {product-short} secrets]:
+. Add your {azure-short} credentials to {product-short}, by adding the following key/value pairs to {configuring-book-link}#provisioning-your-custom-configuration[your {product-short} secrets]:
 
 `AUTHENTICATION_AZURE_TENANT_ID`::
 Enter your saved *Directory (tenant) ID*.
@@ -78,7 +82,7 @@ Enter your saved *Application (client) ID*.
 `AUTHENTICATION_AZURE_CLIENT_SECRET`::
 Enter your saved *Application (client) secret*.
 
-. Enable the Microsoft Graph organization provisioning plugin (`backstage-plugin-catalog-backend-module-msgraph-dynamic`) in your `dynamic-plugins.yaml`
+. Enable the Microsoft Graph catalog provider plugin in your `dynamic-plugins.yaml`
 file.
 This plugin imports {azure-short} users and groups to the {product-short} software catalog.
 +
@@ -89,7 +93,7 @@ plugins:
     disabled: false
 ----
 
-. To provision {azure-short} users and groups to the {product-short} software catalog, add the `catalog.providers.microsoftGraphOrg` section to your custom {product-short} `{my-app-config-file}` configuration file:
+. Enable provisioning {azure-short} users and groups to the {product-short} software catalog, by adding the Microsoft Graph catalog provider section in your `{my-app-config-file}` file:
 +
 [id=microsoftGraphOrgProviderId]
 [source,yaml]
diff --git a/modules/authentication/snip-enabling-user-authentication-with-microsoft-azure-optional-authentication-provider-steps.adoc b/modules/authentication/snip-enabling-user-authentication-with-microsoft-azure-optional-authentication-provider-steps.adoc
diff --git a/modules/authentication/snip-enabling-user-authentication-with-microsoft-azure-optional-catalog-provider-steps.adoc b/modules/authentication/snip-enabling-user-authentication-with-microsoft-azure-optional-catalog-provider-steps.adoc
diff --git a/modules/authentication/snip-enabling-user-authentication-with-rhbk-common-authentication-provider-steps.adoc b/modules/authentication/snip-enabling-user-authentication-with-rhbk-common-authentication-provider-steps.adoc
diff --git a/modules/authentication/snip-enabling-user-authentication-with-rhbk-common-first-steps.adoc b/modules/authentication/snip-enabling-user-authentication-with-rhbk-common-first-steps.adoc
diff --git a/modules/authentication/snip-enabling-user-authentication-with-rhbk-optional-authentication-provider-steps.adoc b/modules/authentication/snip-enabling-user-authentication-with-rhbk-optional-authentication-provider-steps.adoc
diff --git a/modules/authentication/snip-enabling-user-authentication-with-rhbk-optional-catalog-provider-steps.adoc b/modules/authentication/snip-enabling-user-authentication-with-rhbk-optional-catalog-provider-steps.adoc
