[RHDHBUGS-2411]: Clarify auth/provisioning independence and OIDC key alignment (#2034)

themr0c · claude · web-flow · commit 5d3f572c68a3 · 2026-04-15T18:46:26.000+02:00
* [RHDHBUGS-2411]: Clarify auth/provisioning independence and OIDC key alignment - Restructure concept module: provisioning first, authentication second, with explicit independence statements for both mechanisms - Add IMPORTANT notes to all 4 provider snippets warning that the environment key must match the auth.environment value - Clarify LDAP provisioning works with any auth provider, not just Keycloak - Fix copy-paste error in LDAP procedure (GitHub -> LDAP) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Apply suggestion from @themr0c * Apply suggestion from @themr0c * Apply suggestion from @themr0c * Apply suggestion from @themr0c * Apply suggestions from code review Co-authored-by: Fabrice Flore-Thébault <ffloreth@redhat.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
diff --git a/modules/shared/con-understand-authentication-and-user-provisioning.adoc b/modules/shared/con-understand-authentication-and-user-provisioning.adoc
@@ -3,21 +3,40 @@
 = Understand authentication and user provisioning
 
 [role="_abstract"]
-The authentication process covers creating user and group entities in the software catalog, user sign-in, and how authentication and catalog plugins enable each step.
+User provisioning and authentication are two independent mechanisms in {product}.
+You can configure them separately depending on your requirements.
 
-To fully enable catalog features, provision user and group data from the Identity Provider to the {product-short} software catalog.
+== User provisioning
+
+To fully enable catalog features, provision user and group data from an Identity Provider (IdP) to the {product-short} software catalog.
 Catalog provider plugins handle this task asynchronously.
-These plugins query the Identity Provider (IdP) for relevant user and group information, and create or update corresponding entities in the {product-short} catalog.
+These plugins query the IdP for relevant user and group information, and create or update corresponding entities in the {product-short} catalog.
 Scheduled provisioning ensures that the catalog accurately reflects the users and groups in your organization.
 
-When a user attempts to access {product-short}, {product-short} redirects them to a configured authentication provider, such as {rhbk-brand-name} ({rhbk}), GitHub, or {azure-brand-name}.
-This external IdP is responsible for authenticating the user.
+You can provision users and groups from any supported source, including {rhbk-brand-name} ({rhbk}), GitHub, GitLab, {azure-brand-name}, or LDAP.
+LDAP provisioning works independently of your authentication provider.
+Following associations are supported:
 
-On successful authentication, the {product-short} authentication plugin, configured in your `{my-app-config-file}` file, processes the response from the IdP, resolves the identity in the {product-short} software catalog, and establishes a user session within {product-short}.
+|===
+|User provisioning |Authentication
+
+|{rhbk}
+|{rhbk}
+
+|LDAP
+|{rhbk}
+
+|GitHub
+|GitHub
+
+|{azure-brand-name}
+|{azure-brand-name}
+|===
 
-Configuring authentication and user provisioning is critical for several reasons.
+For example, you can authenticate users with {rhbk} while provisioning user and group data from your LDAP directory.
+
+Configuring user provisioning is critical for several reasons.
 
-* 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.
 +
@@ -43,3 +62,15 @@ 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.
 ====
+
+== Authentication
+
+When a user attempts to access {product-short}, {product-short} redirects them to a configured authentication provider, such as {rhbk-brand-name} ({rhbk}), GitHub, GitLab, or {azure-brand-name}.
+This external IdP is responsible for authenticating the user.
+
+On successful authentication, the {product-short} authentication plugin, configured in your `{my-app-config-file}` file, processes the response from the IdP, resolves the identity in the {product-short} software catalog, and establishes a user session within {product-short}.
+
+Authentication works independently of user provisioning.
+By default you cannot authenticate users without provisioning them to the software catalog.
+You can override this behavior to authenticate users without provisioning them to the software catalog, by using the `dangerouslyAllowSignInWithoutUserInCatalog` parameter.
+However, provisioning is a prerequisite for full catalog functionality, such as entity ownership and group-based access controls.
diff --git a/modules/shared/proc-enable-user-provisioning-with-ldap.adoc b/modules/shared/proc-enable-user-provisioning-with-ldap.adoc
@@ -4,10 +4,17 @@
 = Enable user provisioning with LDAP
 
 [role="_abstract"]
-When {rhbk-brand-name} ({rhbk}) depends on Lightweight Directory Access Protocol (LDAP) to resolve user and group identities, you can opt to provision users and groups from LDAP directly to the {product} software catalog, rather than using the {rhbk} provisioning mechanism.
+You can provision users and groups from a Lightweight Directory Access Protocol (LDAP) directory directly to the {product} software catalog.
+
+[NOTE]
+====
+LDAP provisioning works with any authentication provider.
+You do not need {rhbk-brand-name} ({rhbk}) to use LDAP for user and group provisioning.
+For example, you can authenticate users with GitHub or {azure-brand-name} while provisioning user and group data from your LDAP directory.
+====
 
 .Prerequisites
-* You have configured xref:enable-authentication-with-rhbk_{parent-context}[authentication with {rhbk-brand-name} ({rhbk})].
+* You have configured authentication with a supported provider, such as xref:enable-authentication-with-rhbk_{parent-context}[{rhbk-brand-name} ({rhbk})], xref:enable-authentication-with-github_{parent-context}[GitHub], xref:enable-authentication-with-microsoft-azure_{parent-context}[{azure-brand-name}], or xref:enable-authentication-with-gitlab_{parent-context}[GitLab].
 
 * You have collected the required LDAP credentials:
 
@@ -58,7 +65,7 @@ plugins:
     disabled: false
 ----
 
-. Enable provisioning GitHub users and groups to the {product-short} software catalog, by adding the LDAP catalog provider section to your `{my-app-config-file}` file:
+. Enable provisioning LDAP users and groups to the {product-short} software catalog, by adding the LDAP catalog provider section to your `{my-app-config-file}` file:
 
 .. Optional: Remove other catalog providers, by removing the other catalog providers section.
 
diff --git a/modules/shared/snip-enable-user-authentication-with-gitlab-common-first-steps.adoc b/modules/shared/snip-enable-user-authentication-with-gitlab-common-first-steps.adoc
@@ -118,6 +118,11 @@ auth:
         callbackUrl: {my-product-url}/api/auth/gitlab/handler/frame
 ----
 +
+[IMPORTANT]
+====
+The environment key under the provider (for example, `production`) must match the value of the `environment` field under `auth`.
+{product-short} cannot find a complete configuration set in mismatched environments.
+====
 
 `audience`::
 Enter your GitLab instance address: `pass:c,a,q[https://${GITLAB_HOST}]`
diff --git a/modules/shared/snip-enabling-user-authentication-with-github-common-first-steps.adoc b/modules/shared/snip-enabling-user-authentication-with-github-common-first-steps.adoc
@@ -117,6 +117,12 @@ auth:
         clientSecret: ${GITHUB_CLIENT_SECRET}
 signInPage: github
 ----
++
+[IMPORTANT]
+====
+The environment key under the provider (for example, `production`) must match the value of the `environment` field under `auth`.
+{product-short} cannot find a complete configuration set in mismatched environments.
+====
 
 `environment`::
 Enter `production` to disable the Guest login option in the {product-short} login page.
diff --git a/modules/shared/snip-enabling-user-authentication-with-microsoft-azure-common-authentication-provider-steps.adoc b/modules/shared/snip-enabling-user-authentication-with-microsoft-azure-common-authentication-provider-steps.adoc
@@ -14,6 +14,12 @@ auth:
         tenantId: ${MICROSOFT_TENANT_ID}
 signInPage: microsoft
 ----
++
+[IMPORTANT]
+====
+The environment key under the provider (for example, `production`) must match the value of the `environment` field under `auth`.
+{product-short} cannot find a complete configuration set in mismatched environments.
+====
 
 `environment`::
 Enter `production` to disable the **Guest** login option in the {product-short} login page.
diff --git a/modules/shared/snip-enabling-user-authentication-with-rhbk-common-authentication-provider-steps.adoc b/modules/shared/snip-enabling-user-authentication-with-rhbk-common-authentication-provider-steps.adoc
@@ -15,6 +15,12 @@ auth:
         prompt: auto
 signInPage: oidc
 ----
++
+[IMPORTANT]
+====
+The environment key under the provider (for example, `production`) must match the value of the `environment` field under `auth`.
+{product-short} cannot find a complete configuration set in mismatched environments.
+====
 
 `environment: production`::
 Mark the environment as `production` to hide the Guest login in the {product-short} home page.
