Chapter 3. Setting up Systems as IdM Clients

A client is any system which is a member of the Identity Management domain. While this is frequently a Red Hat Enterprise Linux system (and IdM has special tools to make configuring Red Hat Enterprise Linux clients very simple), machines with other operating systems can also be added to the IdM domain.

One important aspect of an IdM client is that only the system configuration determines whether the system is part of the domain. (The configuration includes things like belonging to the Kerberos domain, DNS domain, and having the proper authentication and certificate setup.)

NOTE

IdM does not require any sort of agent or daemon running on a client for the client to join the domain. However, for the best management options, security, and performance, clients should run the System Security Services Daemon (SSSD).

For more information on SSSD, see the SSSD chapter in the Deployment Guide.

This chapter explains how to configure a system to join an IdM domain.

NOTE

Clients can only be configured after at least one IdM server has been installed.

3.1. What Happens in Client Setup

Whether the client configuration is performed automatically on Red Hat Enterprise Linux systems using the client setup script or manually on other systems, the general process of configuring a machine to serve as an IdM client is mostly the same, with slight variation depending on the platform:

Retrieve the CA certificate for the IdM CA.
Create a separate Kerberos configuration to test the provided credentials. This enables a Kerberos connection to the IdM XML-RPC server, necessary to join the IdM client to the IdM domain. This Kerberos configuration is ultimately discarded.
Setting up the Kerberos configuration includes specifying the realm and domain details, and default ticket attributes. Forwardable tickets are configured by default, which facilitates connection to the administration interface from any operating system, and also provides for auditing of administration operations. For example, this is the Kerberos configuration for Red Hat Enterprise Linux systems:
```
[libdefaults]default_realm = EXAMPLE.COMdns_lookup_realm = falsedns_lookup_kdc = falserdns = falseforwardable = yesticket_lifetime = 24h[realms]EXAMPLE.COM = {  kdc = ipaserver.example.com:88  admin_server = ipaserver.example.com:749  }[domain_realm].example.com = EXAMPLE.COMexample.com = EXAMPLE.COM
```
Run the ipa-join command to perform the actual join
Obtain a service principal for the host service and installs it into /etc/krb5.keytab. For example, host/[email protected].
Enable certmonger, retrieve an SSL server certificate, and install the certificate in /etc/pki/nssdb.
Disable the nscd daemon.
Configures SSSD or LDAP/KRB5, including NSS and PAM configuration files.
Configures an OpenSSH server and client, as well as enabling the host to create DNS SSHFP records.
Configure NTP.

3.2. System Ports

IdM uses a number of ports to communicate with its services. These ports, listed in Table 3.1, "IdM Ports", must be open and available for IdM to work. They cannot be in use by another service or blocked by a firewall. To make sure that these ports are available, try iptables to list the available ports or nc, telnet, or nmap to connect to a port or run a port scan.

To open a port:

# iptables -A INPUT -p tcp --dport 389 -j ACCEPT

The iptables man page has more information on opening and closing ports on a system.

Table 3.1. IdM Ports

Service

Ports

Type

HTTP/HTTPS

443

TCP

LDAP/LDAPS

389

636

TCP

Kerberos

464

TCP and UDP

DNS

TCP and UDP

NTP

123

UDP

3.3. Configuring a Red Hat Enterprise Linux System as an IdM Client

There are two elements to prepare before beginning the client setup process for the Red Hat Enterprise Linux client:

There must be a way to connect the client machine to the Kerberos domain, either by having an available Kerberos identity (such as the admin user) or by manually adding the client machine to the KDC on the server with a one-time password before beginning the enrollment process for the client machine.
If there is an Active Directory server on the same network that serves DNS records, the Active Directory DNS records could prevent the client from automatically detecting the IdM server address. The ipa-client-install script retrieves the Active Directory DNS records instead of any records that were added for IdM.
In this case, it is necessary to pass the IdM server address directly to the ipa-client-install script.

To configure the client:

Install the client packages. These packages provide a simple way to configure the system as a client; they also install and configure SSSD.
For a regular user system, this requires only the ipa-client package:
```
# yum install ipa-client
```
An administrator machine requires the ipa-admintools package, as well:
```
# yum install ipa-client ipa-admintools
```
If the IdM server is configured as the DNS server and is in the same domain as the client, add the server's IP address as the first entry in the client's /etc/resolv.conf file.
TIP
If every machine in the domain will be an IdM client, then add the IdM server address to the DHCP configuration.
Run the client setup command.
```
# ipa-client-install --enable-dns-updates
```
The --enable-dns-updates option updates DNS with the client machine's IP address. This option should only be used if the IdM server was installed with integrated DNS or if the DNS server on the network accepts DNS entry updates with the GSS-TSIG protocol.
When using the --server option to specify the IdM server to register with, the server name must be a fully-qualified domain name.
IMPORTANT
This must be a valid DNS name, which means only numbers, alphabetic characters, and hyphens (-) are allowed. Other characters, like underscores, in the hostname will cause DNS failures.
Other options for ipa-client-install are listed in the ipa-client-install manpage.
NOTE
There is an --on-master option that is used as part of configuring an IdM server (which also is an IdM client, since it is within the domain). This option should never be used when configuring a regular IdM client, because it results in slightly different client configuration which may not work on a non-IdM server machine.

If prompted, enter the domain name for the IdM DNS domain.

DNS discovery failed to determine your DNS domainPlease provide the domain name of your IPA server (ex: example.com): example.com

If prompted, enter the fully-qualified domain name of the IdM server. Alternatively, use the --server option with the client installation script to supply the fully-qualified domain name of the IdM server.
```
DNS discovery failed to find the IPA ServerPlease provide your IPA server name (ex: ipa.example.com): ipaserver.example.com
```
IMPORTANT
This must be a valid DNS name, which means only numbers, alphabetic characters, and hyphens (-) are allowed. Other characters, like underscores, in the hostname will cause DNS failures.

The client script then prompts for a Kerberos identity to use to contact and then join the Kerberos realm. When these credentials are supplied, then the client is able to join the IdM Kerberos domain and then complete the configuration:

Continue to configure the system with these values? [no]: yesUser authorized to enroll computers: adminPassword for [email protected]:Enrolled in IdM realm EXAMPLE.COMCreated /etc/ipa/default.confConfigured /etc/sssd/sssd.confConfigured /etc/krb5.conf for IdM realm EXAMPLE.COMSSSD enabledKerberos 5 enabledNTP enabledClient configuration complete.

Test that the client can connect successfully to the IdM domain and can perform basic tasks. For example, check that the IdM tools can be used to get user and group information:
```
$ id$ getent passwd userID$ getent group ipausers
```
Set up NFS to work with Kerberos.
TIP
To help troubleshoot potential NFS setup errors, enable debug information in the /etc/sysconfig/nfs file.
```
RPCGSSDARGS="-vvv"RPCSVCGSSDARGS="-vvv"
```
1. On an IdM server, add an NFS service principal for the NFS client.
```
# ipa service-add nfs/ipaclient.example.com@EXAMPLE
```
  NOTE
  This must be run from a machine with the ipa-admintools package installed so that the ipa command is available.
2. On the IdM server, obtain a keytab for the NFS service principal.
```
# ipa-getkeytab -s ipaserver.example.com -p nfs/ipaclient.example.com@EXAMPLE -k /tmp/krb5.keytab
```
  NOTE
  Some versions of the Linux NFS implementation have limited encryption type support. If the NFS server is hosted on a version older than Red Hat Enterprise Linux 6, use the -e des-cbc-crc option to the ipa-getkeytab command for any nfs/<FQDN> service keytabs to set up, both on the server and on all clients. This instructs the KDC to generate only DES keys.
  When using DES keys, all clients and servers that rely on this encryption type need to have the allow_weak_crypto option enabled in the [libdefaults] section of the /etc/krb5.conf file. Without these configuration changes, NFS clients and servers are unable to authenticate to each other, and attempts to mount NFS filesystems may fail. The client's rpc.gssd and the server's rpc.svcgssd daemons may log errors indicating that DES encryption types are not permitted.
3. Copy the keytab from the IdM server to the IdM client. For example:
```
# scp /tmp/krb5.keytab [email protected]:/etc/krb5.keytab
```
4. Configure the /etc/exports file on the NFS server.
```
/ipashare   gss/krb5p(rw,no_root_squash,subtree_check,fsid=0)
```
5. On the client, mount the NFS share. Use the same -o sec setting as is used in the /etc/exports file for the NFS server.
```
[root@client ~]# mount -v -t nfs4 -o sec=krb5p nfs.example.com:/ /mnt/ipashare
```

3.4. Manually Configuring a Linux Client

The ipa-client-install command automatically configures services like Kerberos, SSSD, PAM, and NSS. However, if the ipa-client-install command cannot be used on a system for some reason, then the IdM client entries and the services can be configured manually.

Install SSSD 1.5.x or later, if it is not already installed.
Optional. Install the IdM tools so that administrative tasks can be performed from the host.
```
# yum install ipa-admintools
```
On an IdM server. Create a host entry for the client.
```
$ ipa host-add --force --ip-address=192.168.166.31 ipaclient.example.com
```
Creating hosts manually is covered in Section 6.2, "Adding Host Entries".

On an IdM server. Create keytabs for the client.

Set the client host to be managed by the server.

$ ipa host-add-managedby --hosts=ipaserver.example.com ipaclient.example.com

Generate the keytab for the client.

$ ipa-getkeytab -s ipaserver.example.com -p host/ipaclient.example.com -k /tmp/ipaclient.keytab

Copy the keytab to the client machine and rename it /etc/krb5.keytab.
TIP
If there is an existing /etc/krb5.keytab that should be preserved, the two files can be combined using ktutil.
Set the correct user permissions and, if necessary, SELinux contexts for the /etc/krb5.keytab file.
```
chown root:root 0600system_u:object_r:krb5_keytab_t:s0
```

Configure SSSD by editing the /etc/sssd/sssd.conf file to point to the IdM domain.

[sssd]config_file_version = 2services = nss, pamdomains = example.com[nss][pam][domain/example.com]cache_credentials = Truekrb5_store_password_if_offline = Trueipa_domain = example.comid_provider = ipaauth_provider = ipaaccess_provider = ipaipa_hostname = ipaclient.example.comchpass_provider = ipaipa_server = ipaserver.example.comldap_tls_cacert = /etc/ipa/ca.crt

Configure NSS to use SSSD for passwords, groups, users, and netgroups.

vim /etc/nsswitch.conf...passwd: files sssshadow: files sssgroup:  files sss...netgroup:   files sss...

Configure the /etc/krb5.conf file to point to the IdM KDC.

[logging] default = FILE:/var/log/krb5libs.log kdc = FILE:/var/log/krb5kdc.log admin_server = FILE:/var/log/kadmind.log[libdefaults] default_realm = EXAMPLE.COM dns_lookup_realm = false dns_lookup_kdc = false rdns = false ticket_lifetime = 24h forwardable = yes allow_weak_crypto = true[realms] EXAMPLE.COM = {  kdc = ipaserver.example.com:88  admin_server = ipaserver.example.com:749  default_domain = example.com}[domain_realm] .example.com = EXAMPLE.COM example.com = EXAMPLE.COM

Update the /etc/pam.d configuration to use the pam_sss.so modules.

For /etc/pam.d/fingerprint-auth:

...account [default=bad success=ok user_unknown=ignore] pam_sss.so...session optional  pam_sss.so

For /etc/pam.d/system-auth:

...auth sufficient pam_sss.so use_first_pass...account [default=bad success=ok user_unknown=ignore] pam_sss.so...password sufficient pam_sss.so use_authtok...session optional  pam_sss.so

For /etc/pam.d/password-auth:

...auth sufficient pam_sss.so use_first_pass...account [default=bad success=ok user_unknown=ignore] pam_sss.so...password sufficient pam_sss.so use_authtok...session optional  pam_sss.so

For /etc/pam.d/smartcard-auth:

...account [default=bad success=ok user_unknown=ignore] pam_sss.so...session optional  pam_sss.so

Install the IdM server's CA certificate.

Obtain the certificate from the server.

[root@ipaclient ~]# wget -O /etc/ipa/ca.crt http://ipa.example.com/ipa/config/ca.crt

Install the certificate in the system's NSS database.

[root@ipaclient ~]# certutil -A -d /etc/pki/nssdb -n "IPA CA" -t CT,C,C -a -i /etc/ipa/ca.crt

Set up a host certificate for the host in IdM.
1. Make sure certmonger is running.
```
[root@ipaclient ~]# service certmonger start
```
  TIP
  Configure chkconfig so that the certmonger service starts by default.
  [root@ipaclient ~]# chkconfig certmonger on
2. Use the ipa-getcert command, which creates and manages the certificate through certmonger. The options are described more in Section B.1, "Requesting a Certificate with certmonger".
```
$ ipa-getcert request -d /etc/pki/nssdb -n Server-Cert -K HOST/ipaclient.example.com -N 'CN=ipaclient.example.com,O=EXAMPLE.COM'
```
If administrative tools were not installed on the client, then the certificate can be generated on an IdM server, copied over to the host, and installed using certutil.
Set up NFS to work with Kerberos.
TIP
To help troubleshoot potential NFS setup errors, enable debug information in the /etc/sysconfig/nfs file.
```
RPCGSSDARGS="-vvv"RPCSVCGSSDARGS="-vvv"
```
1. On an IdM server, add an NFS service principal for the NFS client.
```
# ipa service-add nfs/ipaclient.example.com@EXAMPLE
```
  NOTE
  This must be run from a machine with the ipa-admintools package installed so that the ipa command is available.
2. On the IdM server, obtain a keytab for the NFS service principal.
```
# ipa-getkeytab -s ipaserver.example.com -p nfs/ipaclient.example.com@EXAMPLE -k /tmp/krb5.keytab
```
  NOTE
  Some versions of the Linux NFS implementation have limited encryption type support. If the NFS server is hosted on a version older than Red Hat Enterprise Linux 6, use the -e des-cbc-crc option to the ipa-getkeytab command for any nfs/<FQDN> service keytabs to set up, both on the server and on all clients. This instructs the KDC to generate only DES keys.
  When using DES keys, all clients and servers that rely on this encryption type need to have the allow_weak_crypto option enabled in the [libdefaults] section of the /etc/krb5.conf file. Without these configuration changes, NFS clients and servers are unable to authenticate to each other, and attempts to mount NFS filesystems may fail. The client's rpc.gssd and the server's rpc.svcgssd daemons may log errors indicating that DES encryption types are not permitted.
3. Copy the keytab from the IdM server to the NFS server. For example, if the IdM and NFS servers are on different machines:
```
# scp /tmp/krb5.keytab [email protected]:/etc/krb5.keytab
```
4. Copy the keytab from the IdM server to the IdM client. For example:
```
# scp /tmp/krb5.keytab [email protected]:/etc/krb5.keytab
```
5. Configure the /etc/exports file on the NFS server.
```
/ipashare   gss/krb5p(rw,no_root_squash,subtree_check,fsid=0)
```
6. On the client, mount the NFS share.
  Always specify the share as nfs_server:/ /mountpoint.
  
  Use the same -o sec setting as is used in the /etc/exports file for the NFS server.
```
[root@client ~]# mount -v -t nfs4 -o sec=krb5p nfs.example.com:/ /mnt/ipashare
```

3.5. Setting up a Linux Client Through Kickstart

A kickstart enrollment automatically adds a new system to the IdM domain at the time it is provisioned.

This requires pre-creating the hosts on the IdM server, with a predefined password that can be used to authenticate to complete the enrollment operation.

Create the host entry on the IdM server and set a temporary Kerberos password for the entry.
When the ipa-client-install script is run normally (interactively), it prompts for authentication credentials to access the IdM domain. However, when the script is run automatically, the system has to have some way to access the IdM domain without using an existing IdM user; this is done by setting the host principal in the script and using a Kerberos password (configured for the host account) to access the IdM domain.
For example:
```
[jsmith@ipaserver ~]$ ipa host-add kickstart-server.example.com --password=secret
```
The password expires after the first authentication attempt. After enrollment completes, the host is authenticated using its keytab.

Include the ipa-client package with the other install packages.

%packages@ X Window System @ Desktop @ Sound and Videoipa-client...

Create a post-install instruction that runs the ipa-client-install script, passes all the required information to access and configure the IdM domain services, and specifies the pre-set password. Use the --unattended option to instruct the script to run non-interactively.

%post --log=/root/ks-post.log# Get the hostname to set as the host principal/bin/hostname > /tmp/hostname.txt# Run the client install script/usr/sbin/ipa-client-install --domain=EXAMPLEDOMAIN --enable-dns-updates --mkhomedir -w secret --realm=EXAMPLEREALM --server=ipaserver.example.com --unattended

Run the kickstart script.

3.6. Configuring a Microsoft Windows System to Join the IdM Realm

Download the MIT Kerberos 3.x package for Windows.
```
http://web.mit.edu/kerberos/dist/index.html
```
Run the kfw-3.x-exe file to launch the MIT Kerberos Installation Wizard.
Read and accept the license agreement.
Install the KfW client. All other components are optional.
Accept the default destination path.
Select Download from web path, and enter the URL to the IdM server. For example:
```
http://ipaserver.example.com/ipa/config/
```
Include the trailing backslash, or the configuration will fail.
Select Autostart the Network Identity Manager each time you login to Windows.
Click Install to begin the installation. When the installation is complete, click Finish to exit the Wizard.
Edit the hosts file and add the IdM server. For example:
```
1.2.3.4 ipaserver.example.com   ipaserver
```
Depending on the version of Windows, the HOSTS file could be located in different directories. For Windows XP and later systems, this is in C:\WINDOWS\system32\drivers\etc\.

NOTE

One potential problem is that a ticket is not generated by Kerberos on Windows. Windows can use multiple ticket caches with MIT Kerberos. This can create odd scenarios, where it is possible to authenticate against IdM's domain in the command line, but not to open the web UI.

MIT Kerberos for Windows provides some debugging tools which can be used to troubleshoot Windows Kerberos problems, available at http://web.mit.edu/Kerberos/dist/index.html#kfw-3.2.

3.7. Troubleshooting Client Installations

For clients configured using ipa-client-install, the client installation log is located in /var/log/ipaclient-install.log. The IdM logs, both for the server and client and for IdM-associated services, are covered in Section 19.1.3, "Checking IdM Server Logs".

These are some issues and workarounds for client installation problems.

3.7.1. The client can't resolve reverse hostnames when using an external DNS.

While IdM can host its own DNS server as part of the domain services, it can also use external DNS name server. However, because of some of the limitations of reverse DNS, there can be problems with resolving reverse lookups if the external DNS is listed in the client's /etc/resolv.conf file or if there are other resources on the network with SRV records, like Active Directory.

The problem is that the external DNS name server returns the wrong hostname for the IdM server.

One way this exhibits is errors with finding the IdM server in the Kerberos database:

Jun 30 11:11:48 server1 krb5kdc[1279](info): AS_REQ (4 etypes {18 17 16 23}) 192.168.60.135: NEEDED_PREAUTH: admin EXAMPLE COM for krbtgt/EXAMPLE COM EXAMPLE COM, Additional pre-authentication requiredJun 30 11:11:48 server1 krb5kdc[1279](info): AS_REQ (4 etypes {18 17 16 23}) 192.168.60.135: ISSUE: authtime 1309425108, etypes {rep=18 tkt=18 ses=18}, admin EXAMPLE COM for krbtgt/EXAMPLE COM EXAMPLE COMJun 30 11:11:49 server1 krb5kdc[1279](info): TGS_REQ (4 etypes {18 17 16 23}) 192.168.60.135: UNKNOWN_SERVER: authtime 0,  admin EXAMPLE COM for HTTP/[email protected], Server not found in Kerberos database

There are several ways to work around this issue:

Edit the /etc/resolv.conf file to remove the external DNS name server references.
Add reverse lookup records for each IdM server.
Give the IdM client or domain a subnet and forward all requests for that subnet.

3.7.2. The client is not added to the DNS zone.

If a client is in a subnet not controlled by an IdM DNS server, then the nsupdate command may fail to add the client to the DNS zone when ipa-client-install runs.

If IdM is managing the DNS domain, then add a zone entry for the client manually, as described in Section 10.5, "Managing DNS Record Entries". For example:

[jsmith@ipaserver ~]$ kinit admin[jsmith@ipaserver ~]$ ipa dnsrecord-add ipaclient.example.com www --a-rec 1.2.3.4

If the DNS domain is managed outside of IdM, the resource record can be added manually to the zone configuration. For information on DNS in Red Hat Enterprise Linux, see the DNS chapter in the Deployment Guide.

3.8. Uninstalling an IdM Client

For Red Hat Enterprise Linux clients, the ipa-client-install utility can be used to uninstall the client and remove it from the IdM domain. To remove the client, use the --uninstall option.

# ipa-client-install --uninstall

NOTE

There is an uninstall option with the ipa-join command. This is called by ipa-client-install --uninstall as part of the uninstallation process. However, while the ipa-join option removes the client from the domain, it does not actually uninstall the client or properly remove all of the IdM-related configuration. Do not run ipa-join -u to attempt to uninstall the IdM client. The only way to uninstall a client completely is to use ipa-client-install --uninstall.

Identity Management Guide

Chapter 3. Setting up Systems as IdM Clients

3.1. What Happens in Client Setup

3.2. System Ports

3.3. Configuring a Red Hat Enterprise Linux System as an IdM Client

3.4. Manually Configuring a Linux Client

3.5. Setting up a Linux Client Through Kickstart

3.6. Configuring a Microsoft Windows System to Join the IdM Realm

3.7. Troubleshooting Client Installations

3.7.1. The client can't resolve reverse hostnames when using an external DNS.

3.7.2. The client is not added to the DNS zone.

3.8. Uninstalling an IdM Client