diff --git a/guides/common/attributes-foremanctl-satellite.adoc b/guides/common/attributes-foremanctl-satellite.adoc index e666af2f3c1..8b183218f66 100644 --- a/guides/common/attributes-foremanctl-satellite.adoc +++ b/guides/common/attributes-foremanctl-satellite.adoc @@ -1 +1,3 @@ include::attributes-satellite.adoc[] + +:project-package-install: {package-install} diff --git a/guides/common/modules/con_configuring-kerberos-sso-for-active-directory-users-in-project.adoc b/guides/common/modules/con_configuring-kerberos-sso-for-active-directory-users-in-project.adoc index a4a138a73d1..8fa4e253efa 100644 --- a/guides/common/modules/con_configuring-kerberos-sso-for-active-directory-users-in-project.adoc +++ b/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::[] diff --git a/guides/common/modules/proc_configuring-external-user-groups.adoc b/guides/common/modules/proc_configuring-external-user-groups.adoc index 9f52952973a..a48406e1a0e 100644 --- a/guides/common/modules/proc_configuring-external-user-groups.adoc +++ b/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. diff --git a/guides/common/modules/proc_configuring-hammer-cli-to-accept-freeipa-credentials.adoc b/guides/common/modules/proc_configuring-hammer-cli-to-accept-freeipa-credentials.adoc index 39110fe05db..19891ac5704 100644 --- a/guides/common/modules/proc_configuring-hammer-cli-to-accept-freeipa-credentials.adoc +++ b/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` updates the Hammer configuration as necessary. +==== +endif::[] .Prerequisites * You have enabled {FreeIPA} access to the {Project} API. diff --git a/guides/common/modules/proc_configuring-host-based-access-control-for-freeipa-users-logging-in-to-project.adoc b/guides/common/modules/proc_configuring-host-based-access-control-for-freeipa-users-logging-in-to-project.adoc index 463d82a47b7..893afa2954c 100644 --- a/guides/common/modules/proc_configuring-host-based-access-control-for-freeipa-users-logging-in-to-project.adoc +++ b/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[] +* You have enabled {FreeIPA} as external authentication source on your {ProjectServer}. +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::[] ---- ==== diff --git a/guides/common/modules/proc_configuring-the-active-directory-authentication-source-on-projectserver.adoc b/guides/common/modules/proc_configuring-the-active-directory-authentication-source-on-projectserver.adoc index c9a087a2662..50250955cfd 100644 --- a/guides/common/modules/proc_configuring-the-active-directory-authentication-source-on-projectserver.adoc +++ b/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,16 @@ $ kinit _ad_user_@_AD.EXAMPLE.COM_ + [options="nowrap", subs="+quotes,verbatim,attributes"] ---- -$ curl -k -u : --negotiate https://{foreman-example-com}/users/extlogin - -You are being redirected. +$ curl -k -u : --negotiate https://_{foreman-example-com}_/users/extlogin ---- ++ +If external authentication is configured correctly, the `curl` command redirects you to `\https://{foreman-example-com}/hosts`: ++ +[options="nowrap", subs="+quotes,verbatim,attributes"] +---- +You are being redirected. +---- + .Troubleshooting * Connecting to the AD LDAP can sometimes fail with an error such as the following appearing in the logs: @@ -151,7 +162,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[] diff --git a/guides/common/modules/proc_configuring-the-freeipa-authentication-source-on-projectserver.adoc b/guides/common/modules/proc_configuring-the-freeipa-authentication-source-on-projectserver.adoc index 876c0cbdbfb..3b97bb0f33f 100644 --- a/guides/common/modules/proc_configuring-the-freeipa-authentication-source-on-projectserver.adoc +++ b/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[] diff --git a/guides/common/modules/proc_enrolling-projectserver-in-your-freeipa-domain.adoc b/guides/common/modules/proc_enrolling-projectserver-in-your-freeipa-domain.adoc index 6fc509ea6f2..d6d147f2d0f 100644 --- a/guides/common/modules/proc_enrolling-projectserver-in-your-freeipa-domain.adoc +++ b/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"] diff --git a/guides/common/modules/proc_logging-in-to-hammer-cli-with-freeipa-credentials.adoc b/guides/common/modules/proc_logging-in-to-hammer-cli-with-freeipa-credentials.adoc index fcf9d7c2813..e5183f7fc8f 100644 --- a/guides/common/modules/proc_logging-in-to-hammer-cli-with-freeipa-credentials.adoc +++ b/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): diff --git a/guides/common/modules/proc_resetting-external-authentication-configuration-for-kerberos-sso.adoc b/guides/common/modules/proc_resetting-external-authentication-configuration-for-kerberos-sso.adoc new file mode 100644 index 00000000000..eaa95b0f640 --- /dev/null +++ b/guides/common/modules/proc_resetting-external-authentication-configuration-for-kerberos-sso.adoc @@ -0,0 +1,65 @@ +:_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} with Kerberos single sign-on (SSO). +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 +* Reset the external authentication configuration to the default state: +ifdef::foremanctl[] ++ +[options="nowrap", subs="+quotes,verbatim,attributes"] +---- +# foremanctl deploy --reset-external-authentication +---- +endif::[] +ifndef::foremanctl[] +** 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 +---- ++ +If external authentication is disabled, the `curl` command redirects you to `\https://{foreman-example-com}/users/login`. ++ +[options="nowrap", subs="+quotes,verbatim,attributes"] +---- +You are being redirected. +---- +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::[] diff --git a/guides/common/modules/snip_ext-auth-mutually-exclusive.adoc b/guides/common/modules/snip_ext-auth-mutually-exclusive.adoc new file mode 100644 index 00000000000..88d321006d5 --- /dev/null +++ b/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. +==== diff --git a/guides/common/modules/snip_table-authentication-methods.adoc b/guides/common/modules/snip_table-authentication-methods.adoc index 82c6091a371..6e91509b3a1 100644 --- a/guides/common/modules/snip_table-authentication-methods.adoc +++ b/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::[] diff --git a/guides/doc-Configuring_User_Authentication/master.adoc b/guides/doc-Configuring_User_Authentication/master.adoc index 00e3de0c403..86ab1bb0c6c 100644 --- a/guides/doc-Configuring_User_Authentication/master.adoc +++ b/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::[] diff --git a/web/releases/nightly.json b/web/releases/nightly.json index d58ec7a86ca..12f55359784 100644 --- a/web/releases/nightly.json +++ b/web/releases/nightly.json @@ -145,6 +145,7 @@ ["Installing_Server", "Installing Foreman Server"] ], "Administering Foreman server": [ + ["Configuring_User_Authentication", "Configuring user authentication"] ], "Administering hosts": [ ],