Review & edit IPA external authentication user story (#3015)

* Redefine FreeIPA attributes for RH d/s

* Review and edit the FreeIPA external authentication story

* Review and clarify configuring Hammer for FreeIPA

Based on https://github.com/theforeman/hammer-cli-foreman/blob/master/doc/configuration.md

* Drop warning about restart after satellite-maintain

---------

Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de>

guides/README.md

@@ -128,7 +128,7 @@ The basic structure of the file is a nested path parts in the documentation link
     "accessing_server_admin": [
       "Logging_in_admin",
       "Using_FreeIPA_credentials_to_log_in_to_the_foreman_Hammer_CLI_admin",
-      "Using_FreeIPA_credentials_to_log_in_to_the_foreman_web_UI-with-a-Firefox-browser_admin",
+      "Using_FreeIPA_credentials_to_log_in_to_the_foreman_web_UI-with-Mozilla-Firefox_admin",
       "Using_FreeIPA_credentials_to_log_in_to_the_foreman_web_UI-with-a-Chrome-browser_admin",
       "Navigation_Tabs_in_the_Web_UI_admin",
       "Changing_the_Password_admin",

guides/common/assembly_accessing-server.adoc

@@ -8,11 +8,11 @@ endif::[]
 
 include::modules/proc_logging-in.adoc[leveloffset=+1]
 
-include::modules/proc_using-freeipa-credentials-to-log-in-to-the-project-hammer-cli.adoc[leveloffset=+1]
+include::modules/proc_logging-in-to-hammer-cli-with-freeipa-credentials.adoc[leveloffset=+1]
 
-include::modules/proc_using-freeipa-credentials-to-log-in-to-the-ProjectWebUI-with-a-Firefox-browser.adoc[leveloffset=+1]
+include::modules/proc_logging-in-to-the-projectwebui-with-freeipa-credentials-in-mozilla-firefox.adoc[leveloffset=+1]
 
-include::modules/proc_using-freeipa-credentials-to-log-in-to-the-ProjectWebUI-with-a-Chrome-browser.adoc[leveloffset=+1]
+include::modules/proc_logging-in-to-the-projectwebui-with-freeipa-credentials-in-chrome.adoc[leveloffset=+1]
 
 include::modules/proc_changing-the-password.adoc[leveloffset=+1]
 

guides/common/assembly_configuring-external-authentication.adoc

@@ -2,9 +2,7 @@ include::modules/con_configuring-external-authentication.adoc[]
 
 include::assembly_configuring-an-ldap-server-as-an-external-identity-provider-for-project.adoc[leveloffset=+1]
 
-include::assembly_configuring-a-freeipa-server-as-an-external-identity-provider-for-project.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]
+include::assembly_configuring-freeipa-server-as-an-external-identity-provider-for-project.adoc[leveloffset=+1]
 
 ifdef::context[:parent-context: {context}]
 :context: keycloak-wildfly-general
@@ -56,6 +54,4 @@ include::modules/proc_refreshing-external-user-groups-for-ldap.adoc[leveloffset=
 
 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/proc_disabling-keycloak-authentication.adoc[leveloffset=+1]

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

@@ -0,0 +1,15 @@
+include::modules/con_configuring-freeipa-server-as-an-external-identity-provider-for-project.adoc[]
+
+include::modules/proc_enrolling-projectserver-in-freeipa-domain.adoc[leveloffset=+1]
+
+include::modules/proc_configuring-the-freeipa-authentication-source-on-projectserver.adoc[leveloffset=+1]
+
+include::modules/proc_configuring-host-based-access-control-for-freeipa-users-logging-in-to-project.adoc[leveloffset=+1]
+
+include::modules/proc_configuring-hammer-cli-to-accept-freeipa-credentials.adoc[leveloffset=+1]
+
+include::modules/proc_logging-in-to-hammer-cli-with-freeipa-credentials.adoc[leveloffset=+1]
+
+include::modules/proc_logging-in-to-the-projectwebui-with-freeipa-credentials-in-mozilla-firefox.adoc[leveloffset=+1]
+
+include::modules/proc_logging-in-to-the-projectwebui-with-freeipa-credentials-in-chrome.adoc[leveloffset=+1]

guides/common/attributes-satellite.adoc

@@ -68,8 +68,8 @@
 :foreman-installer-package: satellite-installer
 :foreman-installer: satellite-installer
 :foreman-maintain: satellite-maintain
-:FreeIPA: Red{nbsp}Hat Identity Management
-:FreeIPA-context: Red_Hat_Identity_Management
+:FreeIPA: Identity{nbsp}Management
+:FreeIPA-context: Identity_Management
 :hammer-smart-proxy: hammer capsule
 :installer-log-file: /var/log/foreman-installer/satellite.log
 :installer-scenario-smartproxy: satellite-installer --scenario capsule

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

@@ -7,9 +7,17 @@
 Lightweight Directory Access Protocol (LDAP) is a set of open protocols used to access centrally stored information over a network.
 With {Project}, you can use one or multiple LDAP directories for external authentication.
 
+[NOTE]
+====
+While you can configure the LDAP server integrated with {FreeIPA} as an external authentication source, {FreeIPA} users will not be able to log in using single sign-on.
+Instead, consider configuring {FreeIPA} as an external identity provider.
+For more information, see xref:configuring-{Freeipa-context}-server-as-an-external-identity-provider-for-project_{context}[].
+====
+
 [IMPORTANT]
 ====
-include::snip_do-not-use-both-ldap-and-freeipa.adoc[]
+Users cannot use both {FreeIPA} and LDAP as an authentication method.
+After a user authenticates by using one of these methods, they cannot use the other method.
 
-For more information on using {FreeIPA} as an authentication method, see xref:Using_FreeIPA_{context}[].
+To change the authentication method for a user, remove the automatically created user from {Project}.
 ====

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

@@ -0,0 +1,12 @@
+[id="configuring-{Freeipa-context}-server-as-an-external-identity-provider-for-project_{context}"]
+= Configuring {FreeIPA} server as an external identity provider for {Project}
+
+{FreeIPA} is an open-source identity management solution that provides centralized authentication, authorization, and account management services.
+With {Project}, you can integrate {ProjectServer} with your existing {FreeIPA} server to enable {FreeIPA} users to authenticate to {Project}.
+
+With your {FreeIPA} server configured as an external identity provider, users defined in {FreeIPA} can log in to {Project} with their {FreeIPA} credentials.
+If a cross-forest trust is configured between {FreeIPA} and Active{nbsp}Directory, Active{nbsp}Directory users can also log in to {Project}.
+The following login methods are available:
+
+* Username and password
+* Kerberos single sign-on

guides/common/modules/proc_configuring-hammer-cli-to-accept-freeipa-credentials.adoc

@@ -0,0 +1,30 @@
+[id="configuring-hammer-cli-to-accept-{FreeIPA-context}-credentials_{context}"]
+= Configuring Hammer CLI to accept {FreeIPA} credentials
+
+Configure the {Project} Hammer CLI tool to use {FreeIPA} to authenticate users.
+
+.Prerequisites
+* You have enabled {FreeIPA} access to the {Project} API.
+For more information, see xref:configuring-the-freeipa-authentication-source-on-projectserver_{context}[].
+
+.Procedure
+* Open the `~/.hammer/cli.modules.d/foreman.yml` file on your {ProjectServer} and update the list of `foreman` parameters:
+** To enforce session usage, enable `:use_sessions:`:
++
+[options="nowrap", subs="+quotes,verbatim,attributes"]
+----
+:foreman:
+  :use_sessions: true
+----
++
+With this configuration, you will need to initiate an authentication session manually with `hammer auth login negotiate`.
+** Alternatively, to enforce session usage and also negotiate authentication by default:
++
+[options="nowrap", subs="+quotes,verbatim,attributes"]
+----
+:foreman:
+  :default_auth_type: 'Negotiate_Auth'
+  :use_sessions: true
+----
++
+With this configuration, Hammer will negotiate authentication automatically when you enter the first `hammer` command.