RHIDP-6735 - Added high-level overview of auth and user provisioning (#1186)

* RHIDP-6735 - Added high-level overview of auth and user provisioning

Signed-off-by: Fabrice Flore-Thébault <[email protected]>

* Complete rewrite with the assistance of NotebookLM.

Signed-off-by: Fabrice Flore-Thébault <[email protected]>

* Update assemblies/assembly-enabling-authentication.adoc

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

Co-authored-by: Jessica He <[email protected]>

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

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

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

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

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

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

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

Co-authored-by: Jessica He <[email protected]>

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

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

Co-authored-by: Jessica He <[email protected]>

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

Co-authored-by: Jessica He <[email protected]>

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

Co-authored-by: Jessica He <[email protected]>

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

Co-authored-by: Priyanka Abel <[email protected]>

* Apply suggestions from code review

Co-authored-by: Priyanka Abel <[email protected]>

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

Co-authored-by: Judith Magak <[email protected]>

---------

Signed-off-by: Fabrice Flore-Thébault <[email protected]>
Co-authored-by: Jessica He <[email protected]>
Co-authored-by: Priyanka Abel <[email protected]>
Co-authored-by: Judith Magak <[email protected]>

Author: 4 people

assemblies/assembly-enabling-authentication.adoc

@@ -1,53 +1,10 @@
 [id='enabling-authentication']
 = Enabling authentication in {product}
 
-Depending on your organization's security policies, you might require to identify and authorize users before giving them access to resources, such as {product}.
 
-In {product-short}, authentication and authorization are two separate processes:
 
-. Authentication defines the user identity, and passes on this information to {product-short}.
-Read the following chapters to configure authentication in {product-short}.
-
-. Authorization defines what the authenticated identity can access or do in {product-short}.
-See link:{authorization-book-url}[{authorization-book-title}].
-
-[TIP]
-.Not recommended for production
-====
-To explore {product-short} features, you can enable the guest user to skip configuring authentication and authorization, log in as the guest user, and access all the features.
-====
-
-The authentication system in {product-short} is handled by external authentication providers.
-
-{product-short} supports following authentication providers:
-
-* Red Hat Single-Sign On (RHSSO)
-* GitHub
-* Microsoft Azure
-
-To identify users in {product-short}, configure:
-
-* One (and only one) authentication provider for sign-in and identification.
-* Optionally, additional authentication providers for identification, to add more information to the user identity, or enable access to additional external resources.
-
-For each authentication provider, set up the shared secret that the authentication provider and {product-short} require to communicate, first in the authentication provider, then in {product-short}.
-
-{product-short} stores user identity information in the {product-short} software catalog.
-
-[TIP]
-.Not recommended for production
-====
-To explore the authentication system and use {product-short} without authorization policies, you can bypass the {product-short} software catalog and start using {product-short} without provisioning the {product-short} software catalog.
-====
-
-To get, store, and update additional user information, such as group or team ownership, with the intention to use this data to define authorization policies, provision users and groups in the {product-short} software catalog.
-
-[IMPORTANT]
-====
-{product-short} uses a one-way synchronization system to provision users and groups from your authentication system to the {product-short} software catalog.
-Therefore, deleting users and groups by using {product-short} Web UI or REST API might have unintended consequences.
-====
 
+include::modules/authentication/con-understanding-authentication-and-user-provisioning.adoc[leveloffset=+1]
 
 
 include::assembly-authenticating-with-the-guest-user.adoc[leveloffset=+1]

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

@@ -0,0 +1,37 @@
+= 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.
+Understanding this process is essential for successfully link:{configuring-book-url}[configuring your {product-short} instance], link:{authorization-book-url}[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.
+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.
+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 xref:assembly-authenticating-with-rhbk[{rhbk-brand-name} ({rhbk})], xref:authenticating-with-github[GitHub], or xref:assembly-authenticating-with-microsoft-azure[{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}.
+
+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.
+* 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.
+
+[TIP]
+.Not recommended for production
+====
+To explore {product-short} features, you can:
+
+* To use {product-short} without external IdP, xref:authenticating-with-the-guest-user_{context}[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.
+====
+
+[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.
+====