RH362 - ch03s03

Bookmark this page

Installing an Identity Management Client

Objectives

Choose an installation method, configure the system prerequisites, and install an IdM client.

Installing Identity Management Clients

After the installation of an IdM server, administrators can enroll clients. An IdM client is a system that can authenticate users who are members of the IdM domain. Although systems such as Solaris, AIX, and other Linux distributions can be configured as IdM clients, Red Hat only supports IdM packages supplied by Red Hat and installed on Red Hat Enterprise Linux. There is limited support for Windows clients, but only as members of a trusted Active Directory forest.

Prerequisites for Installing a Client

Before enrolling an IdM client, take the following considerations into account:

The system must be able to authenticate to the Kerberos domain. This can be accomplished by either having an available Kerberos identity, such as the administrative user, or by manually adding the client machine to the Key Distribution Center (KDC) on the IdM server.
If there is another DNS server on the network that is authoritative for another domain, such as Active Directory, the client might not automatically detect the IdM domain. The ipa-client-install command could retrieve the Active Directory DNS records instead of any records that are added for IdM. In this case, you must pass the IdM server address as an option to the ipa-client-install command.
Red Hat does not recommend running the Name Service Caching Daemon (NSCD) on clients. If NSCD must be running, only enable it for maps that SSSD does not cache. The NSCD and the SSSD services both perform caching, which can lead to problems when the services are used on the same system.

IdM Client Components

IdM clients do not require dedicated client software to interact as a part of a domain. Installing the ipa-client package ensures that the dependencies are installed, and provides the ipa-client-install command to configure those dependencies for the IdM domain.

The following list includes some of the services hosted by IdM clients:

System Security Services Daemon (SSSD): A client-side application for caching credentials. This service is recommended, because it simplifies client configuration.
Certmonger: The certmonger service monitors and renews the security certificates on the client. This service can request new certificates for services running on the client system.

Figure 3.1: Hosted services on IdM clients

Note

For more information about the certmonger service, consult the Managing certificates in IdM guide listed in the references section.

Client Installation Methods

You can use any of the following methods to enroll a client:

The manual, interactive method: The interactive method uses the ipa-client-install command, which prompts you for various settings, such as the Kerberos principal, the domain, and an administrative password. The interactive method is useful for troubleshooting or getting acquainted with the product.
The unattended, non-interactive method: This method provides all required information to the ipa-client-install command by parsing a set of parameters passed as options. The non-interactive method has several minimum requirements, including the options that specify the credentials, and the use of the --unattended option, which bypasses any user confirmation to install the client. Configuring an IdM client during kickstart installation is also considered unattended.
The automated, non-interactive method: This method uses an Ansible Playbook from the FreeIPA collection to enroll a client.

Note

Installation of IdM clients, servers, and replicas using Ansible is covered in a later section.

Requirements for Installing Clients

Before you enroll a client system, install the ipa-client package. This package also installs dependencies, such as the System Security Services Daemon (SSSD) and Simple Authentication and Security Layer (SASL) library packages.

The ipa-client-install command configures the host as an IdM client. During the installation process, you are required to provide credentials that are used to enroll the client. Three authentication methods are supported:

Explicit use of credentials of a user with the Enrollment Administrator role, such as the admin user. The ipa-client-install command uses credentials as the default method. These administrative credentials are used to create the host object in IdM, which unprivileged users cannot do.
A random one-time password (OTP), generated by the server. An administrative user creates the host object in advance, running the ipa host-add client --random command to generate an OTP. To use the generated OTP, run the ipa-client-install command with the --password=OTP option.
A principal in keytab form, from a previous enrollment. Add the --keytab option when running the ipa-client-install command. No privileges on the IdM domain are required.

Enrolling Clients Using the Manual Installation Method

When performing the manual, interactive installation, you are prompted for the various settings that define the IdM domain. This includes the hostname, and the username and password of the administrative user. The following procedure describes how to install a client using the interactive method.

Run the ipa-client-install command. Use the --enable-dns-updates option if the IdM server is installed with integrated DNS, or if the external DNS server accepts DNS entry updates (from the Generic Security Service Algorithm for Secret Key Transaction (GSS-TSIG) protocol).

The installer attempts to obtain all the required settings automatically. If your DNS zone and SRV records are correctly configured, the installer can discover all the required values and output them:

Client hostname: host.lab.example.com
Realm: LAB.EXAMPLE.COM
DNS Domain: lab.example.com
IPA Server: idm.lab.example.com
BaseDN: dc=lab,dc=example,dc=com
Continue to configure the system with these values? [no]: yes

To input different values, cancel the current installation, and then rerun the command and provide the required values using the command-line options. If the installer cannot obtain certain settings automatically, then it prompts you for those values.

Important

The fully qualified domain name must be a valid DNS name. Other characters, such as underscores, in the hostname can cause DNS failures.

For recommended naming practices, consult the hostname(7) man page.

The installer prompts for a user identity to enroll the client. By default, the installer uses the admin user:

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

The installer can now configure the client. This includes enrollment in the realm, the SSSD configuration, and the creation of SSH public keys:

...output omitted...
SSSD enabled
Configured /etc/openldap/ldap.conf
Configured /etc/ssh/ssh_config
Configured /etc/ssh/sshd_config
Configuring lab.example.com as NIS domain.
Client configuration complete.
The ipa-client-install command was successful

Enrolling Clients Using the Unattended Installation Method

You can install an IdM client in unattended mode; that is, an automated installation that parses the various options passed on the command line. For an unattended installation, provide all required information to the ipa-client-install command using command-line options. Use the --unattended option to let the installation run without requiring confirmation.

The following table lists the options supported for unattended installation. Each option requires a double dash, for example, --unattended.

Option	Description
`--unattended`	Indicates to the installation to run without requiring user confirmation.
`--hostname`	Specifies the hostname for the client machine.
`--password`	Specifies the password to use for the enrollment.
`--server`	Specifies the hostname of the IdM server that the client uses for the enrollment.
`--domain`	Specifies the domain of the IdM server that the client uses for the enrollment.
`--realm`	Specifies the Kerberos realm name.
`--enable-dns-updates`	Updates the DNS records with the client IP address. This only applies if the IdM server is installed with integrated DNS or if GSS-TSIG is configured on the DNS servers present in the network.
`--no-krb5-offline-passwords`	Disables storage of the Kerberos passwords in the SSSD cache.

You can generate a random one-time password for any new client you need to enroll. To generate a one-time password:

Run the kinit command to obtain a Kerberos ticket from any enrolled client.
```
[user@host ~]$ kinit admin
```

Use the --random option with the ipa host-add command to generate the random password. The password is used for the enrollment process.

[user@host ~]$ ipa host-add client.lab.example.com --random
--------------------------------------------------
Added host "client.lab.example.com"
--------------------------------------------------
Host name: client.lab.example.com
Random password: W5YpARl=7M.n
Password: True
Keytab: False
Managed by: server.lab.example.com

Note

After you use a one-time password to enroll a system in the IdM domain, the password becomes invalid. It is replaced with a new host keytab after enrollment.

Enrolling IdM Clients Using Kickstart

You can use Kickstart to enroll clients to an IdM domain during operating system installation.

To enroll a client using Kickstart:

Run the kinit command to obtain a Kerberos ticket from any currently enrolled client:
```
[user@host ~]$ kinit admin
```

Use the --random option with the ipa host-add command to generate a random password. This password is used for the enrollment process.

[user@host ~]$ ipa host-add client.lab.example.com --random
--------------------------------------------------
Added host "client.lab.example.com"
--------------------------------------------------
Host name: client.lab.example.com
Random password: W5YpARl=7M.n
Password: True
Keytab: False
Managed by: server.lab.example.com

Add the ipa-client package in the %packages group:

%packages
@ X Window System
@ Desktop
@ Sound and Video
ipa-client
...output omitted...

Add the installation directive in the %post section of the Kickstart file:

%post --log=/root/ks-post.log
## SSH Keys
/usr/libexec/openssh/sshd-keygen rsa 

## Environment Variables
env DBUS_SYSTEM_BUS_ADDRESS=unix:path=/dev/null getcert list
env DBUS_SYSTEM_BUS_ADDRESS=unix:path=/dev/null ipa-client-install 

## IPA Client Installation
/usr/sbin/ipa-client-install \
  --hostname=client.lab.example.com \
  --domain=LAB.EXAMPLE.COM \
  --enable-dns-updates \
  --mkhomedir \
  --password W5YpARl=7M.n \
  --realm=LAB.EXAMPLE.COM \
  --server=server.lab.example.com \
  --unattended

	Generates SSH keys to ensure that the `ipa-client-install` command uploads them to the IdM server.
	Sets the system bus address to `/dev/null` for the `getcert` and `ipa-client-install` utilities.
	Runs the enrollment process in unattended mode.

Important

Red Hat recommends that you do not start the sshd service before Kickstart enrollment.

Post-installation Steps

The ipa-client-install command does not remove any previous LDAP or SSSD configuration from the /etc/openldap/ldap.conf and /etc/sssd/sssd.conf files. If you customized these files before enrolling the client, the command adds the new client values, but comments them out.

The following excerpt shows the modified ldap.conf configuration file.

BASE   dc=lab,dc=example,dc=com

URI ldap://ldap.lab.example.com
# URI ldaps://server.lab.example.com # modified by IPA
# BASE dc=ipa,dc=example,dc=com # modified by IPA

To apply the new IdM configuration values, open the /etc/openldap/ldap.conf and /etc/sssd/sssd.conf configuration files and delete the previous configuration. Uncomment the new IdM configuration, and then restart the services that rely on the LDAP configuration to apply the changes. Applications that use the openldap libraries import the configuration when started.

Testing the Client

After enrolling the client, ensure that the client can obtain information about the users defined in the server. The lack of output from the grep command indicates that the admin user is not defined locally. The output of the id command shows that the admin user is resolved correctly on the client machine.

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

Exploring Client Log Files

The client installation provides several log files that you can review to troubleshoot problems. The following table lists the various log files and their usage.

Directory or File	Description
`/var/log/ipaclient-install.log`	The installation log for the IdM client.
`/var/log/sssd/`	SSSD log files.
`~/.ipa/log/cli.log`	The log file for errors returned by JSON-RPC calls and responses by the `ipa` utility. The file is created in the home directory for the system user who runs the `ipa` tools.
`/var/log/messages`	Contains messages from system services.

To review log entries related to client enrollment, access the IdM server over SSH. Entries are logged in the /var/log/krb5kdc.log file.

[user@idm ~]$ grep client /var/log/krb5kdc.log
...output omitted...
Feb 14 12:09:30 idm.lab.example.com krb5kdc[5777](info): AS_REQ (8 etypes {18 17 20 19 16 23 25 26}) 172.25.250.10: NEEDED_PREAUTH: host/client.lab.example.com@LAB.EXAMPLE.COM for krbtgt/LAB.EXAMPLE.COM@LAB.EXAMPLE.COM, Additional pre-authentication required
Feb 14 12:09:30 idm.lab.example.com krb5kdc[5777](info): AS_REQ (8 etypes {18 17 20 19 16 23 25 26}) 172.25.250.10: ISSUE: authtime 1518570570, etypes {rep=18 tkt=18 ses=18}, host/client.lab.example.com@LAB.EXAMPLE.COM for krbtgt/LAB.EXAMPLE.COM@LAB.EXAMPLE.COM
Feb 14 12:09:30 idm.lab.example.com krb5kdc[5776](info): TGS_REQ (8 etypes {18 17 20 19 16 23 25 26}) 172.25.250.10: ISSUE: authtime 1518570570, etypes {rep=18 tkt=18 ses=18}, host/client.lab.example.com@LAB.EXAMPLE.COM for ldap/idm.lab.example.com@LAB.EXAMPLE.COM

Note the Authentication Server requests (AS_REQ) and the Ticket Granting Server requests (TGS_REQ). The /var/log/messages log file also contains entries related to IdM.

[user@idm ~]$ grep client /var/log/messages
...output omitted...
Feb 14 10:39:29 idm named-pkcs11[5944]: client 172.25.250.10#41844/key host/client.lab.example.com\@LAB.EXAMPLE.COM: updating zone 'lab.example.com/IN': adding an RR at 'client.lab.example.com' SSHFP

This log entry shows the creation of an SSH fingerprint (SSHFP) DNS resource record for a client.

Uninstalling an IdM Client

You can uninstall an IdM client at any time. Uninstalling a client removes the client from the IdM domain, along with all the IdM-specific configuration for the system services, such as SSSD. The uninstallation process restores the client machine to its previous configuration.

To uninstall a client, run the ipa-client-install command with the --uninstall option. If external DNS is used, then remove the DNS entries for the client; integrated DNS entries are removed automatically.

Enrolling a Previously Uninstalled Client

If a client is unenrolled, but still has its keytab, you can re-enroll it either interactively or noninteractively. Re-enrollment using the client keytab is appropriate for automated installation, or in other situations when using the administrator password is impossible.

To enroll a client interactively, give the client the same hostname, and then run the ipa-client-install command with the --force-join option.

[user@client ~]$ ipa-client-install --force-join

To enroll a client noninteractively, back up the original client's keytab file.

Recreate the client machine with the same hostname, place the backup keytab in the /tmp or /root directory, and then run the ipa-client-install command with the --keytab option.

[user@client ~]$ ipa-client-install --keytab /tmp/krb5.keytab

Note

The keytab specified by the --keytab option is only used when authenticating the client during the initial enrollment. During the re-enrollment process, the IdM server generates a new keytab for the client.

References

ipa-client-install(1) and hostname(7) man pages

DNS Autodiscovery section in the ipa-client-install(1) man page.

Further information is available in the Installing an IdM Client section of the Installing Identity Management guide at https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html-single/installing_identity_management/index#assembly_installing-an-idm-client_installing-identity-management

Further information is available in the Managing Certificates in IdM guide at https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html-single/managing_certificates_in_idm/index

Discuss Red Hat Security: Identity Management and Authentication

Go to community

Welcome to the Red Hat Security: Identity Management and Active Directory Integration group!

Syed

26 wrz 2023

We are excited to launch a space dedicated to the Red Hat Training course Red Hat Security: Identity Management and Active Directory Integration! To gain the most value from this group - click the "Join Group" button in the upper right hand corner of the group home page.We encourage group members to collaborate in this group to discuss topics, ask questions, share best practices and tips, provide course feedback, and share their accomplishments as it relates to RH362.Read more about Red Hat Security: Identity Management and Active Directory Integration here.

215

Revision: rh362-9.1-4c6fdb8