Red Hat Training

A Red Hat training course is available for Red Hat Enterprise Linux

Linux Domain Identity, Authentication, and Policy Guide

Red Hat Enterprise Linux 7

Using Red Hat Identity Management in Linux environments

Florian Delehaye

Red Hat Customer Content Services

Marc Muehlfeld

Red Hat Customer Content Services

Filip Hanzelka

Red Hat Customer Content Services

Lucie Maňásková

Red Hat Customer Content Services

Aneta Šteflová Petrová

Red Hat Customer Content Services

Tomáš Čapek

Red Hat Customer Content Services

Ella Deon Ballard

Red Hat Customer Content Services

Abstract

Identity and policy management, for both users and machines, is a core function for most enterprise environments. Identity Management provides a way to create an identity domain that allows machines to enroll to a domain and immediately access identity information required for single sign-on and authentication services, as well as policy settings that govern authorization and access.
In addition to this guide, you can find documentation on other features and services related to Red Hat Enterprise Linux Identity Management in the following guides:

System-Level Authentication Guide

The System-Level Authentication Guide documents different applications and services available to configure authentication on local systems, including the authconfig utility, the System Security Services Daemon (SSSD) service, the Pluggable Authentication Module (PAM) framework, Kerberos, the certmonger utility, and single sign-on (SSO) for applications.

Windows Integration Guide

The Windows Integration Guide documents how to integrate Linux domains with Microsoft Windows Active Directory (AD) using Identity Management. Among other topics, the guide covers various aspects of direct and indirect AD integration, using SSSD to access a Common Internet File System (CIFS), and the realmd system.

Part I. Overview of Red Hat Identity Management

This part explains the purpose of Red Hat Identity Management. It also provides basic information about the Identity Management domain, including the client and server machines that are part of the domain.

Chapter 1. Introduction to Red Hat Identity Management

1.1. The Goal of Red Hat Identity Management

Red Hat Identity Management (IdM) provides a centralized and unified way to manage identity stores, authentication, policies, and authorization policies in a Linux-based domain. IdM significantly reduces the administrative overhead of managing different services individually and using different tools on different machines.
IdM is one of the few centralized identity, policy, and authorization software solutions that support:
  • Advanced features of Linux operating system environments
  • Unifying large groups of Linux machines
  • Native integration with Active Directory
IdM creates a Linux-based and Linux-controlled domain:
  • IdM builds on existing, native Linux tools and protocols. It has its own processes and configuration, but its underlying technologies are well-established on Linux systems and trusted by Linux administrators.
  • IdM servers and clients are Red Hat Enterprise Linux machines. However, even though IdM does not support Windows clients directly, it allows integration with Active Directory environment.
    Note
    This guide describes using IdM in Linux environments only. For more information on integration with Active Directory, see the Windows Integration Guide.
    For information on the Samba suite, which allows integrating Linux machines into Active Directory environment, see the Using Samba for Active Directory Integration chapter in the Windows Integration Guide. If you use Samba as a server, note that integrating the server into the IdM domain and authenticating users connecting to the Samba server against the IdM or a trusted Active Directory domain is not supported.

1.1.1. Examples of Benefits Brought by IdM

Managing identities and policies with several Linux servers
Without IdM: Each server is administered separately. All passwords are saved on the local machines. The IT administrator manages users on every machine, sets authentication and authorization policies separately, and maintains local passwords.
With IdM: The IT administrator can:
  • Maintain the identities in one central place: the IdM server
  • Apply policies uniformly to multiples of machines at the same time
  • Set different access levels for users by using host-based access control, delegation, and other rules
  • Centrally manage privilege escalation rules
  • Define how home directories are mounted
Enterprise single sign-on
Without IdM: Users log in to the system and are prompted for a password every single time they access a service or application. These passwords might be different, and the users have to remember which credential to use for which application.
With IdM: After users log in to the system, they can access multiple services and applications without being repeatedly asked for their credentials. This helps:
  • Improve usability
  • Reduce the security risk of passwords being written down or stored insecurely
  • Boost user productivity
Managing a mixed Linux and Windows environment
Without IdM: Windows systems are managed in an Active Directory forest, but development, production, and other teams have many Linux systems. The Linux systems are excluded from the Active Directory environment.
With IdM: The IT administrator can:
  • Manage the Linux systems using native Linux tools
  • Integrate the Linux systems with the Windows systems, thus preserving a centralized user store
  • Expand the Linux base easily
  • Separate management of Linux and Active Directory machines and enable Linux and Windows admins to control their environment directly

1.1.2. Contrasting Identity Management with a Standard LDAP Directory

A standard LDAP directory, such as Red Hat Directory Server, is a general-purpose directory: it can be customized to fit a broad range of use cases.
  • Schema: a flexible schema that can be customized for a vast array of entries, such as users, machines, network entities, physical equipment, or buildings.
  • Typically used as: a back-end directory to store data for other applications, such as business applications that provide services on the Internet.
Identity Management (IdM) has a specific purpose: managing identities as well as authentication and authorization policies that relate to these identities.
  • Schema: a specific schema that defines a particular set of entries relevant to its purpose, such as entries for user or machine identities.
  • Typically used as: the identity and authentication server to manage identities within the boundaries of an enterprise or a project.
The underlying directory server technology is the same for both Red Hat Directory Server and IdM. However, IdM is optimized to manage identities. This limits its general extensibility, but also brings certain benefits: simpler configuration, better automation of resource management, and increased efficiency in managing identities.

Additional Resources

1.2. The Identity Management Domain

The Identity Management (IdM) domain consists of a group of machines that share the same configuration, policies, and identity stores. The shared properties allow the machines within the domain to be aware of each other and operate together.
From the perspective of IdM, the domain includes the following types of machines:
  • IdM servers, which work as domain controllers
  • IdM clients, which are enrolled with the servers
IdM servers are also IdM clients enrolled with themselves: server machines provide the same functionality as clients.
IdM supports Red Hat Enterprise Linux machines as the IdM servers and clients.
Note
This guide describes using IdM in Linux environments. For more information on integration with Active Directory, see the Windows Integration Guide.

1.2.1. Identity Management Servers

The IdM servers act as central repositories for identity and policy information. They also host the services used by domain members. IdM provides a set of management tools to manage all the IdM-associated services centrally: the IdM web UI and command-line utilities.
For information on installing IdM servers, see Chapter 2, Installing and Uninstalling an Identity Management Server.
To support redundancy and load balancing, the data and configuration can be replicated from one IdM server to another: a replica of the initial server. You can configure servers and their replicas to provide different services to clients. For more details on IdM replicas, see Chapter 4, Installing and Uninstalling Identity Management Replicas.

1.2.1.1. Services Hosted by IdM Servers

Most of the following services are not strictly required to be installed on the IdM server. For example, services such as a certificate authority (CA), a DNS server, or a Network Time Protocol (NTP) server can be installed on an external server outside the IdM domain.
Kerberos: krb5kdc and kadmin
IdM uses the Kerberos protocol to support single sign-on. With Kerberos, users only need to present the correct username and password once and can access IdM services without the system prompting for credentials again.
LDAP directory server: dirsrv
The IdM internal LDAP directory server instance stores all IdM information, such as information related to Kerberos, user accounts, host entries, services, policies, DNS, and others.
The LDAP directory server instance is based on the same technology as Red Hat Directory Server. However, it is tuned to IdM-specific tasks.
Note
This guide refers to this component as Directory Server.
Certificate Authority: pki-tomcatd
The integrated Certificate Authority (CA) is based on the same technology as Red Hat Certificate System. pki is the Command-Line Interface for accessing Certificate System services.
Note
This guide refers to this component as Certificate System when addressing the implementation and as certificate authority when addressing the services provided by the implementation.
For information relating to Red Hat Certificate System, a standalone Red Hat product, see Product Documentation for Red Hat Certificate System.
Domain Name System (DNS): named
IdM uses DNS for dynamic service discovery. The IdM client installation utility can use information from DNS to automatically configure the client machine. After the client is enrolled in the IdM domain, it uses DNS to locate IdM servers and services within the domain.
The BIND (Berkeley Internet Name Domain) implementation of the DNS (Domain Name System) protocols in Red Hat Enterprise Linux includes the named DNS server. named-pkcs11 is a version of the BIND DNS server built with native support for the PKCS#11 cryptographic standard.
Network Time Protocol: ntpd
Many services require that servers and clients have the same system time, within a certain variance. For example, Kerberos tickets use time stamps to determine their validity and to prevent replay attacks. If the times between the server and client skew outside the allowed range, the Kerberos tickets are invalidated.
By default, IdM uses the Network Time Protocol (NTP) to synchronize clocks over a network via the ntpd service. With NTP, a central server acts as an authoritative clock and the clients synchronize their times to match the server clock. The IdM server is configured as the NTP server for the IdM domain during the server installation process.
Note
Running an NTP server on an IdM server installed on a virtual machine can lead to inaccurate time synchronization in some environments. To avoid potential problems, do not run NTP on IdM servers installed on virtual machines. For more information on the reliability of an NTP server on a virtual machine, see this Knowledgebase solution.
Apache HTTP Server: httpd
The Apache HTTP web server provides the IdM Web UI, and also manages communication between the Certificate Authority and other IdM services.
Samba / Winbind: smb, winbind
Samba implements the Server Message Block (SMB) protocol, also known as the Common Internet File System (CIFS) protocol), in Red Hat Enterprise Linux. Via the smb service, the SMB protocol enables you to access resources on a server, such as file shares and shared printers. If you have configured a Trust with an Active Directory (AD) environment, the Winbind service manages communication between IdM servers and AD servers.
  • For more information, see Samba in the System Administrator’s Guide.
  • For more information, see the Winbind in the System-Level Authentication Guide
One-time password (OTP) authentication: ipa-otpd
One-time passwords (OTP) are passwords that are generated by an authentication token for only one session, as part of two-factor authentication. OTP authentication is implemented in Red Hat Enterprise Linux via the ipa-otpd service.
Custodia: ipa-custodia
Custodia is a Secrets Services provider, it stores and shares access to secret material such as passwords, keys, tokens, certificates.
OpenDNSSEC: ipa-dnskeysyncd
OpenDNSSEC is a DNS manager that automates the process of keeping track of DNS security extensions (DNSSEC) keys and the signing of zones. The ipa-dnskeysyncd servuce manages synchronization between the IdM Directory Server and OpenDNSSEC.

Figure 1.1. The Identity Management Server: Unifying Services

The Identity Management Server: Unifying Services

1.2.2. Identity Management Clients

IdM clients are machines configured to operate within the IdM domain. They interact with the IdM servers to access domain resources. For example, they belong to the Kerberos domains configured on the servers, receive certificates and tickets issued by the servers, and use other centralized services for authentication and authorization.
An IdM client does not require dedicated client software to interact as a part of the domain. It only requires proper system configuration of certain services and libraries, such as Kerberos or DNS. This configuration directs the client machine to use IdM services.
For information on installing IdM clients, see Chapter 3, Installing and Uninstalling Identity Management Clients.

1.2.2.1. Services Hosted by IdM Clients

System Security Services Daemon: sssd
The System Security Services Daemon (SSSD) is the client-side application that manages user authentication and caching credentials.
Caching enables the local system to continue normal authentication operations if the IdM server becomes unavailable or if the client goes offline.
For more information, see Configuring SSSD in the System-Level Authentication Guide. SSSD also supports Windows Active Directory (AD). For more information about using SSSD with AD, see the Using Active Directory as an Identity Provider for SSSD in the Windows Integration Guide.
certmonger
The certmonger service monitors and renews the certificates on the client. It can request new certificates for the services on the system.
For more information, see Working with certmonger in the System-Level Authentication Guide.

Figure 1.2. Interactions Between IdM Services

Interactions Between IdM Services

Part II. Installing Identity Management

This part explains how to plan the Identity Management deployment and how to install Identity Management server, client, and replicas.

Chapter 2. Installing and Uninstalling an Identity Management Server

An Identity Management (IdM) server is a domain controller: it defines and manages the IdM domain. To set set up an IdM server, you must:
  1. Install the necessary packages
  2. Configure the machine using setup scripts
Red Hat strongly recommends to set up multiple domain controllers within your domain for load balancing and redundancy. These additional servers are replicas of the initial master IdM server.
This chapter describes installing the first, initial IdM server. For information on installing a replica from the initial server, see Chapter 4, Installing and Uninstalling Identity Management Replicas.

2.1. Prerequisites for Installing a Server

2.1.1. Minimal Hardware Requirements

To run Identity Management (IdM), the server requires at a minimum the following hardware configuration:
  • 1 (virtual) CPU core
  • 2 GB RAM
    Even if you can install IdM with less RAM, certain operations, such as updating IdM, require at least 4 GB RAM.
  • 10 GB hard disk
Important
Depending on the amount of data stored in the database, IdM requires more resources, especially more RAM. For details, see Section 2.1.2, “Hardware Recommendations”. The required hardware resources also depend on other factors, such as the production workload of the server or if a trust with Active Directory is configured.

2.1.2. Hardware Recommendations

RAM is the most important hardware feature to size properly. To determine how much RAM you require, consider these recommendations:
  • For 10,000 users and 100 groups: at least 3 GB of RAM and 1 GB swap space
  • For 100,000 users and 50,000 groups: at least 16 GB of RAM and 4 GB of swap space
Note
A basic user entry or a simple host entry with a certificate is approximately 5 - 10 KiB in size.
For larger deployments, it is more effective to increase the RAM than to increase disk space because much of the data is stored in cache.
To increase performance, you can tune the underlying Directory Server to increase performance. For details, see the Red Hat Directory Server Performance Tuning Guide.

2.1.3. System Requirements

Identity Management is supported on Red Hat Enterprise Linux 7. Install an IdM server on a clean system without any custom configuration for services such as DNS, Kerberos, or Directory Server.
Important
For performance and stability reasons, Red Hat recommends that you do not install other applications or services on IdM servers. For example, IdM servers can be exhaustive to the system, especially if the number of LDAP objects is high. Also, IdM is integrated in the system and, if third party applications change configuration files IdM depends on, IdM can break.
The IdM server installation overwrites system files to set up the IdM domain. IdM backs up the original system files to /var/lib/ipa/sysrestore/.
Name Service Cache Daemon (NSCD) requirements
Red Hat recommends to disable NSCD on Identity Management machines. Alternatively, if disabling NSCD is not possible, only enable NSCD for maps that SSSD does not cache.
Both NSCD and the SSSD service perform caching, and problems can occur when systems use both services simultaneously. See the System-Level Authentication Guide for information on how to avoid conflicts between NSCD and SSSD.
IPv6 must be enabled on the system
The IdM server must have the IPv6 protocol enabled in the kernel. Note that IPv6 is enabled by default on Red Hat Enterprise Linux 7 systems.
If you disabled IPv6 before, re-enable it as described in How do I disable or enable the IPv6 protocol in Red Hat Enterprise Linux? in Red Hat Knowledgebase.
Note
IdM does not require the IPv6 protocol to be enabled in the kernel of the hosts you want to enroll as clients. For example, if your internal network only uses the IPv4 protocol, you can configure the System Security Services Daemon (SSSD) to only use IPv4 to communicate with the IdM server. You can do this by inserting the following line into the [domain/_NAME_] section of the /etc/sssd/sssd.conf file: 
lookup_family_order = ipv4_only
For more information on the lookup_family_order, see the sssd.conf(5) man page.

2.1.4. Prerequisites for Installing a Server in a FIPS Environment

In environments set up using Red Hat Enterprise Linux 7.4 and later:
  • You can configure a new IdM server or replica on a system with the Federal Information Processing Standard (FIPS) mode enabled. The installation script automatically detects a system with FIPS enabled and configures IdM without the administrator's intervention.
    To enable FIPS in the operating system, see Enabling FIPS Mode in the Security Guide.
    Important
    You cannot:
    • Enable FIPS mode on existing IdM servers previously installed with FIPS mode disabled.
    • Install a replica in FIPS mode when using an existing IdM server with FIPS mode disabled.
In environments set up using Red Hat Enterprise Linux 7.3 and earlier:
  • IdM does not support the FIPS mode. Disable FIPS on your system before installing an IdM server or replica, and do not enable it after the installation.
For further details about FIPS mode, see Federal Information Processing Standard (FIPS) in the Security Guide.

2.1.5. Host Name and DNS Configuration

Warning
Be extremely cautious and ensure that:
  • you have a tested and functional DNS service available
  • the service is properly configured
This requirement applies to IdM servers with integrated DNS services as well as to IdM servers installed without DNS. DNS records are vital for nearly all IdM domain functions, including running LDAP directory services, Kerberos, and Active Directory integration.
Note that the primary DNS domain and Kerberos realm cannot be changed after the installation.
Do not use single-label domain names, for example .company: the IdM domain must be composed of one or more subdomains and a top level domain, for example example.com or company.example.com.
The server host must have DNS properly configured regardless of whether the DNS server is integrated within IdM or hosted externally.
Identity Management requires one separate DNS domain to be used for service records. To avoid conflicts on the DNS level, the primary IdM DNS domain, the DNS domain whose name is the lower-case version of the IdM Kerberos name, cannot be shared with any other system, such as other IdM or AD domains
The primary IdM DNS domain must contain its own SRV records for standard IdM services. The required records are:
  • the SRV record of both _kerberos._tcp.domain_name and _kerberos._udp.domain_name
  • the SRV record of _ldap._tcp.domain_name
  • the TXT record of _kerberos.domain_name
When an enrolled client, via the ipa command-line tool, is looking for a service provided or mediated by IdM, it looks up the server specified by the xmlrpc_uri parameter in the /etc/ipa/default.conf file. If need be, it also looks up the IdM DNS domain name given in the domain parameter in the same file, and consults the _ldap._tcp.domain_name SRV record for that domain to identify the server it is looking for. If there is no domain given in the /etc/ipa/default.conf file, the client only contacts the server that is set in the xmlrpc_uri parameter of the file.
Note that the host names of IdM clients and servers are not required to be part of the primary DNS domain. However, in trust environments with Active Directory (AD), the host names of IdM servers must be part of the IdM-owned domain, the domain associated with the IdM realm, and not part of the AD-owned domain, the domain associated with the trusted AD realm. From the perspective of the trust, this association is managed using Realm domains.
For information on configuring users to access an IdM client using a host name from the Active Directory DNS domain, while the client itself is joined to IdM, see IdM clients in an Active Directory DNS Domain in the Windows Integration Guide.

Verifying the Server Host Name

The host name must be a fully qualified domain name, such as server.example.com.
Important
Do not use single-label domain names, for example .company: the IdM domain must be composed of one or more subdomains and a top level domain, for example example.com or company.example.com.
The fully qualified domain name must meet the following conditions:
  • It is a valid DNS name, which means only numbers, alphabetic characters, and hyphens (-) are allowed. Other characters, such as underscores (_), in the host name cause DNS failures.
  • It is all lower-case. No capital letters are allowed.
  • The fully qualified domain name must not resolve to the loopback address. It must resolve to the machine's public IP address, not to 127.0.0.1.
For other recommended naming practices, see the Recommended Naming Practices in the Red Hat Enterprise Linux Security Guide.
To verify your machine's host name, use the hostname utility: 
[root@server ~]# hostname
server.example.com
The output of hostname must not be localhost or localhost6.

Verifying the Forward and Reverse DNS Configuration

  1. Obtain the IP address of the server. The ip addr show command displays both the IPv4 and IPv6 addresses:
    • The IPv4 address is displayed on the line starting with inet. In the following example, the configured IPv4 address is 192.0.2.1.
    • The IPv6 address is displayed on the line starting with inet6. Only IPv6 addresses with scope global are relevant for this procedure. In the following example, the returned IPv6 address is 2001:DB8::1111. 
    [root@server ~]# ip addr show
...
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
	link/ether 00:1a:4a:10:4e:33 brd ff:ff:ff:ff:ff:ff
	inet 192.0.2.1/24 brd 192.0.2.255 scope global dynamic eth0
		valid_lft 106694sec preferred_lft 106694sec
	inet6 2001:DB8::1111/32 scope global dynamic
 		valid_lft 2591521sec preferred_lft 604321sec
	inet6 fe80::56ee:75ff:fe2b:def6/64 scope link
	       valid_lft forever preferred_lft forever
  2. Verify the forward DNS configuration by using the dig utility and adding the host name.
    1. Run the dig +short server.example.com A command. The returned IPv4 address must match the IP address returned by ip addr show: 
      [root@server ~]# dig +short server.example.com A
192.0.2.1
    2. Run the dig +short server.example.com AAAA command. If the command returns an address, it must match the IPv6 address returned by ip addr show: 
      [root@server ~]# dig +short server.example.com AAAA
2001:DB8::1111
      Note
      If no output is returned for the AAAA record, it does not indicate incorrect configuration; no output only means that no IPv6 address is configured in DNS for the server machine. If you do not intend to use the IPv6 protocol in your network, you can proceed with the installation in this situation.
  3. Verify the reverse DNS configuration (PTR records) by using the dig utility and adding the IP address.
    1. Run the dig +short -x IPv4 address command. The server host name must be displayed in the command output. For example: 
      [root@server ~]# dig +short -x 192.0.2.1
server.example.com
    2. Use dig to query the IPv6 address as well if the dig +short -x server.example.com AAAA command in the previous step returned an IPv6 address. Again, the server host name must be displayed in the command output. For example: 
      [root@server ~]# dig +short -x 2001:DB8::1111
server.example.com
      Note
      If dig +short server.example.com AAAA in the previous step did not display any IPv6 address, querying the AAAA record does not output anything. In this case, this is normal behavior and does not indicate incorrect configuration.
    If a different host name or no host name is displayed, even though dig +short server.example.com in the previous step returned an IP address, it indicates that the reverse DNS configuration is incorrect.

Verifying the Standards-compliance of DNS Forwarders

When configuring IdM with integrated DNS, it is recommended to use DNS Security Extensions (DNSSEC) records validation. By validating signed DNS records from other servers, you protect your IdM installation against spoofed addresses. However, DNSSEC validation is not a hard requirement for a successful IdM installation.
IdM installer enables DNSSEC records validation by default. For successful DNSSEC validation, it is crucial to have forwarders on which DNSSEC has been properly configured. During installation, IdM checks global forwarders, and if a forwarder does not support DNSSEC, the DNSSEC validation will be disabled on the forwarder.
To verify that all DNS forwarders you want to use with the IdM DNS server comply with the Extension Mechanisms for DNS (EDNS0) and DNSSEC standards: 
$ dig +dnssec @IP_address_of_the_DNS_forwarder . SOA
The expected output displayed by the command contains the following information:
  • status: NOERROR
  • flags: ra
  • EDNS flags: do
  • The RRSIG record must be present in the ANSWER section
If any of these items is missing from the output, inspect the documentation of your DNS forwarder and verify that EDNS0 and DNSSEC are supported and enabled. In latest versions of the BIND server, the dnssec-enable yes; option must be set in the /etc/named.conf file.
For example, the expected output can look like this: 
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 48655
;; flags: qr rd ra ad; QUERY: 1, ANSWER: 2, AUTHORITY: 0, ADDITIONAL: 1

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags: do; udp: 4096

;; ANSWER SECTION:
. 31679 IN SOA a.root-servers.net. nstld.verisign-grs.com. 2015100701 1800 900 604800 86400
. 31679 IN RRSIG SOA 8 0 86400 20151017170000 20151007160000 62530 . GNVz7SQs [...]

The /etc/hosts File

Important
Do not modify the /etc/hosts file manually. If /etc/hosts has been modified, make sure its contents conform to the following rules.
The following is an example of a correctly configured /etc/hosts file. It properly lists the IPv4 and IPv6 localhost entries for the host, followed by the IdM server IP address and host name as the first entry. Note that the IdM server host name cannot be part of the localhost entry. 
127.0.0.1	localhost.localdomain	localhost
::1		localhost6.localdomain6	localhost6
192.0.2.1	server.example.com	server
2001:DB8::1111	server.example.com	server

2.1.6. Port Requirements

IdM uses a number of ports to communicate with its services. These ports must be open and available for IdM to work. They cannot be in use by another service or blocked by a firewall.

List of Required Ports

Table 2.1. Identity Management Ports

Service Ports Protocol
HTTP/HTTPS 80, 443 TCP
LDAP/LDAPS 389, 636 TCP
Kerberos 88, 464 TCP and UDP
DNS 53 TCP and UDP
NTP 123 UDP
Note
Do not be concerned that IdM uses ports 80 and 389.
  • Port 80 (HTTP) is used to provide Online Certificate Status Protocol (OCSP) responses and Certificate Revocation Lists (CRL). Both are digitally signed and therefore secured against man-in-the-middle attacks.
  • Port 389 (LDAP) uses STARTTLS and GSSAPI for encryption.
In addition, IdM can listen on port 8080 and in some installations also on ports 8443 and 749. However, these three ports are only used internally: even though IdM keeps them open, they are not required to be accessible from outside. It is recommended that you do not open ports 8080, 8443, and 749 and instead leave them blocked by a firewall.

List of firewalld Services

Table 2.2. firewalld Services

Service name For details, see:
freeipa-ldap /usr/lib/firewalld/services/freeipa-ldap.xml
freeipa-ldaps /usr/lib/firewalld/services/freeipa-ldaps.xml
dns /usr/lib/firewalld/services/dns.xml

Opening the Required Ports

  1. Make sure the firewalld service is running.
    • To find out if firewalld is currently running: 
      # systemctl status firewalld.service
    • To start firewalld and configure it to start automatically when the system boots: 
      # systemctl start firewalld.service
# systemctl enable firewalld.service
  2. Open the required ports using the firewall-cmd utility. Choose one of the following options:
    1. Add the individual ports to the firewall by using the firewall-cmd --add-port command. For example, to open the ports in the default zone: 
      # firewall-cmd --permanent --add-port={80/tcp,443/tcp,list_of_ports}
    2. Add the firewalld services to the firewall by using the firewall-cmd --add-service command. For example, to open the ports in the default zone: 
      # firewall-cmd --permanent --add-service={freeipa-ldap,list_of_services}
    For details on using firewall-cmd to open ports on a system, see the Modifying Settings in Runtime and Permanent Configuration using CLI in the Security Guide or the firewall-cmd(1) man page.
  3. Reload the firewall-cmd configuration to ensure that the change takes place immediately: 
    # firewall-cmd --reload
    Note that reloading firewalld on a system in production can cause DNS connection time outs. See also Modifying Settings in Runtime and Permanent Configuration using CLI in the Security Guide. If required, to avoid the risk of time outs and to make the changes persistent on the running system, use the --runtime-to-permanent option of the firewall-cmd command, for example: 
    # firewall-cmd --runtime-to-permanent --add-port={80/tcp,443/tcp,389/tcp,636/tcp,88/tcp,88/udp,464/tcp,464/udp,53/tcp,53/udp,123/udp}
  4. Optional. To verify that the ports are available now, use the nc, telnet, or nmap utilities to connect to a port or run a port scan.
Note
Note that you also have to open network-based firewalls for both incoming and outgoing traffic.

2.2. Packages Required to Install an IdM Server

To install the packages required for a server without integrated DNS services: 
# yum install ipa-server
To install the packages required for a server with integrated DNS services: 
# yum install ipa-server ipa-server-dns
Note
To determine whether DNS is right for your use case, see Section 2.3.1, “Determining Whether to Use Integrated DNS”.
The ipa-server package automatically installs other required packages as dependencies, such as:
  • 389-ds-base for the Directory Server LDAP service
  • krb5-server package for the Kerberos service
  • various IdM-specific tools

2.3. Installing an IdM Server: Introduction

Note
The installation procedures and examples in the following sections are not mutually exclusive: you can combine them to achieve the required result. For example, you can install a server with integrated DNS and with an externally hosted root CA.
The ipa-server-install utility installs and configures an IdM server.
Before installing a server, see these sections:
The ipa-server-install utility provides a non-interactive installation mode which allows automated and unattended server setup. For details, see Section 2.3.7, “Installing a Server Non-Interactively”
The ipa-server-install installation script creates a log file at /var/log/ipaserver-install.log. If the installation fails, the log can help you identify the problem.

2.3.1. Determining Whether to Use Integrated DNS

IdM supports installing a server with integrated DNS or without integrated DNS.
An IdM server with integrated DNS services
The integrated DNS server provided by IdM is not designed to be used as a general-purpose DNS server. It only supports features related to IdM deployment and maintenance. It does not support some of the advanced DNS features.
Red Hat strongly recommends IdM-integrated DNS for basic usage within the IdM deployment: When the IdM server also manages DNS, there is tight integration between DNS and native IdM tools which enables automating some of the DNS record management.
Note that even if an IdM server is used as a master DNS server, other external DNS servers can still be used as slave servers.
For example, if your environment is already using another DNS server, such as an Active Directory-integrated DNS server, you can delegate only the IdM primary domain to the IdM-integrated DNS. You are not required to migrate DNS zones over to the IdM-integrated DNS.
Note
If you need to issue certificates for IdM clients with an IP address in the Subject Alternative Name (SAN) extension, you must use the IdM integrated DNS service.
To install a server with integrated DNS, see Section 2.3.3, “Installing a Server with Integrated DNS”
An IdM server without integrated DNS services
An external DNS server is used to provide the DNS services. Consider installing an IdM server without DNS in these situations:
  • If you require advanced DNS features beyond the scope of the IdM DNS
  • In environments with a well-established DNS infrastructure which allows you to use external DNS servers
To install a server without integrated DNS, see Section 2.3.4, “Installing a Server Without Integrated DNS”
Important
Make sure your system meets the DNS requirements described in Section 2.1.5, “Host Name and DNS Configuration”.

Maintenance Requirements for Integrated or External DNS

When using an integrated DNS server, most of the DNS record maintenance is automated. You only must:
  • set up correct delegation from the parent domain to the IdM servers
    For example, if the IdM domain name is ipa.example.com, it must be properly delegated from the example.com domain.
    Note
    You can verify the delegation using the following command: 
    # dig @IP_address +norecurse +short ipa.example.com. NS
    IP_address is the IP address of the server that manages the example.com DNS domain. If the delegation is correct, the command lists the IdM servers that have a DNS server installed.
When using an external DNS server, you must:
  • manually create the new domain on the DNS server
  • fill the new domain manually with records from the zone file that is generated by the IdM installer
  • manually update the records after installing or removing a replica, as well as after any changes in the service configuration, such as after an Active Directory trust is configured

Preventing DNS Amplification Attacks

The default configuration of the IdM-integrated DNS server allows all clients to issue recursive queries to the DNS server. If your server is deployed in a network with an untrusted client, change the server's configuration to limit recursion to authorized clients only. [1]
To ensure that only authorized clients are allowed to issue recursive queries, add the appropriate access control list (ACL) statements to the /etc/named.conf file on your server. For example: 
acl authorized { 192.0.2.0/24; 198.51.100.0/24; };
options {
  allow-query { any; };
  allow-recursion { authorized; };
};

2.3.2. Determining What CA Configuration to Use

IdM supports installing a server with an integrated IdM certificate authority (CA) or without a CA.
Server with an integrated IdM CA
This is the default configuration suitable for most deployments. Certificate System uses a CA signing certificate to create and sign the certificates in the IdM domain.
Warning
Red Hat strongly recommends to keep the CA services installed on more than one server. For information on installing a replica of the initial server including the CA services, see Section 4.5.4, “Installing a Replica with a CA”.
If you install the CA on only one server, you risk losing the CA configuration without a chance of recovery if the CA server fails. See Section B.2.6, “Recovering a Lost CA Server” for details.
The IdM CA signing certificate can be a root CA, which is also called self-signed, or it can be signed by an external CA.
The IdM CA is the root CA
This is the default configuration.
To install a server with this configuration, see Section 2.3.3, “Installing a Server with Integrated DNS” and Section 2.3.4, “Installing a Server Without Integrated DNS”.
An external CA is the root CA
The IdM CA is subordinate to an external CA. However, all certificates for the IdM domain are still issued by the Certificate System instance.
The external CA can be a corporate CA or a third-party CA, such as Verisign or Thawte. The external CA can be a root CA or a subordinate CA. The certificates issued within the IdM domain are potentially subject to restrictions set by the external root CA or intermediate CA certificates for attributes, such as the validity period, or domains for which certificates can be issued.
To install a server with an externally-hosted root CA, see Section 2.3.5, “Installing a Server with an External CA as the Root CA”
Server without a CA
This configuration option is suitable for very rare cases when restrictions within the infrastructure do not allow to install certificate services with the server.
You must request these certificates from a third-party authority prior to the installation:
  • An LDAP server certificate and a private key
  • An Apache server certificate and a private key
  • Full CA certificate chain of the CA that issued the LDAP and Apache server certificates
Warning
Managing certificates without the integrated IdM CA presents a significant maintenance burden. For example, you must manually manage the Apache web server and LDAP server certificates of the IdM server. This includes:
  • Creating and uploading certificates.
  • Monitoring the expiration date of certificates. Note that the certmonger service does not track certificates if you installed IdM without the integrated CA.
  • Renewing certificates before they expire to avoid outages.
To install a server without an integrated CA, see Section 2.3.6, “Installing Without a CA”
Note
If you install an IdM domain without a CA, you can install the CA services afterwards. To install a CA to already existing IdM domain, see Section 26.8, “Installing a CA Into an Existing IdM Domain”.

2.3.3. Installing a Server with Integrated DNS

Note
To install a server with integrated DNS, provide the following information during the installation process:
DNS forwarders
The following DNS forwarder settings are supported:
  • one or more forwarders (the --forwarder option in non-interactive installation)
  • no forwarders (the --no-forwarders option in non-interactive installation)
If you are unsure whether to use DNS forwarding, see Section 33.6, “Managing DNS Forwarding”.
Reverse DNS zones
The following reverse DNS zone settings are supported:
  • automatic detection of the reverse zones that need to be created in IdM DNS (the default setting in interactive installation, the --auto-reverse option in non-interactive installation)
  • no reverse zone auto-detection (the --no-reverse option in interactive installation)
Note that the --allow-zone-overlap option is ignored if the --auto-reverse option is set. Using the combination of options: 
$ ipa-server-install --auto-reverse --allow-zone-overlap
thus does not create reverse zones which would overlap with already existing DNS zones, for example on another DNS server.
For non-interactive installation, add the --setup-dns option as well.

Example 2.1. Installing a Server with Integrated DNS

This procedure installs a server:
  • with integrated DNS
  • with integrated IdM CA as the root CA, which is the default CA configuration
  1. Run the ipa-server-install utility. 
    # ipa-server-install
  2. The script prompts to configure an integrated DNS service. Enter yes. 
    Do you want to configure integrated DNS (BIND)? [no]: yes
  3. The script prompts for several required settings.
    • To accept the default values in brackets, press Enter.
    • To provide a value different than the proposed default value, enter the required value. 
    Server host name [server.example.com]:
Please confirm the domain name [example.com]:
Please provide a realm name [EXAMPLE.COM]:
    Warning
    Red Hat strongly recommends that the Kerberos realm name is the same as the primary DNS domain name, with all letters uppercase. For example, if the primary DNS domain is ipa.example.com, use IPA.EXAMPLE.COM for the Kerberos realm name.
    Different naming practices will prevent you from using Active Directory trusts and can have other negative consequences.
  4. Enter the passwords for the Directory Server superuser, cn=Directory Manager, and for the admin IdM system user account. 
    Directory Manager password:
IPA admin password:
  5. The script prompts for DNS forwarders. 
    Do you want to configure DNS forwarders? [yes]:
    • To configure DNS forwarders, enter yes, and then follow the instructions on the command line.
      The installation process will add the forwarder IP addresses to the /etc/named.conf file on the installed IdM server.
    • If you do not want to use DNS forwarding, enter no.
  6. The script prompts to check if any DNS reverse (PTR) records for the IP addresses associated with the server need to be configured. 
    Do you want to search for missing reverse zones? [yes]:
    If you run the search and missing reverse zones are discovered, the script asks you whether to create the reverse zones along with the PTR records. 
    Do you want to create reverse zone for IP 192.0.2.1 [yes]:
Please specify the reverse zone name [2.0.192.in-addr.arpa.]:
Using reverse zone(s) 2.0.192.in-addr.arpa.
    Note
    Using IdM to manage reverse zones is optional. You can use an external DNS service for this purpose instead.
  7. Enter yes to confirm the server configuration. 
    Continue to configure the system with these values? [no]: yes
  8. The installation script now configures the server. Wait for the operation to complete.
  9. Add DNS delegation from the parent domain to the IdM DNS domain. For example, if the IdM DNS domain is ipa.example.com, add a name server (NS) record to the example.com parent domain.
    Important
    This step must be repeated each time an IdM DNS server is installed.
The script recommends you to back up the CA certificate and to make sure the required network ports are open. For information about IdM port requirements and instructions on how to open these ports, see Section 2.1.6, “Port Requirements”.
To test the new server:
  1. Authenticate to the Kerberos realm using the admin credentials. This verifies that admin is properly configured and the Kerberos realm is accessible. 
    # kinit admin
  2. Run a command such as ipa user-find. On a new server, the command prints the only configured user: admin. 
    # ipa user-find admin
--------------
1 user matched
--------------
User login: admin 
Last name: Administrator 
Home directory: /home/admin 
Login shell: /bin/bash 
UID: 939000000 
GID: 939000000 
Account disabled: False 
Password: True 
Kerberos keys available: True 
----------------------------
Number of entries returned 1
----------------------------

2.3.4. Installing a Server Without Integrated DNS

Note
To install a server without integrated DNS, run the ipa-server-install utility without any DNS-related options.

Example 2.2. Installing a Server Without Integrated DNS

This procedure installs a server:
  • without integrated DNS
  • with integrated IdM CA as the root CA, which is the default CA configuration
  1. Run the ipa-server-install utility. 
    # ipa-server-install
  2. The script prompts to configure an integrated DNS service. Press Enter to select the default no option. 
    Do you want to configure integrated DNS (BIND)? [no]:
  3. The script prompts for several required settings.
    • To accept the default values in brackets, press Enter.
    • To provide a value different than the proposed default value, enter the required value. 
    Server host name [server.example.com]:
Please confirm the domain name [example.com]:
Please provide a realm name [EXAMPLE.COM]:
    Warning
    Red Hat strongly recommends that the Kerberos realm name is the same as the primary DNS domain name, with all letters uppercase. For example, if the primary DNS domain is ipa.example.com, use IPA.EXAMPLE.COM for the Kerberos realm name.
    Different naming practices will prevent you from using Active Directory trusts and can have other negative consequences.
  4. Enter the passwords for the Directory Server superuser, cn=Directory Manager, and for the admin IdM system user account. 
    Directory Manager password:
IPA admin password:
  5. Enter yes to confirm the server configuration. 
    Continue to configure the system with these values? [no]: yes
  6. The installation script now configures the server. Wait for the operation to complete.
  7. The installation script produces a file with DNS resource records: the /tmp/ipa.system.records.UFRPto.db file in the example output below. Add these records to the existing external DNS servers. The process of updating the DNS records varies depending on the particular DNS solution. 
    ...
Restarting the KDC
Please add records in this file to your DNS system: /tmp/ipa.system.records.UFRBto.db
Restarting the web server
...
    Important
    The server installation is not complete until you add the DNS records to the existing DNS servers.
The script recommends you to back up the CA certificate and to make sure the required network ports are open. For information about IdM port requirements and instructions on how to open these ports, see Section 2.1.6, “Port Requirements”.
To test the new server:
  1. Authenticate to the Kerberos realm using the admin credentials. This verifies that admin is properly configured and the Kerberos realm is accessible. 
    # kinit admin
  2. Run a command such as ipa user-find. On a new server, the command prints the only configured user: admin. 
    # ipa user-find admin
--------------
1 user matched
--------------
User login: admin 
Last name: Administrator 
Home directory: /home/admin 
Login shell: /bin/bash 
UID: 939000000 
GID: 939000000 
Account disabled: False 
Password: True 
Kerberos keys available: True 
----------------------------
Number of entries returned 1
----------------------------

2.3.5. Installing a Server with an External CA as the Root CA

Note
To install a server and chain it with an external CA as the root CA, pass these options with the ipa-server-install utility:
  • --external-ca specifies that you want to use an external CA.
  • --external-ca-type specifies the type of the external CA. See the ipa-server-install(1) man page for details.
Otherwise, most of the installation procedure is the same as in Section 2.3.3, “Installing a Server with Integrated DNS” or Section 2.3.4, “Installing a Server Without Integrated DNS”.
During the configuration of the Certificate System instance, the utility prints the location of the certificate signing request (CSR): /root/ipa.csr: 
...

Configuring certificate server (pki-tomcatd): Estimated time 3 minutes 30 seconds
  [1/8]: creating certificate server user
  [2/8]: configuring certificate server instance
The next step is to get /root/ipa.csr signed by your CA and re-run /sbin/ipa-server-install as: /sbin/ipa-server-install --external-cert-file=/path/to/signed_certificate --external-cert-file=/path/to/external_ca_certificate
When this happens:
  1. Submit the CSR located in /root/ipa.csr to the external CA. The process differs depending on the service to be used as the external CA.
    Important
    It can be necessary to request the appropriate extensions for the certificate. The CA signing certificate generated for Identity Management must be a valid CA certificate. This requires that you set the CA parameter in the basic constraints extension true. For further details, see the Basic Constraints section in RFC 5280.
  2. Retrieve the issued certificate and the CA certificate chain for the issuing CA in a base 64-encoded blob (either a PEM file or a Base_64 certificate from a Windows CA). Again, the process differs for every certificate service. Usually, a download link on a web page or in the notification email allows the administrator to download all the required certificates.
    Important
    Be sure to get the full certificate chain for the CA, not just the CA certificate.
  3. Run ipa-server-install again, this time specifying the locations and names of the newly-issued CA certificate and the CA chain files. For example: 
    # ipa-server-install --external-cert-file=/tmp/servercert20110601.pem --external-cert-file=/tmp/cacert.pem
Note
The ipa-server-install --external-ca command can sometimes fail with the following error: 
ipa         : CRITICAL failed to configure ca instance Command '/usr/sbin/pkispawn -s CA -f /tmp/configuration_file' returned non-zero exit status 1
Configuration of CA failed
This failure occurs when the *_proxy environmental variables are set. For a solution on how to fix this problem, see Section B.1.1, “External CA Installation Fails”

2.3.6. Installing Without a CA

Note
To install a server without a CA, you must provide the required certificates manually by adding options to the ipa-server-install utility. Other than that, most of the installation procedure is the same as in Section 2.3.3, “Installing a Server with Integrated DNS” or Section 2.3.4, “Installing a Server Without Integrated DNS”.
Important
You cannot install a server or replica using self-signed third-party server certificates.

Certificates Required to Install an IdM Server without a CA

For a successful CA-less IdM server installation, you must provide the following certificates:
  • The LDAP server certificate and private key, supplied using these options:
    • --dirsrv-cert-file for the certificate and private key files for the LDAP server certificate
    • --dirsrv-pin for the password to access the private key in the files specified in --dirsrv-cert-file
  • The Apache server certificate and private key, supplied using these options:
    • --http-cert-file for the certificate and private key files for the Apache server certificate
    • --http-pin for the password to access the private key in the files specified in --http-cert-file
  • The full CA certificate chain of the CA that issued the LDAP and Apache server certificates, supplied using these options:
    • --dirsrv-cert-file and --http-cert-file for the certificate files with the full CA certificate chain or a part of it
      You can provide the files specified in the --dirsrv-cert-file and --http-cert-file options in the following formats:
      • Privacy-Enhanced Mail (PEM) encoded certificate (RFC 7468). Note that the IdM installer accepts concatenated PEM-encoded objects.
      • Distinguished Encoding Rules (DER)
      • PKCS #7 certificate chain objects
      • PKCS #8 private key objects
      • PKCS #12 archives
      You can specify the --dirsrv-cert-file and --http-cert-file options multiple times to specify multiple files.
  • If necessary, the certificate files to complete the full CA certificate chain, supplied using this option:
    • --ca-cert-file, which you can add this option multiple times
  • Optionally, the certificate files to provide an external Kerberos key distribution center (KDC) PKINIT certificate, supplied using these options:
    • --pkinit-cert-file for the Kerberos KDC SSL certificate and private key
    • --pkinit-pin for the password to unlock the Kerberos KDC private key
    If you do not provide the PKINIT certificate, ipa-server-install configures the IdM server with a local KDC with a self-signed certificate. For details, see Chapter 27, Kerberos PKINIT Authentication in IdM.
The files provided using --dirsrv-cert-file and --http-cert-file combined with the files provided using --ca-cert-file must contain the full CA certificate chain of the CA that issued the LDAP and Apache server certificates.
For details on what the certificate file formats these options accept, see the ipa-server-install(1) man page.
Note
The listed command-line options are incompatible with the --external-ca option.
Note
Earlier versions of Identity Management used the --root-ca-file option to specify the PEM file of the root CA certificate. This is no longer necessary because the trusted CA is always the issuer of the DS and HTTP server certificates. IdM now automatically recognizes the root CA certificate from the certificates specified by --dirsrv-cert-file, --http-cert-file, and --ca-cert-file.

Example 2.3. Command example for installing an IdM server without a CA

[root@server ~]# ipa-server-install \
    --http-cert-file /tmp/server.crt \
    --http-cert-file /tmp/server.key \
    --http-pin secret \
    --dirsrv-cert-file /tmp/server.crt \
    --dirsrv-cert-file /tmp/server.key \
    --dirsrv-pin secret \
    --ca-cert-file ca.crt

2.3.7. Installing a Server Non-Interactively

Note
The minimum required options for a non-interactive installation are:
  • --ds-password to provide the password for the Directory Manager (DM), the Directory Server super user
  • --admin-password to provide the password for admin, the IdM administrator
  • --realm to provide the Kerberos realm name
  • --unattended to let the installation process select default options for the host name and domain name
Optionally, you can provide custom values for these settings:
  • --hostname for the server host name
  • --domain for the domain name
You can also use the --dirsrv-config-file parameter to change default Directory Server settings, by specifying the path to a LDIF file with custom values. For more information, see IdM now supports setting individual Directory Server options during server or replica installation in the Release Notes for Red Hat Enterprise Linux 7.3.
Warning
Red Hat strongly recommends that the Kerberos realm name is the same as the primary DNS domain name, with all letters uppercase. For example, if the primary DNS domain is ipa.example.com, use IPA.EXAMPLE.COM for the Kerberos realm name.
Different naming practices will prevent you from using Active Directory trusts and can have other negative consequences.
For a complete list of options accepted by ipa-server-install, run the ipa-server-install --help command.

Example 2.4. Basic Installation without Interaction

  1. Run the ipa-server-install utility, providing the required settings. For example, the following installs a server without integrated DNS and with an integrated CA: 
    # ipa-server-install --realm EXAMPLE.COM --ds-password DM_password --admin-password admin_password --unattended
  2. The setup script now configures the server. Wait for the operation to complete.
  3. The installation script produces a file with DNS resource records: the /tmp/ipa.system.records.UFRPto.db file in the example output below. Add these records to the existing external DNS servers. The process of updating the DNS records varies depending on the particular DNS solution. 
    ...
Restarting the KDC
Please add records in this file to your DNS system: /tmp/ipa.system.records.UFRBto.db
Restarting the web server
...
    Important
    The server installation is not complete until you add the DNS records to the existing DNS servers.
The script recommends you to back up the CA certificate and to make sure the required network ports are open. For information about IdM port requirements and instructions on how to open these ports, see Section 2.1.6, “Port Requirements”.
To test the new server:
  1. Authenticate to the Kerberos realm using the admin credentials. This verifies that admin is properly configured and the Kerberos realm is accessible. 
    # kinit admin
  2. Run a command such as ipa user-find. On a new server, the command prints the only configured user: admin. 
    # ipa user-find admin
--------------
1 user matched
--------------
User login: admin 
Last name: Administrator 
Home directory: /home/admin 
Login shell: /bin/bash 
UID: 939000000 
GID: 939000000 
Account disabled: False 
Password: True 
Kerberos keys available: True 
----------------------------
Number of entries returned 1
----------------------------

[1] For details, see the DNS Amplification Attacks page.

2.4. Uninstalling an IdM Server

Note
At domain level 0, the procedure is different. See Section D.3.6, “Removing a Replica”.

Prerequisites

  • Before uninstalling a server that serves as a certificate authority (CA), key recovery authority (KRA), or DNS Security Extensions (DNSSEC) server, make sure these services are running on another server in the domain.
    Warning
    Removing the last replica that serves as a CA, KRA, or DNSSEC server can seriously disrupt the Identity Management functionality.

Procedure

To uninstall server.example.com:
  1. On another server, use the ipa server-del command to delete server.example.com from the topology: 
    [root@another_server ~]# ipa server-del server.example.com
  2. On server.example.com, use the ipa-server-install --uninstall command: 
    [root@server ~]# ipa-server-install --uninstall
  3. Make sure all name server (NS) DNS records pointing to server.example.com are deleted from your DNS zones. This applies regardless of whether you use integrated DNS managed by IdM or external DNS.

2.5. Renaming a Server

It is not possible to change the host name of an IdM server after it was set up. However, you can replace the server with a replica with a different name.
  1. Create a new replica of the server, with a CA and with the new required host name or IP address. This is described in Chapter 4, Installing and Uninstalling Identity Management Replicas.
  2. Stop the initial IdM server instance. 
    [root@old_server ~]# ipactl stop
  3. Verify that all other replicas and clients are working as before.
  4. Uninstall the initial IdM server, as described in Section 2.4, “Uninstalling an IdM Server”

Chapter 3. Installing and Uninstalling Identity Management Clients

This chapter explains how to configure a system to join an Identity Management (IdM) domain as a client machine enrolled with a server.
Note
See Section 1.2, “The Identity Management Domain” for details on clients and servers in the IdM domain.

3.1. Prerequisites for Installing a Client

DNS requirements
Employ proper DNS delegation. For details on DNS requirements in IdM, see Section 2.1.5, “Host Name and DNS Configuration”.
Do not alter the resolv.conf file on clients.
Port requirements
IdM clients connect to a number of ports on IdM servers to communicate with their services. These ports must be open on the IdM servers in the incoming direction. For more information on which ports IdM requires, see Section 2.1.6, “Port Requirements”.
On a client, open these ports in the outgoing direction. If you are using a firewall that does not filter outgoing packets, such as firewalld, the ports are already available in the outgoing direction.
Name Service Cache Daemon (NSCD) requirements
Red Hat recommends to disable NSCD on Identity Management machines. Alternatively, if disabling NSCD is not possible, only enable NSCD for maps that SSSD does not cache.
Both NSCD and the SSSD service perform caching, and problems can occur when systems use both services simultaneously. See the System-Level Authentication Guide for information on how to avoid conflicts between NSCD and SSSD.

3.1.1. Supported versions of RHEL for installing IdM clients

An Identity Management (IdM) deployment in which IdM servers are running on the latest minor version of RHEL 7 supports clients that are running on the latest minor versions of:
  • RHEL 7
    RHEL 8
    RHEL 9
Note
If you are planning to make your IdM deployment FIPS-compliant, {RH} strongly recommends migrating your environment to RHEL 9. RHEL 9 is the first major RHEL version certified for FIPS 140-3.

3.1.2. Prerequisites for Installing a Client in a FIPS Environment

In environments set up using Red Hat Enterprise Linux 7.4 and later:
  • You can configure a new client on a system with the Federal Information Processing Standard (FIPS) mode enabled. The installation script automatically detects a system with FIPS enabled and configures IdM without the administrator's intervention.
    To enable FIPS in the operating system, see Enabling FIPS Mode in the Security Guide.
In environments set up using Red Hat Enterprise Linux 7.3 and earlier:
  • IdM does not support the FIPS mode. Disable FIPS on your system before installing an IdM client, and do not enable it after the installation.
For further details about FIPS mode, see Federal Information Processing Standard (FIPS) in the Security Guide.

3.2. Packages Required to Install a Client

Install the ipa-client package: 
# yum install ipa-client
The ipa-client package automatically installs other required packages as dependencies, such as the System Security Services Daemon (SSSD) packages.

3.3. Installing a Client

The ipa-client-install utility installs and configures an IdM client. The installation process requires you to provide credentials that can be used to enroll the client. The following authentication methods are supported:
Credentials of a user authorized to enroll clients, such as admin
By default, ipa-client-install expects this option. See Section 3.3.1, “Installing a Client Interactively” for an example.
To provide the user credentials directly to ipa-client-install, use the --principal and --password options.
A random, one-time password pre-generated on the server
To use this authentication method, add the --random option to ipa-client-install option. See Example 3.1, “Installing a Client Non-interactively Using a Random Password”.
A principal from a previous enrollment
To use this authentication method, add the --keytab option to ipa-client-install. See Section 3.8, “Re-enrolling a Client into the IdM Domain” for details.
See the ipa-client-install(1) man page for details.
The following sections document basic installation scenarios. For more details on using ipa-client-install and a complete list of the accepted options, see the ipa-client-install(1) man page.

3.3.1. Installing a Client Interactively

The following procedure installs a client while prompting the user for input when required. The user provides credentials of a user authorized to enroll clients into the domain, such as the admin user.
  1. Run the ipa-client-install utility.
    Add the --enable-dns-updates option to update the DNS records with the client machine's IP address if one of the following 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
    Add the --no-krb5-offline-passwords option to disable storing Kerberos passwords in the SSSD cache.
  2. The installation script attempts to obtain all the required settings automatically.
    1. If your DNS zone and SRV records are set properly on your system, the script automatically discovers all the required values and prints 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
      If you want to install the system with different values, cancel the current installation. Then run ipa-client-install again, and specify the required values using command-line options.
      For details, see the DNS Autodiscovery section in the ipa-client-install(1) man page.
    2. If the script fails to obtain some settings automatically, it prompts you for the values.
      Important
      Do not use single-label domain names, for example .company: the IdM domain must be composed of one or more subdomains and a top level domain, for example example.com or company.example.com.
      The fully qualified domain name must meet the following conditions:
      • It is a valid DNS name, which means only numbers, alphabetic characters, and hyphens (-) are allowed. Other characters, such as underscores (_), in the host name cause DNS failures.
      • It is all lower-case. No capital letters are allowed.
      • The fully qualified domain name must not resolve to the loopback address. It must resolve to the machine's public IP address, not to 127.0.0.1.
      For other recommended naming practices, see the Recommended Naming Practices in the Red Hat Enterprise Linux Security Guide.
  3. The script prompts for a user whose identity will be used to enroll the client. By default, this is the admin user: 
    User authorized to enroll computers: admin
Password for admin@EXAMPLE.COM
  4. The installation script now configures the client. Wait for the operation to complete. 
    Client configuration complete.
  5. Run the ipa-client-automount utility, which automatically configures NFS for IdM. See Section 34.2.1, “Configuring NFS Automatically” for details.

3.3.2. Installing a Client Non-interactively

For a non-interactive installation, provide all required information to the ipa-client-install utility using command-line options. The minimum required options for a non-interactive installation are:
  • options for specifying the credentials that will be used to enroll the client; see Section 3.3, “Installing a Client” for details
  • --unattended to let the installation run without requiring user confirmation
If your DNS zone and SRV records are set properly on your system, the script automatically discovers all the other required values. If the script cannot discover the values automatically, provide them using command-line options.
  • --hostname to specify a static host name for the client machine
    Important
    Do not use single-label domain names, for example .company: the IdM domain must be composed of one or more subdomains and a top level domain, for example example.com or company.example.com.
    The fully qualified domain name must meet the following conditions:
    • It is a valid DNS name, which means only numbers, alphabetic characters, and hyphens (-) are allowed. Other characters, such as underscores (_), in the host name cause DNS failures.
    • It is all lower-case. No capital letters are allowed.
    • The fully qualified domain name must not resolve to the loopback address. It must resolve to the machine's public IP address, not to 127.0.0.1.
    For other recommended naming practices, see the Recommended Naming Practices in the Red Hat Enterprise Linux Security Guide.
  • --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
Add the --enable-dns-updates option to update the DNS records with the client machine's IP address if one of the following 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
Add the --no-krb5-offline-passwords option to disable storing Kerberos passwords in the SSSD cache.
For a complete list of options accepted by ipa-client-install, see the ipa-client-install(1) man page.

Example 3.1. Installing a Client Non-interactively Using a Random Password

This procedure installs a client without prompting the user for any input. The process includes pre-generating a random one-time password on the server that is used to authorize the enrollment.
  1. On an existing server:
    1. Log in as the administrator: 
      $ kinit admin
    2. Add the new machine as an IdM host. Use the --random option with the ipa host-add command to generate the random password. 
      $ 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
      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.
  2. On the machine where you want to install the client, run ipa-client-install, and use these options:
    • --password for the random password from the ipa host-add output
      Note
      The password often contains special characters. Therefore, enclose it in single quotes (').
    • --unattended to let the installation run without requiring user confirmation
    If your DNS zone and SRV records are set properly on your system, the script automatically discovers all the other required values. If the script cannot discover the values automatically, provide them using command-line options.
    For example: 
    # ipa-client-install --password 'W5YpARl=7M.n' --domain example.com --server server.example.com --unattended
  3. Run the ipa-client-automount utility, which automatically configures NFS for IdM. See Section 34.2.1, “Configuring NFS Automatically” for details.

3.4. Setting up an IdM Client Through Kickstart

A Kickstart enrollment automatically adds a new system to the IdM domain at the time Red Hat Enterprise Linux is installed. For details on Kickstart, see Kickstart Installations in the Installation Guide.
Preparing for a Kickstart client installation includes these steps:
  1. Section 3.4.1, “Pre-creating a Client Host Entry on the IdM Server”
  2. Section 3.4.2, “Creating a Kickstart File for the Client”

3.4.1. Pre-creating a Client Host Entry on the IdM Server

  1. Log in as admin: 
    $ kinit admin
  2. Create the host entry on the IdM server, and set a temporary password for the entry: 
    $ ipa host-add client.example.com --password=secret
    The password is used by Kickstart to authenticate during the client installation and expires after the first authentication attempt. After the client is successfully installed, it authenticates using its keytab.

3.4.2. Creating a Kickstart File for the Client

A Kickstart file used to set up an IdM client must include the following:
  • The ipa-client package in the list of packages to be installed: 
    %packages
@ X Window System
@ Desktop
@ Sound and Video
ipa-client
...
    See Package Selection in the Installation Guide for details.
  • Post-installation instructions that:
    • ensure SSH keys are generated before enrollment
    • runs the ipa-client-install utility, specifying:
      For example: 
      %post --log=/root/ks-post.log

# Generate SSH keys to ensure that ipa-client-install uploads them to the IdM server
/usr/sbin/sshd-keygen

# Run the client install script
/usr/sbin/ipa-client-install --hostname=client.example.com --domain=EXAMPLE.COM --enable-dns-updates --mkhomedir -w secret --realm=EXAMPLE.COM --server=server.example.com
    For a non-interactive installation, add also the --unattended option.
    To let the client installation script request a certificate for the machine:
    • Add the --request-cert option to ipa-client-install.
    • Set the system bus address to /dev/null for both the getcert and ipa-client-install utility in the kickstart chroot environment. To do this, add these lines to the post-installation instruction file before the ipa-client-install instruction: 
      # env DBUS_SYSTEM_BUS_ADDRESS=unix:path=/dev/null getcert list
# env DBUS_SYSTEM_BUS_ADDRESS=unix:path=/dev/null ipa-client-install
    Note
    Red Hat recommends not to start the sshd service prior to the kickstart enrollment. While starting sshd before enrolling the client generates the SSH keys automatically, using the above script is the preferred solution.
    See Post-installation Script in the Installation Guide for details.
For details on using Kickstart, see How Do You Perform a Kickstart Installation? in the Installation Guide. For examples of Kickstart files, see Sample Kickstart Configurations.

3.5. Post-installation Considerations for Clients

3.5.1. Removing Pre-Identity Management Configuration

The ipa-client-install script does not remove any previous LDAP and 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 configuration values:
  1. Open /etc/openldap/ldap.conf and /etc/sssd/sssd.conf.
  2. Delete the previous configuration.
  3. Uncomment the new Identity Management 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.

3.6. Testing the New Client

Check that the client can obtain information about users 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)

3.7. Uninstalling a Client

Uninstalling a client removes the client from the IdM domain, along with all of the IdM-specific configuration for system services, such as SSSD. This restores the client machine's previous configuration.
  1. Run the ipa-client-install --uninstall command: 
    # ipa-client-install --uninstall
  2. Remove the DNS entries for the client host manually from the server. See Section 33.4.6, “Deleting Records from DNS Zones”.

3.8. Re-enrolling a Client into the IdM Domain

If a client virtual machine has been destroyed and you still have its keytab, you can re-enroll the client:
Note
You can only re-enroll clients whose domain entry is still active. If you uninstalled a client (using ipa-client-install --uninstall) or disabled its host entry (using ipa host-disable), you cannot re-enroll it.
During re-enrollment, IdM performs the following:
  • Revokes the original host certificate
  • Generates a new host certificate
  • Creates new SSH keys
  • Generates a new keytab

3.8.1. Re-enrolling a Client Interactively Using the Administrator Account

  1. Re-create the client machine with the same host name.
  2. Run the ipa-client-install --force-join command on the client machine: 
    # ipa-client-install --force-join
  3. The script prompts for a user whose identity will be used to enroll the client. By default, this is the admin user: 
    User authorized to enroll computers: admin
Password for admin@EXAMPLE.COM

3.8.2. Re-enrolling a Client Non-interactively Using the Client Keytab

Re-enrollment using the client keytab is appropriate for automated installation or in other situations when using the administrator password is not feasible.
  1. Back up the original client's keytab file, for example in the /tmp or /root directory.
  2. Re-create the client machine with the same host name.
  3. Re-enroll the client, and specify the keytab location using the --keytab option: 
    # ipa-client-install --keytab /tmp/krb5.keytab
    Note
    The keytab specified in the --keytab option is only used when authenticating to initiate the enrollment. During the re-enrollment, IdM generates a new keytab for the client.

3.9. Renaming Client Machines

This section explains how to rename an IdM client. The process involves:
Warning
Renaming a client is a manual procedure. Red Hat does not recommend it unless changing the host name is absolutely required.

Identifying Current Service and Keytab Configuration

Before uninstalling the current client, make note of certain settings for the client. You will apply this configuration after re-enrolling the machine with a new host name.
  1. Identify which services are running on the machine:
    1. Use the ipa service-find command, and identify services with certificates in the output: 
      $ ipa service-find client.example.com
    2. In addition, each host has a default host service which does not appear in the ipa service-find output. The service principal for the host service, also called a host principal, is host/client.example.com.
  2. Identify all host groups to which the machine belongs. 
    # ipa hostgroup-find client.example.com
  3. For all service principals displayed by ipa service-find client.example.com, determine the location of the corresponding keytabs on client.example.com.
    Each service on the client system has a Kerberos principal in the form service_name/hostname@REALM, such as ldap/client.example.com@EXAMPLE.COM.

Removing the Client Machine from the IdM Domain

  1. Unenroll the client machine from the IdM domain. See Section 3.7, “Uninstalling a Client”.
  2. For each identified keytab other than /etc/krb5.keytab, remove the old principals: 
    [root@client ~]# ipa-rmkeytab -k /path/to/keytab -r EXAMPLE.COM
    See Section 29.4, “Removing Keytabs”.
  3. On an IdM server, remove the host entry. This removes all services and revokes all certificates issued for that host: 
    [root@server ~]# ipa host-del client.example.com
At this point, the host is completely removed from IdM.

Re-enrolling the Client with a New Host Name

  1. Rename the machine as required.
  2. Re-enroll the machine as an IdM client. See Section 3.8, “Re-enrolling a Client into the IdM Domain”.
  3. On an IdM server, add a new keytab for every service identified in the section called “Identifying Current Service and Keytab Configuration”. 
    [root@server ~]# ipa service-add service_name/new_host_name
  4. Generate certificates for services that had a certificate assigned in the section called “Identifying Current Service and Keytab Configuration”. You can do this:
  5. Re-add the client to the host groups identified in the section called “Identifying Current Service and Keytab Configuration”. See Section 13.3, “Adding and Removing User or Host Group Members”.

Chapter 4. Installing and Uninstalling Identity Management Replicas

Replicas are created by cloning the configuration of existing Identity Management servers. Therefore, servers and their replicas share identical core configuration. The replica installation process copies the existing server configuration and installs the replica based on that configuration.
Maintaining several server replicas is a recommended backup solution to avoid data loss, as described in the "Backup and Restore in IdM/IPA" Knowledgebase solution.
Note
Another backup solution, recommended primarily for situations when rebuilding the IdM deployment from replicas is not possible, is the ipa-backup utility, as described in Chapter 9, Backing Up and Restoring Identity Management.

4.1. Explaining IdM Replicas

To provide service availability and redundancy for large numbers of clients, you can deploy multiple IdM servers, called replicas, in a single domain. Replicas are clones of the initial IdM server that are functionally identical to each other: they share the same internal information about users, machines, certificates, and configured policies.
There are, however, two unique server roles that only one server in the environment can fulfill at a time:
  • CA Renewal Server: this server manages renewal of Certificate Authority (CA) subsystem certificates
  • CRL Generation Server: this server generates certificate revocation lists (CRLs).
By default, the first CA server installed fulfills both CA Renewal Server and CRL Generation Server roles. You can transition these roles to any other CA server in the topology, for example if you need to decommission the initially installed server. Both roles do not have to be fulfilled by the same server.
Note
For more information on the types of machines in the IdM topology, see Section 1.2, “The Identity Management Domain”.
Replication is the process of copying data between replicas. The information between replicas is shared using multi-master replication: all replicas joined through a replication agreement receive updates and are therefore considered data masters.

Figure 4.1. Server and Replica Agreements

Server and Replica Agreements

4.2. Deployment Considerations for Replicas

4.2.1. Distribution of Server Services in the Topology

IdM servers can run a number of services, such as a certificate authority (CA) or DNS. A replica can run the same services as the server it was created from, but it is not necessary.
For example, you can install a replica without DNS services, even if the initial server runs DNS. Similarly, you can set up a replica as a DNS server even if the initial server was installed without DNS.

Figure 4.2. Replicas with Different Services

Replicas with Different Services

CA Services on Replicas

If you set up a replica without a CA, it will forward all requests for certificate operations to the CA server in your topology.
Warning
Red Hat strongly recommends to keep the CA services installed on more than one server. For information on installing a replica of the initial server including the CA services, see Section 4.5.4, “Installing a Replica with a CA”.
If you install the CA on only one server, you risk losing the CA configuration without a chance of recovery if the CA server fails. See Section B.2.6, “Recovering a Lost CA Server” for details.
If you set up a CA on the replica, its configuration must mirror the CA configuration of the initial server.

4.2.2. Replica Topology Recommendations

Red Hat recommends to follow these guidelines:
Configure no more than 60 replicas in a single IdM domain
Red Hat guarantees to support environments with 60 replicas or less.
Configure at least two, but no more than four replication agreements per each replica
Configuring additional replication agreements ensures that information is replicated not just between the initial replica and the master server, but between other replicas as well.
  • If you create replica B from server A and then replica C from server A, replicas B and C are not directly joined, so data from replica B must first be replicated to server A before propagating to replica C.

    Figure 4.3. Replicas B and C Are Not Joined in a Replication Agreement

    Replicas B and C Are Not Joined in a Replication Agreement
    Setting up an additional replication agreement between replica B and replica C ensures the data is replicated directly, which improves data availability, consistency, failover tolerance, and performance.

    Figure 4.4. Replicas B and C Are Joined in a Replication Agreement

    Replicas B and C Are Joined in a Replication Agreement
    See Chapter 6, Managing Replication Topology for details on managing replication agreements.
Configuring more than four replication agreements per replica is unnecessary. A large number of replication agreements per server does not bring significant additional benefits, because one consumer server can only be updated by one master at a time, so the other agreements are meanwhile idle and waiting. Additionally, configuring too many replication agreements can have a negative impact on overall performance.
Note
The ipa topologysuffix-verify command checks if your topology meets the most important recommendations. Run ipa topologysuffix-verify --help for details.
The command requires you to specify the topology suffix. See Section 6.1, “Explaining Replication Agreements, Topology Suffixes, and Topology Segments” for details.

Figure 4.5. Topology Example

Topology Example

4.2.2.1. Tight Cell Topology

One of the most resilient topologies is to create a cell configuration for the servers and replicas with a small number of servers in a cell:
  • Each of the cells is a tight cell, where all servers have replication agreements with each other.
  • Each server has one replication agreement with another server outside the cell. This ensures that every cell is loosely coupled to every other cell in the domain.
To accomplish a tight cell topology:
  • Have at least one IdM server in each main office, data center, or locality. Preferably, have two IdM servers.
  • Do not have more than four servers per data center.
  • In small offices, rather than using a replica, use SSSD to cache credentials and an off-site IdM server as the data back end.

4.2.3. The Hidden Replica Mode

By default, when you set up a new replica, the installer automatically creates service (SRV) resource records in DNS. These records enables clients to auto-discover the replica and its services. A hidden replica is an IdM server that has all services running and available. However, it has no SRV records in DNS, and LDAP server roles are not enabled. Therefore, clients cannot use service discovery to detect these hidden replicas.
Note
The hidden replica feature is available in Red Hat Enterprise Linux 7.7 and later as a Technology Preview and, therefore, not supported.
Hidden replicas are primarily designed for dedicated services that can otherwise disrupt clients. For example, a full backup of IdM requires to shut down all IdM services on the master or replica. Since no clients use a hidden replica, administrators can temporarily shut down the services on this host without affecting any clients. Other use cases include high-load operations on the IdM API or the LDAP server, such as a mass import or extensive queries.
To install a replica as hidden, pass the --hidden-replica parameter to the ipa-replica-install command. For further details about installing a replica, see Section 4.5, “Creating the Replica: Introduction”.
Alternatively, you can change the state of an existing replica. For details, see Section 6.5.3, “Demotion and Promotion of Hidden Replicas”.

4.3. Prerequisites for Installing a Replica

The installation requirements for replicas are the same as for IdM servers. Make sure that the replica machine meets all of the prerequisites listed in Section 2.1, “Prerequisites for Installing a Server”.
In addition to the general server requirements, you must also meet the following conditions:
The replica must be running the same or later version of IdM
For example, if the master server is running on Red Hat Enterprise Linux 7 and uses the IdM 4.4 packages, then the replica must also run on Red Hat Enterprise Linux 7 or later and use IdM version 4.4 or later. This ensures that configuration can be properly copied from the server to the replica.
Important
IdM does not support creating a replica of an earlier version than the version of the master. If you try to create a replica using an earlier version, the installation fails.
The replica needs additional ports to be open
In addition to the standard IdM server port requirements described in Section 2.1.6, “Port Requirements”, make sure you also meet the following:
  • At domain level 0, keep the TCP port 22 open on the master server during the replica setup process. This port is required in order to use SSH to connect to the master server.
    Note
    For details on domain levels, see Chapter 7, Displaying and Raising the Domain Level.
  • If one of the servers is running Red Hat Enterprise Linux 6 and has a CA installed, keep also TCP port 7389 open during and after the replica configuration. In a purely Red Hat Enterprise Linux 7 environment, port 7389 is not required.
For information on how to open ports using the firewall-cmd utility, see Section 2.1.6, “Port Requirements”.

4.4. Packages Required to Install a Replica

Replica package requirements are the same as server package requirements. See Section 2.2, “Packages Required to Install an IdM Server”.

4.5. Creating the Replica: Introduction

The ipa-replica-install utility is used to install a new replica from an existing IdM server. Install Identity Management replicas one at a time. The installation of multiple replicas at the same time is not supported.
Note
This chapter describes the simplified replica installation introduced in Red Hat Enterprise Linux 7.3. The procedures require domain level 1 (see Chapter 7, Displaying and Raising the Domain Level).
For documentation on installing a replica at domain level 0, see Appendix D, Managing Replicas at Domain Level 0.
You can install a new replica:
In both of these situations, you can customize your replica by adding options to ipa-replica-install: see the section called “Using ipa-replica-install to Configure the Replica for Your Use Case”.
To install the replica as hidden, pass the --hidden-replica parameter to ipa-replica-install. For further details about hidden replicas, see Section 4.2.3, “The Hidden Replica Mode”.
Important
If the IdM server you are replicating has a trust with Active Directory, set up the replica as a trust agent after running ipa-replica-install. See Trust Controllers and Trust Agents in the Windows Integration Guide.

Promoting an Existing Client to a Replica

To install the replica on an existing client, you must make sure the client is authorized to be promoted. To achieve this, choose one of the following:
Provide a privileged user's credentials
The default privileged user is admin. There are multiple ways to provide the user's credentials. You can:
  • let IdM prompt you to get the credentials interactively
    Note
    This is the default way to provide the privileged user's credentials. If no credentials are available when ipa-replica-install runs, the installation automatically prompts you.
  • log in as the user before running ipa-replica-install on the client: 
    $ kinit admin
  • add the user's principal name and password to ipa-replica-install directly: 
    # ipa-replica-install --principal admin --admin-password admin_password
Add the client to the ipaservers host group
Membership in ipaservers grants the machine elevated privileges analogous to a privileged user's credentials. You will not be required to provide the user's credentials.
Example: Section 4.5.1, “Promoting a Client to a Replica Using a Host Keytab”

Installing a Replica on a Machine That Is Not a Client

When run on a machine that has not yet been enrolled in the IdM domain, ipa-replica-install first enrolls the machine as a client and then installs the replica components.
To install a replica in this situation, choose one of the following:
Provide a privileged user's credentials
The default privileged user is admin. To provide the credentials, add the principal name and password to ipa-replica-install directly: 
# ipa-replica-install --principal admin --admin-password admin_password
Provide a random password for the client
You must generate the random password on a server before installing the replica. You will not be required to provide the user's credentials during the installation.
Example: Section 4.5.2, “Installing a Replica Using a Random Password”
By default, the replica is installed against the first IdM server discovered by the client installer. To install the replica against a particular server, add the following options to ipa-replica-install:
  • --server for the server's fully qualified domain name (FQDN)
  • --domain for the IdM DNS domain

Using ipa-replica-install to Configure the Replica for Your Use Case

When run without any options, ipa-replica-install only sets up basic server services. To install additional services, such as DNS or a certificate authority (CA), add options to ipa-replica-install.
Warning
Red Hat strongly recommends to keep the CA services installed on more than one server. For information on installing a replica of the initial server including the CA services, see Section 4.5.4, “Installing a Replica with a CA”.
If you install the CA on only one server, you risk losing the CA configuration without a chance of recovery if the CA server fails. See Section B.2.6, “Recovering a Lost CA Server” for details.
For example scenarios of installing a replica with the most notable options, see:
You can also use the --dirsrv-config-file parameter to change default Directory Server settings, by specifying the path to a LDIF file with custom values. For more information, see IdM now supports setting individual Directory Server options during server or replica installation in the Release Notes for Red Hat Enterprise Linux 7.3.
For a complete list of the options used to configure the replica, see the ipa-replica-install(1) man page.

4.5.1. Promoting a Client to a Replica Using a Host Keytab

In this procedure, an existing IdM client is promoted to a replica using its own host keytab to authorize the promotion.
The procedure does not require you to provide the administrator or Directory Manager (DM) credentials. It is therefore more secure because no sensitive information is exposed on the command line.
  1. On an existing server:
    1. Log in as the administrator. 
      $ kinit admin
    2. Add the client machine to the ipaservers host group. 
      $ ipa hostgroup-add-member ipaservers --hosts client.example.com
  Host-group: ipaservers
  Description: IPA server hosts
  Member hosts: server.example.com, client.example.com
-------------------------
Number of members added 1
-------------------------
      Membership in ipaservers grants the machine elevated privileges analogous to the administrator's credentials.
  2. On the client, run the ipa-replica-install utility. 
    # ipa-replica-install
  3. Optionally, if the IdM server you are replicating has a trust with Active Directory, set up the replica as a trust agent or trust controller. For details, see Trust Controllers and Trust Agents in the Windows Integration Guide.

4.5.2. Installing a Replica Using a Random Password

In this procedure, a replica is installed from scratch on a machine that is not yet an IdM client. To authorize the enrollment, a client-specific random password valid for one client enrollment only is used.
The procedure does not require you to provide the administrator or Directory Manager (DM) credentials. It is therefore more secure because no sensitive information is exposed on the command line.
  1. On an existing server:
    1. Log in as the administrator. 
      $ kinit admin
    2. Add the new machine as an IdM host. Use the --random option with the ipa host-add command to generate a random one-time password to be used for the replica installation. 
      $ 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
      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.
    3. Add the machine to the ipaservers host group. 
      $ ipa hostgroup-add-member ipaservers --hosts client.example.com
  Host-group: ipaservers
  Description: IPA server hosts
  Member hosts: server.example.com, client.example.com
-------------------------
Number of members added 1
-------------------------
      Membership in ipaservers grants the machine elevated privileges required to set up the necessary server services.
  2. On the machine where you want to install the replica, run ipa-replica-install, and provide the random password using the --password option. Enclose the password in single quotes (') because it often contains special characters: 
    # ipa-replica-install --password 'W5YpARl=7M.n'
  3. Optionally, if the IdM server you are replicating has a trust with Active Directory, set up the replica as a trust agent or trust controller. For details, see Trust Controllers and Trust Agents in the Windows Integration Guide.

4.5.3. Installing a Replica with DNS

This procedure works for installing a replica on a client as well as on a machine that is not part of the IdM domain yet. See Section 4.5, “Creating the Replica: Introduction” for details.
  1. Run ipa-replica-install with these options:
    • --setup-dns to create a DNS zone if it does not exist already and configure the replica as the DNS server
    • --forwarder to specify a forwarder, or --no-forwarder if you do not want to use any forwarders
      To specify multiple forwarders for failover reasons, use --forwarder multiple times.
    For example: 
    # ipa-replica-install --setup-dns --forwarder 192.0.2.1
    Note
    The ipa-replica-install utility accepts a number of other options related to DNS settings, such as --no-reverse or --no-host-dns. For more information about them, see the ipa-replica-install(1) man page.
  2. If the initial server was created with DNS enabled, the replica is automatically created with the proper DNS entries. The entries ensure that IdM clients will be able to discover the new server.
    If the initial server did not have DNS enabled, add the DNS records manually. The following DNS records are necessary for the domain services:
    • _ldap._tcp
    • _kerberos._tcp
    • _kerberos._udp
    • _kerberos-master._tcp
    • _kerberos-master._udp
    • _ntp._udp
    • _kpasswd._tcp
    • _kpasswd._udp
    This example shows how to verify that the entries are present:
    1. Set the appropriate values for the DOMAIN and NAMESERVER variables: 
      # DOMAIN=example.com
# NAMESERVER=replica
    2. Use the following command to check for the DNS entries: 
      # for i in _ldap._tcp _kerberos._tcp _kerberos._udp _kerberos-master._tcp _kerberos-master._udp _ntp._udp ; do
dig @${NAMESERVER} ${i}.${DOMAIN} srv +nocmd +noquestion +nocomments +nostats +noaa +noadditional +noauthority
done | egrep "^_"

_ldap._tcp.example.com. 86400     IN    SRV     0 100 389 server1.example.com.
_ldap._tcp.example.com. 86400     IN    SRV     0 100 389 server2.example.com.
_kerberos._tcp.example.com. 86400 IN    SRV     0 100 88  server1.example.com.
...
  3. Add DNS delegation from the parent domain to the IdM DNS domain. For example, if the IdM DNS domain is ipa.example.com, add a name server (NS) record to the example.com parent domain.
    Important
    This step must be repeated each time an IdM DNS server is installed.
  4. Optional, but recommended. Manually add other DNS servers as backup servers in case the replica becomes unavailable. See Section 33.11.1, “Setting up Additional Name Servers”. This is recommended especially for situations when the new replica is your first DNS server in the IdM domain.
  5. Optionally, if the IdM server you are replicating has a trust with Active Directory, set up the replica as a trust agent or trust controller. For details, see Trust Controllers and Trust Agents in the Windows Integration Guide.

4.5.4. Installing a Replica with a CA

This procedure works for installing a replica on a client as well as on a machine that is not part of the IdM domain yet. See Section 4.5, “Creating the Replica: Introduction” for details.
  1. Run ipa-replica-install with the --setup-ca option. 
    [root@replica ~]# ipa-replica-install --setup-ca
  2. The --setup-ca option copies the CA configuration from the initial server's configuration, regardless of whether the IdM CA on the server is a root CA or whether it is subordinated to an external CA.
    Note
    For details on the supported CA configurations, see Section 2.3.2, “Determining What CA Configuration to Use”.
  3. Optionally, if the IdM server you are replicating has a trust with Active Directory, set up the replica as a trust agent or trust controller. For details, see Trust Controllers and Trust Agents in the Windows Integration Guide.

4.5.5. Installing a Replica from a Server without a CA

This procedure works for installing a replica on a client as well as on a machine that is not part of the IdM domain yet. See Section 4.5, “Creating the Replica: Introduction” for details.
Important
You cannot install a server or replica using self-signed third-party server certificates.
  1. Run ipa-replica-install, and provide the required certificate files by adding these options:
    • --dirsrv-cert-file
    • --dirsrv-pin
    • --http-cert-file
    • --http-pin
    For details about the files that are provided using these options, see Section 2.3.6, “Installing Without a CA”.
    For example: 
    [root@replica ~]# ipa-replica-install \
    --dirsrv-cert-file /tmp/server.crt \
    --dirsrv-cert-file /tmp/server.key \
    --dirsrv-pin secret \
    --http-cert-file /tmp/server.crt \
    --http-cert-file /tmp/server.key \
    --http-pin secret
    Note
    Do not add the --ca-cert-file option. The ipa-replica-install utility takes this part of the certificate information automatically from the master server.
  2. Optionally, if the IdM server you are replicating has a trust with Active Directory, set up the replica as a trust agent or trust controller. For details, see Trust Controllers and Trust Agents in the Windows Integration Guide.

4.6. Testing the New Replica

To check if replication works as expected after creating a replica:
  1. Create a user on one of the servers: 
    [admin@server1 ~]$ ipa user-add test_user --first=Test --last=User
  2. Make sure the user is visible on the other server: 
    [admin@server2 ~]$ ipa user-show test_user

4.7. Uninstalling a Replica

See Section 2.4, “Uninstalling an IdM Server”.

Part III. Administration: Managing Servers

This part covers administration-related topics, such as managing the Identity Management server and services and replication between servers in an Identity Management domain, provides details on the Identity Management topology and gives instructions on how to update the Identity Management packages on the system. Furthermore, this part explains how to manually back up and restore the Identity Management system in case of a disaster affecting an Identity Management deployment. The final chapter details the different internal access control mechanisms.

Chapter 5. The Basics of Managing the IdM Server and Services

This chapter describes the Identity Management command-line and UI tools that are available to manage the IdM server and services, including methods for authenticating to IdM.

5.1. Starting and Stopping the IdM Server

A number of different services are installed together with an IdM server, including Directory Server, Certificate Authority (CA), DNS, Kerberos, and others. Use the ipactl utility to stop, start, or restart the entire IdM server along with all the installed services.
To start the entire IdM server: 
# ipactl start
To stop the entire IdM server: 
# ipactl stop
To restart the entire IdM server: 
# ipactl restart
If you only want to stop, start, or restart an individual service, use the systemctl utility, described in the System Administrator's Guide. For example, using systemctl to manage individual services is useful when customizing the Directory Server behavior: the configuration changes require restarting the Directory Server instance, but it is not necessary to restart all the IdM services.
Important
To restart multiple IdM domain services, Red Hat always recommends to use ipactl. Because of dependencies between the services installed with the IdM server, the order in which they are started and stopped is critical. The ipactl utility ensures that the services are started and stopped in the appropriate order.

5.2. Logging into IdM Using Kerberos

IdM uses the Kerberos protocol to support single sign-on. With Kerberos, users only need to present the correct username and password once and can access IdM services without the system prompting for credentials again.
By default, only machines that are members of the IdM domain can use Kerberos to authenticate to IdM. However, it is possible to configure external systems for Kerberos authentication as well; for more information, see Section 5.4.4, “Configuring an External System for Kerberos Authentication to the Web UI”.

Using kinit

To log in to IdM from the command line, use the kinit utility.
Note
To use kinit, the krb5-workstation package must be installed.
When run without specifying a user name, kinit logs into IdM under the user name of the user that is currently logged-in on the local system. For example, if you are logged-in as local_user on the local system, running kinit attempts to authenticate you as the local_user IdM user: 
[local_user@server ~]$ kinit
Password for local_user@EXAMPLE.COM:
Note
If the user name of the local user does not match any user entry in IdM, the authentication attempt fails.
To log in as a different IdM user, pass the required user name as a parameter to the kinit utility. For example, to log in as the admin user: 
[local_user@server ~]$ kinit admin
Password for admin@EXAMPLE.COM:

Obtaining Kerberos Tickets Automatically

The pam_krb5 pluggable authentication module (PAM) and SSSD can be configured to automatically obtain a TGT for a user after a successful login in to the desktop environment on an IdM client machine. This ensures that after logging in, the user is not required to run kinit.
On IdM systems that have IdM configured in SSSD as the identity and authentication provider, SSSD obtains the TGT automatically after the user logs in with the corresponding Kerberos principal name.
For information on configuring pam_krb5, see the pam_krb5(8) man page. For general information about PAM, see the System-Level Authentication Guide.

Storing Multiple Kerberos Tickets

By default, Kerberos only stores one ticket per logged-in user in the credential cache. Whenever a user runs kinit, Kerberos overwrites the currently-stored ticket with the new ticket. For example, if you use kinit to authenticate as user_A, the ticket for user_A will be lost after you authenticate again as user_B.
To obtain and store another TGT for a user, set a different credential cache, which ensures the contents of the previous cache are not overwritten. You can do this in one of the following two ways:
  • Run the export KRB5CCNAME=path_to_different_cache command, and then use kinit to obtain the ticket.
  • Run the kinit -c path_to_different_cache command, and then reset the KRB5CCNAME variable.
To restore the original TGT stored in the default credential cache:
  1. Run the kdestroy command.
  2. Restore the default credential cache location using the unset $KRB5CCNAME command.

Checking the Current Logged-in User

To verify what TGT is currently stored and used for authentication, use the klist utility to list cached tickets. In the following example, the cache contains a ticket for user_A, which means that only user_A is currently allowed to access IdM services: 
$ klist
Ticket cache: KEYRING:persistent:0:0
Default principal: user_A@EXAMPLE.COM

Valid starting     	Expires            	Service principal
11/10/2015 08:35:45  	11/10/2015 18:35:45  	krbtgt/EXAMPLE.COM@EXAMPLE.COM

5.3. The IdM Command-Line Utilities

The basic command-line script for IdM is named ipa. The ipa script is a parent script for a number of subcommands. These subcommands are then used to manage IdM. For example, the ipa user-add command adds a new user: 
$ ipa user-add user_name
Command-line management has certain benefits over management in UI; for example, the command-line utilities allow management tasks to be automated and performed repeatedly in a consistent way without manual intervention. Additionally, while most management operations are available both from the command line and in the web UI, some tasks can only be performed from the command line.
Note
This section only provides a general overview of the ipa subcommands. More information is available in the other sections dedicated to specific areas of managing IdM. For example, for information about managing user entries using the ipa subcommands, see Chapter 11, Managing User Accounts.

5.3.1. Getting Help for ipa Commands

The ipa script can display help about a particular set of subcommands: a topic. To display the list of available topics, use the ipa help topics command: 
$ ipa help topics

automember         Auto Membership Rule.
automount          Automount
caacl              Manage CA ACL rules.
...
To display help for a particular topic, use the ipa help topic_name command. For example, to display information about the automember topic: 
$ ipa help automember

Auto Membership Rule.

Bring clarity to the membership of hosts and users by configuring inclusive
or exclusive regex patterns, you can automatically assign a new entries into
a group or hostgroup based upon attribute information.

...

EXAMPLES:

 Add the initial group or hostgroup:
   ipa hostgroup-add --desc="Web Servers" webservers
   ipa group-add --desc="Developers" devel
...
The ipa script can also display a list of available ipa commands. To do this, use the ipa help commands command: 
$ ipa help commands
automember-add                         Add an automember rule.
automember-add-condition               Add conditions to an automember rule.
...
For detailed help on the individual ipa commands, add the --help option to a command. For example: 
$ ipa automember-add --help

Usage: ipa [global-options] automember-add AUTOMEMBER-RULE [options]

Add an automember rule.
Options:
  -h, --help            show this help message and exit
  --desc=STR            A description of this auto member rule
...
For more information about the ipa utility, see the ipa(1) man page.

5.3.2. Setting a List of Values

IdM stores entry attributes in lists. For example: 
ipaUserSearchFields: uid,givenname,sn,telephonenumber,ou,title
Any update to a list of attributes overwrites the previous list. For example, an attempt to add a single attribute by only specifying this attribute replaces the whole previously-defined list with the single new attribute. Therefore, when changing a list of attributes, you must specify the whole updated list.
IdM supports the following methods of supplying a list of attributes:
  • Using the same command-line argument multiple times within the same command invocation. For example: 
    $ ipa permission-add --permissions=read --permissions=write --permissions=delete
  • Enclosing the list in curly braces, which allows the shell to do the expansion. For example: 
    $ ipa permission-add --permissions={read,write,delete}

5.3.3. Using Special Characters

When passing command-line arguments in ipa commands that include special characters, such as angle brackets (< and >), ampersand (&), asterisk (*), or vertical bar (|), you must escape these characters by using a backslash (\). For example, to escape an asterisk (*): 
$ ipa certprofile-show certificate_profile --out=exported\*profile.cfg
Commands containing unescaped special characters do not work as expected because the shell cannot properly parse such characters.

5.3.4. Searching IdM Entries

Listing IdM Entries

Use the ipa *-find commands to search for a particular type of IdM entries. For example:
  • To list all users: 
    $ ipa user-find
---------------
4 users matched
---------------
  ...
  • To list user groups whose specified attributes contain keyword: 
    $ ipa group-find keyword
----------------
2 groups matched
----------------
  ...
    To configure the attributes IdM searches for users and user groups, see Section 13.5, “Setting Search Attributes for Users and User Groups”.
When searching user groups, you can also limit the search results to groups that contain a particular user: 
$ ipa group-find --user=user_name
You can also search for groups that do not contain a particular user: 
$ ipa group-find --no-user=user_name

Showing Details for a Particular Entry

Use the ipa *-show command to display details about a particular IdM entry. For example: 
$ ipa host-show server.example.com
 Host name: server.example.com
 Principal name: host/server.example.com@EXAMPLE.COM
 ...

5.3.4.1. Adjusting the Search Size and Time Limit

Some search results, such as viewing lists of users, can return a very large number of entries. By tuning these search operations, you can improve overall server performance when running the ipa *-find commands, such as ipa user-find, and when displaying corresponding lists in the web UI.
The search size limit:
  • Defines the maximum number of entries returned for a request sent to the server from a client, the IdM command-line tools, or the IdM web UI.
  • Default value: 100 entries.
The search time limit:
  • Defines the maximum time that the server waits for searches to run. Once the search reaches this limit, the server stops the search and returns the entries that discovered in that time.
  • Default value: 2 seconds.
If you set the values to -1, IdM will not apply any limits when searching.
Important
Setting search size or time limits too high can negatively affect server performance.

Web UI: Adjusting the Search Size and Time Limit

To adjust the limits globally for all queries:
  1. Select IPA Server → Configuration.
  2. Set the required values in the Search Options area.
  3. Click Save at the top of the page.

Command Line: Adjusting the Search Size and Time Limit

To adjust the limits globally for all queries, use the ipa config-mod command and add the --searchrecordslimit and --searchtimelimit options. For example: 
$ ipa config-mod --searchrecordslimit=500 --searchtimelimit=5
From the command line, you can also adjust the limits only for a specific query. To do this, add the --sizelimit or --timelimit options to the command. For example: 
$ ipa user-find --sizelimit=200 --timelimit=120
Important
Note that adjusting the size or time limits using the ipa config-mod command with the --searchrecordslimit or the --searchtimelimit options affects the number of entries returned by ipacommands, such as ipa user-find.
In addition to these limits, the settings configured at the Directory Server level are also taken into account and may impose stricter limits. For more information on Directory Server limits, see the Red Hat Directory Server Administration Guide.

5.4. The IdM Web UI

The Identity Management web UI is a web application for IdM administration. It has most of the capabilities of the ipa command-line utility. Therefore, the users can choose whether they want to manage IdM from the UI or from the command line.
Note
Management operations available to the logged-in user depend on the user's access rights. For the admin user and other users with administrative privileges, all management tasks are available. For regular users, only a limited set of operations related to their own user account is available.

5.4.1. Supported Web Browsers

Identity Management supports the following browsers for connecting to the web UI:
  • Mozilla Firefox 38 and later
  • Google Chrome 46 and later

5.4.2. Accessing the Web UI and Authenticating

The web UI can be accessed both from IdM server and client machines, as well as from machines outside of the IdM domain. However, to access the UI from a non-domain machine, you must first configure the non-IdM system to be able to connect to the IdM Kerberos domain; see Section 5.4.4, “Configuring an External System for Kerberos Authentication to the Web UI” for more details.

5.4.2.1. Accessing the Web UI

To access the web UI, type the IdM server URL into the browser address bar: 
https://server.example.com
This opens the IdM web UI login screen in your browser.

Figure 5.1. Web UI Login Screen

Web UI Login Screen

5.4.2.2. Available Login Methods

The user can authenticate to the web UI in the following ways:
With an active Kerberos ticket
If the user has a valid TGT obtained with the kinit utility, clicking Login automatically authenticates the user. Note that the browser must be configured properly to support Kerberos authentication.
For information on obtaining a Kerberos TGT, see Section 5.2, “Logging into IdM Using Kerberos”. For information on configuring the browser, see Section 5.4.3, “Configuring the Browser for Kerberos Authentication”.
By providing user name and password
To authenticate using a user name and password, enter the user name and password on the web UI login screen.
IdM also supports one-time password (OTP) authentication. For more information, see Section 22.3, “One-Time Passwords”.
With a smart card
For more information, see Section 23.6, “Authenticating to the Identity Management Web UI with a Smart Card”.
After the user authenticates successfully, the IdM management window opens.

Figure 5.2. The IdM Web UI Layout

The IdM Web UI Layout

5.4.2.3. Web UI Session Length

When a user logged in to the IdM web UI using a user name and password, the session length is the same as the expiration period of the Kerberos ticket obtained during the login operation.

5.4.2.4. Authenticating to the IdM Web UI as an AD User

Active Directory (AD) users can log in to the IdM web UI with their user name and password. In the web UI, AD users can perform only a limited set of operations related to their own user account, unlike IdM users who can perform management operations related to their administrative privileges.
To enable web UI login for AD users, the IdM administrator must define an ID override for each AD user in the Default Trust View. For example: 
[admin@server ~]$ ipa idoverrideuser-add 'Default Trust View' ad_user@ad.example.com
For details on ID views in AD, see Using ID Views in Active Directory Environments in the Windows Integration Guide.

5.4.3. Configuring the Browser for Kerberos Authentication

To enable authentication with Kerberos credentials, you must configure your browser to support Kerberos negotiation for accessing the IdM domain. Note that if your browser is not configured properly for Kerberos authentication, an error message appears after clicking Login on the IdM web UI login screen.

Figure 5.3. Kerberos Authentication Error

Kerberos Authentication Error
You can configure your browser for Kerberos authentication in three ways:
Note
The System-Level Authentication Guide includes a Troubleshooting Firefox Kerberos Configuration. If Kerberos authentication is not working as expected, see this troubleshooting guide for more advice.

Automatic Firefox Configuration in the Web UI

To automatically configure Firefox from the IdM web UI:
  1. Click the link for browser configuration on the web UI login screen.
  2. Choose the link for Firefox configuration to open the Firefox configuration page.
  3. Follow the steps on the Firefox configuration page.

Automatic Firefox Configuration from the Command Line

Firefox can be configured from the command line during IdM client installation. To do this, use the --configure-firefox option when installing the IdM client with the ipa-client-install utility: 
# ipa-client-install --configure-firefox
The --configure-firefox option creates a global configuration file with default Firefox settings that enable Kerberos for single sign-on (SSO).

Manual Browser Configuration

To manually configure your browser:
  1. Click the link for browser configuration on the web UI login screen.
  2. Choose the link for manual browser configuration.
  3. Look for the instructions to configure your browser and follow the steps.

5.4.4. Configuring an External System for Kerberos Authentication to the Web UI

To enable Kerberos authentication to the web UI from a system that is not a member of the IdM domain, you must define an IdM-specific Kerberos configuration file on the external machine. Enabling Kerberos authentication on external systems is especially useful when your infrastructure includes multiple realms or overlapping domains.
To create the Kerberos configuration file:
  1. Copy the /etc/krb5.conf file from the IdM server to the external machine. For example: 
    # scp /etc/krb5.conf root@externalmachine.example.com:/etc/krb5_ipa.conf
    Warning
    Do not overwrite the existing krb5.conf file on the external machine.
  2. On the external machine, set the terminal session to use the copied IdM Kerberos configuration file: 
    $ export KRB5_CONFIG=/etc/krb5_ipa.conf
  3. Configure the browser on the external machine as described in Section 5.4.3, “Configuring the Browser for Kerberos Authentication”.
Users on the external system can now use the kinit utility to authenticate against the IdM server domain.

5.4.5. Proxy Servers and Port Forwarding in the Web UI

Using proxy servers to access the web UI does not require any additional configuration in IdM.
Port forwarding is not supported with the IdM server. However, because it is possible to use proxy servers, an operation similar to port forwarding can be configured using proxy forwarding with OpenSSH and the SOCKS option. This can be configured using the -D option of the ssh utility; for more information on using -D, see the ssh(1) man page.

Chapter 6. Managing Replication Topology

This chapter describes how to manage replication between servers in an Identity Management (IdM) domain.
Note
This chapter describes simplified topology management introduced in Red Hat Enterprise Linux 7.3. The procedures require domain level 1 (see Chapter 7, Displaying and Raising the Domain Level).
For documentation on managing topology at domain level 0, see Section D.3, “Managing Replicas and Replication Agreements”.
For details on installing an initial replica and basic information on replication, see Chapter 4, Installing and Uninstalling Identity Management Replicas.

6.1. Explaining Replication Agreements, Topology Suffixes, and Topology Segments

Replication Agreements

Data stored on an IdM server is replicated based on replication agreements: when two servers have a replication agreement configured, they share their data.
Replication agreements are always bilateral: the data is replicated from the first replica to the other one as well as from the other replica to the first one.
Note
For additional details, see Section 4.1, “Explaining IdM Replicas”.

Topology Suffixes

Topology suffixes store the data that is replicated. IdM supports two types of topology suffixes: domain and ca. Each suffix represents a separate back end, a separate replication topology.
When a replication agreement is configured, it joins two topology suffixes of the same type on two different servers.
The domain suffix: dc=example,dc=com
The domain suffix contains all domain-related data.
When two replicas have a replication agreement between their domain suffixes, they share directory data, such as users, groups, and policies.
The ca suffix: o=ipaca
The ca suffix contains data for the Certificate System component. It is only present on servers with a certificate authority (CA) installed.
When two replicas have a replication agreement between their ca suffixes, they share certificate data.

Figure 6.1. Topology Suffixes

Topology Suffixes
An initial topology segment is set up between two servers by the ipa-replica-install script when installing a new replica.

Example 6.1. Viewing Topology Suffixes

The ipa topologysuffix-find command displays a list of topology suffixes: 
$ ipa topologysuffix-find
---------------------------
2 topology suffixes matched
---------------------------
  Suffix name: ca
  Managed LDAP suffix DN: o=ipaca

  Suffix name: domain
  Managed LDAP suffix DN: dc=example,dc=com
----------------------------
Number of entries returned 2
----------------------------

Topology Segments

When two replicas have a replication agreement between their suffixes, the suffixes form a topology segment. Each topology segment consists of a left node and a right node. The nodes represent the servers joined in the replication agreement.
Topology segments in IdM are always bidirectional. Each segment represents two replication agreements: from server A to server B, and from server B to server A. The data is therefore replicated in both directions.

Figure 6.2. Topology Segments

Topology Segments

Example 6.2. Viewing Topology Segments

The ipa topologysegment-find command shows the current topology segments configured for the domain or CA suffixes. For example, for the domain suffix: 
$ ipa topologysegment-find
Suffix name: domain
-----------------
1 segment matched
-----------------
  Segment name: server1.example.com-to-server2.example.com
  Left node: server1.example.com
  Right node: server2.example.com
  Connectivity: both
----------------------------
Number of entries returned 1
----------------------------
In this example, domain-related data is only replicated between two servers: server1.example.com and server1.example.com.
To display details for a particular segment only, use the ipa topologysegment-show command: 
$ ipa topologysegment-show
Suffix name: domain
Segment name: server1.example.com-to-server2.example.com
  Segment name: server1.example.com-to-server2.example.com
  Left node: server1.example.com
  Right node: server2.example.com
  Connectivity: both

6.2. Web UI: Using the Topology Graph to Manage Replication Topology

Accessing the Topology Graph

The topology graph in the web UI shows the relationships between the servers in the domain:
  1. Select IPA Server → Topology → Topology Graph.
  2. If you make any changes to the topology that are not immediately reflected in the graph, click Refresh.

Customizing the Topology View

You can move individual topology nodes by dragging the mouse:

Figure 6.3. Moving Topology Graph Nodes

Moving Topology Graph Nodes
You can zoom in and zoom out the topology graph using the mouse wheel:

Figure 6.4. Zooming the Topology Graph

Zooming the Topology Graph
You can move the canvas of the topology graph by holding the left mouse button:

Figure 6.5. Moving the Topology Graph Canvas

Moving the Topology Graph Canvas

Interpreting the Topology Graph

Servers joined in a domain replication agreement are connected by an orange arrow. Servers joined in a CA replication agreement are connected by a blue arrow.
Topology graph example: recommended topology
Figure 6.6, “Recommended Topology Example” shows one of the possible recommended topologies for four servers: each server is connected to at least two other servers, and more than one server is a CA master.

Figure 6.6. Recommended Topology Example

Recommended Topology Example
Topology graph example: discouraged topology
In Figure 6.7, “Discouraged Topology Example: Single Point of Failure”, server1 is a single point of failure. All the other servers have replication agreements with this server, but not with any of the other servers. Therefore, if server1 fails, all the other servers will become isolated.
Avoid creating topologies like this.

Figure 6.7. Discouraged Topology Example: Single Point of Failure

Discouraged Topology Example: Single Point of Failure
For details on topology recommendations, see Section 4.2, “Deployment Considerations for Replicas”.

6.2.1. Setting up Replication Between Two Servers

  1. In the topology graph, hover your mouse over one of the server nodes.

    Figure 6.8. Domain or CA Options

    Domain or CA Options
  2. Click on the domain or the ca part of the circle depending on what type of topology segment you want to create.
  3. A new arrow representing the new replication agreement appears under your mouse pointer. Move your mouse to the other server node, and click on it.

    Figure 6.9. Creating a New Segment

    Creating a New Segment
  4. In the Add Topology Segment window, click Add to confirm the properties of the new segment.
IdM creates a new topology segment between the two servers, which joins them in a replication agreement. The topology graph now shows the updated replication topology:

Figure 6.10. New Segment Created

New Segment Created

6.2.2. Stopping Replication Between Two Servers

  1. Click on an arrow representing the replication agreement you want to remove. This highlights the arrow.

    Figure 6.11. Topology Segment Highlighted

    Topology Segment Highlighted
  2. Click Delete.
  3. In the Confirmation window, click OK.
IdM removes the topology segment between the two servers, which deletes their replication agreement. The topology graph now shows the updated replication topology:

Figure 6.12. Topology Segment Deleted

Topology Segment Deleted

6.3. Command Line: Managing Topology Using the ipa topology* Commands

6.3.1. Getting Help for Topology Management Commands

To display all commands used to manage replication topology: 
$ ipa help topology
To display detailed help for a particular command, run it with the --help option: 
$ ipa topologysuffix-show --help

6.3.2. Setting up Replication Between Two Servers

  1. Use the ipa topologysegment-add command to create a topology segment for the two servers. When prompted, provide:
    For example: 
    $ ipa topologysegment-add
Suffix name: domain
Left node: server1.example.com
Right node: server2.example.com
Segment name [server1.example.com-to-server2.example.com]: new_segment
---------------------------
Added segment "new_segment"
---------------------------
  Segment name: new_segment
  Left node: server1.example.com
  Right node: server2.example.com
  Connectivity: both
    Adding the new segment joins the servers in a replication agreement.
  2. Optional. Use the ipa topologysegment-show command to verify that the new segment is configured. 
    $ ipa topologysegment-show
Suffix name: domain
Segment name: new_segment
  Segment name: new_segment
  Left node: server1.example.com
  Right node: server2.example.com
  Connectivity: both

6.3.3. Stopping Replication Between Two Servers

  1. To stop replication, you must delete the corresponding replication segment between the servers. To do that, you need to know the segment name.
    If you do not know the name, use the ipa topologysegment-find command to display all segments, and locate the required segment in the output. When prompted, provide the required topology suffix: domain or ca. For example: 
    $ ipa topologysegment-find
Suffix name: domain
------------------
8 segments matched
------------------
  Segment name: new_segment
  Left node: server1.example.com
  Right node: server2.example.com
  Connectivity: both

...

----------------------------
Number of entries returned 8
----------------------------
  2. Use the ipa topologysegment-del command to remove the topology segment joining the two servers. 
    $ ipa topologysegment-del
Suffix name: domain
Segment name: new_segment
-----------------------------
Deleted segment "new_segment"
-----------------------------
    Deleting the segment removes the replication agreement.
  3. Optional. Use the ipa topologysegment-find command to verify that the segment is no longer listed. 
    $ ipa topologysegment-find
Suffix name: domain
------------------
7 segments matched
------------------
  Segment name: server2.example.com-to-server3.example.com
  Left node: server2.example.com
  Right node: server3.example.com
  Connectivity: both

...

----------------------------
Number of entries returned 7
----------------------------

6.4. Removing a Server from the Topology

IdM does not allow removing a server from the topology if one of the following applies:
  • the server being removed is the only server connecting other servers with the rest of the topology; this would cause the other servers to become isolated, which is not allowed
  • the server being removed is your last CA or DNS server
In these situations, the attempt fails with an error. For example, on the command line: 
$ ipa server-del
Server name: server1.example.com
Removing server1.example.com from replication topology, please wait...
ipa: ERROR: Server removal aborted:

Removal of 'server1.example.com' leads to disconnected topology in suffix 'domain':
Topology does not allow server server2.example.com to replicate with servers:
  server3.example.com
  server4.example.com
...

6.4.1. Web UI: Removing a Server from the Topology

To remove a server from the topology without uninstalling the server components from the machine:
  1. Select IPA Server → Topology → IPA Servers.
  2. Click on the name of the server you want to delete.

    Figure 6.13. Selecting a Server

    Selecting a Server
  3. Click Delete Server.

6.4.2. Command Line: Removing a Server from the Topology

Important
Removing a server is an irreversible action. If you remove a server, the only way to introduce it back into the topology is to install a new replica on the machine.
To remove server1.example.com:
  1. On another server, run the ipa server-del command to remove server1.example.com. The command removes all topology segments pointing to the server: 
    [user@server2 ~]$ ipa server-del
Server name: server1.example.com
Removing server1.example.com from replication topology, please wait...
----------------------------------------------------------
Deleted IPA server "server1.example.com"
----------------------------------------------------------
  2. On server1.example.com, run the ipa server-install --uninstall command to uninstall the server components from the machine. 
    [root@server1 ~]# ipa server-install --uninstall

6.5. Managing Server Roles

Based on the services installed on an IdM server, it can perform various server roles. For example: CA server, DNS server, or key recovery authority (KRA) server.

6.5.1. Viewing Server Roles

Web UI: Viewing Server Roles

For a complete list of the supported server roles, see IPA Server → Topology → Server Roles.
  • Role status absent means that no server in the topology is performing the role.
  • Role status enabled means that one or more servers in the topology are performing the role.

Figure 6.14. Server Roles in the Web UI

Server Roles in the Web UI

Command Line: Viewing Server Roles

The ipa config-show command displays all CA servers, NTP servers, and the current CA renewal master: 
$ ipa config-show
  ...
  IPA masters: server1.example.com, server2.example.com, server3.example.com
  IPA CA servers: server1.example.com, server2.example.com
  IPA NTP servers: server1.example.com, server2.example.com, server3.example.com
  IPA CA renewal master: server1.example.com
The ipa server-show command displays a list of roles enabled on a particular server. For example, for a list of roles enabled on server.example.com: 
$ ipa server-show
Server name: server.example.com
  ...
  Enabled server roles: CA server, DNS server, NTP server, KRA server
The ipa server-find --servrole searches for all servers with a particular server role enabled. For example, to search for all CA servers: 
$ ipa server-find --servrole "CA server"
---------------------
2 IPA servers matched
---------------------
  Server name: server1.example.com
  ...

  Server name: server2.example.com
  ...
----------------------------
Number of entries returned 2
----------------------------

6.5.2. Promoting a Replica to a Master CA Server

Note
This section describes changing the CA renewal master at domain level 1 (see Chapter 7, Displaying and Raising the Domain Level). For documentation on changing the CA renewal master at domain level 0, see Section D.4, “Promoting a Replica to a Master CA Server”.
If your IdM deployment uses an embedded certificate authority (CA), one of the IdM CA servers acts as the master CA: it manages the renewal of CA subsystem certificates and generates certificate revocation lists (CRLs). By default, the master CA is the first server on which the system administrator installed the CA role using the ipa-server-install or ipa-ca-install command.
If you plan to take the master CA server offline or decommission it, promote another CA server to take the its place as the new CA renewal master:
  1. Configure the replica to handle CA subsystem certificate renewal.
  2. Configure the replica to generate CRLs. See Section 6.5.2.2, “Changing Which Server Generates CRLs”.
  3. Before decommissioning the previous master CA server, make sure the new master works properly. See Section 6.5.2.3, “Verifying That the New Master CA Server Is Configured Correctly”.

6.5.2.1. Changing the Current CA Renewal Master

Web UI: Changing the Current CA Renewal Master

  1. Select IPA Server → Configuration.
  2. In the IPA CA renewal master field, select the new CA renewal master.

Command Line: Changing the Current CA Renewal Master

Use the ipa config-mod --ca-renewal-master-server command: 
$ ipa config-mod --ca-renewal-master-server new_ca_renewal_master.example.com
  ...
  IPA masters: old_ca_renewal_master.example.com, new_ca_renewal_master.example.com
  IPA CA servers: old_ca_renewal_master.example.com, new_ca_renewal_master.example.com
  IPA NTP servers: old_ca_renewal_master.example.com, new_ca_renewal_master.example.com
  IPA CA renewal master: new_ca_renewal_master.example.com
The output confirms that the update was successful.

6.5.2.2. Changing Which Server Generates CRLs

To change which server generates certificate revocation lists (CRL):
  1. If you do not know the current CRL generation master, use the ipa-crlgen-manage status command on each IdM certificate authority (CA) to determine whether CRL generation is enabled: 
    # ipa-crlgen-manage status
CRL generation: enabled
  2. On the current CRL generation master, disable the feature: 
    # ipa-crlgen-manage disable
  3. On the other CA host that you want to configure as the new CRL generation master, enable the feature: 
    # ipa-crlgen-manage enable

6.5.2.3. Verifying That the New Master CA Server Is Configured Correctly

Make sure the /var/lib/ipa/pki-ca/publish/MasterCRL.bin file exists on the new master CA server.
The file is generated based on the time interval defined in the /etc/pki/pki-tomcat/ca/CS.cfg file using the ca.crl.MasterCRL.autoUpdateInterval parameter. The default value is 240 minutes (4 hours).
Note
If you update the ca.crl.MasterCRL.autoUpdateInterval parameter, the change will become effective after the next already scheduled CRL update.
If the file exists, the new master CA server is configured correctly, and you can safely dismiss the previous CA master system.

6.5.3. Demotion and Promotion of Hidden Replicas

After a replica has been installed, you can change whether the replica is hidden or visible:
  • To demote a visible replica to a hidden replica:
    1. If the replica is a CA renewal master, move the service to another replica. For details, see Section 6.5.2.1, “Changing the Current CA Renewal Master”.
    2. Change the state of the replica to hidden: 
      # ipa server-state replica.idm.example.com --state=hidden
  • To promote a hidden replica to a visible replica, enter: 
    # ipa server-state replica.idm.example.com --state=enabled
Note
The hidden replica feature is available in Red Hat Enterprise Linux 7.7 and later as a Technology Preview and, therefore, not supported.

Chapter 7. Displaying and Raising the Domain Level

The domain level indicates what operations and capabilities are available in the IdM topology.
Domain level 1
Examples of available functionality:
Important
Domain level 1 was introduced in Red Hat Enterprise Linux 7.3 with IdM version 4.4. To use the domain level 1 features, all your replicas must be running Red Hat Enterprise Linux 7.3 or later.
If your first server was installed with Red Hat Enterprise Linux 7.3, the domain level for your domain is automatically set to 1.
If you upgrade all servers to IdM version 4.4 from earlier versions, the domain level is not raised automatically. If you want to use domain level 1 features, raise the domain level manually, as described in Section 7.2, “Raising the Domain Level”.
Domain level 0
Examples of available functionality:

7.1. Displaying the Current Domain Level

Command Line: Displaying the Current Domain Level

  1. Log in as the administrator: 
    $ kinit admin
  2. Run the ipa domainlevel-get command: 
    $ ipa domainlevel-get
-----------------------
Current domain level: 0
-----------------------

Web UI: Displaying the Current Domain Level

Select IPA Server → Topology → Domain Level.

7.2. Raising the Domain Level

Important
This is a non-reversible operation. If you raise the domain level from 0 to 1, you cannot downgrade from 1 to 0 again.

Command Line: Raising the Domain Level

  1. Log in as the administrator: 
    $ kinit admin
  2. Run the ipa domainlevel-set command and provide the required level: 
    $ ipa domainlevel-set 1
-----------------------
Current domain level: 1
-----------------------

Web UI: Raising the Domain Level

  1. Select IPA Server → Topology → Domain Level.
  2. Click Set Domain Level.

Chapter 8. Updating and Migrating Identity Management

8.1. Updating Identity Management

You can use the yum utility to update the Identity Management packages on the system.
Additionally, if a new minor Red Hat Enterprise Linux version is available, such as 7.3, yum upgrades the Identity Management server or client to this version.
Note
This section does not describe migrating Identity Management from Red Hat Enterprise Linux 6 to Red Hat Enterprise Linux 7. If you want to migrate, see Section 8.2, “Migrating Identity Management from Red Hat Enterprise Linux 6 to Version 7”.

8.1.1. Considerations for Updating Identity Management

  • After you update the Identity Management packages on at least one server, all other servers in the topology receive the updated schema, even if you do not update their packages. This ensures that any new entries which use the new schema can be replicated among the other servers.
  • Downgrading Identity Management packages is not supported.
    Important
    Do not run the yum downgrade command on any of the ipa-* packages.
  • Red Hat recommends upgrading to the next version only. For example, if you want to upgrade to Identity Management for Red Hat Enterprise Linux 7.4, we recommend upgrading from Identity Management for Red Hat Enterprise Linux 7.3. Upgrading from earlier versions can cause problems.

8.1.2. Using yum to Update the Identity Management Packages

To update all Identity Management packages on a server or client: 
# yum update ipa-*
Warning
When upgrading multiple Identity Management servers, wait at least 10 minutes between each upgrade.
When two or more servers are upgraded simultaneously or with only short intervals between the upgrades, there is not enough time to replicate the post-upgrade data changes throughout the topology, which can result in conflicting replication events.

Related Information

  • For details on using the yum utility, see Yum in the System Administrator's Guide.
Important
Due to CVE-2014-3566, the Secure Socket Layer version 3 (SSLv3) protocol needs to be disabled in the mod_nss module. You can ensure that by following these steps:
  1. Edit the /etc/httpd/conf.d/nss.conf file and set the NSSProtocol parameter to TLSv1.0 (for backward compatibility), TLSv1.1, and TLSv1.2. 
    NSSProtocol TLSv1.0,TLSv1.1,TLSv1.2
  2. Restart the httpd service. 
    # systemctl restart httpd.service
Note that Identity Management in Red Hat Enterprise Linux 7 automatically performs the above steps when the yum update ipa-* command is launched to upgrade the main packages.

8.2. Migrating Identity Management from Red Hat Enterprise Linux 6 to Version 7

This procedure describes how to migrate all data and configuration from Red Hat Enterprise Linux 6 Identity Management to Red Hat Enterprise Linux 7 servers. The migration procedure includes:
  • Migrating the Red Hat Enterprise Linux 6-based certificate authority (CA) master server to Red Hat Enterprise Linux 7.
  • Transitioning all services to the new Red Hat Enterprise Linux 7 server. These services include CRL and certificate creating, DNS management, or Kerberos KDC administration.
  • Decommissioning the original Red Hat Enterprise Linux 6 CA master.
In the following procedures:
  • rhel7.example.com is the Red Hat Enterprise Linux 7 system that will become the new CA master.
    Important
    The only minor version that is currently supported is RHEL 7.9. Ensure you have RHEL 7.9 installed on your system.
  • rhel6.example.com is the original Red Hat Enterprise Linux 6 CA master.
    Note
    To identify which Red Hat Enterprise Linux 6 server is the master CA server, determine on which server the certmonger service tracks the renew_ca_cert command. Run this command on every Red Hat Enterprise Linux 6 server: 
    [root@rhel6 ~]# getcert list -d /var/lib/pki-ca/alias -n "subsystemCert cert-pki-ca" | grep post-save
post-save command: /usr/lib64/ipa/certmonger/renew_ca_cert "subsystemCert cert-pki-ca"
    The post-save action that executes renew_ca_cert is defined only for the CA master.

8.2.1. Prerequisites for Migrating Identity Management from Red Hat Enterprise Linux 6 to 7

8.2.2. Updating the Identity Management Schema on Red Hat Enterprise Linux 6

The copy-schema-to-ca.py schema update script prepares rhel6.example.com for the installation of the rhel7.example.com replica. Updating the schema is necessary due to schema changes between Identity Management version 3.1 and later versions.
  1. Copy the copy-schema-to-ca.py schema update script from the rhel7.example.com system to the rhel6.example.com system. For example: 
    [root@rhel7 ~]# scp /usr/share/ipa/copy-schema-to-ca.py root@rhel6:/root/
  2. Run the updated copy-schema-to-ca.py script on rhel6.example.com. 
    [root@rhel6 ~]# python copy-schema-to-ca.py
ipa         : INFO     Installed /etc/dirsrv/slapd-PKI-IPA//schema/60kerberos.ldif
[... output truncated ...]
ipa         : INFO     Schema updated successfully
  3. Repeat the steps on every Red Hat Enterprise Linux 6 IdM replica that runs a certificate authority before connecting to a Red Hat Enterprise Linux 7 replica.

8.2.3. Installing the Red Hat Enterprise Linux 7 Replica

  1. On the rhel6.example.com system, create the replica file you will use to install the rhel7.example.com replica. For example, to create a replica file for rhel7.example.com whose IP address is 192.0.2.1: 
    [root@rhel6 ~]# ipa-replica-prepare rhel7.example.com --ip-address 192.0.2.1

Directory Manager (existing master) password:
Preparing replica for rhel7.example.com from rhel6.example.com
[... output truncated ...]
The ipa-replica-prepare command was successful
    See also Section D.1, “Replica Information File” and Section D.2, “Creating Replicas”.
  2. Copy the replica information file from rhel6.example.com to rhel7.example.com. 
    [root@rhel6 ~]# scp /var/lib/ipa/replica-info-replica.example.com.gpg root@rhel7:/var/lib/ipa/
  3. If you install the new replica with an integrated CA on Red Hat Enterprise Linux 7.6 or later, append the following entry to the end of the NSSCipherSuite parameter in the /etc/httpd/conf.d/nss.conf file: 
    +ecdhe_rsa_aes_128_sha,+ecdhe_rsa_aes_256_sha
    In Red Hat Enterprise Linux 7.6 or later, certain ciphers are no longer enabled by default in the IdM CA. Without adding this entry to the configuration, setting up an IdM server with integrated CA on Red Hat Enterprise Linux 7.6 as a replica of a master running on Red Hat Enterprise Linux 6 fails with a CRITICAL Failed to configure CA instance error.
  4. Install the rhel7.example.com replica using the replica file. For example, the following command uses these options:
    • --setup-ca to set up the Certificate System component
    • --setup-dns and --forwarder to configure an integrated DNS server and set a forwarder
    • --ip-address to specify the IP address of the rhel7.example.com system 
    [root@rhel7 ~]# ipa-replica-install /var/lib/ipa/replica-info-rhel7.example.com.gpg --setup-ca --ip-address 192.0.2.1 --setup-dns --forwarder 192.0.2.20
Directory Manager (existing master) password:

Checking DNS forwarders, please wait ...
Run connection check to master
[... output truncated ...]
Client configuration complete.
    See also:
  5. Verify that the Identity Management services are running on rhel7.example.com. 
    [root@rhel7 ~]# ipactl status
Directory Service: RUNNING
[... output truncated ...]
ipa: INFO: The ipactl command was successful

8.2.4. Transitioning the CA Services to the Red Hat Enterprise Linux 7 Server

Before you begin:
  • Verify that rhel6.example.com and rhel7.example.com CAs are both configured as master servers. 
    [root@rhel7 ~]$ kinit admin
[root@rhel7 ~]$ ipa-csreplica-manage list
rhel6.example.com: master
rhel7.example.com: master
    To display details about a replication agreement: 
    [root@rhel7 ~]# ipa-csreplica-manage list --verbose rhel7.example.com
rhel7.example.com
last init status: None
last init ended: 1970-01-01 00:00:00+00:00
last update status: Error (0) Replica acquired successfully: Incremental update succeeded
last update ended: 2017-02-13 13:55:13+00:00
On the rhel6.example.com original master CA, stop the CA subsystem certificate renewal:
  1. Disable tracking for the original CA certificates. 
    [root@rhel6 ~]# getcert stop-tracking -d /var/lib/pki-ca/alias -n "auditSigningCert cert-pki-ca"
Request "20201127184547" removed.
[root@rhel6 ~]# getcert stop-tracking -d /var/lib/pki-ca/alias -n "ocspSigningCert cert-pki-ca"
Request "20201127184548" removed.
[root@rhel6 ~]# getcert stop-tracking -d /var/lib/pki-ca/alias -n "subsystemCert cert-pki-ca"
Request "20201127184549" removed.
[root@rhel6 ~]# getcert stop-tracking -d /etc/httpd/alias -n ipaCert
Request "20201127184550" removed.
  2. Reconfigure rhel6.example.com to retrieve renewed certificates from a new master CA.
    1. Copy the renewal helper script into the certmonger service directory, and set the appropriate permissions. 
      [root@rhel6 ~]# cp /usr/share/ipa/ca_renewal /var/lib/certmonger/cas/
[root@rhel6 ~]# chmod 0600 /var/lib/certmonger/cas/ca_renewal
    2. Update the SELinux configuration. 
      [root@rhel6 ~]# restorecon /var/lib/certmonger/cas/ca_renewal
    3. Restart certmonger. 
      [root@rhel6 ~]# service certmonger restart
    4. Check that the CA is listed to retrieve certificates. 
      [root@rhel6 ~]# getcert list-cas
...
CA 'dogtag-ipa-retrieve-agent-submit':
        is-default: no
        ca-type: EXTERNAL
	helper-location: /usr/libexec/certmonger/dogtag-ipa-retrieve-agent-submit
    5. Obtain the CA certificate database PIN. 
      [root@rhel6 ~]# grep internal= /var/lib/pki-ca/conf/password.conf
    6. Configure certmonger to track the certificates for external renewal. This requires the database PIN. 
      [root@rhel6 ~]# getcert start-tracking \
    -c dogtag-ipa-retrieve-agent-submit \
    -d /var/lib/pki-ca/alias \
    -n "auditSigningCert cert-pki-ca" \
    -B /usr/lib64/ipa/certmonger/stop_pkicad \
    -C '/usr/lib64/ipa/certmonger/restart_pkicad \
    "auditSigningCert cert-pki-ca"' \
    -T "auditSigningCert cert-pki-ca" \
    -P database_pin
New tracking request "20201127184743" added.
[root@rhel6 ~]# getcert start-tracking \
    -c dogtag-ipa-retrieve-agent-submit \
    -d /var/lib/pki-ca/alias \
    -n "ocspSigningCert cert-pki-ca" \
    -B /usr/lib64/ipa/certmonger/stop_pkicad \
    -C '/usr/lib64/ipa/certmonger/restart_pkicad \
    "ocspSigningCert cert-pki-ca"' \
    -T "ocspSigningCert cert-pki-ca" \
    -P database_pin
New tracking request "20201127184744" added.
[root@rhel6 ~]# getcert start-tracking \
    -c dogtag-ipa-retrieve-agent-submit \
    -d /var/lib/pki-ca/alias \
    -n "subsystemCert cert-pki-ca" \
    -B /usr/lib64/ipa/certmonger/stop_pkicad \
    -C '/usr/lib64/ipa/certmonger/restart_pkicad \
    "subsystemCert cert-pki-ca"' \
    -T "subsystemCert cert-pki-ca" \
    -P database_pin
New tracking request "20201127184745" added.
[root@rhel6 ~]# getcert start-tracking \
    -c dogtag-ipa-retrieve-agent-submit \
    -d /etc/httpd/alias \
    -n ipaCert \
    -C /usr/lib64/ipa/certmonger/restart_httpd \
    -T ipaCert \
    -p /etc/httpd/alias/pwdfile.txt
New tracking request "20201127184746" added.
Move CRL generation from the original rhel6.example.com CA master to rhel7.example.com.
  1. On rhel6.example.com, stop CRL generation:
    1. Stop the CA service. 
      [root@rhel6 ~]# service pki-cad stop
    2. Disable CRL generation on rhel6.example.com. Open the /var/lib/pki-ca/conf/CS.cfg file, and set the values of the ca.crl.MasterCRL.enableCRLCache and ca.crl.MasterCRL.enableCRLUpdates parameters to false. 
      ca.crl.MasterCRL.enableCRLCache=false
ca.crl.MasterCRL.enableCRLUpdates=false
    3. Start the CA service. 
      [root@rhel6 ~]# service pki-cad start
  2. On rhel6.example.com, configure Apache to redirect CRL requests:
    1. Open the /etc/httpd/conf.d/ipa-pki-proxy.conf file, and uncomment the RewriteRule entry: 
      RewriteRule ^/ipa/crl/MasterCRL.bin https://rhel6.example.com/ca/ee/ca/getCRL?op=getCRL&crlIssuingPoint=MasterCRL [L,R=301,NC]
      Note
      Do not replace the server host name in the URL. The URL must refer to the local host name.
    2. Restart Apache. 
      [root@rhel6 ~]# service httpd restart
    IdM obtains now the Certificate Revocation List (CRL) from the local CA instead of from a local file.
  3. On rhel7.example.com, configure rhel7.example.com as the new CA master:
    1. Configure rhel7.example.com to handle CA subsystem certificate renewal, as described in Section D.4.1, “Changing Which Server Handles Certificate Renewal”.
    2. Configure rhel7.example.com to general certificate revocation lists (CRLs), as described in Section 6.5.2.2, “Changing Which Server Generates CRLs”.

Related Information

8.2.5. Stop the Red Hat Enterprise Linux 6 Server

Stop all service on rhel6.example.com to force domain discovery to the new rhel7.example.com server. 
[root@rhel6 ~]# ipactl stop
Stopping CA Service
Stopping pki-ca:                                           [  OK  ]
Stopping HTTP Service
Stopping httpd:                                            [  OK  ]
Stopping MEMCACHE Service
Stopping ipa_memcached:                                    [  OK  ]
Stopping DNS Service
Stopping named: .                                          [  OK  ]
Stopping KPASSWD Service
Stopping Kerberos 5 Admin Server:                          [  OK  ]
Stopping KDC Service
Stopping Kerberos 5 KDC:                                   [  OK  ]
Stopping Directory Service
Shutting down dirsrv:
    EXAMPLE-COM...                                         [  OK  ]
    PKI-IPA...                                             [  OK  ]
After this, using the ipa utility will contact the new server through a remote procedure call (RPC).

8.2.6. Next Steps After Migrating the Master CA Server

For each Red Hat Enterprise Linux 6 server in your topology:
  1. Create a replica file from rhel7.example.com.
    Note
    After installing a Red Hat Enterprise Linux 7 replica from a Red Hat Enterprise Linux 6 server, the domain level for the Identity Management domain is automatically set to 0.
    Red Hat Enterprise Linux 7.3 introduced an easier way to install and manage replicas. To use these features, your topology must be at domain level 1. See Chapter 7, Displaying and Raising the Domain Level.
  2. Use the replica file to install a new replica on another Red Hat Enterprise Linux 7 system.
See Chapter 4, Installing and Uninstalling Identity Management Replicas.
To decommission a Red Hat Enterprise Linux 6 server:
  • Remove the server from the topology by executing the removal commands on a Red Hat Enterprise Linux 7 server.
See Section 2.4, “Uninstalling an IdM Server”.
Important
Client configurations will not update automatically. If you decommission an IDM server and configured the new server with a different name, you should review the overall client configurations. In particular, you must update the following files manually:
  • /etc/openldap/ldap.conf
  • /etc/ipa/default.conf
  • /etc/sssd/sssd.conf

Chapter 9. Backing Up and Restoring Identity Management

Red Hat Enterprise Linux Identity Management provides a solution to manually back up and restore the IdM system, for example when a server stops performing correctly or data loss occurs. During backup, the system creates a directory containing information on your IdM setup and stores it. During restore, you can use this backup directory to bring your original IdM setup back.
Important
Use the backup and restore procedures described in this chapter only if you cannot rebuild the lost part of the IdM server group from the remaining servers in the deployment, by reinstalling the lost replicas as replicas of the remaining ones.
The "Backup and Restore in IdM/IPA" Knowledgebase solution describes how to avoid losses by maintaining several server replicas. Rebuilding from an existing replica with the same data is preferable, because the backed-up version usually contains older, thus potentially outdated, information.
The potential threat scenarios that backup and restore can prevent include:
  • Catastrophic hardware failure on a machine occurs and the machine becomes incapable of further functioning. In this situation:
    1. Reinstall the operating system from scratch.
    2. Configure the machine with the same host name, fully qualified domain name (FQDN), and IP address.
    3. Install the IdM packages as well as all other optional packages relating to IdM that were present on the original system.
    4. Restore the full backup of the IdM server.
  • An upgrade on an isolated machine fails. The operating system remains functional, but the IdM data is corrupted, which is why you want to restore the IdM system to a known good state.
    Important
    In cases of hardware or upgrade failure, such as the two mentioned above, restore from backup only if all replicas or a replica with a special role, such as the only certificate authority (CA), were lost. If a replica with the same data still exists, it is recommended to delete the lost replica and then rebuild it from the remaining one.
  • Undesirable changes were made to the LDAP content, for example entries were deleted, and you want to revert them. Restoring backed-up LDAP data returns the LDAP entries to the previous state without affecting the IdM system itself.
The restored server becomes the only source of information for IdM; other master servers are re-initialized from the restored server. Any data created after the last backup was made are lost. Therefore you should not use the backup and restore solution for normal system maintenance. If possible, always rebuild the lost server by reinstalling it as a replica.
The backup and restore features can be managed only from the command line and are not available in the IdM web UI.

9.1. Full-Server Backup and Data-Only Backup

IdM offers two backup options:
Full-IdM server backup
Full-server backup creates a backup copy of all the IdM server files as well as LDAP data, which makes it a standalone backup. IdM affects hundreds of files; the files that the backup process copies is a mix of whole directories and specific files, such as configuration files or log files, and relate directly to IdM or to various services that IdM depends on. Because the full-server backup is a raw file backup, it is performed offline. The script that performs the full-server backup stops all IdM services to ensure a safe course of the backup process.
For the full list of files and directories that the full-server backup copies, see Section 9.1.3, “List of Directories and Files Copied During Backup”.
Data-only Backup
The data-only backup only creates a backup copy of LDAP data and the changelog. The process backs up the IPA-REALM instance and can also back up multiple back ends or only a single back end; the back ends include the IPA back end and the CA Dogtag back end. This type of backup also backs up a record of the LDAP content stored in LDIF (LDAP Data Interchange Format). The data-only backup can be performed both online and offline.
By default, IdM stores the created backups in the /var/lib/ipa/backup/ directory. The naming conventions for the subdirectories containing the backups are:
  • ipa-full-YEAR-MM-DD-HH-MM-SS in the GMT time zone for the full-server backup
  • ipa-data-YEAR-MM-DD-HH-MM-SS in the GMT time zone for the data-only backup

9.1.1. Creating a Backup

Both full-server and data-only backups are created using the ipa-backup utility which must always be run as root.
To create a full-server backup, run ipa-backup.
Important
Performing a full-server backup stops all IdM services because the process must run offline. The IdM services will start again after the backup is finished.
To create a data-only backup, run the ipa-backup --data command.
You can add several additional options to ipa-backup:
  • --online performs an online backup; this option is only available with data-only backups
  • --logs includes the IdM service log files in the backup
For further information on using ipa-backup, see the ipa-backup(1) man page.

9.1.1.1. Working Around Insufficient Space on Volumes Involved During Backup

This section describes how to address problems if directories involved in the IdM backup process are stored on volumes with insufficient free space.

Insufficient Space on the Volume That Contains /var/lib/ipa/backup/

If the /var/lib/ipa/backup/ directory is stored on a volume with insufficient free space, it is not possible to create a backup. To address the problem, use one of the following workarounds:
  • Create a directory on a different volume and link it to /var/lib/ipa/backup/. For example, if /home is stored on a different volume with enough free space:
    1. Create a directory, such as /home/idm/backup/: 
      # mkdir -p /home/idm/backup/
    2. Set the following permissions to the directory: 
      # chown root:root /home/idm/backup/
# chmod 700 /home/idm/backup/
    3. If /var/lib/ipa/backup/ contains existing backups, move them to the new directory: 
      # mv /var/lib/ipa/backup/* /home/idm/backup/
    4. Remove the /var/lib/ipa/backup/ directory: 
      # rm -rf /var/lib/ipa/backup/
    5. Create the /var/lib/ipa/backup/ link to the /home/idm/backup/ directory: 
      # ln -s /home/idm/backup/ /var/lib/ipa/backup/
  • Mount a directory stored on a different volume to /var/lib/ipa/backup/. For example, if /home is stored on a different volume with enough free space, create /home/idm/backup/ and mount it to /var/lib/ipa/backup/:
    1. Create the /home/idm/backup/ directory: 
      # mkdir -p /home/idm/backup/
    2. Set the following permissions to the directory: 
      # chown root:root /home/idm/backup/
# chmod 700 /home/idm/backup/
    3. If /var/lib/ipa/backup/ contains existing backups, move them to the new directory: 
      # mv /var/lib/ipa/backup/* /home/idm/backup/
    4. Mount /home/idm/backup/ to /var/lib/ipa/backup/: 
      # mount -o bind /home/idm/backup/ /var/lib/ipa/backup/
    5. To automatically mount /home/idm/backup/ to /var/lib/ipa/backup/ when the system boots, append the following to the /etc/fstab file: 
      /home/idm/backup/     /var/lib/ipa/backup/     none     bind     0 0

Insufficient Space on the Volume That Contains /tmp

If the backup fails due to insufficient space being available in the /tmp directory, change the location of the staged files to be created during the backup by using the TMPDIR environment variable: 
# TMPDIR=/path/to/backup ipa-backup
For more details, see the ipa-backup command fails to finish Knowledgebase solution.

9.1.2. Encrypting Backup

You can encrypt the IdM backup using the GNU Privacy Guard (GPG) encryption.
To create a GPG key:
  1. Create a keygen file containing the key details, for example, by running cat >keygen <<EOF and providing the required encryption details to the file from the command line: 
    [root@server ~]# cat >keygen <<EOF
> %echo Generating a standard key
> Key-Type: RSA
> Key-Length:2048
> Name-Real: IPA Backup
> Name-Comment: IPA Backup
> Name-Email: root@example.com
> Expire-Date: 0
> %pubring /root/backup.pub
> %secring /root/backup.sec
> %commit
> %echo done
> EOF
[root@server ~]#
  2. Generate a new key pair called backup and feed the contents of keygen to the command. The following example generates a key pair with the path names /root/backup.sec and /root/backup.pub: 
    [root@server ~]# gpg --batch --gen-key keygen
[root@server ~]# gpg --no-default-keyring --secret-keyring /root/backup.sec \
		     --keyring /root/backup.pub --list-secret-keys
To create a GPG-encrypted backup, pass the generated backup key to ipa-backup by supplying the following options:
  • --gpg, which instructs ipa-backup to perform the encrypted backup
  • --gpg-keyring=GPG_KEYRING, which provides the full path to the GPG keyring without the file extension.
For example: 
[root@server ~]# ipa-backup --gpg --gpg-keyring=/root/backup
Note
You might experience problems if your system uses the gpg2 utility to generate GPG keys because gpg2 requires an external program to function. To generate the key purely from console in this situation, add the pinentry-program /usr/bin/pinentry-curses line to the .gnupg/gpg-agent.conf file before generating a key.

9.1.3. List of Directories and Files Copied During Backup

Directories: 
/usr/share/ipa/html
/root/.pki
/etc/pki-ca
/etc/pki/pki-tomcat
/etc/sysconfig/pki
/etc/httpd/alias
/var/lib/pki
/var/lib/pki-ca
/var/lib/ipa/sysrestore
/var/lib/ipa-client/sysrestore
/var/lib/ipa/dnssec
/var/lib/sss/pubconf/krb5.include.d/
/var/lib/authconfig/last
/var/lib/certmonger
/var/lib/ipa
/var/run/dirsrv
/var/lock/dirsrv
Files: 
/etc/named.conf
/etc/named.keytab
/etc/resolv.conf
/etc/sysconfig/pki-ca
/etc/sysconfig/pki-tomcat
/etc/sysconfig/dirsrv
/etc/sysconfig/ntpd
/etc/sysconfig/krb5kdc
/etc/sysconfig/pki/ca/pki-ca
/etc/sysconfig/ipa-dnskeysyncd
/etc/sysconfig/ipa-ods-exporter
/etc/sysconfig/named
/etc/sysconfig/ods
/etc/sysconfig/authconfig
/etc/ipa/nssdb/pwdfile.txt
/etc/pki/ca-trust/source/ipa.p11-kit
/etc/pki/ca-trust/source/anchors/ipa-ca.crt
/etc/nsswitch.conf
/etc/krb5.keytab
/etc/sssd/sssd.conf
/etc/openldap/ldap.conf
/etc/security/limits.conf
/etc/httpd/conf/password.conf
/etc/httpd/conf/ipa.keytab
/etc/httpd/conf.d/ipa-pki-proxy.conf
/etc/httpd/conf.d/ipa-rewrite.conf
/etc/httpd/conf.d/nss.conf
/etc/httpd/conf.d/ipa.conf
/etc/ssh/sshd_config
/etc/ssh/ssh_config
/etc/krb5.conf
/etc/ipa/ca.crt
/etc/ipa/default.conf
/etc/dirsrv/ds.keytab
/etc/ntp.conf
/etc/samba/smb.conf
/etc/samba/samba.keytab
/root/ca-agent.p12
/root/cacert.p12
/var/kerberos/krb5kdc/kdc.conf
/etc/systemd/system/multi-user.target.wants/ipa.service
/etc/systemd/system/multi-user.target.wants/sssd.service
/etc/systemd/system/multi-user.target.wants/certmonger.service
/etc/systemd/system/pki-tomcatd.target.wants/pki-tomcatd@pki-tomcat.service
/var/run/ipa/services.list
/etc/opendnssec/conf.xml
/etc/opendnssec/kasp.xml
/etc/ipa/dnssec/softhsm2.conf
/etc/ipa/dnssec/softhsm_pin_so
/etc/ipa/dnssec/ipa-ods-exporter.keytab
/etc/ipa/dnssec/ipa-dnskeysyncd.keytab
/etc/idm/nssdb/cert8.db
/etc/idm/nssdb/key3.db
/etc/idm/nssdb/secmod.db
/etc/ipa/nssdb/cert8.db
/etc/ipa/nssdb/key3.db
/etc/ipa/nssdb/secmod.db
Log files and directories: 
/var/log/pki-ca
/var/log/pki/
/var/log/dirsrv/slapd-PKI-IPA
/var/log/httpd
/var/log/ipaserver-install.log
/var/log/kadmind.log
/var/log/pki-ca-install.log
/var/log/messages
/var/log/ipaclient-install.log
/var/log/secure
/var/log/ipaserver-uninstall.log
/var/log/pki-ca-uninstall.log
/var/log/ipaclient-uninstall.log
/var/named/data/named.run

9.2. Restoring a Backup

If you have a directory with a backup created using ipa-backup, you can restore your IdM server or the LDAP content to the state in which they were when the backup was performed. You cannot restore a backup on a host different from the host on which the backup was originally created.
Note
Uninstalling an IdM server does not automatically remove the backup of this server.

9.2.1. Restoring from the Full-Server or Data-Only Backup

Important
It is recommended that you uninstall a server before performing a full-server restore on it.
Both full-server and data-only backups are restored using the ipa-restore utility which must always be run as root. Pass the backup to the command:
  • Pass only the name of the directory with the backup if it is located in the default /var/lib/ipa/backup/ directory.
  • Pass the full path to the backup if the directory containing the backup is not located in the default directory. For example: 
    [root@server ~]# ipa-restore /path/to/backup
The ipa-restore utility automatically detects what type of backup the backup directory contains and by default performs the same type of restore.
You can add the following options to ipa-restore:
  • --data performs a data-only restore from a full-server backup, that is, restores only the LDAP data component from a backup directory containing the full-server backup
  • --online restores the LDAP data in a data-only restore online
  • --instance specifies which 389 DS instance is restored. IdM in Red Hat Enterprise Linux 7 only uses the IPA-REALM instance, but it might be possible, for example, to create a backup on a system with separate instances; in such cases, --instance allows you to restore only IPA-REALM. For example: 
    [root@server ~]# ipa-restore --instance=IPA-REALM /path/to/backup
    You can use this option only when performing a data-only restore.
  • --backend specifies which back end is restored; without this option, ipa-restore restores all back ends it discovers. The arguments defining the possible back ends are userRoot, which restores the IPA data back end, and ipaca, which restores the CA back end.
    You can use this option only when performing a data-only restore.
  • --no-logs restores the backup without restoring the log files
To avoid authentication problems on an IdM master, clear the SSSD cache after a restore:
  1. Stop the SSSD service: 
    [root@server ~]# systemctl stop sssd
  2. Remove all cached content from SSSD: 
    [root@server ~]# find /var/lib/sss/ ! -type d | xargs rm -f
  3. Start the SSSD service: 
    [root@server ~]# systemctl start sssd
Note
It is recommended that you reboot your system after restoring from backup.
For further information on using ipa-restore, see the ipa-restore(1) man page.

9.2.2. Restoring with Multiple Master Servers

For details about restoring IdM in a multi-master replication environment, see “Backup and Restore in IdM”.

9.2.3. Restoring from an Encrypted Backup

If you want to restore from a backup encrypted with GPG, provide the full path to the private and public keys using the --gpg-keyring option. For example: 
[root@server ~]# ipa-restore --gpg-keyring=/root/backup /path/to/backup

Chapter 10. Defining Access Control for IdM Users

Access control is a set of security features which defines who can access certain resources, such as machines, services or entries, and what kinds of operations they are allowed to perform. Identity Management provides several access control areas to make it clear what kind of access is being granted and to whom it is granted. As part of this, Identity Management draws a distinction between access controls to resources within the domain and access control to the IdM configuration itself.
This chapter details the different internal access control mechanisms that are available for users within IdM to the IdM server and other IdM users.

10.1. Access Controls for IdM Entries

Access control defines the rights or permissions users have been granted to perform operations on other users or objects.
The Identity Management access control structure is based on standard LDAP access controls. Access within the IdM server is based on the IdM users, stored in the back end Directory Server instance, who are allowed to access other IdM entities, also stored as LDAP entries in the Directory Server instance.
An access control instruction (ACI) has three parts:
Actor
This is the entity who is being granted permission to do something. In LDAP access control models, this is called the bind rule because it defines who the user is and can optionally require other limits on the bind attempt, such as restricting attempts to a certain time of day or a certain machine.
Target
This defines the entry which the actor is allowed to perform operations on.
Operation type
Operation type — the last part determines what kinds of actions the user is allowed to perform. The most common operations are add, delete, write, read, and search. In Identity Management, all users are implicitly granted read and search rights to all entries in the IdM domain, with restrictions only for sensitive attributes like passwords and Kerberos keys. Anonymous users are restricted from seeing security-related configuration, like sudo rules and host-based access control.
When any operation is attempted, the first thing that the IdM client does is send user credentials as part of the bind operation. The back end Directory Server checks those user credentials and then checks the user account to see if the user has permission to perform the requested operation.

10.1.1. Access Control Methods in Identity Management

To make access control rules simple and clear to implement, Identity Management divides access control definitions into three categories:
Self-service rules
Self-service rules, which define what operations a user can perform on his own personal entry. The access control type only allows write permissions to attributes within the entry; it does not allow add or delete operations for the entry itself.
Delegation rules
Delegation rules, which allow a specific user group to perform write (edit) operations on specific attributes for users in another user group. Like self-service rules, this form of access control rule is limited to editing the values of specific attributes; it does not grant the ability to add or remove whole entries or control over unspecified attributes.
Role-based access control
Role-based access control, which creates special access control groups which are then granted much broader authority over all types of entities in the IdM domain. Roles can be granted edit, add, and delete rights, meaning they can be granted complete control over entire entries, not just selected attributes.
Some roles are already created and available within Identity Management. Special roles can be created to manage any type of entry in specific ways, such as hosts, automount configuration, netgroups, DNS settings, and IdM configuration.

10.2. Defining Self-Service Settings

Self-service access control rules define the operations that an entity can perform on itself. These rules define only what attributes a user (or other IdM entity) can edit on their personal entries.

10.2.1. Creating Self-Service Rules from the Web UI

  1. On the IPA Server tab in the top menu, select the Role-Based Access Control → Self Service Permissions subtab.
  2. Click Add at the top of the list of the self-service access control instructions.

    Figure 10.1. Adding a Current Self-Service Rule

    Adding a Current Self-Service Rule
  3. Enter the name of the rule in the pop-up window. Spaces are allowed.

    Figure 10.2. Form for Adding a Self-Service Rule

    Form for Adding a Self-Service Rule
  4. Select the check boxes by the attributes which this ACI will permit users to edit.
  5. Click the Add button to save the new self-service ACI.

10.2.2. Creating Self-Service Rules from the Command Line

A new self-service rule can be added using the selfservice-add command. These two options are required:
  • --permissions to set which permissions – such as write, add, or delete – the ACI grants
  • --attrs to give the full list of attributes which this ACI grants permission to. 
[jsmith@server ~]$ ipa selfservice-add "Users can manage their own name details" --permissions=write --attrs=givenname --attrs=displayname --attrs=title --attrs=initials
-----------------------------------------------------------
Added selfservice "Users can manage their own name details"
-----------------------------------------------------------
    Self-service name: Users can manage their own name details
    Permissions: write
    Attributes: givenname, displayname, title, initials

10.2.3. Editing Self-Service Rules

In the self-service entry in the web UI, the only element that can be edited is the list of attributes that are included in the ACI. The check boxes can be selected or deselected.

Figure 10.3. Self-Service Edit Page

Self-Service Edit Page
With the command line, self-service rules are edited using the ipa selfservice-mod command. The --attrs option overwrites whatever the previous list of supported attributes was, so always include the complete list of attributes along with any new attributes. 
[jsmith@server ~]$ ipa selfservice-mod "Users can manage their own name details" --attrs=givenname --attrs=displayname --attrs=title --attrs=initials --attrs=surname
--------------------------------------------------------------
Modified selfservice "Users can manage their own name details"
--------------------------------------------------------------
Self-service name: Users can manage their own name details
Permissions: write
Attributes: givenname, displayname, title, initials
Important
Include all of the attributes when modifying a self-service rule, including existing ones.

10.3. Delegating Permissions over Users

Delegation is very similar to roles in that one group of users is assigned permission to manage the entries for another group of users. However, the delegated authority is much more similar to self-service rules in that complete access is granted but only to specific user attributes, not to the entire entry. Also, the groups in delegated authority are existing IdM user groups instead of roles specifically created for access controls.

10.3.1. Delegating Access to User Groups in the Web UI

  1. On the IPA Server tab in the top menu, select the Role-Based Access Control → Delegations subtab.
  2. Click the Add link at the top of the list of the delegation access control instructions.

    Figure 10.4. Adding a New Delegation

    Adding a New Delegation
  3. Name the new delegation ACI.
  4. Set the permissions by selecting the check boxes whether users will have the right to view the given attributes (read) and add or change the given attributes (write).
    Some users may have a need to see information, but should not be able to edit it.
  5. In the User group drop-down menu, select the group who is being granted permissions to the entries of users in the user group.

    Figure 10.5. Form for Adding a Delegation

    Form for Adding a Delegation
  6. In the Member user group drop-down menu, select the group whose entries can be edited by members of the delegation group.
  7. In the attributes box, select the check boxes by the attributes to which the member user group is being granted permission.
  8. Click the Add button to save the new delegation ACI.

10.3.2. Delegating Access to User Groups in the Command Line

A new delegation access control rule is added using the delegation-add command. There are three required arguments:
  • --group, the group who is being granted permissions to the entries of users in the user group.
  • --membergroup, the group whose entries can be edited by members of the delegation group.
  • --attrs, the attributes which users in the member group are allowed to view or edit.
For example: 
$ ipa delegation-add "basic manager attrs" --attrs=manager --attrs=title --attrs=employeetype --attrs=employeenumber --group=engineering_managers --membergroup=engineering
--------------------------------------
Added delegation "basic manager attrs"
--------------------------------------
  Delegation name: basic manager attrs
  Permissions: write
  Attributes: manager, title, employeetype, employeenumber
  Member user group: engineering
  User group: engineering_managers
Delegation rules are edited using the delegation-mod command. The --attrs option overwrites whatever the previous list of supported attributes was, so always include the complete list of attributes along with any new attributes. 
[jsmith@server ~]$ ipa delegation-mod "basic manager attrs" --attrs=manager --attrs=title --attrs=employeetype --attrs=employeenumber --attrs=displayname
-----------------------------------------
Modified delegation "basic manager attrs"
-----------------------------------------
  Delegation name: basic manager attrs
  Permissions: write
  Attributes: manager, title, employeetype, employeenumber, displayname
  Member user group: engineering
  User group: engineering_managers
Important
Include all of the attributes when modifying a delegation rule, including existing ones.

10.4. Defining Role-Based Access Controls

Role-based access control grants a very different kind of authority to users compared to self-service and delegation access controls. Role-based access controls are fundamentally administrative, providing the ability to modify entries.
There are three parts to role-based access controls: the permission, the privilege and the role. A privilege consists of one or more permissions, and a role consists of one or more privileges.
  • A permission defines a specific operation or set of operations (such as read, write, add, or delete) and the target entries within the IdM LDAP directory to which those operations apply. Permissions are building blocks; they can be assigned to multiple privileges as needed.
    With IdM permissions, you can control which users have access to which objects and even which attributes of these objects. IdM enables you to whitelist or blacklist individual attributes or change the entire visibility of a specific IdM function, such as users, groups, or sudo, to all anonymous users, all authenticated users, or just a certain group of privileged users. This flexible approach to permissions is useful in scenarios when, for example, the administrator wants to limit access of users or groups only to the specific sections these users or groups need to access and to make the other sections completely hidden to them.
  • A privilege is a group of permissions that can be applied to a role. For example, a permission can be created to add, edit, and delete automount locations. Then that permission can be combined with another permission relating to managing FTP services, and they can be used to create a single privilege that relates to managing filesystems.
    Note
    A privilege, in the context of Red Hat Identity Management, has a very specific meaning of an atomic unit of access control on which permissions and then roles are created. Privilege escalation as a concept of regular users temporarily gaining additional privileges does not exist in Red Hat Identity Management. Privileges are assigned to users by using Role-Based Access Controls (RBAC). Users either have the role that grants access, or they do not.
    Apart from users, privileges are also assigned to user groups, hosts, host groups and network services. This practice permits a fine-grained control of operations by a set of users on a set of hosts via specific network services.
  • A role is a list of privileges which users specified for the role possess.
    Important
    Roles are used to classify permitted actions. They are not used as a tool to implement privilege separation or to protect from privilege escalation.
It is possible to create entirely new permissions, as well as to create new privileges based on existing permissions or new permissions. Red Hat Identity Management provides the following range of pre-defined roles.

Table 10.1. Predefined Roles in Red Hat Identity Management

Role Privilege Description
Helpdesk
Modify Users and Reset passwords, Modify Group membership Responsible for performing simple user administration tasks
IT Security Specialist
Netgroups Administrators, HBAC Administrator, Sudo Administrator Responsible for managing security policy such as host-based access controls, sudo rules
IT Specialist
Host Administrators, Host Group Administrators, Service Administrators, Automount Administrators Responsible for managing hosts
Security Architect
Delegation Administrator, Replication Administrators, Write IPA Configuration, Password Policy Administrator Responsible for managing the Identity Management environment, creating trusts, creating replication agreements
User Administrator
User Administrators, Group Administrators, Stage User Administrators Responsible for creating users and groups

10.4.1. Roles

10.4.1.1. Creating Roles in the Web UI

  1. Open the IPA Server tab in the top menu, and select the Role-Based Access Control subtab.
  2. Click the Add link at the top of the list of the role-based access control instructions.

    Figure 10.6. Adding a New Role

    Adding a New Role
  3. Enter the role name and a description.

    Figure 10.7. Form for Adding a Role

    Form for Adding a Role
  4. Click the Add and Edit button to save the new role and go to the configuration page.
  5. At the top of the Users tab, or in the Users Groups tab when adding groups, click Add.

    Figure 10.8. Adding Users

    Adding Users
  6. Select the users on the left and use the > button to move them to the Prospective column.

    Figure 10.9. Selecting Users

    Selecting Users
  7. At the top of the Privileges tab, click Add.

    Figure 10.10. Adding Privileges

    Adding Privileges
  8. Select the privileges on the left and use the > button to move them to the Prospective column.

    Figure 10.11. Selecting Privileges

    Selecting Privileges
  9. Click the Add button to save.

10.4.1.2. Creating Roles in the Command Line

  1. Add the new role: 
    [root@server ~]# kinit admin
[root@server ~]# ipa role-add --desc="User Administrator" useradmin
  ------------------------
  Added role "useradmin"
  ------------------------
  Role name: useradmin
  Description: User Administrator
  2. Add the required privileges to the role: 
    [root@server ~]# ipa role-add-privilege --privileges="User Administrators" useradmin
  Role name: useradmin
  Description: User Administrator
  Privileges: user administrators
  ----------------------------
  Number of privileges added 1
----------------------------
  3. Add the required groups to the role. In this case, we are adding only a single group, useradmins, which already exists. 
    [root@server ~]# ipa role-add-member --groups=useradmins useradmin
  Role name: useradmin
  Description: User Administrator
  Member groups: useradmins
  Privileges: user administrators
  -------------------------
  Number of members added 1
-------------------------

10.4.2. Permissions

10.4.2.1. Creating New Permissions from the Web UI

  1. Open the IPA Server tab in the top menu, and select the Role-Based Access Control subtab.
  2. Select the Permissions task link.

    Figure 10.12. Permissions Task

    Permissions Task
  3. Click the Add button at the top of the list of the permissions.

    Figure 10.13. Adding a New Permission

    Adding a New Permission
  4. Define the properties for the new permission in the form that shows up.

    Figure 10.14. Form for Adding a Permission

    Form for Adding a Permission
  5. Click the Add button under the form to save the permission.
You can specify the following permission properties:
  1. Enter the name of the new permission.
  2. Select the appropriate Bind rule type:
    • permission is the default permission type, granting access through privileges and roles
    • all specifies that the permission applies to all authenticated users
    • anonymous specifies that the permission applies to all users, including unauthenticated users
    Note
    It is not possible to add permissions with a non-default bind rule type to privileges. You also cannot set a permission that is already present in a privilege to a non-default bind rule type.
  3. Choose the rights that the permission grants in Granted rights.
  4. Define the method to identify the target entries for the permission:
    • Type specifies an entry type, such as user, host, or service. If you choose a value for the Type setting, a list of all possible attributes which will be accessible through this ACI for that entry type appears under Effective Attributes.
      Defining Type sets Subtree and Target DN to one of the predefined values.
    • Subtree specifies a subtree entry; every entry beneath this subtree entry is then targeted. Provide an existing subtree entry, as Subtree does not accept wildcards or non-existent domain names (DNs). For example: 
      cn=automount,dc=example,dc=com
    • Extra target filter uses an LDAP filter to identify which entries the permission applies to. The filter can be any valid LDAP filter, for example: 
      (!(objectclass=posixgroup))
      IdM automatically checks the validity of the given filter. If you enter an invalid filter, IdM warns you about this after you attempt to save the permission.
    • Target DN specifies the domain name (DN) and accepts wildcards. For example: 
      uid=*,cn=users,cn=accounts,dc=com
    • Member of group sets the target filter to members of the given group.
    After you fill out the filter settings and click Add, IdM validates the filter. If all the permission settings are correct, IdM will perform the search. If some of the permissions settings are incorrect, IdM will display a message informing you about which setting is set incorrectly.
  5. If you set Type, choose the Effective attributes from the list of available ACI attributes. If you did not use Type, add the attributes manually by writing them into the Effective attributes field. Add a single attribute at a time; to add multiple attributes, click Add to add another input field.
    Important
    If you do not set any attributes for the permission, then all attributes are included by default.

10.4.2.2. Creating New Permissions from the Command Line

To add a new permission, issue the ipa permission-add command. Specify the properties of the permission by supplying the corresponding options:
  • Supply the name of the permission. For example: 
    [root@server ~]# ipa permission-add "dns admin permission"
  • --bindtype specifies the bind rule type. This options accepts the all, anonymous, and permission arguments. For example: 
    --bindtype=all
    If you do not use --bindtype, the type is automatically set to the default permission value.
    Note
    It is not possible to add permissions with a non-default bind rule type to privileges. You also cannot set a permission that is already present in a privilege to a non-default bind rule type.
  • --permissions lists the rights granted by the permission. You can set multiple attributes by using multiple --permissions options or by listing the options in a comma-separated list inside curly braces. For example: 
    --permissions=read --permissions=write
--permissions={read,write}
  • --attrs gives the list of attributes over which the permission is granted. You can set multiple attributes by using multiple --attrs options or by listing the options in a comma-separated list inside curly braces. For example: 
    --attrs=description --attrs=automountKey
--attrs={description,automountKey}
    The attributes provided with --attrs must exist and be allowed attributes for the given object type, otherwise the command fails with schema syntax errors.
  • --type defines the entry object type, such as user, host, or service. Each type has its own set of allowed attributes. For example: 
    [root@server ~]# ipa permission-add "manage service" --permissions=all --type=service --attrs=krbprincipalkey --attrs=krbprincipalname --attrs=managedby
  • --subtree gives a subtree entry; the filter then targets every entry beneath this subtree entry. Provide an existing subtree entry; --subtree does not accept wildcards or non-existent domain names (DNs). Include a DN within the directory.
    Because IdM uses a simplified, flat directory tree structure, --subtree can be used to target some types of entries, like automount locations, which are containers or parent entries for other configuration. For example: 
    [root@server ~]# ipa permission-add "manage automount locations" --subtree="ldap://ldap.example.com:389/cn=automount,dc=example,dc=com" --permissions=write --attrs=automountmapname --attrs=automountkey --attrs=automountInformation
    The --type and --subtree options are mutually exclusive.
  • --filter uses an LDAP filter to identify which entries the permission applies to. IdM automatically checks the validity of the given filter. The filter can be any valid LDAP filter, for example: 
    [root@server ~]# ipa permission-add "manage Windows groups" --filter="(!(objectclass=posixgroup))" --permissions=write --attrs=description
  • --memberof sets the target filter to members of the given group after checking that the group exists. For example: 
    [root@server ~]# ipa permission-add ManageHost --permissions="write" --subtree=cn=computers,cn=accounts,dc=testrelm,dc=com --attr=nshostlocation --memberof=admins
  • --targetgroup sets target to the specified user group after checking that the group exists.
The Target DN setting, available in the web UI, is not available on the command line.
Note
For information about modifying and deleting permissions, run the ipa permission-mod --help and ipa permission-del --help commands.

10.4.2.3. Default Managed Permissions

Managed permissions are permissions that come preinstalled with Identity Management. They behave like other permissions created by the user, with the following differences:
  • You cannot modify their name, location, and target attributes.
  • You cannot delete them.
  • They have three sets of attributes:
    • default attributes, which are managed by IdM and the user cannot modify them
    • included attributes, which are additional attributes added by the user; to add an included attribute to a managed permission, specify the attribute by supplying the --includedattrs option with the ipa permission-mod command
    • excluded attributes, which are attributes removed by the user; to add an excluded attribute to a managed permission, specify the attribute by supplying the --excludedattrs option with the ipa permission-mod command
A managed permission applies to all attributes that appear in the default and included attribute sets but not in the excluded set.
If you use the --attrs option when modifying a managed permission, the included and excluded attribute sets automatically adjust, so that only the attributes supplied with --attrs are enabled.
Note
While you cannot delete a managed permission, setting its bind type to permission and removing the managed permission from all privileges effectively disables it.
Names of all managed permissions start with System:, for example System: Add Sudo rule or System: Modify Services.
Earlier versions of IdM used a different scheme for default permissions, which, for example, forbade the user from modifying the default permissions and the user could only assign them to privileges. Most of these default permissions have been turned into managed permissions, however, the following permissions still use the previous scheme:
  • Add Automember Rebuild Membership Task
  • Add Replication Agreements
  • Certificate Remove Hold
  • Get Certificates status from the CA
  • Modify DNA Range
  • Modify Replication Agreements
  • Remove Replication Agreements
  • Request Certificate
  • Request Certificates from a different host
  • Retrieve Certificates from the CA
  • Revoke Certificate
  • Write IPA Configuration
If you attempt to modify a managed permission from the web UI, the attributes that you cannot modify will be disabled.

Figure 10.15. Disabled Attributes

Disabled Attributes
If you attempt to modify a managed permission from the command line, the system will not allow you to change the attributes that you cannot modify. For example, attempting to change a default System: Modify Users permission to apply to groups fails: 
$ ipa permission-mod 'System: Modify Users' --type=group
ipa: ERROR: invalid 'ipapermlocation': not modifiable on managed permissions
You can, however, make the System: Modify Users permission not to apply to the GECOS attribute: 
$ ipa permission-mod 'System: Modify Users' --excludedattrs=gecos
------------------------------------------
Modified permission "System: Modify Users"

10.4.2.4. Permissions in Earlier Versions of Identity Management

Earlier versions of Identity Management handled permissions differently, for example:
  • The global IdM ACI granted read access to all users of the server, even anonymous ones – that is, not authenticated – users.
  • Only write, add, and delete permission types were available. The read permission was available too, but it was of little practical value because all users, including unauthenticated ones, had read access by default.
The current version of Identity Management contains options for setting permissions which are much more fine-grained:
  • The global IdM ACI does not grant read access to unauthenticated users.
  • It is now possible to, for example, add both a filter and a subtree in the same permission.
  • It is possible to add search and compare rights.
The new way of handling permissions has significantly improved the IdM capabilities for controlling user or group access, while retaining backward compatibility with the earlier versions. Upgrading from an earlier version of IdM deletes the global IdM ACI on all servers and replaces it with managed permissions.
Permissions created in the previous way are automatically converted to the current style whenever you modify them. If you do not attempt to change them, the permissions of the previous type stay unconverted. Once a permission uses the current style, it can never downgrade to the previous style.
Note
It is still possible to assign permissions to privileges on servers running an earlier version of IdM.
The ipa permission-show and ipa permission-find commands recognize both the current permissions and the permissions of the previous style. While the outputs from both of these commands display permissions in the current style, the permissions themselves remain unchanged; the commands upgrade the permission entries before outputting the data only in memory, without committing the changes to LDAP.
Permissions with both the previous and the current characteristics have effect on all servers – those running previous versions of IdM, as well as those running the current IdM version. However, you cannot create or modify permissions with the current permissions on servers running previous versions of IdM.

10.4.3. Privileges

10.4.3.1. Creating New Privileges from the Web UI

  1. Open the IPA Server tab in the top menu, and select the Role-Based Access Control subtab.
  2. Select the Privileges task link.
  3. Click the Add link at the top of the list of the privileges.

    Figure 10.17. Adding a New Privilege

    Adding a New Privilege
  4. Enter the name and a description of the privilege.

    Figure 10.18. Form for Adding a Privilege

    Form for Adding a Privilege
  5. Click the Add and Edit button to go to the privilege configuration page to add permissions.
  6. Select the Permissions tab.
  7. Click Add at the top of the list of the permissions to add permission to the privilege.

    Figure 10.19. Adding Permissions

    Adding Permissions
  8. Click the check box by the names of the permissions to add, and use the > button to move the permissions to the Prospective column.

    Figure 10.20. Selecting Permissions

    Selecting Permissions
  9. Click the Add button to save.

10.4.3.2. Creating New Privileges from the Command Line

Privilege entries are created using the privilege-add command, and then permissions are added to the privilege group using the privilege-add-permission command.
  1. Create the privilege entry. 
    [jsmith@server ~]$ ipa privilege-add "managing filesystems" --desc="for filesystems"
  2. Assign the required permissions. For example: 
    [jsmith@server ~]$ ipa privilege-add-permission "managing filesystems" --permissions="managing automount" --permissions="managing ftp services"

Part IV. Administration: Managing Identities

This part details how to manage user accounts, hosts, as well as user groups and host groups. In addition, it details how to assign and view unique UID and GID numbers and how user and group schema works. The following chapter deals with managing services and delegating access to hosts and services. The final chapters provide instruction on how to define Access Control for Identity Management users, how to manage Kerberos flags and principal aliases, and how to integrate with NIS domains and Netgroups.

Chapter 11. Managing User Accounts

This chapter covers general management and configuration of user accounts.

11.1. Setting up User Home Directories

It is recommended that every user has a home directory configured. The default expected location for user home directories is in the /home/ directory. For example, IdM expects a user with the user_login login to have a home directory set up at /home/user_login.
Note
You can change the default expected location for user home directories using the ipa config-mod command.
IdM does not automatically create home directories for users. However, you can configure a PAM home directory module to create a home directory automatically when a user logs in. Alternatively, you can add home directories manually using NFS shares and the automount utility.

11.1.1. Mounting Home Directories Automatically Using the PAM Home Directory Module

Supported PAM Home Directory Modules

To configure a PAM home directory module to create home directories for users automatically when they log in to the IdM domain, use one of the following PAM modules:
  • pam_oddjob_mkhomedir
  • pam_mkhomedir
IdM first attempts to use pam_oddjob_mkhomedir. If this module is not installed, IdM attempts to use pam_mkhomedir instead.
Note
Auto-creating home directories for new users on an NFS share is not supported.

Configuring the PAM Home Directory Module

Enabling the PAM home directory module has local effect. Therefore, you must enable the module individually on each client and server where it is required.
To configure the module during the installation of the server or client, use the --mkhomedir option with the ipa-server-install or ipa-client-install utility when installing the machine.
To configure the module on an already installed server or client, use the authconfig utility. For example: 
# authconfig --enablemkhomedir --update
For more information on using authconfig to create home directories, see the System-Level Authentication Guide.

11.1.2. Mounting Home Directories Manually

You can use an NFS file server to provide a /home/ directory that will be available to all machines in the IdM domain, and then mount the directory on an IdM machine using the automount utility.

Potential Problems When Using NFS

Using NFS can potentially have negative impact on performance and security. For example, using NFS can lead to security vulnerabilities resulting from granting root access to the NFS user, performance issues with loading the entire /home/ directory tree, or network performance issues for using remote servers for home directories.
To reduce the effect of these problems, it is recommended to follow these guidelines:
  • Use automount to mount only the user's home directory and only when the user logs in. Do not use it to load the entire /home/ tree.
  • Use a remote user who has limited permissions to create home directories, and mount the share on the IdM server as this user. Because the IdM server runs as an httpd process, it is possible to use sudo or a similar program to grant limited access to the IdM server to create home directories on the NFS server.

Configuring Home Directories Using NFS and automount

To manually add home directories to the IdM server from separate locations using NFS shares and automount:
  1. Create a new location for the user directory maps. 
    $ ipa automountlocation-add userdirs
Location: userdirs
  2. Add a direct mapping to the new location's auto.direct file. The auto.direct file is the automount map automatically created by the ipa-server-install utility. In the following example, the mount point is /share: 
    $ ipa automountkey-add userdirs auto.direct --key=/share --info="-ro,soft, server.example.com:/home/share"

Key: /share
Mount information: -ro,soft, server.example.com:/home/share
For more details on using automount with IdM, see Chapter 34, Using Automount.

11.2. User Life Cycle

Identity Management supports three user account states: stage, active, and preserved.
  • Stage users are not allowed to authenticate. This is an initial state. Some of the user account properties required for active users might not yet be set.
  • Active users are allowed to authenticate. All required user account properties must be set in this state.
  • Preserved users are former active users. They are considered inactive and cannot authenticate to IdM. Preserved users retain most of the account properties they had as active users, but they are not part of any user groups.
    Note
    The list of users in the preserved state can provide a history of past user accounts.
User entries can also be permanently deleted from the IdM database. Deleting a user entry permanently removes the entry itself and all its information from IdM, including group memberships and passwords. Any external configuration for the user, such as the system account and home directory, is not deleted, but is no longer accessible through IdM.
Important
Deleted user accounts cannot be restored. When you delete a user account, all the information associated with the account is lost permanently.
A new administrator user can only be created by another administrator, such as the default admin user. If you accidentally delete all administrator accounts, the Directory Manager must create a new administrator manually in the Directory Server.
Warning
Do not delete the admin user. As admin is a pre-defined user required by IdM, this operation causes problems with certain commands. If you want to define and use an alternative admin user, rather disable the pre-defined admin user with ipa user-disable admin after you granted admin permissions to at least one different user.

User Life Cycle Management Operations

To manage user provisioning, the administrator can move user accounts from one state to another. New user accounts can be added as either active or stage, but not as preserved.
IdM supports the following operations for user life cycle management:
stage → active
When an account in the stage state is ready to be properly activated, the administrator moves it to the active state.
active → preserved
After the user leaves the company, the administrator moves the account to the preserved state.
preserved → active
A former user joins the company again. The administrator restores the user account by moving it from the preserved state back to the active state.
preserved → stage
A former user is planning to join the company again. The administrator moves the account from the preserved state to the stage state to prepare the account for later reactivation.
You can also permanently delete active, stage, and preserved users from IdM. Note that you cannot move stage users to the preserved state, you can only delete them permanently.

Figure 11.1. User Life Cycle Operations

User Life Cycle Operations

11.2.1. Adding Stage or Active Users

Adding Users in the Web UI

  1. Select the Identity → Users tab.
  2. Select the Active users or Stage users category, depending on whether you want to add a user in the active or stage state.

    Figure 11.2. Selecting User Category

    Selecting User Category
    For more information about the active or stage user life cycle states, see Section 11.2, “User Life Cycle”.
  3. Click Add at the top of the users list.

    Figure 11.3. Adding a User

    Adding a User
  4. Fill in the Add User form.
    Note that if you do not set a user login manually, IdM generates the login automatically based on the specified first name and last name.
  5. Click Add.
    Alternatively, click Add and Add Another to start adding another user or Add and Edit to start editing the new user entry. For information on editing user entries, see Section 11.3, “Editing Users”.

Adding Users from the Command Line

To add a new user in the active state, use the ipa user-add command. To add a new user in the stage state, use the ipa stageuser-add command.
Note
For more information about the active or stage user life cycle states, see Section 11.2, “User Life Cycle”.
When run without any options, ipa user-add and ipa stageuser-add prompt you for the minimum required user attributes and use default values for the other attributes. Alternatively, you can add options specifying various attributes directly to the commands.
In the interactive session, after you run the command without any options, IdM proposes an automatically generated user login based on the provided first name and last name and displays it in brackets ([ ]). To accept the default login, confirm by pressing Enter. To specify a custom login, do not confirm the default and specify the custom login instead. 
$ ipa user-add
First name: first_name
Last name: last_name
User login [default_login]: custom_login
Adding options to ipa user-add and ipa stageuser-add enables you to define custom values for many of the user attributes. This means that you can specify more information than in the interactive session. For example, to add a stage user: 
$ ipa stageuser-add stage_user_login --first=first_name --last=last_name --email=email_address
For a complete list of options accepted by ipa user-add and ipa stageuser-add, run the commands with the --help option added.

11.2.1.1. User Name Requirements

IdM supports user names that can be described by the following regular expression: 
'(?!^[0-9]+$)^[a-zA-Z0-9_.][a-zA-Z0-9_.-]*[a-zA-Z0-9_.$-]?$'
User names may only include letters, numbers, _, -, ., $ and must include at least one letter.
Note
User names ending with the trailing dollar sign ($) are supported to enable Samba 3.x machine support.
If you add a user whose user name contains uppercase characters, IdM automatically converts the name to lowercase when saving it. Therefore, IdM always requires users to enter their user names all lowercase when logging in. Additionally, it is not possible to add users whose user names only differ in letter casing, such as user and User.
The default maximum length for user names is 32 characters. To change it, use the ipa config-mod --maxusername command. For example, to increase the maximum user name length to 64 characters: 
$ ipa config-mod --maxusername=64
  Maximum username length: 64
  ...

11.2.1.2. Defining a Custom UID or GID Number

If you add a new user entry without specifying a custom UID or GID number, IdM automatically assigns an ID number that is next available in the ID range. This means that users' ID numbers are always unique. For more information about ID ranges, see Chapter 14, Unique UID and GID Number Assignments.
When you specify a custom ID number, the server does not validate whether the custom ID number is unique. Due to this, multiple user entries might have the same ID number assigned. Red Hat recommends to prevent having multiple entries with the same ID number.

11.2.2. Listing Users and Searching for Users

Listing Users in the Web UI

  1. Select the Identity → Users tab.
  2. Select the Active users, Stage users, or Preserved users category.

    Figure 11.4. Listing Users

    Listing Users

Displaying Information About a User in the Web UI

To display detailed information about a user, click the name of the user in the list of users:

Figure 11.5. Displaying User Information

Displaying User Information

Listing Users from the Command Line

To list all active users run the ipa user-find command. To list all stage users, use the ipa stageuser-find command. To list preserved users, run the ipa user-find --preserved=true command.
For example: 
$ ipa user-find
---------------
23 users matched
---------------
  User login: admin
  Last name: Administrator
  Home directory: /home/admin
  Login shell: /bin/bash
  UID: 1453200000
  GID: 1453200000
  Account disabled: False
  Password: True
  Kerberos keys available: True

  User login: user
...
By adding options and arguments to ipa user-find and ipa stageuser-find, you can define the search criteria and filter the search results. For example, to display all active users with a specific title defined: 
$ ipa user-find --title=user_title
---------------
2 users matched
---------------
  User login: user
...
  Job Title: Title
...

  User login: user2
...
  Job Title: Title
...
Similarly, to display all stage users whose login contains user: 
$ ipa user-find user
---------------
3 users matched
---------------
User login: user
...

User login: user2
...

User login: user3
...
For a complete list of options accepted by ipa user-find and ipa stageuser-find, run the commands with the --help option added.

Displaying Information about a User from the Command Line

To display information about an active or preserved user, use the ipa user-show command: 
$ ipa user-show user_login
  User login: user_login
  First name: first_name
  Last name: last_name
...
To display information about a stage user, use the ipa stageuser-show command:

11.2.3. Activating, Preserving, Deleting, and Restoring Users

This section describes moving user accounts between different user life cycle states. For details on the life cycle states in IdM, see Section 11.2, “User Life Cycle”.

Managing User Life Cycle in the Web UI

To activate a stage user:
  • In the Stage users list, select the user to activate, and click Activate.

    Figure 11.6. Activating a User

    Activating a User
To preserve or delete a user:
  1. In the Active users or Stage users lists, select the user. Click Delete.

    Figure 11.7. Deleting a User

    Deleting a User
  2. If you selected an active user, select delete or preserve. If you selected a stage user, you can only delete the user. The default UI option is delete.
    For example, to preserve an active user:

    Figure 11.8. Selecting the Delete Mode in the Web UI

    Selecting the Delete Mode in the Web UI
    To confirm, click the Delete button.
To restore a preserved user:
  • In the Preserved users list, select the user to restore, and click Restore.

    Figure 11.9. Restoring a User

    Restoring a User
Note
Restoring a user does not restore all of the account's previous attributes. For example, the user's password is not restored and must be defined again.
Note that in the web UI, it is not possible to move a user from the preserved state to the stage state.

Managing User Life Cycle from the Command Line

To activate a user account by moving it from stage to active, use the ipa stageuser-activate command. 
$ ipa stageuser-activate user_login
-------------------------
Stage user user_login activated
-------------------------
...
To preserve or delete a user account, use the ipa user-del or ipa stageuser-del commands.
  • To remove an active user permanently from the IdM database, run ipa user-del without any options. 
    $ ipa user-del user_login
--------------------
Deleted user "user3"
--------------------
  • To preserve an active user account, run ipa user-del with the --preserve option. 
    $ ipa user-del --preserve user_login
--------------------
Deleted user "user_login"
--------------------
  • To remove a stage user permanently from the IdM database, run ipa stageuser-del. 
    $ ipa stageuser-del user_login
--------------------------
Deleted stage user "user_login"
--------------------------
Note
When deleting multiple users, use the --continue option to force the command to continue regardless of errors. A summary of the successful and failed operations is printed to the stdout standard output stream when the command completes. 
$ ipa user-del --continue user1 user2 user3
If --continue is not used, the command proceeds with deleting users until it encounters an error, after which it stops and exits.
To restore a preserved user account by moving it from preserved to active, use the ipa user-undel command. 
$ ipa user-undel user_login
------------------------------
Undeleted user account "user_login"
------------------------------
To restore a preserved user account by moving it from preserved to stage, use the ipa user-stage command. 
$ ipa user-stage user_login
------------------------------
Staged user account "user_login"
------------------------------
Note
Restoring a user account does not restore all of the account's previous attributes. For example, the user's password is not restored and must be defined again.
For more information about these commands and the options they accept, run them with the --help option added.

11.3. Editing Users

Editing Users in the Web UI

  1. Select the Identity → Users tab.
  2. Search the Active users, Stage users, or Preserved users category to find the user to edit.
  3. Click the name of the user to edit.

    Figure 11.10. Selecting a User to Edit

    Selecting a User to Edit
  4. Edit the user attribute fields as required.
  5. Click Save at the top of the page.

    Figure 11.11. Save Modified User Attributes

    Save Modified User Attributes
After you update user details in the web UI, the new values are not synchronized immediately. It might take up to approximately 5 minutes before the new values are reflected at the client system.

Editing Users from the Command Line

To modify a user in the active or preserved states, use the ipa user-mod command. To modify a user in the stage state, use the ipa stageuser-mod command.
The ipa user-mod and ipa stageuser-mod commands accept the following options:
  • the user login, which identifies the user account to be modified
  • options specifying the new attribute values
For a complete list of user entry attributes that can be modified from the command line, see the list of options accepted by ipa user-mod and ipa stageuser-mod. To display the list of options, run the commands with the --help option added.
Simply adding an attribute option to ipa user-mod or ipa stageuser-mod overwrites the current attribute value. For example, the following changes a user's title or adds a new title if the user did not yet have a title specified: 
$ ipa user-mod user_login --title=new_title
For LDAP attributes that are allowed to have multiple values, IdM also accepts multiple values. For example, a user can have two email addresses saved in their user account. To add an additional attribute value without overwriting the existing value, use the --addattr option together with the option to specify the new attribute value. For example, to add a new email address to a user account that already has an email address specified: 
$ ipa user-mod user --addattr=mobile=new_mobile_number
--------------------
Modified user "user"
--------------------
  User login: user
...
  Mobile Telephone Number: mobile_number, new_mobile_number
...
To set two attribute values at the same time, use the --addattr option twice: 
$ ipa user-mod user --addattr=mobile=mobile_number_1 --addattr=mobile=mobile_number_2
The ipa user-mod command also accepts the --setattr option for setting attribute values and the --delattr option for deleting attribute values. These options are used in a way similar to using --addattr. For details, see the output of the ipa user-mod --help command.
Note
To overwrite the current email address for a user, use the --email option. However, to add an additional email address, use the mail option with the --addattr option: 
$ ipa user-mod user --email=email@example.com

$ ipa user-mod user --addattr=mail=another_email@example.com

11.4. Enabling and Disabling User Accounts

The administrator can disable and enable active user accounts. Disabling a user account deactivates the account. Disabled user accounts cannot be used to authenticate. A user whose account has been disabled cannot log into IdM and cannot use IdM services, such as Kerberos, or perform any tasks.
Disabled user accounts still exist within IdM and all of the associated information remains unchanged. Unlike preserved user accounts, disabled user accounts remain in the active state. Therefore, they are displayed in the output of the ipa user-find command. For example: 
$ ipa user-find
...
  User login: user
  First name: User
  Last name: User
  Home directory: /home/user
  Login shell: /bin/sh
  UID: 1453200009
  GID: 1453200009
  Account disabled: True
  Password: False
  Kerberos keys available: False
...
Any disabled user account can be enabled again.
Note
After disabling a user account, existing connections remain valid until the user's Kerberos TGT and other tickets expire. After the ticket expires, the user will not be able renew it.

Enabling and Disabling User Accounts in the Web UI

  1. Select the Identity → Users tab.
  2. From the Active users list, select the required user or users, and then click Disable or Enable.

    Figure 11.12. Disabling or Enabling a User Account

    Disabling or Enabling a User Account

Disabling and Enabling User Accounts from the Command Line

To disable a user account, use the ipa user-disable command. 
$ ipa user-disable user_login
----------------------------
Disabled user account "user_login"
----------------------------
To enable a user account, use the ipa user-enable command. 
$ ipa user-enable user_login
----------------------------
Enabled user account "user_login"
----------------------------

11.5. Allowing Non-admin Users to Manage User Entries

By default, only the admin user is allowed to manage user life cycle and disable or enable user accounts. To allow another, non-admin user to do this, create a new role, add the relevant permissions to this role, and assign the non-admin user to the role.
By default, IdM includes the following privileges related to managing user accounts:
Modify Users and Reset passwords
This privilege includes permissions to modify various user attributes.
User Administrators
This privilege includes permissions to add active users, activate non-active users, remove users, modify user attributes, and other permissions.
Stage User Provisioning
This privilege includes a permission to add stage users.
Stage User Administrator
This privilege includes permissions to perform a number of life cycle operations, such as adding stage users or moving users between life cycle states. However, it does not include permissions to move users to the active state.
For information on defining roles, permissions, and privileges, see Section 10.4, “Defining Role-Based Access Controls”.

Allowing Different Users to Perform Different User Management Operations

The different privileges related to managing user accounts can be added to different users. For example, you can separate privileges for employee account entry and activation by:
  • Configuring one user as a stage user administrator, who is allowed to add future employees to IdM as stage users, but not to activate them.
  • Configuring another user as a security administrator, who is allowed to activate the stage users after their employee credentials are verified on the first day of employment.
To allow a user to perform certain user management operations, create a new role with the required privilege or privileges, and assign the user to that role.

Example 11.1. Allowing a Non-admin User to Add Stage Users

This example shows how to create a user who is only allowed to add new stage users, but not to perform any other stage user management operations.
  1. Log in as the admin user or another user allowed to manage role-based access control. 
    $ kinit admin
  2. Create a new custom role to manage adding stage users.
    1. Create the System Provisioning role. 
      $ ipa role-add --desc "Responsible for provisioning stage users" "System Provisioning"
--------------------------------
Added role "System Provisioning"
--------------------------------
Role name: System Provisioning
Description: Responsible for provisioning stage users
    2. Add the Stage User Provisioning privilege to the role. This privilege provides the ability to add stage users. 
      $ ipa role-add-privilege "System Provisioning" --privileges="Stage User Provisioning"
Role name: System Provisioning
Description: Responsible for provisioning stage users
Privileges: Stage User Provisioning
----------------------------
Number of privileges added 1
----------------------------
  3. Grant a non-admin user the rights to add stage users.
    1. If the non-admin user does not yet exist, create a new user. In this example, the user is named stage_user_admin. 
      $ ipa user-add stage_user_admin --password
First name: first_name
Last name: last_name
Password:
Enter password again to verify:
...
    2. Assign the stage_user_admin user to the System Provisioning role. 
      $ ipa role-add-member "System Provisioning" --users=stage_user_admin
Role name: System Provisioning
Description: Responsible for provisioning stage users
Member users: stage_user_admin
Privileges: Stage User Provisioning
-------------------------
Number of members added 1
-------------------------
    3. To make sure the System Provisioning role is configured correctly, you can use the ipa role-show command to display the role settings. 
      $ ipa role-show "System Provisioning"
--------------
1 role matched
--------------
Role name: System provisioning
Description: Responsible for provisioning stage users
Member users: stage_user_admin
Privileges: Stage User Provisioning
----------------------------
Number of entries returned 1
----------------------------
  4. Test adding a new stage user as the stage_user_admin user.
    1. Log in as stage_user_admin. Note that if you created stage_user_admin as a new user in one of the previous steps, IdM will ask you to change the initial password set by admin. 
      $ kinit stage_user_admin
Password for stage_user_admin@EXAMPLE.COM:
Password expired.  You must change it now.
Enter new password:
Enter it again:
    2. To make sure your Kerberos ticket for admin has been replaced with a Kerberos ticket for stage_user_admin, you can use the klist utility. 
      $ klist
Ticket cache: KEYRING:persistent:0:krb_ccache_xIlCQDW
Default principal: stage_user_admin@EXAMPLE.COM

Valid starting       Expires              Service principal
02/25/2016 11:42:20  02/26/2016 11:42:20  krbtgt/EXAMPLE.COM
    3. Add a new stage user. 
      $ ipa stageuser-add stage_user
First name: first_name
Last name: last_name
ipa: ERROR: stage_user: stage user not found
      Note
      The error that IdM reports after adding a stage user is expected. The stage_user_admin is only allowed to add stage users, not to display information about them. Therefore, instead of displaying a summary of the newly added stage_user settings, IdM displays the error.
The stage_user_admin user is not allowed to display information about stage users. Therefore, an attempt to display information about the new stage_user user while logged in as stage_user_admin fails: 
$ ipa stageuser-show stage_user
ipa: ERROR: stage_user: stage user not found
To display information about stage_user, you can log in as admin: 
$ kinit admin
Password for admin@EXAMPLE.COM:
$ ipa stageuser-show stage_user
  User login: stage_user
  First name: Stage
  Last name: User
...

11.6. Using an External Provisioning System for Users and Groups

Identity Management supports configuring your environment, so that an external solution for managing identities is used to provision user and group identities in IdM. This section describes an example of such configuration. The example includes:

11.6.1. Configuring User Accounts to Be Used by the External Provisioning System

This procedure shows how to configure two IdM user accounts to be used by the external provisioning system. By adding the accounts to a group with an appropriate password policy, you enable the external provisioning system to manage user provisioning in IdM.
  1. Create a user, provisionator, with the privileges to add stage users. The user account will be used by the external provisioning system to add new stage users.
    1. Add the provisionator user account: 
      $ ipa user-add provisionator --first=provisioning --last=account --password
    2. Grant the provisionator user the required privileges.
      Create a custom role, System Provisioning, to manage adding stage users: 
      $ ipa role-add --desc "Responsible for provisioning stage users" "System Provisioning"
      Add the Stage User Provisioning privilege to the role. This privilege provides the ability to add stage users: 
      $ ipa role-add-privilege "System Provisioning" --privileges="Stage User Provisioning"
      Add the provisionator user to the role: 
      $ ipa role-add-member --users=provisionator "System Provisioning"
  2. Create a user, activator, with the privileges to manage user accounts. The user account will be used to automatically activate stage users added by the external provisioning system.
    1. Add the activator user account: 
      $ ipa user-add activator --first=activation --last=account --password
    2. Grant the activator user the required privileges.
      Add the user to the default User Administrator role: 
      $ ipa role-add-member --users=activator "User Administrator"
  3. Create a user group for service and application accounts: 
    $ ipa group-add service-accounts
  4. Update the password policy for the group. The following policy prevents password expiration and lockout for the account but compensates the potential risks by requiring complex passwords: 
    $ ipa pwpolicy-add service-accounts --maxlife=10000 --minlife=0 --history=0 --minclasses=4 --minlength=20 --priority=1 --maxfail=0 --failinterval=1 --lockouttime=0
  5. Add the provisioning and activation accounts to the group for service and application accounts: 
    $ ipa group-add-member service-accounts --users={provisionator,activator}
  6. Change the passwords for the user accounts: 
    $ kpasswd provisionator
$ kpasswd activator
    Changing the passwords is necessary because passwords of new IdM users expire immediately.
Additional resources:

11.6.2. Configuring IdM to Automatically Activate Stage User Accounts

This procedure shows how to create a script for activating stage users. The system runs the script automatically at specified time intervals. This ensures that new user accounts are automatically activated and available for use shortly after they are created.
Important
The procedure assumes that the new user accounts do not require validation before the script adds them to IdM. For example, validation is not required when the users have already been validated by the owner of the external provisioning system.
It is sufficient to enable the activation process on only one of your IdM servers.
  1. Generate a keytab file for the activation account: 
    # ipa-getkeytab -s example.com -p "activator" -k /etc/krb5.ipa-activation.keytab
    If you want to enable the activation process on more than one IdM server, generate the keytab file on one server only. Then copy the keytab file to the other servers.
  2. Create a script, /usr/local/sbin/ipa-activate-all, with the following contents to activate all users: 
    #!/bin/bash

kinit -k -i activator

ipa stageuser-find --all --raw | grep "  uid:" | cut -d ":" -f 2 | while read uid; do ipa stageuser-activate ${uid}; done
  3. Edit the permissions and ownership for the ipa-activate-all script to make it executable: 
    # chmod 755 /usr/local/sbin/ipa-activate-all
# chown root:root /usr/local/sbin/ipa-activate-all
  4. Create a systemd unit file, /etc/systemd/system/ipa-activate-all.service, with the following contents: 
    [Unit]
Description=Scan IdM every minute for any stage users that must be activated

[Service]
Environment=KRB5_CLIENT_KTNAME=/etc/krb5.ipa-activation.keytab
Environment=KRB5CCNAME=FILE:/tmp/krb5cc_ipa-activate-all
ExecStart=/usr/local/sbin/ipa-activate-all
  5. Create a systemd timer, /etc/systemd/system/ipa-activate-all.timer, with the following contents: 
    [Unit]
Description=Scan IdM every minute for any stage users that must be activated

[Timer]
OnBootSec=15min
OnUnitActiveSec=1min

[Install]
WantedBy=multi-user.target
  6. Enable ipa-activate-all.timer: 
    # systemctl enable ipa-activate-all.timer
Additional resources:

11.6.3. Configuring the LDAP Provider of the External Provisioning System to Manage the IdM Identities

This section shows templates for various user and group management operations. Using these templates, you can configure the LDAP provider of your provisioning system to manage IdM user accounts. For example, you can configure the system to inactivate a user account after the employee has left the company.

Managing User Accounts Using LDAP

You can add new user entries, modify existing entries, move users between different life cycle states, or delete users by editing the underlying Directory Server database. To edit the database, use the ldapmodify utility.
The following LDIF-formatted templates provide information on what attributes to modify using ldapmodify. For detailed example procedures, see Example 11.2, “Adding a Stage User with ldapmodify” and Example 11.3, “Preserving a User with ldapmodify”.
Adding a new stage user
Adding a user with UID and GID automatically assigned: 
dn: uid=user_login,cn=staged users,cn=accounts,cn=provisioning,dc=example,dc=com
changetype: add
objectClass: top
objectClass: inetorgperson
uid: user_login
sn: surname
givenName: first_name
cn: full_name
Adding a user with UID and GID statically assigned: 
dn: uid=user_login,cn=staged users,cn=accounts,cn=provisioning,dc=example,dc=com
changetype: add
objectClass: top
objectClass: person
objectClass: inetorgperson
objectClass: organizationalperson
objectClass: posixaccount
uid: user_login
uidNumber: UID_number
gidNumber: GID_number
sn: surname
givenName: first_name
cn: full_name
homeDirectory: /home/user_login
You are not required to specify any IdM object classes when adding stage users. IdM adds these classes automatically after the users are activated.
Note that the distinguished name (DN) of the created entry must start with uid=user_login.
Modifying existing users
Before modifying a user, obtain the user's distinguished name (DN) by searching by the user's login. In the following example, the user_allowed_to_read user in the following example is a user allowed to read user and group information, and password is this user's password: 
# ldapsearch -LLL -x -D "uid=user_allowed_to_read,cn=users,cn=accounts,dc=example, dc=com" -w "password" -H ldap://server.example.com -b "cn=users, cn=accounts, dc=example, dc=com" uid=user_login
To modify a user's attribute: 
dn: distinguished_name
changetype: modify
replace: attribute_to_modify
attribute_to_modify: new_value
To disable a user: 
dn: distinguished_name
changetype: modify
replace: nsAccountLock
nsAccountLock: TRUE
To enable a user: 
dn: distinguished_name
changetype: modify
replace: nsAccountLock
nsAccountLock: FALSE
To preserve a user: 
dn: distinguished_name
changetype: modrdn
newrdn: uid=user_login
deleteoldrdn: 0
newsuperior: cn=deleted users,cn=accounts,cn=provisioning,dc=example
Updating the nssAccountLock attribute has no effect on stage and preserved users. Even though the update operation completes successfully, the attribute value remains nssAccountLock: TRUE.
Creating a new group
To create a new group: 
dn: cn=group_distinguished_name,cn=groups,cn=accounts,dc=example,dc=com
changetype: add
objectClass: top
objectClass: ipaobject
objectClass: ipausergroup
objectClass: groupofnames
objectClass: nestedgroup
objectClass: posixgroup
cn: group_name
gidNumber: GID_number
Modifying groups
Before modifying a group, obtain the group's distinguished name (DN) by searching by the group's name. 
# ldapsearch -YGSSAPI  -H ldap://server.example.com -b "cn=groups,cn=accounts,dc=example,dc=com" "cn=group_name"
To delete an existing group: 
dn: group_distinguished_name
changetype: delete
To add a member to a group: 
dn: group_distinguished_name
changetype: modify
add: member
member: uid=user_login,cn=users,cn=accounts,dc=example,dc=com
To remove a member from a group: 
dn: distinguished_name
changetype: modify
delete: member
member: uid=user_login,cn=users,cn=accounts,dc=example,dc=com
Do not add stage or preserved users to groups. Even though the update operation completes successfully, the users will not be updated as members of the group. Only active users can belong to groups.

Example 11.2. Adding a Stage User with ldapmodify

To add a new stageuser user using the standard interorgperson object class:
  1. Use ldapmodify to add the user. 
    # ldapmodify -Y GSSAPI
SASL/GSSAPI authentication started
SASL username: admin@EXAMPLE
SASL SSF: 56
SASL data security layer installed.
dn: uid=stageuser,cn=staged users,cn=accounts,cn=provisioning,dc=example
changetype: add
objectClass: top
objectClass: inetorgperson
cn: Stage
sn: User

adding new entry "uid=stageuser,cn=staged users,cn=accounts,cn=provisioning,dc=example"
  2. Consider validating the contents of the stage entry to make sure your provisioning system added all required POSIX attributes and the stage entry is ready to be activated. To display the new stage user's LDAP attributes using the ipa stageuser-show --all --raw command. Note that the user is explicitly disabled by the nsaccountlock attribute: 
    $ ipa stageuser-show stageuser --all --raw
  dn: uid=stageuser,cn=staged users,cn=accounts,cn=provisioning,dc=example
  uid: stageuser
  sn: User
  cn: Stage
  has_password: FALSE
  has_keytab: FALSE
  nsaccountlock: TRUE
  objectClass: top
  objectClass: inetorgperson
  objectClass: organizationalPerson
  objectClass: person

Example 11.3. Preserving a User with ldapmodify

To preserve user by using the LDAP modrdn operation:
  1. Use the ldapmodify utility to modify the user entry. 
    $ ldapmodify -Y GSSAPI
SASL/GSSAPI authentication started
SASL username: admin@EXAMPLE
SASL SSF: 56
SASL data security layer installed.
dn: uid=user1,cn=users,cn=accounts,dc=example
changetype: modrdn
newrdn: uid=user1
deleteoldrdn: 0
newsuperior: cn=deleted users,cn=accounts,cn=provisioning,dc=example

modifying rdn of entry "uid=user1,cn=users,cn=accounts,dc=example"
  2. Optionally, verify the user has been preserved by listing all preserved users. 
    $ ipa user-find --preserved=true
---------------
1 user matched
---------------
  User login: user1
  First name: first_name
  Last name: last_name
...
----------------------------
Number of entries returned 1
----------------------------

Chapter 12. Managing Hosts

Both DNS and Kerberos are configured as part of the initial client configuration. This is required because these are the two services that bring the machine within the IdM domain and allow it to identify the IdM server it will connect with. After the initial configuration, IdM has tools to manage both of these services in response to changes in the domain services, changes to the IT environment, or changes on the machines themselves which affect Kerberos, certificate, and DNS services.
This chapter describes how to manage identity services that relate directly to the client machine:
  • DNS entries and settings
  • Machine authentication
  • Host name changes (which affect domain services)

12.1. About Hosts, Services, and Machine Identity and Authentication

The basic function of an enrollment process is to create a host entry for the client machine in the IdM directory. This host entry is used to establish relationships between other hosts and even services within the domain (as described in Chapter 1, Introduction to Red Hat Identity Management). These relationships are part of delegating authorization and control to hosts within the domain.
A host entry contains all of the information about the client within IdM:
  • Service entries associated with the host
  • The host and service principal
  • Access control rules
  • Machine information, such as its physical location and operating system
Some services that run on a host can also belong to the IdM domain. Any service that can store a Kerberos principal or an SSL certificate (or both) can be configured as an IdM service. Adding a service to the IdM domain allows the service to request an SSL certificate or keytab from the domain. (Only the public key for the certificate is stored in the service record. The private key is local to the service.)
An IdM domain establishes a commonality between machines, with common identity information, common policies, and shared services. Any machine which belongs to a domain functions as a client of the domain, which means it uses the services that the domain provides. An IdM domain provides three main services specifically for machines:
  • DNS
  • Kerberos
  • Certificate management
Like users, machines are an identity that is managed by IdM. Client machines use DNS to identify IdM servers, services, and domain members. These are, like user identities, stored in the 389 Directory Server instance for the IdM server. Like users, machines can be authenticated to the domain using Kerberos or certificates.
From the machine perspective, there are several tasks that can be performed that access these domain services:
  • Joining the DNS domain (machine enrollment)
  • Managing DNS entries and zones
  • Managing machine authentication
Authentication in IdM includes machines as well as users. Machine authentication is required for the IdM server to trust the machine and to accept IdM connections from the client software installed on that machine. After authenticating the client, the IdM server can respond to its requests. IdM supports three different approaches to machine authentication:
  • SSH keys. The SSH public key for the host is created and uploaded to the host entry. From there, the System Security Services Daemon (SSSD) uses IdM as an identity provider and can work in conjunction with OpenSSH and other services to reference the public keys located centrally in Identity Management. This is described in Section 12.5, “Managing Public SSH Keys for Hosts”.
  • Key tables (or keytabs, a symmetric key resembling to some extent a user password) and machine certificates. Kerberos tickets are generated as part of the Kerberos services and policies defined by the server. Initially granting a Kerberos ticket, renewing the Kerberos credentials, and even destroying the Kerberos session are all handled by the IdM services. Managing Kerberos is covered in Chapter 29, Managing the Kerberos Domain.
  • Machine certificates. In this case, the machine uses an SSL certificate that is issued by the IdM server's certificate authority and then stored in IdM's Directory Server. The certificate is then sent to the machine to present when it authenticates to the server. On the client, certificates are managed by a service called certmonger.

12.2. About Host Entry Configuration Properties

A host entry can contain information about the host that is outside its system configuration, such as its physical location, MAC address, keys, and certificates.
This information can be set when the host entry is created if it is created manually; otherwise, most of this information needs to be added to the host entry after the host is enrolled in the domain.

Table 12.1. Host Configuration Properties

UI Field Command-Line Option Description
Description --desc=description A description of the host.
Locality --locality=locality The geographic location of the host.
Location --location=location The physical location of the host, such as its data center rack.
Platform --platform=string The host hardware or architecture.
Operating system --os=string The operating system and version for the host.
MAC address --macaddress=address The MAC address for the host. This is a multi-valued attribute. The MAC address is used by the NIS plug-in to create a NIS ethers map for the host.
SSH public keys --sshpubkey=string The full SSH public key for the host. This is a multi-valued attribute, so multiple keys can be set.
Principal name (not editable) --principalname=principal The Kerberos principal name for the host. This defaults to the host name during the client installation, unless a different principal is explicitly set in the -p. This can be changed using the command-line tools, but cannot be changed in the UI.
Set One-Time Password --password=string Sets a password for the host which can be used in bulk enrollment.
- --random Generates a random password to be used in bulk enrollment.
- --certificate=string A certificate blob for the host.
- --updatedns This sets whether the host can dynamically update its DNS entries if its IP address changes.

12.3. Adding Host Entries

12.3.1. Adding Host Entries from the Web UI

  1. Open the Identity tab, and select the Hosts subtab.
  2. Click Add at the top of the hosts list.

    Figure 12.1. Adding Host Entries

    Adding Host Entries
  3. Fill in the machine name and select the domain from the configured zones in the drop-down list. If the host has already been assigned a static IP address, then include that with the host entry so that the DNS entry is fully created.
    Optionally, to add an extra value to the host for some use cases, use the Class field. Semantics placed on this attribute are for local interpretation.

    Figure 12.2. Add Host Wizard

    Add Host Wizard
    DNS zones can be created in IdM, which is described in Section 33.4.1, “Adding and Removing Master DNS Zones”. If the IdM server does not manage the DNS server, the zone can be entered manually in the menu area, like a regular text field.
    Note
    Select the Force check box if you want to skip checking whether the host is resolvable via DNS.
  4. Click the Add and Edit button to go directly to the expanded entry page and fill in more attribute information. Information about the host hardware and physical location can be included with the host entry.

    Figure 12.3. Expanded Entry Page

    Expanded Entry Page

12.3.2. Adding Host Entries from the Command Line

Host entries are created using the host-add command. This commands adds the host entry to the IdM Directory Server. The full list of options with host-add are listed in the ipa host manpage. At its most basic, an add operation only requires the client host name to add the client to the Kerberos realm and to create an entry in the IdM LDAP server: 
$ ipa host-add client1.example.com
If the IdM server is configured to manage DNS, then the host can also be added to the DNS resource records using the --ip-address and --force options.

Example 12.1. Creating Host Entries with Static IP Addresses

$ ipa host-add --force --ip-address=192.168.166.31 client1.example.com
Commonly, hosts may not have a static IP address or the IP address may not be known at the time the client is configured. For example, laptops may be preconfigured as Identity Management clients, but they do not have IP addresses at the time they are configured. Hosts which use DHCP can still be configured with a DNS entry by using --force. This essentially creates a placeholder entry in the IdM DNS service. When the DNS service dynamically updates its records, the host's current IP address is detected and its DNS record is updated.

Example 12.2. Creating Host Entries with DHCP

$ ipa host-add --force client1.example.com
Host records are deleted using the host-del command. If the IdM domain uses DNS, then the --updatedns option also removes the associated records of any kind for the host from the DNS. 
$ ipa host-del --updatedns client1.example.com

12.4. Disabling and Re-enabling Host Entries

Active hosts can be accessed by other services, hosts, and users within the domain. There can be situations when it is necessary to remove a host from activity. However, deleting a host removes the entry and all the associated configuration, and it removes it permanently.

12.4.1. Disabling Host Entries

Disabling a host prevents domain users from access it without permanently removing it from the domain. This can be done by using the host-disable command.
For example: 
[jsmith@ipaserver ~]$ kinit admin
[jsmith@ipaserver ~]$ ipa host-disable server.example.com
Important
Disabling a host entry not only disables that host. It disables every configured service on that host as well.

12.4.2. Re-enabling Hosts

This section describes how to re-enable a disabled IdM host.
Disabling a host removes its active keytabs, which removed the host from the IdM domain without otherwise touching its configuration entry.
To re-enable a host, use the ipa-getkeytab command, adding:
  • the -s option to specify which IdM server to request the keytab from
  • the -p option to specify the principal name
  • the -k option to specify the file to which to save the keytab.
For example, to request a new host keytab from server.example.com for client.example.com, and store the keytab in the /etc/krb5.keytab file: 
$ ipa-getkeytab -s server.example.com -p host/client.example.com -k /etc/krb5.keytab -D "cn=directory manager" -w password
Note
You can also use the administrator’s credentials, specifying -D "uid=admin,cn=users,cn=accounts,dc=example,dc=com". It is important that the credentials correspond to a user allowed to create the keytab for the host.
If you run the ipa-getkeytab command on an active IdM client or server, then you can run it without any LDAP credentials (-D and -w) if the user has a TGT obtained using, for example, kinit admin. To run the command directly on the disabled host, supply LDAP credentials to authenticate to the IdM server.

12.5. Managing Public SSH Keys for Hosts

OpenSSH uses public keys to authenticate hosts. One machine attempts to access another machine and presents its key pair. The first time the host authenticates, the administrator on the target machine has to approve the request manually. The machine then stores the host's public key in a known_hosts file. Any time that the remote machine attempts to access the target machine again, the target machine simply checks its known_hosts file and then grants access automatically to approved hosts.
There are a few problems with this system:
  • The known_hosts file stores host entries in a triplet of the host IP address, host name, and key. This file can rapidly become out of date if the IP address changes (which is common in virtual environments and data centers) or if the key is updated.
  • SSH keys have to be distributed manually and separately to all machines in an environment.
  • Administrators have to approve host keys to add them to the configuration, but it is difficult to verify either the host or key issuer properly, which can create security problems.
On Red Hat Enterprise Linux, the System Security Services Daemon (SSSD) can be configured to cache and retrieve host SSH keys so that applications and services only have to look in one location for host keys. Because SSSD can use Identity Management as one of its identity information providers, Identity Management provides a universal and centralized repository of keys. Administrators do not need to worry about distributing, updating, or verifying host SSH keys.

12.5.1. About the SSH Key Format

When keys are uploaded to the IdM entry, the key format can be either an OpenSSH-style key or a raw RFC 4253-style blob. Any RFC 4253-style key is automatically converted into an OpenSSH-style key before it is imported and saved into the IdM LDAP server.
The IdM server can identify the type of key, such as an RSA or DSA key, from the uploaded key blob. However, in a key file such as ~/.ssh/known_hosts, a key entry is identified by the host name and IP address of the server, its type, then lastly the key itself. For example: 
host.example.com,1.2.3.4 ssh-rsa AAA...ZZZ==
This is slightly different than a user public key entry, which has the elements in the order type key== comment: 
"ssh-rsa ABCD1234...== ipaclient.example.com"
All three parts from the key file can be uploaded to and viewed for the host entry. In that case, the host public key entry from the ~/.ssh/known_hosts file needs to be reordered to match the format of a user key, type key== comment: 
ssh-rsa AAA...ZZZ== host.example.com,1.2.3.4
The key type can be determined automatically from the content of the public key, and the comment is optional, to make identifying individual keys easier. The only required element is the public key blob itself.

12.5.2. About ipa-client-install and OpenSSH

The ipa-client-install script, by default, configures an OpenSSH server and client on the IdM client machine. It also configures SSSD to perform host and user key caching. Essentially, simply configuring the client does all of the configuration necessary for the host to use SSSD, OpenSSH, and Identity Management for key caching and retrieval.
If the SSH service is enabled with the client installation (which is the default), then an RSA key is created when the ssh service is first started.
Note
When the machine is added as an IdM client using ipa-client-install, the client is created with two SSH keys, RSA and DSS.
There is an additional client configuration option, --ssh-trust-dns, which can be run with ipa-client-install and automatically configures OpenSSH to trust the IdM DNS records, where the key fingerprints are stored.
Alternatively, it is possible to disable OpenSSH at the time the client is installed, using the --no-sshd option. This prevents the install script from configuring the OpenSSH server.
Another option, --no-dns-sshfp, prevents the host from creating DNS SSHFP records with its own DNS entries. This can be used with or without the --no-sshd option.

12.5.3. Uploading Host SSH Keys Through the Web UI

  1. The key for a host can probably be retrieved from a ~/.ssh/known_hosts. For example: 
    server.example.com,1.2.3.4 ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEApvjBvSFSkTU0WQW4eOweeo0DZZ08F9Ud21xlLy6FOhzwpXFGIyxvXZ52+siHBHbbqGL5+14N7UvElruyslIHx9LYUR/pPKSMXCGyboLy5aTNl5OQ5EHwrhVnFDIKXkvp45945R7SKYCUtRumm0Iw6wq0XD4o+ILeVbV3wmcB1bXs36ZvC/M6riefn9PcJmh6vNCvIsbMY6S+FhkWUTTiOXJjUDYRLlwM273FfWhzHK+SSQXeBp/zIn1gFvJhSZMRi9HZpDoqxLbBB9QIdIw6U4MIjNmKsSI/ASpkFm2GuQ7ZK9KuMItY2AoCuIRmRAdF8iYNHBTXNfFurGogXwRDjQ==
    If necessary, generate a host key. When using the OpenSSH tools, make sure to use a blank passphrase and to save the key to a different location than the user's ~/.ssh/ directory, so it will not overwrite any existing keys. 
    [jsmith@server ~]$ ssh-keygen -t rsa -C "server.example.com,1.2.3.4"
Generating public/private rsa key pair.
Enter file in which to save the key (/home/jsmith/.ssh/id_rsa): /home/jsmith/.ssh/host_keys
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/jsmith/.ssh/host_keys.
Your public key has been saved in /home/jsmith/.ssh/host_keys.pub.
The key fingerprint is:
SHA256:GAUIDVVEgly7rs1lTWP6oguHz8BKvyZkpqCqVSsmi7c server.example.com
The key's randomart image is:
+--[ RSA 2048]----+
|              .. |
|               .+|
|          o   .* |
|         o . .. *|
|        S + .  o+|
|         E . .. .|
|        . = .  o |
|         o .  ..o|
|            .....|
+-----------------+
  2. Copy the public key from the key file. The full key entry has the form host name,IP type key==. Only the key== is required, but the entire entry can be stored. To use all elements in the entry, rearrange the entry so it has the order type key== [host name,IP] 
    [jsmith@server ~]$ cat /home/jsmith/.ssh/host_keys.pub

ssh-rsa AAAAB3NzaC1yc2E...tJG1PK2Mq++wQ== server.example.com,1.2.3.4
  3. Open the Identity tab, and select the Hosts subtab.
  4. Click the name of the host to edit.

    Figure 12.4. List of Hosts

    List of Hosts
  5. In the Host Settings area of the Settings tab, click Add next to SSH public keys.

    Figure 12.5. Adding an SSH Key

    Adding an SSH Key
  6. Paste in the public key for the host, and click Set.

    Figure 12.6. Setting an SSH Key

    Setting an SSH Key
    The SSH public keys area now shows the new key. Clicking Show/Set key opens the submitted key.
  7. To upload multiple keys, click the Add link below the list of public keys, and upload the other keys.
  8. When all the keys have been submitted, click Save at the top of the host's page to save the changes.
When the public key is saved, the entry is displayed as the key fingerprint, the comment (if one was included), and the key type[2].
After uploading the host keys, configure SSSD to use Identity Management as one of its identity domains and set up OpenSSH to use the SSSD tooling for managing host keys, covered in Section 22.6, “Configuring SSSD to Provide a Cache for the OpenSSH Services”.

12.5.4. Adding Host Keys from the Command Line

Host SSH keys are added to host entries in IdM, either when the host is created using host-add or by modifying the entry later.
Note
RSA and DSS host keys are created by the ipa-client-install command, unless the SSH service is explicitly disabled in the installation script.
  1. Run the host-mod command with the --sshpubkey option to upload the base64-encoded public key to the host entry.
    Adding a host key also changes the DNS SSHFP entry for the host, so also use the --updatedns option to update the host's DNS entry.
    For example: 
    [jsmith@server ~]$ ipa host-mod --sshpubkey="ssh-rsa RjlzYQo==" --updatedns host1.example.com
    A real key also usually ends with an equal sign (=) but is longer.
    To upload more than one key, enter multiple --sshpubkey command-line parameters: 
    --sshpubkey="RjlzYQo==" --sshpubkey="ZEt0TAo=="
    Note
    A host can have multiple public keys.
  2. After uploading the host keys, configure SSSD to use Identity Management as one of its identity domains and set up OpenSSH to use the SSSD tooling for managing host keys, covered in Section 22.6, “Configuring SSSD to Provide a Cache for the OpenSSH Services”.

12.5.5. Removing Host Keys

Host keys can be removed once they expire or are no longer valid.
To remove an individual host key, it is easiest to remove the key through the web UI:
  1. Open the Identity tab, and select the Hosts subtab.
  2. Click the name of the host to edit.

    Figure 12.7. List of Hosts

    List of Hosts
  3. In the SSH public keys area, click Delete by the fingerprint of the key to remove it.

    Figure 12.8. Public Key Deletion

    Public Key Deletion
  4. Click Save at the top of the host's page to save the changes.
The command-line tools can be used to remove all keys. This is done by running ipa host-mod with the --sshpubkey= set to a blank value; this removes all public keys for the host. Also, use the --updatedns option to update the host's DNS entry. For example: 
[jsmith@server ~]$ kinit admin
[jsmith@server ~]$ ipa host-mod --sshpubkey= --updatedns host1.example.com

[2] The key type is determined automatically from the key itself, if it is not included in the uploaded key.

12.6. Setting ethers Information for a Host

NIS can host an ethers table which can be used to manage DHCP configuration files for systems based on their platform, operating system, DNS domain, and MAC address — all information stored in host entries in IdM.
In Identity Management, each system is created with a corresponding ethers entry in the directory, in the ou=ethers subtree. 
cn=server,ou=ethers,dc=example,dc=com
This entry is used to create a NIS map for the ethers service which can be managed by the NIS compatibility plug-in in IdM.
To configure NIS maps for ethers entries:
  1. Add the MAC address attribute to a host entry. For example: 
    [jsmith@server ~]$ kinit admin
[jsmith@server ~]$ ipa host-mod --macaddress=12:34:56:78:9A:BC server.example.com
  2. Open the nsswitch.conf file.
  3. Add a line for the ethers service, and set it to use LDAP for its lookup. 
    ethers: ldap
  4. Check that the ethers information is available for the client. 
    [root@server ~]# getent ethers server.example.com

Chapter 13. Managing User and Host Groups

13.1. How User and Host Groups Work in IdM

13.1.1. What User and Host Groups Are

A user group is a set of users with common privileges, password policies, and other characteristics.
A host group is a set of IdM hosts with common access control rules and other characteristics.
For example, you can define groups around company departments, physical locations, or access control requirements.

13.1.2. Supported Group Members

A user group in IdM can include:
  • IdM users
  • other IdM user groups
  • external users, which are users that exist outside IdM
A host group in IdM can include:
  • IdM servers and clients
  • other IdM host groups

13.1.3. Direct and Indirect Group Members

User and host group attributes in IdM apply to both direct and indirect members: when group B is a member of group A, all users in group B are considered members of group A.
For example, in Figure 13.1, “Direct and Indirect Group Membership”:
  • User 1 and User 2 are direct members of group A.
  • User 3, User 4, and User 5 are indirect members of group A.

Figure 13.1. Direct and Indirect Group Membership

Direct and Indirect Group Membership
If you set a password policy for user group A, the policy applies to all users in user group B as well.

Example 13.1. Viewing Direct and Indirect Group Members

  1. Create two groups: group_A and group_B. See Section 13.2, “Adding and Removing User or Host Groups”.
  2. Add:
    • one user as a member of group_A
    • another user as a member of group_B
    • group_B as a member of group_A
    See Section 13.3, “Adding and Removing User or Host Group Members”.
  3. In the web UI: Select Identity → Groups. From the individual group types which are listed in a side bar on the left, select User Groups, and click the name of group_A. Switch between Direct Membership and Indirect Membership.

    Figure 13.2. Indirect and Direct Members

    Indirect and Direct Members
  4. From the command line: Use the ipa group-show command: 
    $ ipa group-show group_A
  ...
  Member users: user_1
  Member groups: group_B
  Indirect Member users: user_2
The list of indirect members does not include external users from trusted Active Directory domains. The Active Directory trust user objects are not visible in the IdM interface because they do not exist as LDAP objects within IdM.

13.1.4. User Group Types in IdM

POSIX groups (the default)
POSIX groups support POSIX attributes for their members. Note that groups that interact with Active Directory cannot use POSIX attributes.
Non-POSIX groups
All group members of this type of group must belong to the IdM domain.
External groups
External groups allow adding group members that exist in an identity store outside of the IdM domain. The external store can be a local system, an Active Directory domain, or a directory service.
Non-POSIX and external groups do not support POSIX attributes. For example, these groups do not have a GID defined.

Example 13.2. Searching for Different Types of User Groups

  1. Run the ipa group-find command to display all user groups.
  2. Run the ipa group-find --posix command to display all POSIX groups.
  3. Run the ipa group-find --nonposix command to display all non-POSIX groups.
  4. Run the ipa group-find --external command to display all external groups.

13.1.5. User and Host Groups Created by Default

Table 13.1. User and Host Groups Created by Default

Group Name User or Host Default Group Members
ipausers User group All IdM users
admins User group Users with administrative privileges, initially the default admin user
editors User group Users allowed to edit other IdM users in the web UI, without all the rights of an administrative user
trust admins User group Users with privileges to manage Active Directory trusts
ipaservers Host group All IdM server hosts
Adding a user to a user group applies the privileges and policies associated with the group. For example, adding a user to the admins group grants the user administrative privileges.
Warning
Do not delete the admins group. As admins is a pre-defined group required by IdM, this operation causes problems with certain commands.
Warning
Be careful when adding hosts to the ipaservers host group. All hosts in ipaservers have the ability to promote themselves to an IdM server.
In addition, IdM creates user private groups by default whenever a new user is created in IdM.
  • The user private group has the same name as the user for which it was created.
  • The user is the only member of the user private group.
  • GID of the private groups matches the UID of the user.

Example 13.3. Viewing User Private Groups

Run the ipa group-find --private command to display all user private groups: 
$ ipa group-find --private
----------------
2 groups matched
----------------
  Group name: user1
  Description: User private group for user1
  GID: 830400006

  Group name: user2
  Description: User private group for user2
  GID: 830400004
----------------------------
Number of entries returned 2
----------------------------
In some situations, it is better to avoid creating user private groups, such as when a NIS group or another system group already uses the GID that would be assigned to the user private group. See Section 13.4, “Disabling User Private Groups”.

13.2. Adding and Removing User or Host Groups

To add a group, you can use:
IdM enables specifying a custom GID when creating a user group. If you do this, be careful to avoid ID conflicts. See Section 14.6, “Ensuring That ID Values Are Unique”. If you do not specify a custom GID, IdM automatically assigns a GID from the available ID range.
To remove a group, you can use:
Note that removing a group does not delete the group members from IdM.

Web UI: Adding a User or Host Group

  1. Click Identity → Groups, and select User Groups or Host Groups in the left sidebar.
  2. Click Add to start adding the group.
  3. Fill out the information about the group.
    For details on user group types, see Section 13.1.4, “User Group Types in IdM”.
  4. Click Add to confirm.

Command Line: Adding a User or Host Group

  1. Log in as the administrator: 
    $ kinit admin
  2. To add a user group, use the ipa group-add command. To add a host group, use the ipa hostgroup-add command. 
    $ ipa group-add group_name
-----------------------
Added group "group_name"
------------------------
By default, ipa group-add adds a POSIX user group. To specify a different group type, add options to ipa group-add:
  • --nonposix to create a non-POSIX group
  • --external to create an external group
For details on group types, see Section 13.1.4, “User Group Types in IdM”.

Web UI: Removing a User or Host Group

  1. Click Identity → Groups and select User Groups or Host Groups in the left sidebar.
  2. Select the group to remove, and click Delete.

Command Line: Removing a User or Host Group

  1. Log in as the administrator: 
    $ kinit admin
  2. To delete a user group, use the ipa group-del group_name command. To delete a host group, use the ipa hostgroup-del group_name command. 
    $ ipa group-del group_name
--------------------------
Deleted group "group_name"
--------------------------

13.3. Adding and Removing User or Host Group Members

To add members to user groups, you can use:
Important
When adding another user group as a member, do not create recursive groups. For example, if Group A is a member of Group B, do not add Group B as a member of Group A. Recursive groups can cause unpredictable behavior.
To remove members from user groups, you can use:
Note
After you add a member to a user or host group, the update may take some time to spread to all clients in your Identity Management environment. This is because when any given host resolves users, groups or netgroups, the System Security Services Daemon (SSSD) first looks into its cache and performs server lookups only for missing or expired records.
To see the changes applied to the host group immediately, update the SSSD cache on your host by using the cache purge utility, sss_cache. Using sss_cache to invalidate the current records in the SSSD cache for a host group forces the SSSD cache to retrieve the updated records from the identity provider, so changes can be realized quickly.
To clear a host group entry in the SSSD cache: 
# sss_cache -n host_group_name

Web UI: Adding a Member to a User or Host Group

  1. Click Identity → Groups and select User Groups or Host Groups in the left sidebar.
  2. Click the name of the group.
  3. Select the type of group member you want to add. For example, Users, User Groups, or External for user groups.

    Figure 13.3. Adding User Group Members

    Adding User Group Members
  4. Click Add.
  5. Select the member you want to add, and click Add to confirm.

Command Line: Adding a Member to a User Group

  1. Optional. Use the ipa group-find or ipa hostgroup-find command to find the group.
  2. To add a member to a user group, use the ipa group-add-member command. To add a member to a host group, use the ipa hostgroup-add-member command.
    When adding a user group member, specify the member using these options:
    • --users adds an IdM user
    • --external adds a user that exists outside the IdM domain, in the format of DOMAIN\user_name or user_name@domain
    • --groups adds an IdM user group
    When adding a host group member, specify the member using these options:
    • --hosts adds an IdM host
    • --groups adds an IdM host group

    Example 13.4. Example commands for adding a member to a user group

    To add user1, user2, and group1 to a group named group_name: 
    $ ipa group-add-member group_name --users=user1 --users=user2 --groups=group1
    To add ad_user from a domain named ad_domain to a group named group_name, you can choose how to specify the external user. For example: 
    $ ipa group-add-member group_name --external='AD_DOMAIN\ad_user'
$ ipa group-add-member group_name --external='ad_user@AD_DOMAIN'
$ ipa group-add-member group_name --external='ad_user@AD_DOMAIN.EXAMPLE.COM'

Web UI: Removing a Member from a User Group

  1. Click Identity → Groups and select User Groups or Host Groups in the left sidebar.
  2. Click the name of the group.
  3. Select the type of group member you want to remove. For example, Users, User Groups, or External for user groups.

    Figure 13.4. Removing User Group Members

    Removing User Group Members
  4. Select the check box next to the required member.
  5. Click Delete.

Command Line: Removing a Member from a User Group

  1. Optional. Use the ipa group-show or ipa hostgroup-show command to confirm that the group includes the member you want to remove.
  2. To remove a user group member, use the ipa group-remove-member command. To remove a host group member, use the ipa hostgroup-remove-member command.
    When removing a user group member, specify the member using these options:
    • --users removes an IdM user
    • --external removes a user that exists outside the IdM domain, in the format of DOMAIN\user_name or user_name@domain
    • --groups removes an IdM user group
    When removing a host group member, specify the member using these options:
    • --hosts removes an IdM host
    • --groups removes an IdM host group
    For example, to remove user1, user2, and group1 from a group called group_name: 
    $ ipa group-remove-member group_name --users=user1 --users=user2 --groups=group1

13.4. Disabling User Private Groups

To ensure that IdM does not create a default user private group for a new user, choose one of the following:
Even after you disable creating default user private groups, IdM will still require a GID when adding new users. To ensure that adding the user succeeds, see Section 13.4.3, “Adding a User with User Private Groups Disabled”.
Note
If you want to disable creating default user private groups because of GID conflicts, consider changing the default UID and GID assignment ranges. See Chapter 14, Unique UID and GID Number Assignments.

13.4.1. Creating a User without a User Private Group

Add the --noprivate option to the ipa user-add command. Note that for the command to succeed, you must specify a custom private group. See Section 13.4.3, “Adding a User with User Private Groups Disabled”.

13.4.2. Disabling User Private Groups Globally for All Users

  1. Log in as the administrator: 
    $ kinit admin
  2. IdM uses the Directory Server Managed Entries Plug-in to manage user private groups. List the instances of the plug-in: 
    $ ipa-managed-entries --list
  3. To ensure IdM does not create user private groups, disable the plug-in instance responsible for managing user private groups: 
    $ ipa-managed-entries -e "UPG Definition" disable
Disabling Plugin
    Note
    To re-enable the UPG Definition instance later, use the ipa-managed-entries -e "UPG Definition" enable command.
  4. Restart Directory Server to load the new configuration. 
    # systemctl restart dirsrv.target

13.4.3. Adding a User with User Private Groups Disabled

To make sure adding a new user succeeds when creating default user private groups is disabled, choose one of the following:

13.5. Setting Search Attributes for Users and User Groups

When searching entries for a specified keyword using the ipa user-find keyword and ipa group-find keyword commands, IdM only searches certain attributes. Most notably:
  • In user searches: first name, last name, user name (login ID), job title, organization unit, phone number, UID, email address.
  • In group searches: group name, description.
The following procedure shows how to configure IdM to search other attributes as well. Note that IdM always searches the default attributes. For example, even if you remove the job title attribute from the list of user search attributes, IdM will still search user titles.

Prerequisites

Before adding a new attribute, make sure that a corresponding index exists within the LDAP directory for this attribute. Most standard LDAP attributes have indexes in LDAP, but if you want to add a custom attribute, you must create an index manually. See Creating Standard Indexes in the Red Hat Directory Server 10 Administration Guide.

Web UI: Setting Search Attributes

  1. Select IPA Server → Configuration.
  2. In the User Options area, set the user search attributes in User search fields.
  3. In the Group Options area, set the group search attributes in Group search fields.
  4. Click Save at the top of the page.

Command Line: Setting Search Attributes

Use the ipa config-mod command with these options:
  • --usersearch defines a new list of search attributes for users
  • --groupsearch defines a new list of search attributes for groups
For example: 
$ ipa config-mod --usersearch="uid,givenname,sn,telephonenumber,ou,title"
$ ipa config-mod --groupsearch="cn,description"

13.6. Defining Automatic Group Membership for Users and Hosts

13.6.1. How Automatic Group Membership Works in IdM

13.6.1.1. What Automatic Group Membership Is

Using automatic group membership, you can assign users and hosts to groups automatically based on their attributes. For example, you can:
  • Divide employees' user entries into groups based on the employees' manager, location, or any other attribute.
  • Divide hosts based on their class, location, or any other attribute.
  • Add all users or all hosts to a single global group.

13.6.1.2. Benefits of Automatic Group Membership

Reduced overhead of managing group membership manually
With automatic group membership, the administrator no longer assigns users and hosts to groups manually.
Improved consistency in user and host management
With automatic group membership, users and hosts are assigned to groups based on strictly defined and automatically evaluated criteria.
Easier management of group-based settings
Various settings are defined for groups and then applied to individual group members, for example sudo rules, automount, or access control. When using automatic group membership, users and hosts are automatically added to specified groups, which makes managing group-based settings easier.

13.6.1.3. Automember Rules

When configuring automatic group membership, the administrator defines automember rules. An automember rule applies to a specific user or host group. It includes conditions that the user or host must meet to be included or excluded from the group:
Inclusive conditions
When a user or host entry meets an inclusive condition, it will be included in the group.
Exclusive conditions
When a user or host entry meets an exclusive condition, it will not be included in the group.
The conditions are specified as regular expressions in the Perl-compatible regular expressions (PCRE) format. For more information on PCRE, see the pcresyntax(3) man page.
IdM evaluates exclusive conditions before inclusive conditions. In case of a conflict, exclusive conditions take precedence over inclusive conditions.

13.6.2. Adding an Automember Rule

To add an automember rule using:
After you add an automember rule:

Web UI: Add an Automember Rule

  1. Select Identity → Automember → User group rules or Host group rules.
  2. Click Add.
  3. In the Automember rule field, select the group to which the rule will apply. Click Add and Edit.
  4. Define one or more inclusive and exclusive conditions. See Section 13.6.1.3, “Automember Rules” for details.
    1. In the Inclusive or Exclusive sections, click Add.
    2. In the Attribute field, select the required attribute.
    3. In the Expression field, define the regular expression.
    4. Click Add.
    For example, the following condition targets all users with any value (.*) in their user login attribute (uid).

    Figure 13.5. Adding Automember Rule Conditions

    Adding Automember Rule Conditions

Command Line: Add an Automember Rule

  1. Use the ipa automember-add command to add an automember rule. When prompted, specify:
    • Automember rule, which matches the target group name.
    • Grouping Type, which specifies whether the rule targets a user group or a host group. To target a user group, enter group. To target a host group, enter hostgroup.
    For example, to add an automember rule for a user group named user_group: 
    $ ipa automember-add
Automember Rule: user_group
Grouping Type: group
--------------------------------
Added automember rule "user_group"
--------------------------------
  Automember Rule: user_group
  2. Define one or more inclusive and exclusive conditions. See Section 13.6.1.3, “Automember Rules” for details.
    1. To add a condition, use the ipa automember-add-condition command. When prompted, specify:
      • Automember rule, which matches the target group name.
      • Attribute Key, which specifies the entry attribute to which the filter will apply. For example, manager for users.
      • Grouping Type, which specifies whether the rule targets a user group or a host group. To target a user group, enter group. To target a host group, enter hostgroup.
      • Inclusive regex and Exclusive regex, which specify one or more conditions as regular expressions. If you only want to specify one condition, press Enter when prompted for the other.
      For example, the following condition targets all users with any value (.*) in their user login attribute (uid). 
      $ ipa automember-add-condition
Automember Rule: user_group
Attribute Key: uid
Grouping Type: group
[Inclusive Regex]: .*
[Exclusive Regex]:
----------------------------------
Added condition(s) to "user_group"
----------------------------------
  Automember Rule: user_group
  Inclusive Regex: uid=.*
----------------------------
Number of conditions added 1
----------------------------
    2. To remove a condition, use the ipa automember-remove-condition command.

Example 13.5. Command Line: Creating an Automember Rule to Add All Entries to a Single Group

By creating an inclusive condition for an attribute that all user or host entries contain, such as cn or fqdn, you can ensure that all users or hosts created in the future will be added to a single group.
  1. Create the group, such as a host group named all_hosts. See Section 13.2, “Adding and Removing User or Host Groups”.
  2. Add an automember rule for the new host group. For example: 
    $ ipa automember-add
Automember Rule: all_hosts
Grouping Type: hostgroup
-------------------------------------
Added automember rule "all_hosts"
-------------------------------------
  Automember Rule: all_hosts
  3. Add an inclusive condition that targets all hosts. In the following example, the inclusive condition targets hosts that have any value (.*) in the fqdn attribute: 
    $ ipa automember-add-condition
Automember Rule: all_hosts
Attribute Key: fqdn
Grouping Type: hostgroup
[Inclusive Regex]: .*
[Exclusive Regex]:
---------------------------------
Added condition(s) to "all_hosts"
---------------------------------
  Automember Rule: all_hosts
  Inclusive Regex: fqdn=.*
----------------------------
Number of conditions added 1
----------------------------
All hosts added in the future will automatically become members of the all_hosts group.

Example 13.6. Command Line: Creating an Automember Rule for Synchronized AD Users

Windows users synchronized from Active Directory (AD) share the ntUser object class. By creating an automember condition that targets all users with ntUser in their objectclass attribute, you can ensure that all synchronized AD users created in the future will be included in a common group for AD users.
  1. Create a user group for the AD users, such as ad_users. See Section 13.2, “Adding and Removing User or Host Groups”.
  2. Add an automember rule for the new user group. For example: 
    $ ipa automember-add
Automember Rule: ad_users
Grouping Type: group
-------------------------------------
Added automember rule "ad_users"
-------------------------------------
  Automember Rule: ad_users
  3. Add an inclusive condition to filter the AD users. In the following example, the inclusive condition targets all users that have the ntUser value in the objectclass attribute: 
    $ ipa automember-add-condition
Automember Rule: ad_users
Attribute Key: objectclass
Grouping Type: group
[Inclusive Regex]: ntUser
[Exclusive Regex]:
-------------------------------------
Added condition(s) to "ad_users"
-------------------------------------
  Automember Rule: ad_users
  Inclusive Regex: objectclass=ntUser
----------------------------
Number of conditions added 1
----------------------------
All AD users added in the future will automatically become members of the ad_users user group.

13.6.3. Applying Automember Rules to Existing Users and Hosts

Automember rules apply automatically to user and hosts entries created after the rules were added. They are not applied retrospectively to entries that existed before the rules were added.
To apply automember rules to entries that existed before you added the rules, manually rebuild automatic membership. Rebuilding automatic membership re-evaluates all existing automember rules and applies them either to all entries or to specific entries.

Web UI: Rebuild Automatic Membership for Existing Entries

To rebuild automatic membership for all users or all hosts:
  1. Select Identity → Users or Hosts.
  2. Click Actions → Rebuild auto membership.

    Figure 13.6. Rebuilding Automatic Membership for All Users or Hosts

    Rebuilding Automatic Membership for All Users or Hosts
To rebuild automatic membership for a single user or host only:
  1. Select Identity → Users or Hosts, and click on the required user login or host name.
  2. Click Actions → Rebuild auto membership.

    Figure 13.7. Rebuilding Automatic Membership for a Single User or Host

    Rebuilding Automatic Membership for a Single User or Host

Command Line: Rebuild Automatic Memberhips for Existing Entries

To rebuild automatic membership for all users, use the ipa automember-rebuild --type=group command: 
$ ipa automember-rebuild --type=group
--------------------------------------------------------
Automember rebuild task finished. Processed (9) entries.
--------------------------------------------------------
To rebuild automatic membership for all users, use the ipa automember-rebuild --type=hostgroup command.
To rebuild automatic membership for a specified user or users, use the ipa automember-rebuild --users=user command: 
$ ipa automember-rebuild --users=user1 --users=user2
--------------------------------------------------------
Automember rebuild task finished. Processed (2) entries.
--------------------------------------------------------
To rebuild automatic membership for a specified host or hosts, use the ipa automember-rebuild --hosts=example.com command.

13.6.4. Configuring a Default Automember Group

When a default automember group is configured, user or host entries that do not match any automember rule are automatically added to the default group.
  1. Use the ipa automember-default-group-set command to configure a default automember group. When prompted, specify:
    • Default (fallback) Group, which specifies the target group name.
    • Grouping Type, which specifies whether the target is a user group or a host group. To target a user group, enter group. To target a host group, enter hostgroup.
    For example: 
    $ ipa automember-default-group-set
Default (fallback) Group: default_user_group
Grouping Type: group
---------------------------------------------------
Set default (fallback) group for automember "default_user_group"
---------------------------------------------------
  Default (fallback) Group: cn=default_user_group,cn=groups,cn=accounts,dc=example,dc=com
  2. To verify that the group is set correctly, use the ipa automember-default-group-show command. The command displays the current default automember group. For example: 
    $ ipa automember-default-group-show
Grouping Type: group
  Default (fallback) Group: cn=default_user_group,cn=groups,cn=accounts,dc=example,dc=com
To remove the current default automember group, use the ipa automember-default-group-remove command.

Chapter 14. Unique UID and GID Number Assignments

An IdM server generates user ID (UID) and group ID (GID) values and simultaneously ensures that replicas never generate the same IDs. The need for unique UIDs and GIDs might even be across IdM domains, if a single organization uses multiple separate domains.

14.1. ID Ranges

The UID and GID numbers are divided into ID ranges. By keeping separate numeric ranges for individual servers and replicas, the chances are minimal that an ID value issued for an entry is already used by another entry on another server or replica.
The Distributed Numeric Assignment (DNA) plug-in, as part of the back end 389 Directory Server instance for the domain, ensures that ranges are updated and shared between servers and replicas; the plug-in manages the ID ranges across all masters and replicas. Every server or replica has a current ID range and an additional next ID range that the server or replica uses after the current range has been depleted. For more information about the DNA Directory Server plug-in, see the Red Hat Directory Server Deployment Guide.

14.2. ID Range Assignments During Installation

During server installation, the ipa-server-install command by default automatically assigns a random current ID range to the installed server. The setup script randomly selects a range of 200,000 IDs from a total of 10,000 possible ranges. Selecting a random range in this way significantly reduces the probability of conflicting IDs in case you decide to merge two separate IdM domains in the future.
However, you can define a current ID range manually during server installation by using the following two options with ipa-server-install:
  • --idstart gives the starting value for UID and GID numbers; by default, the value is selected at random,
  • --idmax gives the maximum UID and GID number; by default, the value is the --idstart starting value plus 199,999.
If you have a single IdM server installed, a new user or group entry receives a random ID from the whole range. When you install a new replica and the replica requests its own ID range, the initial ID range for the server splits and is distributed between the server and replica: the replica receives half of the remaining ID range that is available on the initial master. The server and replica then use their respective portions of the original ID range for new entries. Also, if less than 100 IDs from the ID range that was assigned to a replica remain, meaning the replica is close to depleting its allocated ID range, the replica contacts the other available servers with a request for a new ID range.
A server receives an ID range the first time the DNA plug-in is used; until then, the server has no ID range defined. For example, when you create a replica from a master server, the replica does not receive an ID range immediately. The replica requests an ID range from the initial master only when the first ID is about to be assigned on the replica.
Note
If the initial master stops functioning before the replica requests an ID range from it, the replica is unable to contact the master with a request for the ID range. An attempt to add a new user on the replica fails. In such situations, you can find out what ID range is assigned to the disabled master and assign an ID range to the replica manually, which is described in Section 14.5, “Manual ID Range Extension and Assigning a New ID Range”.

14.3. Displaying Currently Assigned ID Ranges

To display which ID ranges are configured for a server, use the following commands:
  • ipa-replica-manage dnarange-show displays the current ID range that is set on all servers or, if you specify a server, only on the specified server, for example: 
    # ipa-replica-manage dnarange-show
masterA.example.com: 1001-1500
masterB.example.com: 1501-2000
masterC.example.com: No range set

# ipa-replica-manage dnarange-show masterA.example.com
masterA.example.com: 1001-1500
  • ipa-replica-manage dnanextrange-show displays the next ID range currently set on all servers or, if you specify a server, only on the specified server, for example: 
    # ipa-replica-manage dnanextrange-show
masterA.example.com: 1001-1500
masterB.example.com: No on-deck range set
masterC.example.com: No on-deck range set

# ipa-replica-manage dnanextrange-show masterA.example.com
 masterA.example.com: 1001-1500
For more information about these two commands, see the ipa-replica-manage(1) man page.

14.4. Automatic ID Range Extension After Deleting a Replica

When you delete a functioning replica, the ipa-replica-manage del command retrieves the ID ranges that were assigned to the replica and adds them as a next range to other available IdM replicas. This ensures that ID ranges remain available to be used by other replicas.
After you delete a replica, you can verify which ID ranges are configured for other servers by using the ipa-replica-manage dnarange-show and ipa-replica-manage dnanextrange-show commands, described in Section 14.3, “Displaying Currently Assigned ID Ranges”.

14.5. Manual ID Range Extension and Assigning a New ID Range

In certain situations, it is necessary to manually adjust an ID range:
An assigned ID range has been depleted
A replica has exhausted the ID range that was assigned to it, and requesting additional IDs failed because no more free IDs are available in the ID ranges of other replicas. You want to extend the ID range assigned to the replica. This might involve splitting an existing ID range or extending it past the initial configured ID range for the server. Alternatively, you might want to assign a new ID range.
Note
If you assign a new ID range, the UIDs of the already existing entries on the server or replica stay the same. This does not pose a problem because even if you change the current ID range, IdM keeps a record of what ranges were assigned in the past.
A replica stopped functioning
ID range is not automatically retrieved when a replica dies and needs to be deleted, which means the ID range previously assigned to the replica becomes unavailable. You want to recover the ID range and make it available for other replicas.
If you want to recover the ID range belonging to a server that stopped functioning and assign it to another server, first find out what are the ID range values using the ipa-replica-manage dnarange-show command described in Section 14.3, “Displaying Currently Assigned ID Ranges”, and then manually assign that ID range to the server. Also, to avoid duplicate UIDs or GIDs, make sure that no ID value from the recovered range was previously assigned to a user or group; you can do this by examining the UIDs and GIDs of existent users and groups.
To manually define the ID ranges, use the following two commands:
  • ipa-replica-manage dnarange-set allows you to define the current ID range for a specified server: 
    # ipa-replica-manage dnarange-set masterA.example.com 1250-1499
  • ipa-replica-manage dnanextrange-set allows you to define the next ID range for a specified server: 
    # ipa-replica-manage dnanextrange-set masterB.example.com 1001-5000
For more information about these commands, see the ipa-replica-manage(1) man page.
Important
Be careful not to create overlapping ID ranges. If any of the ID ranges you assign to servers or replicas overlap, it could result in two different servers assigning the same ID value to different entries.
Do not set ID ranges that include UID values of 1000 and lower; these values are reserved for system use. Also, do not set an ID range that would include the 0 value; the SSSD service does not handle the 0 ID value.
When extending an ID range manually, make sure that the newly extended range is included in the IdM ID range; you can check this using the ipa idrange-find command. Run the ipa idrange-find -h command to display help for how to use ipa idrange-find.

14.6. Ensuring That ID Values Are Unique

It is recommended to avoid conflicting UIDs or GIDs. UIDs and GIDs should always be unique: two users should not have the same UID, and two groups should not have the same GID.
Automatic ID assignment
When a user or a group is created interactively or without a manually specified ID number, the server assigns the next available ID number from the ID range to the user account. This ensures that the UID or GID is always unique.
Manual ID assignment
When you assign an ID to a user or a group entry manually, the server does not verify that the specified UID or GID is unique; it does not warn you of a conflict if you choose a value that is already used by another entry.
As explained in Section 14.7, “Repairing Changed UID and GID Numbers”, the SSSD service does not handle entries with identical IDs. If two entries share the same ID number, a search for this ID only returns the first entry. However, if you search for other attributes or run the ipa user-find --all command, both entries are returned.
UIDs and GIDs are both selected from the same ID range. A user and a group can have the same ID; no conflict arises in this situation because the UID and the GID are set in two different attributes: uidNumber and gidNumber.
Note
Setting the same ID for both a user and a group allows you to configure user private groups. To create a unique system group for a user in this way, set the same ID value for a user and also for a group, in which the only member is the mentioned user.

14.7. Repairing Changed UID and GID Numbers

When a user logs into an IdM system or service, SSSD on that system caches their user name together with the UID and GID of the user. SSSD then uses the UID as the identifying key for the user. If a user with the same user name but a different UID attempts to log into the system, SSSD registers two different UIDs and assumes that there are two different users with conflicting user names. This can pose a problem if a UID of a user changes. In such a situation, SSSD incorrectly interprets the user with a modified UID as a new user, instead of recognizing that it as the same user with a different UID. If the UID of an existing user changes, the user cannot log into SSSD and associated services and domains. This also affects client applications that use SSSD for identity information.
To work around this problem, if a UID or GID changes, clear the SSSD cache, which ensures that the user is able to log in again. For example, to clear the SSSD cache for a specified user, use the sss_cache utility as follows: 
[root@server ~]# sss_cache -u user

Chapter 15. User and Group Schema

When a user entry is created, it is automatically assigned certain LDAP object classes which, in turn, make available certain attributes. LDAP attributes are the way that information is stored in the directory. (This is discussed in detail in the Directory Server Deployment Guide and the Directory Server Schema Reference.)

Table 15.1. Default Identity Management User Object Classes

Object Classes Description
ipaobject
ipasshuser
IdM object classes
person
organizationalperson
inetorgperson
inetuser
posixAccount
Person object classes
krbprincipalaux
krbticketpolicyaux
Kerberos object classes
mepOriginEntry Managed entries (template) object classes
A number of attributes are available to user entries. Some are set manually and some are set based on defaults if a specific value is not set. There is also an option to add any attributes available in the object classes in Table 15.1, “Default Identity Management User Object Classes”, even if there is not a UI or command-line argument for that attribute. Additionally, the values generated or used by the default attributes can be configured, as in Section 15.4, “Specifying Default User and Group Attributes”.

Table 15.2. Default Identity Management User Attributes

UI Field Command-Line Option Required, Optional, or Default[a]
User login username Required
First name --first Required
Last name --last Required
Full name --cn Optional
Display name --displayname Optional
Initials --initials Default
Home directory --homedir Default
GECOS field --gecos Default
Shell --shell Default
Kerberos principal --principal Default
Email address --email Optional
Password --password [b] Optional
User ID number --uid Default
Group ID number --gidnumber Default
Street address --street Optional
City --city Optional
State/Province --state Optional
Zip code --postalcode Optional
Telephone number --phone Optional
Mobile telephone number --mobile Optional
Pager number --pager Optional
Fax number --fax Optional
Organizational unit --orgunit Optional
Job title --title Optional
Manager --manager Optional
Car license --carlicense Optional
--noprivate Optional
SSH Keys --sshpubkey Optional
Additional attributes --addattr Optional
Department Number --departmentnumber Optional
Employee Number --employeenumber Optional
Employee Type --employeetype Optional
Preferred Language --preferredlanguage Optional
[a] Required attributes must be set for every entry. Optional attributes may be set, while default attributes are automatically added with a predefined value unless a specific value is given.
[b] The script prompts for the new password, rather than accepting a value with the argument.

15.1. About Changing the Default User and Group Schema

It is possible to add or change the object classes and attributes used for user and group entries (Chapter 15, User and Group Schema).
The IdM configuration provides some validation when object classes are changed:
  • All of the object classes and their specified attributes must be known to the LDAP server.
  • All default attributes that are configured for the entry must be supported by the configured object classes.
There are limits to the IdM schema validation, however. Most important, the IdM server does not check that the defined user or group object classes contain all of the required object classes for IdM entries. For example, all IdM entries require the ipaobject object class. However, when the user or group schema is changed, the server does not check to make sure that this object class is included; if the object class is accidentally deleted, then future entry add operations will fail.
Also, all object class changes are atomic, not incremental. The entire list of default object classes has to be defined every time there is a change. For example, a company may create a custom object class to store employee information like birthdays and employment start dates. The administrator cannot simply add the custom object class to the list; he must set the entire list of current default object classes plus the new object class. The existing default object classes must always be included when the configuration is updated. Otherwise, the current settings will be overwritten, which causes serious performance problems.

15.2. Applying Custom Object Classes to New User Entries

User and group accounts are created with a predefined set of LDAP object classes applied to the entry. Any attributes which belong to the object class can be added to the user entry.
While the standard and IdM-specific LDAP object classes will cover most deployment scenarios, administrators can create custom object classes with custom attributes. Note that after an administrator modifies the list of default object classes, new entries will contain the custom object classes but the old entries are not automatically modified.

15.2.1. From the Web UI

  1. Add all of the custom schema elements to the 389 Directory Server instance used by Identity Management. Adding schema elements is described in the schema chapter of the Directory Server Administrator's Guide.
  2. Open the IPA Server tab.
  3. Select the Configuration subtab.
  4. Scroll to the User Options area.

    Figure 15.1. User Options in Server Configuration

    User Options in Server Configuration
  5. At the bottom of the users area, click Add to include a new field for another object class.
    Important
    Always include the existing default object classes when the configuration is updated. Otherwise, the current settings will be overwritten. If any object classes required by Identity Management are not included, then subsequent attempts to add an entry will fail with object class violations.

    Figure 15.2. Changing Default User Object Classes

    Changing Default User Object Classes
  6. When the changes are complete, click Save at the top of the Configuration page.

15.2.2. From the Command Line

  1. Add all of the custom schema elements to the 389 Directory Server instance used by Identity Management. Adding schema elements is described in the schema chapter of the Directory Server Administrator's Guide.
  2. Add the new object class to the list of object classes added to entries. The option for user object classes is --userobjectclasses.
    Important
    Always include the existing default object classes when the configuration is updated. Otherwise, the current settings will be overwritten. If any object classes required by Identity Management are not included, then subsequent attempts to add an entry will fail with object class violations.
    All object classes must be included in the list of object classes. The information passed with the config-mod command overwrites the previous values. This can be done by specifying each object class with a --userobjectclasses argument or by listing all of the object classes in a comma-separated list inside curly braces with no spaces allowed, such as {attr1,attr2,attr3}. Especially for long lists, it can be easier to use the curly braces than multiple options. For example: 
    [bjensen@server ~]$ ipa config-mod --userobjectclasses={top,person,organizationalperson,inetorgperson,inetuser,posixaccount,krbprincipalaux,krbticketpolicyaux,ipaobject,ipasshuser,employeeinfo}
Note
To use the curly braces option, the brace expansion feature must be switched on. To activate the feature, use the set command: 
# set -o braceexpand

15.3. Applying Custom Object Classes to New Group Entries

As with user entries, administrators may create custom object classes with custom attributes. These can be added automatically by adding the object classes to the IdM server configuration. Note that after an administrator modifies the list of default object classes, new entries will contain the custom object classes but the old entries are not automatically modified.

15.3.1. From the Web UI

  1. Add all of the custom schema elements to the 389 Directory Server instance used by Identity Management. Adding schema elements is described in the schema chapter of the Directory Server Administrator's Guide.
  2. Open the IPA Server tab.
  3. Select the Configuration subtab.
  4. Scroll to the Group Options area.

    Figure 15.3. Group Options in Server Configuration

    Group Options in Server Configuration
  5. Click Add to include a new field for another object class.
    Important
    Always include the existing default object classes when the configuration is updated. Otherwise, the current settings will be overwritten. If any object classes required by Identity Management are not included, then subsequent attempts to add an entry will fail with object class violations.
  6. When the changes are complete, click Save at the top of the Configuration page.

15.3.2. From the Command Line

  1. Add all of the custom schema elements to the 389 Directory Server instance used by Identity Management. Adding schema elements is described in the schema chapter of the Directory Server Administrator's Guide.
  2. Add the new object class to the list of object classes added to entries. The option for group object classes is --groupobjectclasses.
    Important
    Always include the existing default object classes when the configuration is updated. Otherwise, the current settings will be overwritten. If any object classes required by Identity Management are not included, then subsequent attempts to add an entry will fail with object class violations.
    All object classes must be included in the list of object classes. The information passed with the config-mod command overwrites the previous values. This can be done by specifying each object class with a --groupobjectclasses argument or by listing all of the object classes in a comma-separated list inside curly braces with no spaces allowed, such as {attr1,attr2,attr3}. Especially for long lists, it can be easier to use the curly braces than multiple options. For example: 
    [bjensen@server ~]$ ipa config-mod --groupobjectclasses={top,groupofnames,nestedgroup,ipausergroup,ipaobject,ipasshuser,employeegroup}

15.4. Specifying Default User and Group Attributes

Identity Management uses a template when it creates new entries.
For users, the template is very specific. Identity Management uses default values for several core attributes for IdM user accounts. These defaults can define actual values for user account attributes (such as the home directory location) or it can define the format of attribute values, such as the user name length. These settings also define the object classes assigned to users.
For groups, the template only defines the assigned object classes.
These default definitions are all contained in a single configuration entry for the IdM server, cn=ipaconfig,cn=etc,dc=example,dc=com.
The configuration can be changed using the ipa config-mod command.

Table 15.3. Default User Parameters

Field Command-Line Option Descriptions
Maximum user name length --maxusername Sets the maximum number of characters for user names. The default value is 32.
Root for home directories --homedirectory Sets the default directory to use for user home directories. The default value is /home.
Default shell --defaultshell Sets the default shell to use for users. The default value is /bin/sh.
Default user group --defaultgroup Sets the default group to which all newly created accounts are added. The default value is ipausers, which is automatically created during the IdM server installation process.
Default e-mail domain --emaildomain Sets the email domain to use to create email addresses based on the new accounts. The default is the IdM server domain.
Search time limit --searchtimelimit Sets the maximum amount of time, in seconds, to spend on a search before the server returns results.
Search size limit --searchrecordslimit Sets the maximum number of records to return in a search.
User search fields --usersearch Sets the fields in a user entry that can be used as a search string. Any attribute listed has an index kept for that attribute, so setting too many attributes could affect server performance.
Group search fields --groupsearch Sets the fields in a group entry that can be used as a search string.
Certificate subject base Sets the base DN to use when creating subject DNs for client certificates. This is configured when the server is set up.
Default user object classes --userobjectclasses Defines an object class that is used to create IdM user accounts. This can be invoked multiple times. The complete list of object classes must be given because the list is overwritten when the command is run.
Default group object classes --groupobjectclasses Defines an object class that is used to create IdM group accounts. This can be invoked multiple times. The complete list of object classes must be given because the list is overwritten when the command is run.
Password expiration notification --pwdexpnotify Sets how long, in days, before a password expires for the server to send a notification.
Password plug-in features Sets the format of passwords that are allowed for users.

15.4.1. Viewing Attributes from the Web UI

  1. Open the IPA Server tab.
  2. Select the Configuration subtab.
  3. The complete configuration entry is shown in three sections, one for all search limits, one for user templates, and one for group templates.

    Figure 15.4. Setting Search Limits

    Setting Search Limits

    Figure 15.5. User Attributes

    User Attributes

    Figure 15.6. Group Attributes

    Group Attributes

15.4.2. Viewing Attributes from the Command Line

The config-show command shows the current configuration which applies to all new user accounts. By default, only the most common attributes are displayed; use the --all option to show the complete configuration. 
[bjensen@server ~]$ kinit admin
[bjensen@server ~]$ ipa config-show --all
dn: cn=ipaConfig,cn=etc,dc=example,dc=com
Maximum username length: 32
Home directory base: /home
Default shell: /bin/sh
Default users group: ipausers
Default e-mail domain: example.com
Search time limit: 2
Search size limit: 100
User search fields: uid,givenname,sn,telephonenumber,ou,title
Group search fields: cn,description
Enable migration mode: FALSE
Certificate Subject base: O=EXAMPLE.COM
Default group objectclasses: top, groupofnames, nestedgroup, ipausergroup, ipaobject
Default user objectclasses: top, person, organizationalperson, inetorgperson, inetuser, posixaccount, krbprincipalaux, krbticketpolicyaux, ipaobject, ipasshuser
Password Expiration Notification (days): 4
Password plugin features: AllowNThash
SELinux user map order: guest_u:s0$xguest_u:s0$user_u:s0$staff_u:s0-s0:c0.c1023$unconfined_u:s0-s0:c0.c1023
Default SELinux user: unconfined_u:s0-s0:c0.c1023
Default PAC types: MS-PAC, nfs:NONE
cn: ipaConfig
objectclass: nsContainer, top, ipaGuiConfig, ipaConfigObject

Chapter 16. Managing Services

Some services that run on a host can also belong to the IdM domain. Any service that can store a Kerberos principal or an SSL certificate (or both) can be configured as an IdM service. Adding a service to the IdM domain allows the service to request an SSL certificate or keytab from the domain. (Only the public key for the certificate is stored in the service record. The private key is local to the service.)
An IdM domain establishes a commonality between machines, with common identity information, common policies, and shared services. Any machine which belongs to a domain functions as a client of the domain, which means it uses the services that the domain provides. An IdM domain (as described in Chapter 1, Introduction to Red Hat Identity Management) provides three main services specifically for machines:
  • DNS
  • Kerberos
  • Certificate management

16.1. Adding and Editing Service Entries and Keytabs

As with host entries, service entries for the host (and any other services on that host which will belong to the domain) must be added manually to the IdM domain. This is a two step process. First, the service entry must be created, and then a keytab must be created for that service which it will use to access the domain.
By default, Identity Management saves its HTTP keytab to /etc/httpd/conf/ipa.keytab.
Note
This keytab is used for the web UI. If a key were stored in ipa.keytab and that keytab file is deleted, the IdM web UI will stop working, because the original key would also be deleted.
Similar locations can be specified for each service that needs to be made Kerberos aware. There is no specific location that must be used, but, when using ipa-getkeytab, you should avoid using /etc/krb5.keytab. This file should not contain service-specific keytabs; each service should have its keytab saved in a specific location and the access privileges (and possibly SELinux rules) should be configured so that only this service has access to the keytab.

16.1.1. Adding Services and Keytabs from the Web UI

  1. Open the Identity tab, and select the Services subtab.
  2. Click the Add button at the top of the services list.
  3. Select the service type from the drop-down menu, and give it a name.
  4. Select the host name of the IdM host on which the service is running. The host name is used to construct the full service principal name.
  5. Click the Add button to save the new service principal.
  6. Use the ipa-getkeytab command to generate and assign the new keytab for the service principal. 
    [root@ipaserver ~]# # ipa-getkeytab -s ipaserver.example.com -p HTTP/server.example.com -k /etc/httpd/conf/krb5.keytab -e aes256-cts
    • The realm name is optional. The IdM server automatically appends the Kerberos realm for which it is configured. You cannot specify a different realm.
    • The host name must resolve to a DNS A record for it to work with Kerberos. You can use the --force flag to force the creation of a principal should this prove necessary.
    • The -e argument can include a list of encryption types to include in the keytab. This supersedes any default encryption type. Lists of entries can be set by using the option multiple times with the same command invocation or by listing the options in a comma-separated list inside curly braces, such as --option={val1,val2,val3}.
    Warning
    Creating a new key resets the secret for the specified principal. This means that all other keytabs for that principal are rendered invalid.

16.1.2. Adding Services and Keytabs from the Command Line

  1. Create the service principal. The service is recognized through a name like service/FQDN: 
    # ipa service-add serviceName/hostname
    For example: 
    $ ipa service-add HTTP/server.example.com
-------------------------------------------------------
Added service "HTTP/server.example.com@EXAMPLE.COM"
-------------------------------------------------------
  Principal: HTTP/server.example.com@EXAMPLE.COM
  Managed by: ipaserver.example.com
  2. Create the service keytab file using the ipa-getkeytab command. This command is run on the client in the IdM domain. (Actually, it can be run on any IdM server or client, and then the keys copied to the appropriate machine. However, it is simplest to run the command on the machine with the service being created.)
    The command requires the Kerberos service principal (-p), the IdM server name (-s), the file to write (-k), and the encryption method (-e). Be sure to copy the keytab to the appropriate directory for the service.
    For example: 
    # ipa-getkeytab -s server.example.com -p HTTP/server.example.com -k /etc/httpd/conf/krb5.keytab -e aes256-cts
    • The realm name is optional. The IdM server automatically appends the Kerberos realm for which it is configured. You cannot specify a different realm.
    • The host name must resolve to a DNS A record for it to work with Kerberos. You can use the --force flag to force the creation of a principal should this prove necessary.
    • The -e argument can include a comma-separated list of encryption types to include in the keytab. This supersedes any default encryption type. Lists of entries can be set by using the option multiple times with the same command invocation or by listing the options in a comma-separated list inside curly braces, such as --option={val1,val2,val3}.
    Warning
    The ipa-getkeytab command resets the secret for the specified principal. This means that all other keytabs for that principal are rendered invalid.

16.2. Configuring Clustered Services

The IdM server is not cluster aware. However, it is possible to configure a clustered service to be part of IdM by synchronizing Kerberos keys across all of the participating hosts and configuring services running on the hosts to respond to whatever names the clients use.
  1. Enroll all of the hosts in the cluster into the IdM domain.
  2. Create any service principals and generate the required keytabs.
  3. Collect any keytabs that have been set up for services on the host, including the host keytab at /etc/krb5.keytab.
  4. Use the ktutil command to produce a single keytab file that contains the contents of all of the keytab files.
    1. For each file, use the rkt command to read the keys from that file.
    2. Use the wkt command to write all of the keys which have been read to a new keytab file.
  5. Replace the keytab files on each host with the newly-created combined keytab file.
  6. At this point, each host in this cluster can now impersonate any other host.
  7. Some services require additional configuration to accommodate cluster members which do not reset host names when taking over a failed service.
    • For sshd, set GSSAPIStrictAcceptorCheck no in /etc/ssh/sshd_config.
    • For mod_auth_kerb, set KrbServiceName Any in /etc/httpd/conf.d/auth_kerb.conf.
Note
For SSL servers, the subject name or a subject alternative name for the server's certificate must appear correct when a client connects to the clustered host. If possible, share the private key among all of the hosts.
If each cluster member contains a subject alternative name which includes the names of all the other cluster members, that satisfies any client connection requirements.

16.3. Using the Same Service Principal for Multiple Services

Within a cluster, the same service principal can be used for multiple services, spread across different machines.
  1. Retrieve a service principal using the ipa-getkeytab command. 
    # ipa-getkeytab -s kdc.example.com -p HTTP/server.example.com -k /etc/httpd/conf/krb5.keytab -e aes256-cts
  2. Either direct multiple servers or services to use the same file, or copy the file to individual servers as required.

16.4. Retrieve Existing Keytabs for Multiple Servers

In some scenarios, like in a cluster environment, the same keytab file is required for a service represented on one common host name by different machines. IdM commands can be used to retrieve the same keytab on each of the hosts.
To prepare the common host name and the service principal, run the following commands on an IdM server:
  1. Authenticate as admin user: 
    [root@ipaserver ~]# kinit admin
  2. Add a common forward DNS record for all IP addresses that share this host name: 
    [root@ipaserver ~]# ipa dnsrecord-add idm.example.com cluster --a-rec={192.0.2.40,192.0.2.41}
  Record name: cluster
    A record: 192.0.2.40, 192.0.2.41
  3. Create a new host entry object for the common DNS name: 
    [root@ipaserver ~]# ipa host-add cluster.idm.example.com
------------------------------------
Added host "cluster.idm.example.com"
------------------------------------
  Host name: cluster.idm.example.com
  Principal name: host/cluster.idm.example.com@IDM.EXAMPLE.COM
  Password: False
  Keytab: False
  Managed by: cluster.idm.example.com
  4. Add the service principal for the host: 
    [root@ipaserver ~]# ipa service-add HTTP/cluster.idm.example.com
------------------------------------------------------------
Added service "HTTP/cluster.idm.example.com@IDM.EXAMPLE.COM"
------------------------------------------------------------
  Principal: HTTP/clu