Chapter 10. Installing an IdM client: Basic scenario

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.

Several options are available for a basic installation:

10.1. Prerequisites

Before you start installing the IdM client, make sure that you have met all the prerequisites. See Chapter 9, Preparing the system for IdM client installation.

10.2. An overview of the IdM client installation options

To install an Identity Management (IdM) client successfully, you must provide credentials that can be used to enroll the client. The following authentication methods are available:

Additional resources

  • For details on the options accepted by ipa-client-install, see the ipa-client-install(1) man page.

10.3. Installing a client by using user credentials: Interactive installation

This procedure describes installing 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

    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

    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
    • If the script fails to obtain some settings automatically, it prompts you for the values.
    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.
  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.

10.4. Installing a client by using a one-time password: Interactive installation

This procedure describes installing an Identity Management (IdM) client interactively by using a one-time password to enroll the system into the domain.

Prerequisites

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

    $ 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

    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

    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
    • If the script fails to obtain some settings automatically, it prompts you for the values.
    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.
  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.

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

For details, see Section 10.2, “An overview of the IdM client installation options”.

The option for unattended installation

The --unattended 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 host name for the client machine

    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.
  • --server to specify the host name of the IdM server the client will be enrolled with
  • --domain to specify the DNS domain name of the IdM server the client will be enrolled with
  • --realm to specify the Kerberos realm name

An example of a basic ipa-client-install command for non-interactive installation:

# ipa-client-install --password 'W5YpARl=7M.n' --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 example.com --server server.idm.example.com --unattended

Additional resources

  • For a complete list of options accepted by ipa-client-install, see the ipa-client-install(1) man page.

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

10.7. 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 ~]#

10.8. Connections performed during an IdM client installation

Table 10.1, “Requests performed during an IdM client installation” lists the operations performed by ipa-client-install, the Identity Management (IdM) client installation tool.

Table 10.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 masters; (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 masters

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

10.9. 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)
  • the browser-based web UI

The browser-based web UI is optional.

] shows the operations performed by the CLI during an IdM client post-installation deployment. xref:tab-browser-operations_install-client-basic[ shows the operations performed by the web UI during an IdM client post-installation deployment.

Two daemons run on the IdM client, the System Security Services Daemon (SSSD) and certmonger. ] and xref:certmonger-deployment-operations_install-client-basic[ describe how these daemons communicate with the services available on the IdM and Active Directory servers.

Table 10.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 masters

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 masters

HTTPS

any ipa utility usage

Table 10.3. webUI post-installation operations

OperationProtocol usedPurpose

JSON-RPC calls to the IdM Apache-based web-service on discovered or configured IdM masters

HTTPS

To retrieve the IdM web UI pages

10.9.1. 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. Communication patterns of SSSD on IdM clients when talking to IdM servers and Communication patterns of SSSD on IdM servers acting as trust agents when talking to Active Directory Domain Controllers show common communication patterns for SSSD in IdM.

Table 10.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 masters

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 10.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 masters

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

10.9.2. Certmonger communication patterns

Certmonger is a daemon running on Identity Management (IdM) masters and IdM clients to allow a timely renewal of SSL certificates associated with the services on the host. The Table 10.6, “Certmonger communication patterns” shows the operations performed by IdM client’s certmonger utility on IdM masters.

Table 10.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 masters

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 masters

HTTPS

To request new certificates

Access over port 8080 (TCP/TCP6) on the IdM master

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 master

HTTPS

To administer the Certificate Authority on the IdM master (only during IdM master and replica installation)