Chapter 14. 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.
14.1. Prerequisites
- You have prepared the system for IdM client installation. For details, see Preparing the system for IdM client installation.
14.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.# 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
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 runipa-client-install
again, and specify the required values by adding command-line options toipa-client-install
, for example:-
--hostname
-
--realm
-
--domain
-
--server
-
--mkhomedir
ImportantThe 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:User authorized to enroll computers:
hostadmin
Password forhostadmin
@EXAMPLE.COM
: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 theipa-client-install
(1) man page.
14.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 theipa host-add
command to generate a one-time random password for the enrollment.NoteThe
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
NoteThe 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 (').# 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
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 runipa-client-install
again, and specify the required values by adding command-line options toipa-client-install
, for example:-
--hostname
-
--realm
-
--domain
-
--server
-
--mkhomedir
ImportantThe 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.
Client configuration complete.
Additional resources
-
For details on how the client installation script searches for the DNS records, see the
DNS Autodiscovery
section in theipa-client-install
(1) man page.
14.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.ImportantThe 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 asexample.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.
14.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:
-
Open
/etc/openldap/ldap.conf
and/etc/sssd/sssd.conf
. - Delete the previous 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.
14.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 ~]#
14.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.
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 |
14.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.
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 |
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.
14.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.
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 |
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
14.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 14.6, “Certmonger communication patterns” shows the operations performed by the certmonger
utility on 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) 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). |
Additional resources