Update Kerberos SSO documentation for foremanctl

guides/common/attributes-foremanctl-satellite.adoc

@@ -1 +1,3 @@
 include::attributes-satellite.adoc[]
+
+:project-package-install: {package-install}

guides/common/modules/con_configuring-kerberos-sso-for-active-directory-users-in-project.adoc

@@ -12,6 +12,7 @@ AD users can log in using the following methods:
 * Username and password
 * Kerberos single sign-on
 
+ifndef::foremanctl[]
 [NOTE]
 ====
 You can also connect your {Project} deployment to AD in the following ways:
@@ -25,3 +26,4 @@ ifndef::orcharhino[]
 For an example configuration, see https://access.redhat.com/solutions/1498773[How to configure Active Directory authentication with TLS on {Project}].
 endif::[]
 ====
+endif::[]

guides/common/modules/proc_configuring-external-user-groups.adoc

@@ -14,11 +14,13 @@ To assign additional permissions to an external user, add this user to an intern
 Then assign the required roles to this group.
 
 .Prerequisites
+ifndef::foremanctl[]
 * If you use an LDAP server, configure {Project} to use LDAP authentication.
 For more information, see xref:configuring-an-ldap-server-as-an-external-identity-provider-for-project_{context}[].
 +
 When using external user groups from an LDAP source, you cannot use the `$login` variable as a substitute for the account user name.
 You must use either an anonymous or dedicated service user.
+endif::[]
 * If you use a {FreeIPA} or AD server, configure {Project} to use {FreeIPA} or AD authentication.
 For more information, see {ConfiguringUserAuthenticationDocURL}[_{ConfiguringUserAuthenticationDocTitle}_].
 * Ensure that at least one external user authenticates for the first time.

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

@@ -4,7 +4,18 @@
 = Configuring Hammer CLI to accept {FreeIPA} credentials
 
 [role="_abstract"]
+ifndef::foremanctl[]
 To enable users to authenticate to the Hammer CLI by using their {FreeIPA} credentials, update Hammer configuration.
+endif::[]
+ifdef::foremanctl[]
+If you want to enable users to authenticate to the Hammer CLI by using their {FreeIPA} credentials from a system with standalone Hammer installed, update Hammer configuration on that system.
+
+[NOTE]
+====
+Updating Hammer configuration manually is not required on systems that have been configured with `foremanctl`.
+Running `foremanctl --add-feature hammer` includes updating the Hammer configuration as necessary.
+====
+endif::[]
 
 .Prerequisites
 * You have enabled {FreeIPA} access to the {Project} API.

guides/common/modules/proc_configuring-host-based-access-control-for-freeipa-users-logging-in-to-project.adoc

@@ -12,6 +12,10 @@ By configuring a HBAC rule in the {FreeIPA} domain, you can ensure {Project} doe
 
 .Prerequisites
 * {FreeIPA} user account with privileges to configure HBAC rules
+ifdef::foremanctl[]
+* The external authentication source has been enabled on your {ProjectServer} by using the `foremanctl deploy --external-authentication` command.
+For more information, see xref:configuring-the-freeipa-authentication-source-on-projectserver_{context}[].
+endif::[]
 
 .Procedure
 . On the {FreeIPA} server, configure HBAC control.
@@ -32,7 +36,12 @@ endif::[]
 +
 [options="nowrap", subs="+quotes,verbatim,attributes"]
 ----
+ifdef::foremanctl[]
+# foremanctl deploy --external-authentication-pam-service foreman-prod
+endif::[]
+ifndef::foremanctl[]
 # {foreman-installer} --foreman-pam-service foreman-prod
+endif::[]
 ----
 
 .Verification
@@ -109,10 +118,22 @@ $ ipa hbactest --user=_ipa-user_ --host=_{foreman-example-com}_ --service={proje
 $ ipa hbacrule-disable allow_all
 ----
 
-On {ProjectServer}, a {Project} administrator re-runs {foreman-installer} to load the host-based access control rules from {FreeIPA}:
+On {ProjectServer}, a {Project} administrator re-runs
+ifdef::foremanctl[]
+`foremanctl deploy`
+endif::[]
+ifndef::foremanctl[]
+`{foreman-installer}`
+endif::[]
+to load the host-based access control rules from {FreeIPA}:
 
 [options="nowrap", subs="+quotes,verbatim,attributes"]
 ----
-# {foreman-installer} --foreman-pam-service {project-context}-prod
+ifdef::foremanctl[]
+# foremanctl deploy --external-authentication-pam-service foreman-prod
+endif::[]
+ifndef::foremanctl[]
+# {foreman-installer} --foreman-pam-service foreman-prod
+endif::[]
 ----
 ====

guides/common/modules/proc_configuring-the-active-directory-authentication-source-on-projectserver.adoc

@@ -29,7 +29,7 @@ For more information on direct AD integration, see link:https://docs.redhat.com/
 endif::[]
 
 .Procedure
-. Define AD realm configuration in a location where {foreman-installer} expects it:
+. Define AD realm configuration in a location where {Project} expects it:
 .. Create a directory named `/etc/ipa/`:
 +
 [options="nowrap", subs="+quotes,verbatim,attributes"]
@@ -103,7 +103,12 @@ Without the option, AD users are unable to use `kinit` to authenticate to {Proje
 +
 [options="nowrap", subs="+quotes,verbatim,attributes"]
 ----
+ifdef::foremanctl[]
+# foremanctl deploy --external-authentication ipa
+endif::[]
+ifndef::foremanctl[]
 # {foreman-installer} --foreman-ipa-authentication true
+endif::[]
 ----
 
 .Verification
@@ -120,10 +125,12 @@ $ kinit _ad_user_@_AD.EXAMPLE.COM_
 +
 [options="nowrap", subs="+quotes,verbatim,attributes"]
 ----
-$ curl -k -u : --negotiate https://{foreman-example-com}/users/extlogin
+$ curl -k -u : --negotiate https://_{foreman-example-com}_/users/extlogin
 
-<html><body>You are being <a href="{foreman-example-com}/hosts">redirected</a>.</body></html>
+<html><body>You are being <a href="_{foreman-example-com}_/hosts">redirected</a>.</body></html>
 ----
++
+When external authentication is configured correctly, the `curl` command redirects you to `\https://{foreman-example-com}/hosts`.
 
 .Troubleshooting
 * Connecting to the AD LDAP can sometimes fail with an error such as the following appearing in the logs:
@@ -151,7 +158,8 @@ ifdef::foreman-el,katello[]
 For information on configuring system-wide cryptographic policies, see link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/security_hardening/using-the-system-wide-cryptographic-policies_security-hardening[Using system-wide cryptographic policies] in _{RHEL}{nbsp}9 Security hardening_.
 endif::[]
 
-ifndef::orcharhino[]
 .Additional resources
+ifndef::orcharhino[]
 * https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/configuring_authentication_and_authorization_in_rhel/configuring_applications_for_sso#Configuring_Firefox_to_use_Kerberos_for_SSO[Configuring Firefox to use Kerberos for single sign-on in _{RHEL}{nbsp}9 Configuring authentication and authorization in RHEL_]
 endif::[]
+* xref:resetting-external-authentication-configuration-for-kerberos-sso[]

guides/common/modules/proc_configuring-the-freeipa-authentication-source-on-projectserver.adoc

@@ -6,6 +6,8 @@
 [role="_abstract"]
 Connect your {ProjectServer} to your {FreeIPA} domain by configuring {FreeIPA} as an authentication provider on your {ProjectServer}.
 
+include::snip_ext-auth-mutually-exclusive.adoc[]
+
 .Prerequisites
 * {ProjectServer} running on a system that is enrolled in the {FreeIPA} domain.
 
@@ -15,16 +17,26 @@ Connect your {ProjectServer} to your {FreeIPA} domain by configuring {FreeIPA} a
 +
 [options="nowrap", subs="+quotes,verbatim,attributes"]
 ----
+ifdef::foremanctl[]
+# foremanctl deploy --external-authentication ipa
+endif::[]
+ifndef::foremanctl[]
 # {foreman-installer} \
 --foreman-ipa-authentication true
+endif::[]
 ----
 * To enable access to the {ProjectWebUI} and the {Project} API, including Hammer CLI:
 +
 [options="nowrap", subs="+quotes,verbatim,attributes"]
 ----
+ifdef::foremanctl[]
+# foremanctl deploy --external-authentication ipa_with_api
+endif::[]
+ifndef::foremanctl[]
 # {foreman-installer} \
 --foreman-ipa-authentication-api true \
 --foreman-ipa-authentication true
+endif::[]
 ----
 +
 [WARNING]
@@ -33,13 +45,6 @@ Enabling access to both the {ProjectWebUI} and the {Project} API poses a securit
 After the {FreeIPA} user enters `kinit` to receive a Kerberos ticket-granting ticket (TGT), an attacker might obtain an API session.
 The attack is possible even if the user did not previously enter the {Project} login credentials anywhere, for example in the browser.
 ====
-* To disable external authentication with {FreeIPA}, reset the options.
-For example, to disable access to the {Project} API and Hammer CLI:
-+
-[options="nowrap", subs="+quotes,verbatim,attributes"]
-----
-# {foreman-installer} --reset-foreman-ipa-authentication-api
-----
 . If your {ProjectServer} runs in an IPv6-only network and also runs on {EL}{nbsp}9.6 and earlier or {EL}{nbsp}10.0, set the `lookup_family_order` option in the `[domain/_{freeipaserver-example-com}_]` section of the `/etc/sssd/sssd.conf` file:
 +
 [source, ini, options="nowrap", subs="+quotes,verbatim,attributes"]
@@ -54,3 +59,6 @@ Without the option, IdM users are unable to use `kinit` to authenticate to {Proj
 
 .Verification
 * Log in to {ProjectWebUI} by entering the credentials of a user defined in {FreeIPA}.
+
+.Additional resources
+* xref:resetting-external-authentication-configuration-for-kerberos-sso[]

guides/common/modules/proc_enrolling-projectserver-in-your-freeipa-domain.adoc

@@ -30,7 +30,6 @@ ifndef::orcharhino[]
 For more information, see link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux//9/html-single/installing_identity_management/index#assembly_installing-an-idm-client_installing-identity-management[{RHEL}{nbsp}9 Installing Identity Management].
 endif::[]
 ifdef::foreman-deb[]
-+
 . Ensure that the hostname is set to the fully qualified domain name (FQDN); the short name is not sufficient:
 +
 [options="nowrap", subs="+quotes,verbatim,attributes"]

guides/common/modules/proc_logging-in-to-hammer-cli-with-freeipa-credentials.adoc

@@ -6,16 +6,11 @@
 [role="_abstract"]
 Authenticate to the {Project} Hammer CLI with your {FreeIPA} username and password.
 
+ifndef::foremanctl[]
 .Prerequisites
 * You have configured Hammer CLI to accept {FreeIPA} credentials.
-ifeval::["{context}" == "{project-context}"]
 See xref:configuring-hammer-cli-to-accept-{FreeIPA-context}-credentials_{context}[].
 endif::[]
-ifeval::["{context}" != "{project-context}"]
-ifndef::orcharhino[]
-For more information, see {InstallingServerDocURL}configuring-hammer-cli-to-accept-{FreeIPA-context}-credentials_{context}[Configuring Hammer CLI to accept {FreeIPA} credentials] in _{InstallingServerDocTitle}_.
-endif::[]
-endif::[]
 
 .Procedure
 . Authenticate as a user defined in {FreeIPA} to obtain a Kerberos ticket-granting ticket (TGT):

guides/common/modules/proc_resetting-external-authentication-configuration-for-kerberos-sso.adoc

@@ -0,0 +1,63 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="resetting-external-authentication-configuration-for-kerberos-sso"]
+= Resetting external authentication configuration for Kerberos SSO
+
+[role="_abstract"]
+You can disable external authentication with {FreeIPA} or Active Directory (AD) by resetting the configuration for the `IPA` authentication type.
+This prevents user accounts defined in the external authentication source from accessing {Project}.
+
+[IMPORTANT]
+====
+Resetting external authentication prevents users from accessing {Project} as described in xref:configuring-kerberos-sso-with-{FreeIPA-context}-in-{project-context}[] and xref:configuring-kerberos-sso-for-active-directory-users-in-project_{context}[].
+However, some configuration files, such as configuration files for the System Security Services Daemon (SSSD), will remain modified because {Project} does not have access to the previous state of these files.
+====
+
+.Procedure
+ifdef::foremanctl[]
+* Reset the external authentication configuration to the default state:
++
+[options="nowrap", subs="+quotes,verbatim,attributes"]
+----
+# foremanctl deploy --reset-external-authentication
+----
+endif::[]
+ifndef::foremanctl[]
+* Reset the external authentication configuration to the default state:
+** To disable access to {ProjectWebUI}:
++
+[options="nowrap", subs="+quotes,verbatim,attributes"]
+----
+# {foreman-installer} --reset-foreman-ipa-authentication
+----
+** To disable access to {ProjectWebUI}, {Project} API, and Hammer CLI:
++
+[options="nowrap", subs="+quotes,verbatim,attributes"]
+----
+# {foreman-installer} --reset-foreman-ipa-authentication-api
+----
+endif::[]
+
+.Verification
+ifdef::foremanctl[]
+* Verify your external authentication configuration:
++
+[options="nowrap", subs="+quotes,verbatim,attributes"]
+----
+$ curl -k -u : --negotiate https://_{foreman-example-com}_/users/extlogin
+
+<html><body>You are being <a href="https://_{foreman-example-com}_/users/login">redirected</a>.</body></html>
+----
++
+When external authentication is disabled, the `curl` command redirects you to `\https://{foreman-example-com}/users/login`.
+endif::[]
+ifndef::foremanctl[]
+* Display the value for the `foreman-ipa-authentication` and `foreman-ipa-authentication-api` configuration options:
++
+[options="nowrap", subs="+quotes,verbatim,attributes"]
+----
+# {foreman-installer} --help | grep foreman-ipa-authentication
+----
++
+The expected value for disabled external authentication is `false`.
+endif::[]

guides/common/modules/snip_ext-auth-mutually-exclusive.adoc

@@ -0,0 +1,12 @@
+[NOTE]
+====
+The {FreeIPA} and Active{nbsp}Directory authentication sources are mutually exclusive.
+Running
+ifdef::foremanctl[]
+`foremanctl deploy --external-authentication`
+endif::[]
+ifndef::foremanctl[]
+`{foreman-installer} --foreman-ipa-authentication` or `{foreman-installer} --foreman-ipa-authentication-api`
+endif::[]
+overwrites any previously defined configuration for these authentication sources.
+====

guides/common/modules/snip_table-authentication-methods.adoc

@@ -71,24 +71,26 @@ ifndef::satellite[]
 |No
 endif::[]
 |xref:configuring-kerberos-sso-with-{FreeIPA-context}-in-{project-context}[]
-ifndef::foreman-deb,satellite[]
+ifndef::foremanctl,foreman-deb,satellite[]
 |{Keycloak-quarkus}|Yes|Yes|Yes|Yes
 ifndef::satellite[]
 |Yes
 endif::[]
 |xref:configuring-sso-and-2fa-with-keycloak-wildfly-in-project_keycloak-wildfly[]
 endif::[]
-ifndef::foreman-deb[]
+ifndef::foremanctl,foreman-deb[]
 |{Keycloak-wildfly}|Yes|Yes|Yes|Yes
 ifndef::satellite[]
 |Yes
 endif::[]
 |xref:configuring-sso-and-2fa-with-keycloak-wildfly-in-project_keycloak-wildfly[]
 endif::[]
+ifndef::foremanctl[]
 |LDAP|Yes|No|No|No
 ifndef::satellite[]
 |No
 endif::[]
 |xref:configuring-an-ldap-server-as-an-external-identity-provider-for-project_{context}[]
+endif::[]
 |====
 endif::[]

guides/doc-Configuring_User_Authentication/master.adoc

@@ -14,6 +14,7 @@ include::common/assembly_accessing-project-from-web-ui.adoc[leveloffset=+1]
 
 include::common/assembly_configuring-kerberos-sso-with-freeipa-in-project.adoc[leveloffset=+1]
 
+ifndef::foremanctl[]
 ifndef::foreman-deb[]
 // The following ifdef sets :keycloak: to `Red Hat Single Sign-On` for Satellite builds only. For, non-Satellite builds, :keycloak: stays set to `Keycloak`.
 ifdef::satellite[]
@@ -42,19 +43,26 @@ include::common/assembly_configuring-sso-and-2fa-with-keycloak-quarkus-in-projec
 // The following attribute reloads the original context value from parent-context that was defined earlier.
 :context: {parent-context}
 endif::[]
+endif::[]
 
 include::common/assembly_configuring-kerberos-sso-for-active-directory-users-in-project.adoc[leveloffset=+1]
 
+ifndef::foremanctl[]
 include::common/assembly_configuring-an-ldap-server-as-an-external-identity-provider-for-project.adoc[leveloffset=+1]
+endif::[]
 
 include::common/modules/proc_configuring-external-user-groups.adoc[leveloffset=+1]
 
+ifndef::foremanctl[]
 include::common/modules/proc_refreshing-external-user-groups-for-ldap-using-cli.adoc[leveloffset=+1]
 
 include::common/modules/proc_refreshing-external-user-groups-for-ldap-using-web-ui.adoc[leveloffset=+1]
+endif::[]
 
 include::common/modules/con_refreshing-external-user-groups-for-freeipa-or-ad.adoc[leveloffset=+1]
 
+include::common/modules/proc_resetting-external-authentication-configuration-for-kerberos-sso.adoc[leveloffset=+1]
+
 ifndef::orcharhino,satellite[]
 include::common/ribbons.adoc[]
 endif::[]

web/releases/nightly.json

@@ -145,6 +145,7 @@
           ["Installing_Server", "Installing Foreman Server"]
         ],
         "Administering Foreman server": [
+          ["Configuring_User_Authentication", "Configuring user authentication"]
         ],
         "Administering hosts": [
         ],