Merge branch 'main' into RHIDP-7849

Author: themr0c

.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]
 
 

assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc

@@ -15,17 +15,24 @@ include::assembly-enabling-configuring-jfrog.adoc[leveloffset=+1]
 // Keycloak - modularized
 include::assembly-enabling-configuring-keycloak.adoc[leveloffset=+1]
 
+
 // Nexus - modularized
 include::assembly-enabling-configuring-nexus.adoc[leveloffset=+1]
 
 // Tekton - modularized
 include::../../modules/dynamic-plugins/proc-enabling-the-tekton-plugin.adoc[leveloffset=+1]
 
-// Topology - no-change
-include::assembly-install-topology-plugin.adoc[leveloffset=+1]
+// Topology
+include::../dynamic-plugins/assembly-install-topology-plugin.adoc[leveloffset=+1]
+
+// Bulk Importing
+include::../assembly-bulk-importing-from-github.adoc[leveloffset=+1]
 
+// ServiceNow
 include::../assembly-using-servicenow.adoc[leveloffset=+1]
 
+// Kubernetes Custom Actions
 include::../assembly-using-kubernetes-custom-actions.adoc[leveloffset=+1]
 
-include::../../modules/dynamic-plugins/proc-overriding-core-backend-services.adoc[leveloffset=+1]
+// Overriding Core Backend Service Configuration
+include::../modules/dynamic-plugins/proc-overriding-core-backend-services.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}.