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

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

  1. Run the ipa-client-install utility on the system that you want to configure as an IdM client. 

    # ipa-client-install --mkhomedir

    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 
    # ipa-client-install --enable-dns-updates --mkhomedir

    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

  2. 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. 

      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

    • 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.

  3. 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: 

    User authorized to enroll computers: hostadmin
Password for hostadmin@EXAMPLE.COM:

  4. The installation script now configures the client. Wait for the operation to complete. 

    Client configuration 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. 

    $ 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
    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

  1. 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 ('). 

    # ipa-client-install --mkhomedir --password=password

    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 
    # ipa-client-install --password 'W5YpARl=7M.n' --enable-dns-updates --mkhomedir

    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

  2. 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. 

      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

    • 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.

  3. The installation script now configures the client. Wait for the operation to complete. 

    Client configuration 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 previous 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: 

# ipa-client-install --password 'W5YpARl=7M.n' --mkhomedir --unattended

 

An example of an ipa-client-install command for non-interactive installation with more options specified: 

# ipa-client-install --password 'W5YpARl=7M.n' --domain idm.example.com --server server.idm.example.com --realm IDM.EXAMPLE.COM --mkhomedir --unattended

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 previous 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: 

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

To apply the new Identity Management (IdM)} configuration values:

  1. Open /etc/openldap/ldap.conf and /etc/sssd/sssd.conf.
  2. Delete the previous configuration.
  3. Uncomment the new IdM configuration.
  4. 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 interface 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: 

[user@client ~]$ id admin
uid=1254400000(admin) gid=1254400000(admins) groups=1254400000(admins)

To test that authentication works correctly, su to a root user from a non-root user: 

[user@client ~]$ su -
Last login: Thu Oct 18 18:39:11 CEST 2018 from 192.168.122.1 on pts/0
[root@client ~]#

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

OperationProtocol usedPurpose

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

OperationProtocol usedPurpose

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

OperationProtocol usedPurpose

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

OperationProtocol usedPurpose

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

OperationProtocol usedPurpose

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

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

OperationProtocol usedPurpose

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