Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 14. Installing an IdM client

Enroll systems into Identity Management (IdM) as clients to centralize authentication and access control. Configure client systems by using the ipa-client-install utility to enable integration with IdM domain services.

14.1. Prerequisites
Copy link

Install Identity Management (IdM) clients interactively using the credentials of an authorized user to enroll the system into the domain securely.

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, adding the options that correspond to your use case:

    • Add the --mkhomedir option to configure PAM to create a user home directory if it does not exist.

    • Consider adding the --enable-dns-updates option to update the DNS records with the IP address of the client system in one of the following situations:

      • Your client has a dynamic IP address issued using the Dynamic Host Configuration Protocol.

      • Your client has a static IP address but it has just been allocated and the IdM server does not know about it.

        IMPORTANT
        Use the --enable-dns-updates option only if your DNS server accepts DNS entry updates with the GSS-TSIG protocol. If your client is going to be enrolled with an IdM server with integrated DNS, this condition is met.

    For example: 

    # ipa-client-install --mkhomedir --enable-dns-updates
    Copy to Clipboard Toggle word wrap

  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
      Copy to Clipboard Toggle word wrap

    • 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:
    Copy to Clipboard Toggle word wrap

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

    Client configuration complete.
    Copy to Clipboard Toggle word wrap

Install Identity Management (IdM) clients interactively by using one-time passwords to securely enroll systems without providing administrator credentials.

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_hostname> 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_hostname> --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
    Copy to Clipboard Toggle word wrap
    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, adding the options that correspond to your use case:

    • 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>
      Copy to Clipboard Toggle word wrap

    • Consider adding the --enable-dns-updates option to update the DNS records with the IP address of the client system in one of the following situations:

      • Your client has a dynamic IP address issued using the Dynamic Host Configuration Protocol.

      • Your client has a static IP address but it has just been allocated and the IdM server does not know about it.

        IMPORTANT
        Use the --enable-dns-updates option only if your DNS server accepts DNS entry updates with the GSS-TSIG protocol. If your client is going to be enrolled with an IdM server with integrated DNS, this condition is met.

    For example: 

    # ipa-client-install --password 'W5YpARl=7M.n' --enable-dns-updates --mkhomedir
    Copy to Clipboard Toggle word wrap

  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
      Copy to Clipboard Toggle word wrap

    • 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.
    Copy to Clipboard Toggle word wrap

Review the non-interactive Identity Management (IdM) client installation options to automate deployment across multiple systems.

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
Copy to Clipboard Toggle word wrap

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

# ipa-client-install --password 'W5YpARl=7M.n' --domain <domain_name> --server <server_hostname> --realm <realm-name> --mkhomedir --unattended
Copy to Clipboard Toggle word wrap

Remove pre-existing LDAP and System Security Services Daemon (SSSD) configurations after you install an Identity Management (IdM) client. You can resolve configuration conflicts and ensure that the host uses IdM settings exclusively by manually updating files that the installation script modified.

The ipa-client-install script preserves existing LDAP and SSSD settings within 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
Copy to Clipboard Toggle word wrap

Procedure

  1. Open /etc/openldap/ldap.conf and /etc/sssd/sssd.conf to apply the new IdM configuration values.
  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.

14.6. Testing an IdM client
Copy link

Verify Identity Management (IdM) client functionality by testing user information resolution and authentication to ensure proper deployment.

Procedure

  • 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)
    Copy to Clipboard Toggle word wrap

  • 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 ~]#
    Copy to Clipboard Toggle word wrap

Understand network operations and protocols used during Identity Management(IdM) client installation to ensure proper network configuration and troubleshoot connectivity issues.

Expand
Table 14.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

Understand network operations performed by Identity Management (IdM) client tools and Web UI after installation to ensure proper connectivity and troubleshoot communication issues.

The client side of IdM framework is implemented with two different applications:

  • The ipa command-line interface (CLI)
  • (optional) the browser-based Web UI .CLI post-installation operations
Expand
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

Expand
Table 14.2. 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

14.9. SSSD communication patterns
Copy link

Review the System Security Services Daemon (SSSD) communication patterns with Identity Management (IdM) servers. You can ensure secure identity lookups, optimize authentication performance, and verify that your firewall rules support the necessary Kerberos, LDAP, and DNS traffic.

If you configure SSSD on an 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.

Expand
Table 14.3. 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

Expand
Table 14.4. 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

14.10. Certmonger communication patterns
Copy link

Understand network operations performed by the Certmonger daemon on Identity Management (IdM) servers and clients to ensure timely SSL certificate renewal.

Certmonger runs on IdM servers and IdM clients to allow a timely renewal of SSL certificates associated with the services on the host.

Expand
Table 14.5. 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.

Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top