diff --git a/guides/common/assembly_configuring-active-directory-as-an-external-identity-provider-for-project.adoc b/guides/common/assembly_configuring-active-directory-as-an-external-identity-provider-for-project.adoc index 57abef317cb..ef122b7a3a6 100644 --- a/guides/common/assembly_configuring-active-directory-as-an-external-identity-provider-for-project.adoc +++ b/guides/common/assembly_configuring-active-directory-as-an-external-identity-provider-for-project.adoc @@ -1,9 +1,5 @@ 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/proc_configuring-the-active-directory-authentication-source-on-projectserver.adoc[leveloffset=+1] include::modules/con_kerberos-configuration-in-web-browsers.adoc[leveloffset=+1] diff --git a/guides/common/modules/con_configuring-active-directory-as-an-external-identity-provider-for-project.adoc b/guides/common/modules/con_configuring-active-directory-as-an-external-identity-provider-for-project.adoc index bcf75ce6d00..376e14846d4 100644 --- a/guides/common/modules/con_configuring-active-directory-as-an-external-identity-provider-for-project.adoc +++ b/guides/common/modules/con_configuring-active-directory-as-an-external-identity-provider-for-project.adoc @@ -1,23 +1,23 @@ [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}. +If the base system of your {ProjectServer} is connected directly to Active Directory (AD), you can configure AD as an external authentication source for {Project}. +Direct AD integration means that a Linux system is joined directly to the AD domain where the identity is stored. +The following login methods are available for AD users: + +* Username and password +* Kerberos single sign-on [NOTE] ==== -You can attach Active Directory as an external authentication source with no single sign-on support. +You can also connect your {Project} deployment to AD in the following ways: + +* By using indirect AD integration. +With indirect integration, your {ProjectServer} is connected to a {FreeIPA} server which is then connected to AD. +For more information, see xref:configuring-kerberos-single-sign-on-with-{Freeipa-context}-in-project_{context}[]. +* By attaching the LDAP server of the AD domain as an external authentication source with no single sign-on support. For more information, see xref:configuring-an-ldap-server-as-an-external-identity-provider-for-project_{context}[]. ifndef::orcharhino[] For an example configuration, see https://access.redhat.com/solutions/1498773[How to configure Active Directory authentication with TLS on {Project}]. 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}[]. - -ifndef::orcharhino[] -For information about integrating {RHEL} systems with Active{nbsp}Directory, see link:{RHELDocsBaseURL}8/html/integrating_rhel_systems_directly_with_windows_active_directory/index[{RHEL}{nbsp}8 _Integrating RHEL systems directly with Windows Active Directory_]. -endif::[] 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/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 04b5521e1a4..00000000000 --- a/guides/common/modules/proc_configuring-direct-ad-integration-with-gss-proxy.adoc +++ /dev/null @@ -1,150 +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 ----- -. 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 your `/etc/sssd/sssd.conf` file, add the following lines to the `domain` section for the Active Directory domain: -+ -[options="nowrap", subs="+quotes,verbatim,attributes"] ----- -[domain/_EXAMPLE_] -access_provider = ad -ad_gpo_access_control = enforcing -ad_gpo_map_service = +foreman ----- -ifndef::orcharhino[] -+ -For more information on GPOs, see 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 _{RHEL}{nbsp}9 Integrating RHEL systems directly with Windows Active Directory_ or 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 _{RHEL}{nbsp}8 Integrating RHEL systems directly with Windows Active Directory_. -endif::[] -.. Restart the `sssd` service: -+ -[options="nowrap", subs="+quotes,verbatim,attributes"] ----- -# systemctl restart sssd ----- -. 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 ----- - -.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. ----- - -.Additional resources - -* For more information about the options to configure an Active Directory provider for SSSD, see the `sssd-ad(5)` man page. 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}[]. -====