diff --git a/guides/common/assembly_configuring-external-authentication.adoc b/guides/common/assembly_configuring-external-authentication.adoc index 724570564f2..08a3f70afc9 100644 --- a/guides/common/assembly_configuring-external-authentication.adoc +++ b/guides/common/assembly_configuring-external-authentication.adoc @@ -20,11 +20,7 @@ include::modules/proc_configuring-host-based-authentication-control.adoc[levelof 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/proc_configuring-the-active-directory-authentication-source-on-projectserver.adoc[leveloffset=+2] include::modules/con_kerberos-configuration-in-web-browsers.adoc[leveloffset=+2] diff --git a/guides/common/modules/con_gss-proxy.adoc b/guides/common/modules/con_gss-proxy.adoc deleted file mode 100644 index f0b8db59862..00000000000 --- a/guides/common/modules/con_gss-proxy.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="GSS_Proxy_{context}"] -= GSS-Proxy - -The traditional process of Kerberos authentication in Apache requires the Apache process to have read access to the keytab file. -GSS-Proxy allows you to implement stricter privilege separation for the Apache server by removing access to the keytab file while preserving Kerberos authentication functionality. -When using AD as an external authentication source for {Project}, it is recommended to implement GSS-proxy, because the keys in the keytab file are the same as the host keys. - -ifndef::orcharhino[] -Perform the following procedures on {EL} that acts as a base operating system for your {ProjectServer}. -For the examples in this section _EXAMPLE.ORG_ is the Kerberos realm for the AD domain. -By completing the procedures, users that belong to the EXAMPLE.ORG realm can log in to {ProjectServer}. -endif::[] diff --git a/guides/common/modules/con_using-active-directory.adoc b/guides/common/modules/con_using-active-directory.adoc index 1d7aad823b1..51ae967d8ee 100644 --- a/guides/common/modules/con_using-active-directory.adoc +++ b/guides/common/modules/con_using-active-directory.adoc @@ -13,7 +13,3 @@ endif::[] ==== Direct AD integration means that {ProjectServer} is joined directly to the AD domain where the identity is stored. -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}[]. diff --git a/guides/common/modules/proc_configuring-direct-ad-integration-with-gss-proxy.adoc b/guides/common/modules/proc_configuring-direct-ad-integration-with-gss-proxy.adoc deleted file mode 100644 index 3cc13685cad..00000000000 --- a/guides/common/modules/proc_configuring-direct-ad-integration-with-gss-proxy.adoc +++ /dev/null @@ -1,145 +0,0 @@ -[id="Configuring_Direct_AD_Integration_with_GSS_Proxy_{context}"] -= Configuring direct AD integration with GSS-proxy - -In the {Project} CLI, configure the direct Active Directory integration with GSS-proxy. - -.Prerequisites -* {Project} is enrolled with the Active Directory server. -For more information, see xref:Enrolling_Server_with_the_AD_Server_{context}[]. - -.Procedure -. Create the `/etc/ipa/` directory and the `default.conf` file: -+ -[options="nowrap", subs="+quotes,verbatim,attributes"] ----- -# mkdir /etc/ipa -# touch /etc/ipa/default.conf ----- -. To the `default.conf` file, add the following content: -+ -[options="nowrap", subs="+quotes,verbatim,attributes"] ----- -[global] -server = unused -realm = _EXAMPLE.ORG_ ----- -. Create the `/etc/net-keytab.conf` file with the following content: -+ -[options="nowrap", subs="+quotes,verbatim,attributes"] ----- -[global] -workgroup = EXAMPLE -realm = EXAMPLE.ORG -kerberos method = system keytab -security = ads ----- -. Determine the effective user ID of the Apache user: -+ -[options="nowrap", subs="+quotes,verbatim,attributes"] ----- -# id {apache-user} ----- -+ -Apache user must not have access to the keytab file. -. Create the `/etc/gssproxy/00-http.conf` file with the following content: -+ -[options="nowrap", subs="+quotes,verbatim,attributes"] ----- -[service/HTTP] -mechs = krb5 -cred_store = keytab:/etc/httpd/conf/http.keytab -cred_store = ccache:/var/lib/gssproxy/clients/krb5cc_%U -euid = __ID_of_Apache_User__ ----- -. Create a keytab entry: -+ -[options="nowrap", subs="+quotes,verbatim,attributes"] ----- -# KRB5_KTNAME=FILE:/etc/httpd/conf/http.keytab net ads keytab add HTTP -U administrator -d3 -s /etc/net-keytab.conf -# chown root.{apache-user} /etc/httpd/conf/http.keytab -# chmod 640 /etc/httpd/conf/http.keytab ----- -. Enable IPA authentication in {Project}: -+ -[options="nowrap", subs="+quotes,verbatim,attributes"] ----- -# {foreman-installer} --foreman-ipa-authentication=true ----- -. Start and enable the `gssproxy` service: -+ -[options="nowrap", subs="+quotes,verbatim,attributes"] ----- -# systemctl restart gssproxy -# systemctl enable gssproxy ----- -. To configure the Apache server to use the `gssproxy` service, create a `systemd` drop-in file and add the following content to it: -+ -[options="nowrap", subs="+quotes,verbatim,attributes"] ----- -# mkdir -p /etc/systemd/system/httpd.service.d/ -# vi /etc/systemd/system/httpd.service.d/gssproxy.conf -[Service] -Environment=GSS_USE_PROXY=1 ----- -. Apply changes to the service: -+ -[options="nowrap", subs="+quotes,verbatim,attributes"] ----- -# systemctl daemon-reload ----- -. Start and enable the `httpd` service: -+ -[options="nowrap", subs="+quotes,verbatim,attributes"] ----- -# systemctl restart httpd ----- - -[IMPORTANT] -==== -With direct AD integration, HBAC through {FreeIPA} is not available. -As an alternative, you can use Group Policy Objects (GPO) that enable administrators to centrally manage policies in AD environments. -To ensure correct GPO to PAM service mapping, add the following SSSD configuration to `/etc/sssd/sssd.conf`: - -[options="nowrap", subs="+quotes,verbatim,attributes"] ----- -access_provider = ad -ad_gpo_access_control = enforcing -ad_gpo_map_service = +foreman ----- - -Here, _foreman_ is the PAM service name. -ifdef::satellite[] -For more information on GPOs, see https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/integrating_rhel_systems_directly_with_windows_active_directory/managing-direct-connections-to-ad_integrating-rhel-systems-directly-with-active-directory#how-sssd-interprets-gpo-access-control-rules_applying-group-policy-object-access-control-in-rhel[How SSSD interprets GPO access control rules] in _{RHEL} 9 guide_ or https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/integrating_rhel_systems_directly_with_windows_active_directory/managing-direct-connections-to-ad_integrating-rhel-systems-directly-with-active-directory#how-sssd-interprets-gpo-access-control-rules_applying-group-policy-object-access-control-in-rhel[How SSSD interprets GPO access control rules] in _{RHEL} 8 guide_. -endif::[] -==== - -.Verification -Verify that SSO is working as expected. - -With a running Apache server, users making HTTP requests against the server are authenticated if the client has a valid Kerberos ticket. - -. Retrieve the Kerberos ticket of the LDAP user, using the following command: -+ -[options="nowrap", subs="+quotes,verbatim,attributes"] ----- -# kinit ldapuser ----- -. View the Kerberos ticket, using the following command: -+ -[options="nowrap", subs="+quotes,verbatim,attributes"] ----- -# klist ----- -. View output from successful SSO-based authentication, using the following command: -+ -[options="nowrap", subs="+quotes,attributes"] ----- -# curl -k -u : --negotiate https://__{foreman-example-com}/__users/extlogin ----- -+ -This returns the following response: -+ -[options="nowrap", subs="+quotes,attributes"] ----- -You are being redirected. ----- 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 new file mode 100644 index 00000000000..a32c5f39c2e --- /dev/null +++ b/guides/common/modules/proc_configuring-the-active-directory-authentication-source-on-projectserver.adoc @@ -0,0 +1,109 @@ +[id="configuring-the-active-directory-authentication-source-on-projectserver_{context}"] += Configuring the Active Directory authentication source on {ProjectServer} + +Enable Active Directory (AD) users to access {Project} by configuring the corresponding authentication provider on your {ProjectServer}. + +.Prerequisites +* The base system of your {ProjectServer} must be joined to an Active Directory (AD) domain. +To enable AD users to sign in with Kerberos single sign-on, use the System Security Services Daemon (SSSD) and Samba services to join the base system to the AD domain: ++ +Install the following packages on {ProjectServer}: ++ +[options="nowrap", subs="+quotes,verbatim,attributes"] +---- +# {project-package-install} adcli krb5-workstation oddjob-mkhomedir oddjob realmd samba-winbind-clients samba-winbind samba-common-tools samba-winbind-krb5-locator sssd +---- ++ +Specify the required software when joining the AD domain: ++ +[options="nowrap", subs="+quotes,verbatim,attributes"] +---- +# realm join _AD.EXAMPLE.COM_ --membership-software=samba --client-software=sssd +---- ++ +For more information on direct AD integration, see link:{RHELDocsBaseURL}9/html-single/integrating_rhel_systems_directly_with_windows_active_directory/index#connecting-rhel-systems-directly-to-ad-using-samba-winbind_integrating-rhel-systems-directly-with-active-directory[Connecting RHEL systems directly to AD using Samba Winbind]. + +.Procedure +. Define AD realm configuration in a location where {foreman-installer} expects it: +.. Create a directory named `/etc/ipa/`: ++ +[options="nowrap", subs="+quotes,verbatim,attributes"] +---- +# mkdir /etc/ipa/ +---- ++ +.. Create the `/etc/ipa/default.conf` file with the following contents to configure the Kerberos realm for the AD domain: ++ +[options="nowrap", subs="+quotes,verbatim,attributes"] +---- +[global] +realm = _AD.EXAMPLE.COM_ +---- +. Configure the Apache keytab for Kerberos connections: +.. Update the `/etc/samba/smb.conf` file with the following settings to configure how Samba interacts with AD: ++ +[options="nowrap", subs="+quotes,verbatim,attributes"] +---- +[global] +workgroup = _AD.EXAMPLE_ +realm = _AD.EXAMPLE.COM_ +kerberos method = system keytab +security = ads +---- ++ +.. Add the Kerberos service principal to the keytab file at `/etc/httpd/conf/http.keytab`: ++ +[options="nowrap", subs="+quotes,verbatim,attributes"] +---- +# KRB5_KTNAME=FILE:/etc/httpd/conf/http.keytab net ads keytab add HTTP -U Administrator -s /etc/samba/smb.conf +---- +. Configure the System Security Services Daemon (SSSD) to use the AD access control provider to evaluate and enforce Group Policy Object (GPO) access control rules for the `foreman` PAM service: +.. In the `[domain/_ad.example.com_]` section of your `/etc/sssd/sssd.conf` file, configure the `ad_gpo_access_control` and `ad_gpo_map_service` options as follows: ++ +[options="nowrap", subs="+quotes,verbatim,attributes"] +---- +[domain/_ad.example.com_] +ad_gpo_access_control = enforcing +ad_gpo_map_service = +foreman +---- +ifndef::orcharhino[] ++ +For more information on GPOs, see the following documents: ++ +* link:{RHELDocsBaseURL}9/html/integrating_rhel_systems_directly_with_windows_active_directory/managing-direct-connections-to-ad_integrating-rhel-systems-directly-with-active-directory#how-sssd-interprets-gpo-access-control-rules_applying-group-policy-object-access-control-in-rhel[How SSSD interprets GPO access control rules] in _Integrating RHEL systems directly with Windows Active Directory (RHEL{nbsp}9)_ +* link:{RHELDocsBaseURL}8/html/integrating_rhel_systems_directly_with_windows_active_directory/managing-direct-connections-to-ad_integrating-rhel-systems-directly-with-active-directory#applying-group-policy-object-access-control-in-rhel_managing-direct-connections-to-ad[How SSSD interprets GPO access control rules] in _Integrating RHEL systems directly with Windows Active Directory (RHEL{nbsp}8)_ +endif::[] +.. Restart SSSD: ++ +[options="nowrap", subs="+quotes,verbatim,attributes"] +---- +# systemctl restart sssd +---- +. Enable the authentication source: ++ +[options="nowrap", subs="+quotes,verbatim,attributes"] +---- +# {foreman-installer} --foreman-ipa-authentication=true +---- + +.Verification +* To verify that AD users can log in to {Project} by entering their credentials, log in to {ProjectwebUI} at \https://{foreman-example-com}. +Enter the user name in the user principal name (UPN) format, for example: `_ad_user_@_AD.EXAMPLE.COM_`. +* To verify that AD users can authenticate by using Kerberos single sign-on: +** Obtain a Kerberos ticket-granting ticket (TGT) on behalf of an AD user: ++ +[options="nowrap", subs="+quotes,verbatim,attributes"] +---- +$ kinit _ad_user_@_AD.EXAMPLE.COM_ +---- +** Verify user authentication by using your TGT: ++ +[options="nowrap", subs="+quotes,verbatim,attributes"] +---- +$ curl -k -u : --negotiate https://{foreman-example-com}/users/extlogin + +You are being redirected. +---- + +.Additional resources +* `sssd-ad(5)` man page on your system diff --git a/guides/common/modules/proc_enrolling-server-with-the-ad-server.adoc b/guides/common/modules/proc_enrolling-server-with-the-ad-server.adoc deleted file mode 100644 index 5b73b55108e..00000000000 --- a/guides/common/modules/proc_enrolling-server-with-the-ad-server.adoc +++ /dev/null @@ -1,35 +0,0 @@ -[id="Enrolling_Server_with_the_AD_Server_{context}"] -= Enrolling {ProjectServer} with the AD server - -In the {Project} CLI, enroll {ProjectServer} with the Active Directory server. - -.Prerequisites -* GSS-proxy and {nfs-client-package} are installed. -+ -Installing GSS-proxy and {nfs-client-package}: -+ -[options="nowrap", subs="+quotes,verbatim,attributes"] ----- -# {project-package-install} gssproxy {nfs-client-package} ----- - -.Procedure -. Install the required packages: -+ -[options="nowrap", subs="+quotes,verbatim,attributes"] ----- -# {project-package-install} adcli krb5-workstation \ -oddjob oddjob-mkhomedir realmd samba-common-tools sssd ----- -. Enroll {ProjectServer} with the AD server. -You may need to have administrator permissions to perform the following command: -+ -[options="nowrap", subs="+quotes,verbatim,attributes"] ----- -# realm join -v _EXAMPLE.ORG_ --membership-software=samba -U Administrator ----- -+ -[NOTE] -==== -You must use the Samba client software to enroll with the AD server to create the HTTP keytab in xref:Configuring_Direct_AD_Integration_with_GSS_Proxy_{context}[]. -====