Chapter 13. Installing an IdM client
Chapter 13. Installing an IdM client The following sections describe how to configure a system as an Identity Management (IdM) client by using the ipa-client-install utility. Configuring a system as an IdM client enrolls it into an IdM domain and enables the system to use IdM services on IdM servers in the domain. To install an Identity Management (IdM) client successfully, you must provide credentials that can be used to enroll the client. 13.1. Prerequisites You have prepared the system for IdM client installation. For details, see Preparing the system for IdM client installation . 13.2. Installing a client by using user credentials: Interactive installation Follow this procedure to install an Identity Management (IdM) client interactively by using the credentials of an authorized user to enroll the system into the domain. Prerequisites Ensure you have the credentials of a user authorized to enroll clients into the IdM domain. This could be, for example, a hostadmin user with the Enrollment Administrator role. Procedure Run the ipa-client-install utility on the system that you want to configure as an IdM client. Add the --enable-dns-updates option to update the DNS records with the IP address of the client system if either of the following conditions applies: The IdM server the client will be enrolled with was installed with integrated DNS The DNS server on the network accepts DNS entry updates with the GSS-TSIG protocol Enabling DNS updates is useful if your client: has a dynamic IP address issued using the Dynamic Host Configuration Protocol has a static IP address but it has just been allocated and the IdM server does not know about it The installation script attempts to obtain all the required settings, such as DNS records, automatically. If the SRV records are set properly in the IdM DNS zone, the script automatically discovers all the other required values and displays them. Enter yes to confirm. To install the system with different values, enter no . Then run ipa-client-install again, and specify the required values by adding command-line options to ipa-client-install , for example: --hostname --realm --domain --server --mkhomedir Important The fully qualified domain name must be a valid DNS name: Only numbers, alphabetic characters, and hyphens ( - ) are allowed. For example, underscores are not allowed and can cause DNS failures. The host name must be all lower-case. No capital letters are allowed. If the script fails to obtain some settings automatically, it prompts you for the values. The script prompts for a user whose identity will be used to enroll the client. This could be, for example, a hostadmin user with the Enrollment Administrator role: The installation script now configures the client. Wait for the operation to complete. Additional resources For details on how the client installation script searches for the DNS records, see the DNS Autodiscovery section in the ipa-client-install (1) man page. 13.3. Installing a client by using a one-time password: Interactive installation Follow this procedure to install an Identity Management (IdM) client interactively by using a one-time password to enroll the system into the domain. Prerequisites On a server in the domain, add the future client system as an IdM host. Use the --random option with the ipa host-add command to generate a one-time random password for the enrollment. Note The ipa host-add <client_fqdn> command requires that the client FQDN is resolvable through DNS. If it is not resolvable, provide the IdM client system's IP address using the --ip address option or alternatively, use the --force option. Note The generated password will become invalid after you use it to enroll the machine into the IdM domain. It will be replaced with a proper host keytab after the enrollment is finished. Procedure Run the ipa-client-install utility on the system that you want to configure as an IdM client. Use the --password option to provide the one-time random password. Because the password often contains special characters, enclose it in single quotes ('). Add the --enable-dns-updates option to update the DNS records with the IP address of the client system if either of the following conditions applies: The IdM server the client will be enrolled with was installed with integrated DNS The DNS server on the network accepts DNS entry updates with the GSS-TSIG protocol Enabling DNS updates is useful if your client: has a dynamic IP address issued using the Dynamic Host Configuration Protocol has a static IP address but it has just been allocated and the IdM server does not know about it The installation script attempts to obtain all the required settings, such as DNS records, automatically. If the SRV records are set properly in the IdM DNS zone, the script automatically discovers all the other required values and displays them. Enter yes to confirm. To install the system with different values, enter no . Then run ipa-client-install again, and specify the required values by adding command-line options to ipa-client-install , for example: --hostname --realm --domain --server --mkhomedir Important The fully qualified domain name must be a valid DNS name: Only numbers, alphabetic characters, and hyphens ( - ) are allowed. For example, underscores are not allowed and can cause DNS failures. The host name must be all lower-case. No capital letters are allowed. If the script fails to obtain some settings automatically, it prompts you for the values. The installation script now configures the client. Wait for the operation to complete. Additional resources For details on how the client installation script searches for the DNS records, see the DNS Autodiscovery section in the ipa-client-install (1) man page. 13.4. Installing a client: Non-interactive installation For a non-interactive installation, you must provide all required information to the ipa-client-install utility using command-line options. The following sections describe the minimum required options for a non-interactive installation. Options for the intended authentication method for client enrollment The available options are: --principal and --password to specify the credentials of a user authorized to enroll clients --random to specify a one-time random password generated for the client --keytab to specify the keytab from a enrollment The option for unattended installation The --unattended option lets the installation run without requiring user confirmation. If the SRV records are set properly in the IdM DNS zone, the script automatically discovers all the other required values. If the script cannot discover the values automatically, provide them using command-line options, such as: --hostname to specify a static fully qualified domain name (FQDN) for the client machine. Important The FQDN must be a valid DNS name: Only numbers, alphabetic characters, and hyphens (-) are allowed. For example, underscores are not allowed and can cause DNS failures. The host name must be all lower-case. No capital letters are allowed. --domain to specify the primary DNS domain of an existing IdM deployment, such as example.com . The name is a lowercase version of the IdM Kerberos realm name. --server to specify the FQDN of the IdM server to connect to. When this option is used, DNS autodiscovery for Kerberos is disabled and a fixed list of KDC and Admin servers is configured. Under normal circumstances, this option is not needed as the list of servers is retrieved from the primary IdM DNS domain. --realm to specify the Kerberos realm of an existing IdM deployment. Usually it is an uppercase version of the primary DNS domain used by the IdM installation. Under normal circumstances, this option is not needed as the realm name is retrieved from the IdM server. An example of a basic ipa-client-install command for non-interactive installation: An example of an ipa-client-install command for non-interactive installation with more options specified: Additional resources For a complete list of options accepted by ipa-client-install , see the ipa-client-install (1) man page. 13.5. Removing pre-IdM configuration after installing a client The ipa-client-install script does not remove any LDAP and System Security Services Daemon (SSSD) configuration from the /etc/openldap/ldap.conf and /etc/sssd/sssd.conf files. If you modified the configuration in these files before installing the client, the script adds the new client values, but comments them out. For example: Procedure To apply the new Identity Management (IdM)} configuration values: Open /etc/openldap/ldap.conf and /etc/sssd/sssd.conf . Delete the configuration. Uncomment the new IdM configuration. Server processes that rely on system-wide LDAP configuration might require a restart to apply the changes. Applications that use openldap libraries typically import the configuration when started. 13.6. Testing an IdM client The command line informs you that the ipa-client-install was successful, but you can also do your own test. To test that the Identity Management (IdM) client can obtain information about users defined on the server, check that you are able to resolve a user defined on the server. For example, to check the default admin user: To test that authentication works correctly, su to a root user from a non-root user: 13.7. Connections performed during an IdM client installation Requests performed during an IdM client installation lists the operations performed by ipa-client-install , the Identity Management (IdM) client installation tool. Table 13.1. Requests performed during an IdM client installation Operation Protocol used Purpose DNS resolution against the DNS resolvers configured on the client system DNS To discover the IP addresses of IdM servers; (optionally) to add A/AAAA and SSHFP records Requests to ports 88 (TCP/TCP6 and UDP/UDP6) on an IdM replica Kerberos To obtain a Kerberos ticket JSON-RPC calls to the IdM Apache-based web-service on discovered or configured IdM servers HTTPS IdM client enrollment; retrieval of CA certificate chain if LDAP method fails; request for a certificate issuance if required Requests over TCP/TCP6 to ports 389 on IdM servers, using SASL GSSAPI authentication, plain LDAP, or both LDAP IdM client enrollment; identity retrieval by SSSD processes; Kerberos key retrieval for the host principal Network time protocol (NTP) discovery and resolution (optionally) NTP To synchronize time between the client system and an NTP server 13.8. IdM client's communications with the server during post-installation deployment The client side of Identity Management (IdM) framework is implemented with two different applications: The ipa command-line interface (CLI) ( optional ) the browser-based Web UI CLI post-installation operations shows the operations performed by the CLI during an IdM client post-installation deployment. Web UI post-installation operations shows the operations performed by the Web UI during an IdM client post-installation deployment. Table 13.2. CLI post-installation operations Operation Protocol used Purpose DNS resolution against the DNS resolvers configured on the client system DNS To discover the IP addresses of IdM servers Requests to ports 88 (TCP/TCP6 and UDP/UDP6) and 464 (TCP/TCP6 and UDP/UDP6) on an IdM replica Kerberos To obtain a Kerberos ticket; change a Kerberos password; authenticate to the IdM Web UI JSON-RPC calls to the IdM Apache-based web-service on discovered or configured IdM servers HTTPS any ipa utility usage Table 13.3. Web UI post-installation operations Operation Protocol used Purpose JSON-RPC calls to the IdM Apache-based web-service on discovered or configured IdM servers HTTPS To retrieve the IdM Web UI pages Additional resources SSSD communication patterns for more information about how the SSSD daemon communicates with the services available on the IdM and Active Directory servers. Certmonger communication patterns for more information about how the certmonger daemon communicates with the services available on the IdM and Active Directory servers. 13.9. SSSD communication patterns The System Security Services Daemon (SSSD) is a system service to access remote directories and authentication mechanisms. If configured on an Identity Management IdM client, it connects to the IdM server, which provides authentication, authorization and other identity and policy information. If the IdM server is in a trust relationships with Active Directory (AD), SSSD also connects to AD to perform authentication for AD users using the Kerberos protocol. By default, SSSD uses Kerberos to authenticate any non-local user. In special situations, SSSD might be configured to use the LDAP protocol instead. The SSSD can be configured to communicate with multiple servers. The tables below show common communication patterns for SSSD in IdM. Table 13.4. Communication patterns of SSSD on IdM clients when talking to IdM servers Operation Protocol used Purpose DNS resolution against the DNS resolvers configured on the client system DNS To discover the IP addresses of IdM servers Requests to ports 88 (TCP/TCP6 and UDP/UDP6), 464 (TCP/TCP6 and UDP/UDP6), and 749 (TCP/TCP6) on an Identity Management replica and Active Directory domain controllers Kerberos To obtain a Kerberos ticket; to change a Kerberos password Requests over TCP/TCP6 to ports 389 on IdM servers, using SASL GSSAPI authentication, plain LDAP, or both LDAP To obtain information about IdM users and hosts, download HBAC and sudo rules, automount maps, the SELinux user context, public SSH keys, and other information stored in IdM LDAP (optionally) In case of smart-card authentication, requests to the Online Certificate Status Protocol (OCSP) responder, if it is configured. This often is done via port 80, but it depends on the actual value of the OCSP responder URL in a client certificate. HTTP To obtain information about the status of the certificate installed in the smart card Table 13.5. Communication patterns of SSSD on IdM servers acting as trust agents when talking to Active Directory Domain Controllers Operation Protocol used Purpose DNS resolution against the DNS resolvers configured on the client system DNS To discover the IP addresses of IdM servers Requests to ports 88 (TCP/TCP6 and UDP/UDP6), 464 (TCP/TCP6 and UDP/UDP6), and 749 (TCP/TCP6) on an Identity Management replica and Active Directory domain controllers Kerberos To obtain a Kerberos ticket; change a Kerberos password; administer Kerberos remotely Requests to ports 389 (TCP/TCP6 and UDP/UDP6) and 3268 (TCP/TCP6) LDAP To query Active Directory user and group information; to discover Active Directory domain controllers (optionally) In case of smart-card authentication, requests to the Online Certificate Status Protocol (OCSP) responder, if it is configured. This often is done via port 80, but it depends on the actual value of the OCSP responder URL in a client certificate. HTTP To obtain information about the status of the certificate installed in the smart card Additional resources IdM client's communications with the server during post-installation deployment 13.10. Certmonger communication patterns Certmonger is a daemon running on Identity Management (IdM) servers and IdM clients to allow a timely renewal of SSL certificates associated with the services on the host. The Table 13.6, "Certmonger communication patterns" shows the operations performed by the certmonger utility on IdM servers. Table 13.6. Certmonger communication patterns Operation Protocol used Purpose DNS resolution against the DNS resolvers configured on the client system DNS To discover the IP addresses of IdM servers Requests to ports 88 (TCP/TCP6 and UDP/UDP6) and 464 (TCP/TCP6 and UDP/UDP6) on an IdM replica Kerberos To obtain a Kerberos ticket JSON-RPC calls to the IdM Apache-based web-service on discovered or configured IdM servers HTTPS To request new certificates Access over port 8080 (TCP/TCP6) on the IdM server HTTP To obtain an Online Certificate Status Protocol (OCSP) responder and certificate status (on the first installed server or on the server where certificate tracking has been transferred) Access over port 8443 (TCP/TCP6) on the IdM server HTTPS To administer the Certificate Authority on the IdM server (only during IdM server and replica installation). certmonger on the server contacts only its own local server on ports 8080 and 8443 for CA-related certificate renewal. Additional resources IdM client's communications with the server during post-installation deployment
ipa-client-install --mkhomedir ipa-client-install --enable-dns-updates --mkhomedir Client hostname: client.example.com Realm: EXAMPLE.COM DNS Domain: example.com IPA Server: server.example.com BaseDN: dc=example,dc=com Continue to configure the system with these values? [no]: yes User authorized to enroll computers: hostadmin Password for hostadmin @ EXAMPLE.COM : Client configuration complete. ipa host-add client.example.com --random -------------------------------------------------- Added host "client.example.com" -------------------------------------------------- Host name: client.example.com Random password: W5YpARl=7M.n Password: True Keytab: False Managed by: server.example.com ipa-client-install --mkhomedir --password= password ipa-client-install --password 'W5YpARl=7M.n' --enable-dns-updates --mkhomedir Client hostname: client.example.com Realm: EXAMPLE.COM DNS Domain: example.com IPA Server: server.example.com BaseDN: dc=example,dc=com Continue to configure the system with these values? [no]: yes Client configuration complete. ipa-client-install --password ' W5YpARl=7M.n ' --mkhomedir --unattended ipa-client-install --password ' W5YpARl=7M.n ' --domain idm.example.com --server server.idm.example.com --realm IDM.EXAMPLE.COM --mkhomedir --unattended BASE dc=example,dc=com URI ldap://ldap.example.com #URI ldaps://server.example.com # modified by IPA #BASE dc=ipa,dc=example,dc=com # modified by IPA [user@client ~]USD id admin uid=1254400000(admin) gid=1254400000(admins) groups=1254400000(admins) [user@client ~]USD su - Last login: Thu Oct 18 18:39:11 CEST 2018 from 192.168.122.1 on pts/0