Create assemblies for ext auth (#2938)

The assemblies are based on user stories for scenarios related to external authentication.

* Create an assembly for ext auth with LDAP

* Create an assembly for ext auth with FreeIPA

* Create an assembly for ext auth with cross-forest AD trust

* Create an assembly for ext auth with keycloak-general

* Create an assembly for ext auth with keycloak-totp

* Create an assembly for ext auth with ad

* Create an assembly for keycloak-cac-cards

* Create an assembly for managing IdM system lc

* Remove obsolete list of ext auth scenarios

It's obsolete now because it's included in the guide's ToC and the
assembly intros.

* Peer review feedback and cleanup

Co-authored-by: Maximilian Kolb <[email protected]>
Co-authored-by: Ewoud Kohl van Wijngaarden <[email protected]>

guides/common/assembly_configuring-a-freeipa-server-as-an-external-identity-provider-for-project.adoc

@@ -0,0 +1,7 @@
+include::modules/con_configuring-a-freeipa-server-as-an-external-identity-provider-for-project.adoc[]
+
+include::modules/con_using-freeipa.adoc[leveloffset=+1]
+
+include::modules/proc_configuring-freeipa-authentication-on-server.adoc[leveloffset=+1]
+
+include::modules/proc_configuring-host-based-authentication-control.adoc[leveloffset=+1]

guides/common/assembly_configuring-active-directory-as-an-external-identity-provider-for-project.adoc

@@ -0,0 +1,11 @@
+include::modules/con_configuring-active-directory-as-an-external-identity-provider-for-project.adoc[]
+
+include::modules/con_gss-proxy.adoc[leveloffset=+1]
+
+include::modules/proc_enrolling-server-with-the-ad-server.adoc[leveloffset=+1]
+
+include::modules/proc_configuring-direct-ad-integration-with-gss-proxy.adoc[leveloffset=+1]
+
+include::modules/con_kerberos-configuration-in-web-browsers.adoc[leveloffset=+1]
+
+include::modules/proc_configuring-the-freeipa-server-to-use-cross-forest-trust.adoc[leveloffset=+1]

guides/common/assembly_configuring-ad-integrated-with-freeipa-through-cross-forest-kerberos-trust-as-an-external-identity-provider-for-project.adoc

@@ -0,0 +1,3 @@
+include::modules/con_configuring-ad-integrated-with-freeipa-through-cross-forest-kerberos-trust-as-an-external-identity-provider-for-project.adoc[]
+
+include::modules/con_active-directory-with-cross-forest-trust.adoc[leveloffset=+1]

guides/common/assembly_configuring-an-ldap-server-as-an-external-identity-provider-for-project.adoc

@@ -0,0 +1,13 @@
+include::modules/con_configuring-an-ldap-server-as-an-external-identity-provider-for-project.adoc[]
+
+include::modules/con_using-ldap.adoc[leveloffset=+1]
+
+include::modules/proc_configuring-tls-for-secure-ldap.adoc[leveloffset=+1]
+
+include::modules/proc_configuring-project-to-use-ldap.adoc[leveloffset=+1]
+
+include::modules/ref_description-of-ldap-settings.adoc[leveloffset=+1]
+
+include::modules/ref_example-settings-for-ldap-connections.adoc[leveloffset=+1]
+
+include::modules/ref_examples-ldap-filters.adoc[leveloffset=+1]

guides/common/assembly_configuring-external-authentication.adoc

@@ -1,128 +1,41 @@
 include::modules/con_configuring-external-authentication.adoc[]
 
-include::modules/con_using-ldap.adoc[leveloffset=+1]
+include::assembly_configuring-an-ldap-server-as-an-external-identity-provider-for-project.adoc[leveloffset=+1]
 
-include::modules/proc_configuring-tls-for-secure-ldap.adoc[leveloffset=+2]
+include::assembly_configuring-a-freeipa-server-as-an-external-identity-provider-for-project.adoc[leveloffset=+1]
 
-include::modules/proc_configuring-project-to-use-ldap.adoc[leveloffset=+2]
-
-include::modules/ref_description-of-ldap-settings.adoc[leveloffset=+2]
-
-include::modules/ref_example-settings-for-ldap-connections.adoc[leveloffset=+2]
-
-include::modules/ref_examples-ldap-filters.adoc[leveloffset=+2]
-
-include::modules/con_using-freeipa.adoc[leveloffset=+1]
-
-include::modules/proc_configuring-freeipa-authentication-on-server.adoc[leveloffset=+2]
-
-include::modules/proc_configuring-host-based-authentication-control.adoc[leveloffset=+2]
-
-include::modules/con_using-active-directory.adoc[leveloffset=+1]
-
-include::modules/con_gss-proxy.adoc[leveloffset=+2]
-
-include::modules/proc_enrolling-server-with-the-ad-server.adoc[leveloffset=+2]
-
-include::modules/proc_configuring-direct-ad-integration-with-gss-proxy.adoc[leveloffset=+2]
-
-include::modules/con_kerberos-configuration-in-web-browsers.adoc[leveloffset=+2]
-
-include::modules/con_active-directory-with-cross-forest-trust.adoc[leveloffset=+2]
-
-include::modules/proc_configuring-the-freeipa-server-to-use-cross-forest-trust.adoc[leveloffset=+2]
-
-include::modules/proc_configuring-external-user-groups.adoc[leveloffset=+1]
-
-include::modules/proc_refreshing-external-user-groups-for-ldap.adoc[leveloffset=+1]
-
-include::modules/con_refreshing-external-user-groups-for-freeipa-or-ad.adoc[leveloffset=+1]
-
-include::modules/proc_configuring-the-hammer-cli-to-use-freeipa-user-authentication.adoc[leveloffset=+1]
-
-include::modules/con_external-authentication-for-provisioned-hosts.adoc[leveloffset=+1]
+include::assembly_configuring-ad-integrated-with-freeipa-through-cross-forest-kerberos-trust-as-an-external-identity-provider-for-project.adoc[leveloffset=+1]
 
 ifdef::context[:parent-context: {context}]
 :context: keycloak-general
-
-include::modules/con_configuring-project-with-keycloak-authentication.adoc[leveloffset=+1]
-
-include::modules/con_prerequisites-for-configuring-project-with-keycloak-authentication.adoc[leveloffset=+2]
-
-include::modules/proc_registering-project-as-a-keycloak-client.adoc[leveloffset=+2]
-
-include::modules/proc_configuring-the-project-client-in-keycloak.adoc[leveloffset=+2]
-
-include::modules/con_project-settings-for-keycloak-authentication.adoc[leveloffset=+2]
-
-include::modules/proc_configuring-project-settings-for-keycloak-authentication-using-the-web-ui.adoc[leveloffset=+3]
-
-include::modules/proc_configuring-project-settings-for-keycloak-authentication-using-the-cli.adoc[leveloffset=+3]
-
-include::modules/proc_logging-in-to-the-project-web-ui-using-keycloak.adoc[leveloffset=+2]
-
-include::modules/proc_logging-in-to-the-project-CLI-using-keycloak.adoc[leveloffset=+2]
-
-include::modules/proc_configuring-group-mapping-for-keycloak-authentication.adoc[leveloffset=+2]
+include::assembly_configuring-keycloak-authentication-for-project.adoc[leveloffset=+1]
 ifdef::parent-context[:context: {parent-context}]
 ifndef::parent-context[:!context:]
 
 ifdef::context[:parent-context: {context}]
 :context: keycloak-totp
-
-include::modules/con_configuring-keycloak-authentication-with-totp.adoc[leveloffset=+1]
-
-include::modules/con_prerequisites-for-configuring-project-with-keycloak-authentication.adoc[leveloffset=+2]
-
-include::modules/proc_registering-project-as-a-keycloak-client.adoc[leveloffset=+2]
-
-include::modules/proc_configuring-the-project-client-in-keycloak.adoc[leveloffset=+2]
-
-include::modules/con_project-settings-for-keycloak-authentication.adoc[leveloffset=+2]
-
-include::modules/proc_configuring-project-settings-for-keycloak-authentication-using-the-web-ui.adoc[leveloffset=+3]
-
-include::modules/proc_configuring-project-settings-for-keycloak-authentication-using-the-cli.adoc[leveloffset=+3]
-
-include::modules/proc_configuring-project-with-keycloak-for-totp-authentication.adoc[leveloffset=+2]
-
-include::modules/proc_logging-in-to-the-project-web-ui-using-keycloak-totp-authentication.adoc[leveloffset=+2]
-
-include::modules/proc_logging-in-to-the-project-CLI-using-keycloak.adoc[leveloffset=+2]
-
-include::modules/proc_configuring-group-mapping-for-keycloak-authentication.adoc[leveloffset=+2]
+include::assembly_configuring-keycloak-authentication-with-totp-cards-for-project.adoc[leveloffset=+1]
 ifdef::parent-context[:context: {parent-context}]
 ifndef::parent-context[:!context:]
 
 ifndef::satellite,orcharhino[]
 ifdef::context[:parent-context: {context}]
 :context: keycloak-cac-cards
+include::assembly_configuring-keycloak-authentication-with-piv-cards-for-project.adoc[leveloffset=+1]
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]
+endif::[]
 
-include::modules/con_configuring-keycloak-authentication-with-piv-cards.adoc[leveloffset=+1]
-
-include::modules/con_prerequisites-for-configuring-project-with-keycloak-authentication.adoc[leveloffset=+2]
-
-include::modules/proc_registering-project-as-a-keycloak-client.adoc[leveloffset=+2]
-
-include::modules/proc_configuring-the-project-client-in-keycloak.adoc[leveloffset=+2]
-
-include::modules/con_project-settings-for-keycloak-authentication.adoc[leveloffset=+2]
-
-include::modules/proc_configuring-project-settings-for-keycloak-authentication-using-the-web-ui.adoc[leveloffset=+3]
-
-include::modules/proc_configuring-project-settings-for-keycloak-authentication-using-the-cli.adoc[leveloffset=+3]
+include::assembly_configuring-active-directory-as-an-external-identity-provider-for-project.adoc[leveloffset=+1]
 
-include::modules/proc_configuring-keycloak-settings-for-authentication-with-cac-cards.adoc[leveloffset=+2]
+include::assembly_configuring-project-to-manage-the-lifecycle-of-a-host-registered-to-a-freeipa-realm.adoc[leveloffset=+1]
 
-include::modules/proc_configuring-users-os-for-keycloak-authentication-with-cac-cards.adoc[leveloffset=+2]
+include::modules/proc_configuring-external-user-groups.adoc[leveloffset=+1]
 
-include::modules/proc_logging-in-to-the-project-web-ui-using-keycloak-cac-cards.adoc[leveloffset=+2]
+include::modules/proc_refreshing-external-user-groups-for-ldap.adoc[leveloffset=+1]
 
-include::modules/proc_logging-in-to-the-project-CLI-using-keycloak.adoc[leveloffset=+2]
+include::modules/con_refreshing-external-user-groups-for-freeipa-or-ad.adoc[leveloffset=+1]
 
-include::modules/proc_configuring-group-mapping-for-keycloak-authentication.adoc[leveloffset=+2]
-ifdef::parent-context[:context: {parent-context}]
-ifndef::parent-context[:!context:]
-endif::[]
+include::modules/proc_configuring-the-hammer-cli-to-use-freeipa-user-authentication.adoc[leveloffset=+1]
 
 include::modules/proc_disabling-keycloak-authentication.adoc[leveloffset=+1]

guides/common/assembly_configuring-keycloak-authentication-for-project.adoc

@@ -0,0 +1,17 @@
+include::modules/con_configuring-keycloak-authentication-for-project.adoc[]
+
+include::modules/con_prerequisites-for-configuring-project-with-keycloak-authentication.adoc[leveloffset=+1]
+
+include::modules/proc_registering-project-as-a-keycloak-client.adoc[leveloffset=+1]
+
+include::modules/proc_configuring-the-project-client-in-keycloak.adoc[leveloffset=+1]
+
+include::modules/proc_configuring-project-settings-for-keycloak-authentication-using-the-web-ui.adoc[leveloffset=+1]
+
+include::modules/proc_configuring-project-settings-for-keycloak-authentication-using-the-cli.adoc[leveloffset=+1]
+
+include::modules/proc_logging-in-to-the-project-web-ui-using-keycloak.adoc[leveloffset=+1]
+
+include::modules/proc_logging-in-to-the-project-CLI-using-keycloak.adoc[leveloffset=+1]
+
+include::modules/proc_configuring-group-mapping-for-keycloak-authentication.adoc[leveloffset=+1]

guides/common/assembly_configuring-keycloak-authentication-with-piv-cards-for-project.adoc

@@ -0,0 +1,21 @@
+include::modules/con_configuring-keycloak-authentication-with-piv-cards-for-project.adoc[]
+
+include::modules/con_prerequisites-for-configuring-project-with-keycloak-authentication.adoc[leveloffset=+1]
+
+include::modules/proc_registering-project-as-a-keycloak-client.adoc[leveloffset=+1]
+
+include::modules/proc_configuring-the-project-client-in-keycloak.adoc[leveloffset=+1]
+
+include::modules/proc_configuring-project-settings-for-keycloak-authentication-using-the-web-ui.adoc[leveloffset=+1]
+
+include::modules/proc_configuring-project-settings-for-keycloak-authentication-using-the-cli.adoc[leveloffset=+1]
+
+include::modules/proc_configuring-keycloak-settings-for-authentication-with-cac-cards.adoc[leveloffset=+1]
+
+include::modules/proc_configuring-users-os-for-keycloak-authentication-with-cac-cards.adoc[leveloffset=+1]
+
+include::modules/proc_logging-in-to-the-project-web-ui-using-keycloak-cac-cards.adoc[leveloffset=+1]
+
+include::modules/proc_logging-in-to-the-project-CLI-using-keycloak.adoc[leveloffset=+1]
+
+include::modules/proc_configuring-group-mapping-for-keycloak-authentication.adoc[leveloffset=+1]

guides/common/assembly_configuring-keycloak-authentication-with-totp-cards-for-project.adoc

@@ -0,0 +1,19 @@
+include::modules/con_configuring-keycloak-authentication-with-totp-cards-for-project.adoc[]
+
+include::modules/con_prerequisites-for-configuring-project-with-keycloak-authentication.adoc[leveloffset=+1]
+
+include::modules/proc_registering-project-as-a-keycloak-client.adoc[leveloffset=+1]
+
+include::modules/proc_configuring-the-project-client-in-keycloak.adoc[leveloffset=+1]
+
+include::modules/proc_configuring-project-settings-for-keycloak-authentication-using-the-web-ui.adoc[leveloffset=+1]
+
+include::modules/proc_configuring-project-settings-for-keycloak-authentication-using-the-cli.adoc[leveloffset=+1]
+
+include::modules/proc_configuring-project-with-keycloak-for-totp-authentication.adoc[leveloffset=+1]
+
+include::modules/proc_logging-in-to-the-project-web-ui-using-keycloak-totp-authentication.adoc[leveloffset=+1]
+
+include::modules/proc_logging-in-to-the-project-CLI-using-keycloak.adoc[leveloffset=+1]
+
+include::modules/proc_configuring-group-mapping-for-keycloak-authentication.adoc[leveloffset=+1]

guides/common/assembly_configuring-project-to-manage-the-lifecycle-of-a-host-registered-to-a-freeipa-realm.adoc

@@ -0,0 +1 @@
+include::modules/con_configuring-project-to-manage-the-lifecycle-of-a-host-registered-to-a-freeipa-realm.adoc[]

guides/common/modules/con_active-directory-with-cross-forest-trust.adoc

@@ -1,12 +1,9 @@
 [id="Active_Directory_with_Cross_Forest_Trust_{context}"]
 = Active Directory with cross-forest trust
 
-Kerberos can create `cross-forest trust` that defines a relationship between two otherwise separate domain forests.
-A domain forest is a hierarchical structure of domains; both AD and {FreeIPA} constitute a forest.
-With a trust relationship enabled between AD and {FreeIPA}, users of AD can access Linux hosts and services using a single set of credentials.
+From the {Project} point of view, the configuration process is the same as integration with {FreeIPA} server without cross-forest trust configured.
+{ProjectServer} has to be enrolled in the IdM domain and integrated as described in xref:Using_FreeIPA_{context}[].
+
 ifdef::satellite[]
 For more information on cross-forest trusts, see https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/planning_identity_management/planning-a-cross-forest-trust-between-idm-and-ad_planning-identity-management[Planning a cross-forest trust between IdM and AD] in _{RHEL} 9 guide_ or https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/planning_identity_management/planning-a-cross-forest-trust-between-idm-and-ad_planning-identity-management[Planning a cross-forest trust between IdM and AD] in _{RHEL} 8 guide_.
 endif::[]
-
-From the {Project} point of view, the configuration process is the same as integration with {FreeIPA} server without cross-forest trust configured.
-{ProjectServer} has to be enrolled in the IdM domain and integrated as described in xref:Using_FreeIPA_{context}[].

guides/common/modules/con_configuring-a-freeipa-server-as-an-external-identity-provider-for-project.adoc

@@ -0,0 +1,4 @@
+[id="configuring-a-freeipa-server-as-an-external-identity-provider-for-project_{context}"]
+= Configuring a {FreeIPA} server as an external identity provider for {Project}
+
+{FreeIPA} deals with the management of individual identities, their credentials, and privileges used in a networking environment.

guides/common/modules/con_using-active-directory.adoc → guides/common/modules/con_configuring-active-directory-as-an-external-identity-provider-for-project.adoc

@@ -1,5 +1,5 @@
-[id="Using_Active_Directory_{context}"]
-= Using Active Directory
+[id="configuring-active-directory-as-an-external-identity-provider-for-project_{context}"]
+= Configuring Active Directory as an external identity provider for {Project}
 
 This section shows how to use direct Active Directory (AD) as an external authentication source for {ProjectServer}.
 
@@ -16,4 +16,4 @@ Direct AD integration means that {ProjectServer} is joined directly to the AD do
 The recommended setup consists of two steps:
 
 * Enrolling {ProjectServer} with the Active Directory server as described in xref:Enrolling_Server_with_the_AD_Server_{context}[].
-* Configuring direct Active Directory integration with GSS-proxy as described in xref:Configuring_Direct_AD_Integration_with_GSS_Proxy_{context}[].
+* Configuring direct Active Directory integration with GSS-proxy as described in xref:Configuring_Direct_AD_Integration_with_GSS_Proxy_{context}[].

guides/common/modules/con_configuring-ad-integrated-with-freeipa-through-cross-forest-kerberos-trust-as-an-external-identity-provider-for-project.adoc

@@ -0,0 +1,6 @@
+[id="configuring-ad-integrated-with-freeipa-through-cross-forest-kerberos-trust-as-an-external-identity-provider-for-project_{context}"]
+= Configuring Active Directory integrated with {FreeIPA} through cross-forest Kerberos trust as an external identity provider for {Project}
+
+Kerberos can create `cross-forest trust` that defines a relationship between two otherwise separate domain forests.
+A domain forest is a hierarchical structure of domains; both AD and {FreeIPA} constitute a forest.
+With a trust relationship enabled between AD and {FreeIPA}, AD users can access Linux hosts and services using a single set of credentials.

guides/common/modules/con_configuring-an-ldap-server-as-an-external-identity-provider-for-project.adoc

@@ -0,0 +1,5 @@
+[id="configuring-an-ldap-server-as-an-external-identity-provider-for-project_{context}"]
+= Configuring an LDAP server as an external identity provider for {Project}
+
+Lightweight Directory Access Protocol (LDAP) is a set of open protocols used to access centrally stored information over a network.
+With {Project}, you can manage LDAP entirely through the {ProjectWebUI}.

guides/common/modules/con_configuring-external-authentication.adoc

@@ -14,43 +14,5 @@ For example, to check if entries for `puppet`, `{apache-user}`, `foreman` and `f
 
 [options="nowrap", subs="+quotes,verbatim,attributes"]
 ----
-# cat /etc/passwd | grep 'puppet\|{apache-user}\|foreman\|foreman-proxy'
-# cat /etc/group | grep 'puppet\|{apache-user}\|foreman\|foreman-proxy'
+# grep 'puppet\|{apache-user}\|foreman\|foreman-proxy' /etc/passwd /etc/group
 ----
-
-.Scenarios for configuring external authentication
-{ProjectName} supports the following general scenarios for configuring external authentication:
-
-* Using _Lightweight Directory Access Protocol_ (LDAP) server as an external identity provider.
-LDAP is a set of open protocols used to access centrally stored information over a network.
-With {Project}, you can manage LDAP entirely through the {ProjectWebUI}.
-For more information, see xref:Using_LDAP_{context}[].
-Though you can use LDAP to connect to a {FreeIPA} or AD server, the setup does not support server discovery, cross-forest trusts, or single sign-on with Kerberos in {Project}'s web UI.
-* Using a {FreeIPA} server as an external identity provider.
-{FreeIPA} deals with the management of individual identities, their credentials and privileges used in a networking environment.
-Configuration using {FreeIPA} cannot be completed using only the {ProjectWebUI} and requires some interaction with the CLI.
-For more information see xref:Using_FreeIPA_{context}[].
-* Using _Active Directory_ (AD) integrated with {FreeIPA} through cross-forest Kerberos trust as an external identity provider.
-For more information see xref:Active_Directory_with_Cross_Forest_Trust_{context}[].
-* Using {Keycloak} as an OpenID provider for external authentication to {Project}.
-For more information, see xref:Configuring_Project_with_Keycloak_Authentication_keycloak-general[].
-* Using {Keycloak} as an OpenID provider for external authentication to {Project} with TOTP.
-For more information, see xref:Configuring_Keycloak_Authentication_with_TOTP_keycloak-totp[].
-ifndef::satellite,orcharhino[]
-* Using {Keycloak} as an OpenID provider for external authentication to {Project} with {PIV} cards.
-For more information, see xref:Configuring_Keycloak_Authentication_with_CAC_Cards_keycloak-cac-cards[].
-endif::[]
-
-As well as providing access to {ProjectServer}, hosts provisioned with {Project} can also be integrated with {FreeIPA} realms.
-{ProjectName} has a realm feature that automatically manages the lifecycle of any system registered to a realm or domain provider.
-For more information, see xref:External_Authentication_for_Provisioned_Hosts_{context}[].
-
-.Authentication overview
-|====
-|Type |Authentication | User Groups
-
-|{FreeIPA} | Kerberos or LDAP | Yes
-|Active Directory | Kerberos or LDAP | Yes
-|POSIX | LDAP | Yes
-
-|====

guides/common/modules/con_configuring-keycloak-authentication-for-project.adoc

@@ -0,0 +1,4 @@
+[id="configuring-keycloak-authentication-for-project_{context}"]
+= Configuring {keycloak} authentication for {Project}
+
+Use this section to configure {Project} to use {Keycloak} as an OpenID provider for external authentication.

guides/common/modules/con_configuring-keycloak-authentication-with-piv-cards-for-project.adoc

@@ -0,0 +1,4 @@
+[id="Configuring_Keycloak_Authentication_with_CAC_Cards_for_Project_{context}"]
+= Configuring {Keycloak} authentication with {PIV} cards for {Project}
+
+Use this section to configure {Project} to use {Keycloak} as an OpenID provider for external authentication with {PIV} cards.

guides/common/modules/con_configuring-keycloak-authentication-with-totp-cards-for-project.adoc

@@ -0,0 +1,4 @@
+[id="configuring-keycloak-authentication-with-totp-cards-for-project_{context}"]
+= Configuring {keycloak} authentication with TOTP cards for {Project}
+
+Use this section to configure {Project} to use {Keycloak} as an OpenID provider for external authentication with TOTP cards.