Buscar
ApoyoConsolaDesarrolladoresIniciar una pruebaContacto

Este contenido no está disponible en el idioma seleccionado.

Identity Management Guide

download PDF
Red Hat Enterprise Linux 6

Managing Identity and Authorization Policies for Linux-Based Infrastructures

Aneta Šteflová Petrová

Red Hat Customer Content Services

Marc Muehlfeld

Red Hat Customer Content Services

Tomáš Čapek

Red Hat Customer Content Services

Milan Navrátil

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 almost any enterprise environment. IPA 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. This manual covers all aspects of installing, configuring, and managing IPA domains, including both servers and clients. This guide is intended for IT and systems administrators.

Chapter 1. Introduction to Identity Management

Red Hat Enterprise Linux IdM is a way to create identity stores, centralized authentication, domain control for Kerberos and DNS services, and authorization policies — all on Linux systems, using native Linux tools. While centralized identity/policy/authorization software is hardly new, Identity Management is one of the only options that supports Linux/Unix domains.
Identity Management provides a unifying skin for standards-defined, common network services, including PAM, LDAP, Kerberos, DNS, NTP, and certificate services, and it allows Red Hat Enterprise Linux systems to serve as the domain controllers.
Identity Management defines a domain, with servers and clients that share centrally-managed services, like Kerberos and DNS. This chapter first explains what Identity Management is. This chapter also covers how all of these services work together within the domain and how servers and clients interact with each other.

1.1. IdM v. LDAP: A More Focused Type of Service

At the most basic level, Red Hat Identity Management is a domain controller for Linux and Unix machines. Identity Management defines the domain, using controlling servers and enrolled client machines. This provides centralized structure that has previously been unavailable to Linux/Unix environments, and it does it using native Linux applications and protocols.

1.1.1. A Working Definition for Identity Management

Security information frequently relates to identities of users, machines, and services. Once the identity is verified, then access to services and resources can be controlled.
For efficiency, risk management, and ease of administration, IT administrators try to manage identities as centrally as possible and to unite identity management with authentication and authorization policies. Historically, Linux environments have had a very difficult time establishing this centralized management. There are a number of different protocols (such as NIS and Kerberos) which define domains, while other applications store data (such as LDAP) and still others manage access (such as sudo). None of these applications talk to each other or use the same management tools. Every application had to be administered separately and it had to be managed locally. The only way to get a consistent identity policy was to copy configuration files around manually or to try to develop a proprietary application to manage identities and policies.
The goal of Identity Management is to simplify that administrative overhead. Users, machines, services, and polices are all configured in one place, using the same tools. Because IdM creates a domain, multiple machines can all use the same configuration and the same resources simply by joining the domain. Users only have to sign into services once, and administrators only have to manage a single user account.
IdM does three things:
  • Create a Linux-based and Linux-controlled domain. Both IdM servers and IdM clients are Linux or Unix machines. While IdM can synchronize data with an Active Directory domain to allow integration with Windows servers, it is not an administrative tool for Windows machines and it does not support Windows clients. Identity Management is a management tool for Linux domains.
  • Centralize identity management and identity policies.
  • Build on existing, native Linux applications and protocols. While IdM has its own processes and configuration, its underlying technologies are familiar and trusted by Linux administrators and are well established on Linux systems.
In a sense, Identity Management isn't making administrators do something new; it is helping them do it better. There are a few ways to illustrate that.
On one extreme is the low control environment. Little Example Corp. has several Linux and Unix servers, but each one is administered separately. All passwords are kept on the local machine, so there is no central identity or authentication process. Tim the IT Guy just has to manage users on every machine, set authentication and authorization policies separately, and maintain local passwords. With IdM, things come to order. There is a simple way to have central user, password, and policy stores, so Tim the IT Guy only has to maintain the identities on one machine (the IdM server) and users and policies are uniformly applied to all machines. Using host-based access control, delegation, and other rules, he can even set different access levels for laptops and remote users.
In the middle is the medium control environment. Mid-Example Corp. has several Linux and Unix servers, but Bill the IT Guy has tried to maintain a greater degree of control by creating a NIS domain for machines, an LDAP directory for users, and Kerberos for authentication. While his environment is well under control, every application has to be maintained separately, using different tools. He also has to update all of the services manually whenever a new machine is added to his infrastructure or when one is taken offline. In this situation, IdM greatly reduces his administrative overhead because it integrates all of the different applications together seamlessly, using a single and simplified tool set. It also makes it possible for him to implement single sign-on services for all of the machines in his domain.
On the other extreme is the absent control environment. At Big Example Corp., most of the systems are Windows based and are managed in a tightly-knit Active Directory forest. However, development, production, and other teams have many Linux and Unix systems — which are basically excluded from the Windows controlled environment. IdM brings native control to the Linux/Unix servers, using their native tools and applications — something that is not possible in an Active Directory forest. Additionally, because IdM is Windows-aware, data can be synchronized between Active Directory and IdM, preserving a centralized user store.
IdM provides a very simple solution to a very common, very specific problem: identity management.

1.1.2. Contrasting Identity Management with a Standard LDAP Directory

The closest relative to Identity Management is a standard LDAP directory like 389 Directory Server, but there are some intrinsic differences between what they do and what they're intended to do.
First, it helps to understand what a directory service is. A directory service is a collection of software, hardware, and processes that stores information. While directory services can be highly specific (for example, DNS is a directory service because it stores information on hostnames), a generic directory service can store and retrieve any kind of information. LDAP directories like 389 Directory Server are generic directories. They have a flexible schema that supports entries for users, machines, network entities, physical equipment, and buildings, and that schema can be customized to define entries of almost anything. Because of its extensibility, LDAP servers like 389 Directory Server are frequently used as backends that store data for other applications. 389 Directory Server not only contains information, it organizes information. LDAP directories use a hierarchical structure, a directory tree, that organize entries into root entries (suffixes), intermediate or container entries (subtrees or branches), and leaf entries (the actual data). Directory trees can be very complex, with a lot of branch points, or very simple (flat) with few branch points.
The primary feature of an LDAP directory is its generality. It can be made to fit into a variety of applications.
Identity Management, on the other hand, has a very specific purpose and fits a very specific application. It is not a general LDAP directory, it is not a backend, and it is not a general policy server. It is not generic.
Identity Management focuses on identities (user and machine) and policies that relate to those identities and their interactions. While it uses an LDAP backend to store its data, IdM has a highly-customized and specific set of schema that defines a particular set of identity-related entries and defines them in detail. It has a relatively flat and simple directory tree because it has only a handful of entry types and relationships that are relevant to its purpose. It has rules and limitations on how the IdM server can be deployed because it can only be deployed for a specific purpose: managing identities.
The restrictions on IdM also give it a great deal of administrative simplicity. It has a simple installation process, a unified set of commands, and a clearly defined role in the overall IT infrastructure. An IdM domain is easy to configure, easy to join, and easy to manage, and the functions that it serves — particularly identity/authentication tasks like enterprise-wide single sign-on — are also easier to do with IdM than with a more general-purpose directory service.
Table 1.1. Identity Management Compared to 389 Directory Server
389 Directory Server Identity Management
Use General purpose Single domain, focused on identity management
Flexibility Highly-customizable Limitations to focus on identity and authentication
Schema Default LDAP schema Optimized, special schema for identity management
Directory Tree Standard and flexible hierarchy Flat tree with a fixed hierarchy
Authentication LDAP Kerberos or Kerberos and LDAP
Active Directory Synchronization Bi-directional Unidirectional, Active Directory to Identity Management
Password Policies LDAP-based Kerberos-based
User Tools Java Console and standard LDAP utilities Web-based UI and special Python command-line tools
LDAP directories like 389 Directory Server have flexibility and adaptability which makes them a perfect backend to any number of applications. Its primary purpose is to store and retrieve data efficiently.
IdM fills a very different niche. It is optimized to perform a single task very effectively. It stores user information and authentication and authorization policies, as well as other information related to access, like host information. Its single purpose is to manage identities.

1.2. Bringing Linux Services Together

Identity Management unifies disparate yet related Linux services into a single management environment. From there, it establishes a simple, easy way to bring host machines into the domain of those services.
An IdM server is, at its core, an identity and authentication server. The primary IdM server, essentially a domain controller, uses a Kerberos server and KDC for authentication. An LDAP backend contains all of the domain information, including users, client machines, and domain configuration.
The IdM Server: Unifying Services

Figure 1.1. The IdM Server: Unifying Services

Other services are included to provide support for the core identity/authentication functions. DNS is used for machine discovery and for connecting to other clients in the domain. NTP is used to synchronize all domain clocks so that logging, certificates, and operations can occur as expected. A certificate service provides certificates for Kerberos-aware services. All of these additional services work together under the control of the IdM server.
The IdM server also has a set of tools which are used to manage all of the IdM-associated services. Rather than managing the LDAP server, KDC, or DNS settings individually, using different tools on local machines, IdM has a single management toolset (CLI and web UI) that allows centralized and cohesive administration of the domain.

1.2.1. Authentication: Kerberos KDC

Kerberos is an authentication protocol. Kerberos uses symmetric key cryptography to generate tickets to users. Kerberos-aware services check the ticket cache (a keytab) and authenticate users with valid tickets.
Kerberos authentication is significantly safer than normal password-based authentication because passwords are never sent over the network — even when services are accessed on other machines.
In Identity Management, the Kerberos administration server is set up on the IdM domain controller, and all of the Kerberos data are stored in IdM's backend Directory Server. The Directory Server instance defines and enforces access controls for the Kerberos data.

Note

The IdM Kerberos server is managed through IdM tools instead of Kerberos tools because all of its data are stored in the Directory Server instance. The KDC is unaware of the Directory Server, so managing the KDC with Kerberos tools does not affect the IdM configuration.

1.2.2. Data Storage: 389 Directory Server

Identity Management contains an internal 389 Directory Server instance. All of the Kerberos information, user accounts, groups, services, policy information, DNS zone and host entries, and all other information in IdM is stored in this 389 Directory Server instance.
When multiple servers are configured, they can talk to each other because 389 Directory Server supports multi-master replication. Agreements are automatically configured between the initial server and any additional replicas which are added to the domain.

1.2.3. Authentication: Dogtag Certificate System

Kerberos can use certificates along with keytabs for authentication, and some services require certificates for secure communication. Identity Management includes a certificate authority, through Dogtag Certificate System, with the server. This CA issues certificates to the server, replicas, and hosts and services within the IdM domain.
The CA can be a root CA or it can have its policies defined by another, external CA (so that it is subordinate to that CA). Whether the CA is a root or subordinate CA is determined when the IdM server is set up.

1.2.4. Server/Client Discovery: DNS

Identity Management defines a domain — multiple machines with different users and services, each accessing shared resources and using shared identity, authentication, and policy configuration. The clients need to be able to contact each other, as IdM servers. Additionally, services like Kerberos depend on hostnames to identify their principal identities.
Hostnames are associated with IP addresses using the Domain Name Service (DNS). DNS maps hostnames to IP addresses and IP addresses to hostnames, providing a resource that clients can use when they need to look up a host. From the time a client is enrolled in the IdM domain, it uses DNS service discovery to locate IdM servers within the domain and then all of the services and clients within the domain.
The client installation tool automatically configures the local System Security Services Daemon (SSSD) to use the IdM domain for service discovery. SSSD uses DNS already to look for LDAP/TCP and Kerberos / UDP services; the client installation only needs to supply the domain name. SSSD service discovery is covered in the SSSD chapter in the Red Hat Enterprise Linux Deployment Guide.
On the server, the installation script configures the DNS file to set which services the DNS service discovery queries. By default, DNS discovery queries the LDAP service on TCP and different Kerberos services on both UDP and TCP. The DNS file which is created is described in Section 17.2, “Using IdM and DNS Service Discovery with an Existing DNS Configuration”.

Note

While it is technically possible to configure the IdM domain to use DNS service discovery without having an IdM server host the DNS services, this is not recommended.
Multiple DNS servers are usually configured, each one working as an authoritative resource for machines within a specific domain. Having the IdM server also be a DNS server is optional, but it is strongly recommended. When the IdM server also manages DNS, there is tight integration between the DNS zones and the IdM clients and the DNS configuration can be managed using native IdM tools. Even if an IdM server is a DNS server, other external DNS servers can still be used.

1.2.5. Management: SSSD

The System Security Services Daemon (SSSD) is a platform application that caches credentials. Most system authentication is configured locally, which means that services must check with a local user store to determine users and credentials. SSSD allows a local service to check with a local cache in SSSD; the cache may be taken from any variety of remote identity providers, including Identity Management.
SSSD can cache user names and passwords, Kerberos principals and keytabs, automount maps, sudo rules that are defined on IPA servers, and SSH keys that are used by Identity Management domain users and systems. This allows two significant benefits to administrators: all identity configuration can be centralized in a single application (the IdM server); and, external information can be cached on a local system to continue normal authentication operations, in case the system or the IdM server becomes unavailable.
SSSD is automatically configured by IdM client installation and management scripts, so the system configuration never needs to be manually updated, even as domain configuration changes.
Consistently with Windows Active Directory, SSSD allows the user to log in with either the user name attribute or the User Principal Name (UPN) attribute.
SSSD supports the true, false, and preserve values for the case_sensitive option. When the preserve value is enabled, the input matches regardless of the case, but the output is always the same case as on the server; SSSD preserves the case for the UID field as it is configured.
SSSD allows certain cached entries to be refreshed in the background, so the entries are returned instantly because the back end keeps them updated at all times. Currently, entries for users, groups, and netgroups are supported.

1.2.6. Management: NTP

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. If the times between the server and client skew outside the allowed range, then any Kerberos tickets are invalidated.
Clocks are synchronized over a network using Network Time Protocol (NTP). A central server acts as an authoritative clock and all of the clients which reference that NTP server sync their times to match.
When the IdM server is the NTP server for the domain, all times and dates are synchronized before any other operations are performed. This allows all of the date-related services — including password expirations, ticket and certificate expirations, account lockout settings, and entry creation dates — to function as expected.
The IdM server, by default, works as the NTP server for the domain. Other NTP servers can also be used for the hosts.

1.3. Relationships Between Servers and Clients

Identity Management itself defines a domain, a group of machines that have shared configuration, policies, and identity stores. This shared configuration allows the machines (and users) within the domain to be aware of each other and operate together. This awareness can be used to enable cross-platform compatibility, like unifying Windows and Linux systems, or to enable infrastructure-wide single sign-on.

1.3.1. About IdM Servers and Replicas

Identity Management works by having identified servers which are the master stores of information for user and machine identities and domain-wide policies. These servers host domain-related services such as certificate authorities, NTP, Kerberos, SSH, and DNS. The server also acts as a central repository of identity and policy information.
Clients interact indirectly with IdM servers when they attempt to access domain resources, such as fileshares, services, remote machines, or authentication (through SSSD and Kerberos).
As said, an IdM server is a controller for a lot of associated services. While a number of those services are supported, most of them are not required. For example, a server may have a CA, a DNS server, or an NTP server — or it can be installed without those services.
Once an IdM server is set up, its configuration can be copied and used as the basis for another IdM server. When an IdM server is copied, that copy is called a replica.

Note

The only real difference between an IdM server and an IdM replica is that a server is a new installation — so that it defines the domain configuration — and a replica is based on an existing server and existing domain configuration.
Once an instance is configured, servers and replicas are basically identical in functionality and behavior within the IdM domain.
There is a good deal of flexibility in the IdM server (and replica) topology. For example, Server A can be installed with a CA and DNS services, while Replica A can be based on Server A's configuration but not host either DNS or CA services. Replica B can be added to the domain, also without CA or DNS services. At any time in the future, a CA or DNS service can be created and configured on Replica A or Replica B.
Servers and replicas both use underlying LDAP directories to store user and host entries, configuration data, policy configuration, and keytabs, certificates, and keys. Servers and replicas propagate data among each other through multi-master replication agreements. Replication agreements are configured for all LDAP backends as well as the LDAP subtrees used by Dogtag Certificate System. Both servers and replicas are masters (peers) in the replication topology.
Because the servers within the IdM domain are all LDAP peer servers, the replication topology must conform to the topology limits of a 389 Directory Server domain. This means that there can be no more than 20 peer servers in the IdM domain. Planning the server/replica topology is described more in Section 4.1, “Planning the Server/Replica Topologies”.
Server and Replica Interactions

Figure 1.2. Server and Replica Interactions

Note

The replication topology essentially creates a cloud of IdM servers. One benefit of a server domain is automatic load balancing, using the SRV records in DNS. The SRV record sets the priority order that servers and replicas are contacted, while weight distributes the load between servers/replicas with the same priority. The server and replica DNS entries can be edited to change the load balancing, which is covered in Example 17.9, “SRV Record” and Section 28.4.3, “Changing Load Balancing for IdM Servers and Replicas”.

1.3.2. About IdM Clients

A client is simply any machine which is configured to operate within the IdM domain, using its Kerberos and DNS services, NTP settings, and certificate services. That's an important distinction: a client does not require a daemon or (necessarily) an installed product. It requires only system configurations which direct it to use IdM services.
For Red Hat Enterprise Linux systems, a certain number of platform tools are available for IdM to use, such as the System Security Services Daemon (SSSD). IdM-enabled platform applications are aspects of the underlying platform that work with IdM services. Other tools, like certain PAM and NSS modules and IdM command-line utilities, are provided by Identity Management itseld as IdM-specific packages that must be installed on the machine. These are IdM components, rather than platform components used by Identity Management.
Server and Client Interactions

Figure 1.3. Server and Client Interactions

IdM uses the local storage (cache) on a client to improve performance in a few ways:
  • Store IdM information when the machine is offline.
  • Keep information active beyond its normal timeout period if the client cannot access the central server. The cache is persistent even after rebooting the machine.
  • Reduce the round-trip time of requests by checking information locally before looking at the server.
Information is stored either in an LDB database (similar to LDAP) or the local filesystem (as XML files), depending on the type of information.
  • Identity information (about users, machines, and groups) is stored in the LDB database, which uses the same syntax as an LDAP directory. This identity information is originally stored in the IdM server's 389 Directory Server instance. Because this information changes frequently and is referenced frequently, it is important to be able to call the more current information quickly, which is possible using an LDB database on the client and the Directory Server on the server.
  • Policy information is more static than identity information, and it can include configuration for SELinux or sudo. These policies are set globally on the server and then are propagated to the clients. On the client, the policy information is stored in the filesystem in XML files which can be downloaded and converted into a native file for whatever service is being managed.
A specific set of services on the IdM server interact with a subset of services and modules on the IdM client. A client is any machine (a host) which can retrieve a keytab or certificates from the IdM domain.
Interactions Between IdM Services

Figure 1.4. Interactions Between IdM Services

Figure 1.4, “Interactions Between IdM Services” shows that Red Hat Enterprise Linux uses two native daemons to interact with the IdM server:
  • SSSD provides the user authentication for the machine and enforces host-based access control rules.
  • certmonger monitors and renews the certificates on the client. It can request new certificates for the services on the system, including virtual machines.
When a Red Hat Enterprise Linux client is added to the domain (enrolled), its SSSD and certmonger are configured to connect to the IdM server and the required Kerberos keytab and host certificates are created. (The host certificate is not used directly by IdM; it may be used by other services, such as a web server.)

Part I. Installing Identity Management; Servers and Services

Chapter 2. Prerequisites for Installation

Before you install IdM, ensure that the installation environment is suitably configured. You also need to provide certain information during the installation and configuration procedures, including realm names and certain usernames and passwords. This section describes the information that you need to provide.

2.1. Supported Server Platforms

IdM 3.0 is supported on these platforms:
  • Red Hat Enterprise Linux 6 i386
  • Red Hat Enterprise Linux 6 x86_64

2.2. Hardware Recommendations

A basic user entry is about 1 KB in size, as is a simple host entry with a certificate. The most important hardware feature to size properly is RAM. While all deployments are different, depending on the number of users and groups and the type of data stored, there is a rule of thumb to use to help determine how much RAM to use:
  • For 10,000 users and 100 groups, have at least 2GB of RAM and 1GB swap space.
  • For 100,000 users and 50,000 groups, have at least 16GB of RAM and 4GB of swap space.

Note

For larger deployments, it is more effective to increase the RAM than to increase disk space because much of the data are stored in cache.
The underlying Directory Server instance used by the IdM server can be tuned to increase performance. For tuning information, see the Directory Server documentation.

2.3. Software Requirements

Most of the packages that an IdM server depends on are installed as dependencies when the IdM packages are installed. There are some packages, however, which are required before installing the IdM packages:
  • Kerberos 1.10. This is installed as a dependency if it is not already installed.
  • The bind and bind-dyndb-ldap packages for DNS. The bind package is installed as a dependency if it is not already available; however, the bind-dyndb-ldap package must be explicitly installed first or attempting to configure an IdM server with DNS support will fail.

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) and TLSv1.1. 
    NSSProtocol TLSv1.0,TLSv1.1
  2. Restart the httpd service. 
    # service httpd restart

2.4. System Prerequisites

The IdM server is set up using a configuration script, and this script makes certain assumption about the host system. If the system does not meet these prerequisites, then server configuration may fail.

2.4.1. DNS Records

Proper forward and reverse DNS settings are critical for both IdM servers and replicas (copies of servers) to be configured. DNS is used for replicating data between servers, for identifying servers in SSL certificates, and in Kerberos tickets, among other places. Therefore, servers must be resolvable in both forward and reverse DNS configuration.
The DNS settings for a host can be determined easily used ifconfig and dig.
  1. Obtain the hostname. 
    [root@server ~]# hostname
server.example.com
  2. Get the IP address. In this example, the returned IP address is 196.2.3.4. 
    [root@server !]# ifconfig eth0
eth0      Link encap:Ethernet  HWaddr 52:54:01:4C:E1:2C
          inet addr:196.2.3.4  Bcast:196.9.8.7  Mask:255.255.255.255
          inet6 addr: 2620:52:0:102f:5054:1ff:fe4c:e12c/64 Scope:Global
	  inet6 addr: fe80::5054:1ff:fe4c:e12c/64 Scope:Link
...
  3. Verify that forward DNS is properly configured by using dig to query the hostname and check what IP address is returned. In this example, the expected IP address is 196.2.3.4. 
    [root@server ~]# dig server.example.com
; <<>> DiG 9.8.2rc1-RedHat-9.8.2-0.17.rc1.el6 <<>> server.example.com
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 56680
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 7, ADDITIONAL: 12

;; QUESTION SECTION:
;server.example.com. IN A

;; ANSWER SECTION:
server.example.com. 2946 IN A 196.2.3.4
  4. Verify the reverse DNS configuration using dig with the -t ptr to query the PTR records (reverse records) for the address. This is the IP address in reverse order, with .in-addr.arpa. appended to the address. This should resolve to the hostname, server.example.com. in this example. 
    [root@server ~]# dig -t ptr 4.3.2.196.in-addr.arpa. 
; <<>> DiG 9.8.2rc1-RedHat-9.8.2-0.17.rc1.el6 <<>> -t ptr 241.40.16.10.in-addr.arpa
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 57899
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 7, ADDITIONAL: 10

;; QUESTION SECTION:
;4.3.2.196.in-addr.arpa. IN PTR

;; ANSWER SECTION:
4.3.2.196.in-addr.arpa. 21600 IN PTR server.example.com.
The DNS records should resolve to whatever hostname is used in the IdM certificates.

Note

If the IdM server is configured to host its own DNS server, the IdM DNS service processes all DNS queries. The IdM DNS records take precedence, and any previous existing DNS configuration is ignored.
All systems within the domain must be configured to use the IdM-managed DNS server.

2.4.2. Hostname and IP Address Requirements

Regardless of whether the DNS is within the IdM server or external, the server host must have DNS properly configured:
  • The hostname must be a fully-qualified domain name. For example, ipaserver.example.com.

    Important

    This must be a valid DNS name, which means only numbers, alphabetic characters, and hyphens (-) are allowed. Other characters, like underscores, in the hostname will cause DNS failures.
  • The hostname must be all lower-case.
  • The server's A record must be set and resolve to its public IP address.
    The fully-qualified domain name cannot resolve to the loopback address. It must resolve to the machine's public IP address, not to 127.0.0.1. The output of the hostname command cannot be localhost or localhost6.
    The A adn PTR records do not need to match for the server.
  • The server's hostname and IP address must be in its own /etc/hosts file. The fully-qualified domain name for the IdM server must be listed in the hosts file before any aliases.

    Note

    A misconfigured file can prevent the IdM command-line tools from functioning correctly and can prevent the IdM web interface from connecting to the IdM server.
    Additionally, the hostname cannot be part of the localhost entry.
    For example, this lists the IPv4 and IPv6 localhost entries for the host (properly), then the IdM server IP address and hostname as the first entry. 
    127.0.0.1	localhost.localdomain	localhost
::1		localhost6.localdomain6	localhost6
192.168.1.1	ipaserver.example.com	ipaserver
  • It is recommended that a separate DNS domain be allocated for the IdM server to manage. While not required (clients from other domains can still be enrolled in the IdM domain), this is a convenience for overall DNS management.

2.4.3. Directory Server

There must not be any instances of 389 Directory Server installed on the host machine.

2.4.4. System Files

The server script overwrites system files to set up the IdM domain. The system should be clean, without custom configuration for services like DNS and Kerberos, before configuring the IdM server.

2.4.5. System Ports

IdM uses a number of ports to communicate with its services. These ports, listed in Table 2.1, “IdM Ports”, must be open and available for IdM to work. They cannot be in use by another service or blocked by a firewall. To make sure that these ports are available, try the iptables utility to list the available ports or the nc, telnet, or nmap utilities to connect to a port or run a port scan.
To open a port: 
[root@server ~]# iptables -A INPUT -p tcp --dport 389 -j ACCEPT
The iptables(8) man page has more information on opening and closing ports on a system.
Table 2.1. IdM Ports
Service Ports Type
HTTP/HTTPS 80, 443 TCP
LDAP/LDAPS 389, 636 TCP
Kerberos 88, 464 TCP and UDP
DNS 53 TCP and UDP
NTP 123 UDP
Dogtag Certificate System - LDAP 7389 TCP

2.4.6. NTP

Network time protocol (NTP) synchronizes time between systems on a network. An NTP server centralizes and manages that clock synchronization. By default, Identity Management installs and configures an NTP server which is used by the domain to synchronize clocks for other Identity Management servers, replicas, and systems and services within the IdM domain.
Some sort of NTP server must be running for some domain tasks — such as Kerberos ticket maintenance and data replication between servers and replicas in the topology — to function properly. It is not required that an IdM server host the NTP server, but it is strongly recommended. This is the default configuration.
If a server is being installed on a virtual machine, that server should not run an NTP server. To disable NTP for IdM, use the --no-ntp option when the IdM server is configured to prevent an NTP server from being installed.

2.4.7. NSCD

It is strongly recommended that you avoid or restrict the use of nscd in an IdM deployment. The nscd service is extremely useful for reducing the load on the server, and for making clients more responsive, but there can be problems when a system is also using SSSD, which performs its own caching.
nscd caches authentication and identity information for all services that perform queries through nsswitch, including getent. Because nscd performs both positive and negative caching, if a request determines that a specific IdM user does not exist, it caches this as a negative response. Values stored in the cache remain until the cache expires, regardless of any changes that may occur on the server. The results of such caching is that new users and memberships may not be visible, and users and memberships that have been removed may still be visible.
To avoid clashes with SSSD caches and to prevent locking out users, avoid using nscd altogether. Alternatively, use a shorter cache time by resetting the time-to-live caching values in the /etc/nscd.conf file: 
positive-time-to-live   group           3600
negative-time-to-live   group           60
positive-time-to-live   hosts           3600
negative-time-to-live   hosts           20

2.4.8. Networking

The default networking service used by Red Hat Enterprise Linux is NetworkManager. However, NetworkManager can cause problems with IdM and the KDC. It is highly recommended that you use the network service to manage the networking requirements in an IdM environment and disable the NetworkManager service.
  1. Boot the machine into single-user mode.
  2. Disable off the NetworkManager service in the start list and stop the NetworkManager service. 
    [root@server ~]# chkconfig NetworkManager off; service NetworkManager stop
  3. If NetworkManagerDispatcher is installed, ensure that it is stopped and disabled: 
    [root@server ~]# chkconfig NetworkManagerDispatcher off; service NetworkManagerDispatcher stop
  4. Then, make sure that the network service is properly started. 
    [root@server ~]# chkconfig network on; service network start
  5. Ensure that static networking is correctly configured.
  6. Restart the system.

Chapter 3. Installing an IdM Server

The IdM domain is defined and managed by an IdM server which is essentially a domain controller. There can be multiple domain controllers within a domain for load-balancing and failover tolerance. These additional servers are called replicas of the master IdM server.
Both IdM servers and replicas only run on Red Hat Enterprise Linux systems. For both servers and replicas, the necessary packages must be installed and then the IdM server or replica itself is configured through setup scripts, which configure all of the requisite services.

3.1. Installing the IdM Server Packages

Installing only the IdM server requires a single package, ipa-server. If the IdM server will also manage a DNS server, then it requires two additional packages to set up the DNS.
All of these packages can be installed using the yum command: 
[root@server ~]# yum install ipa-server bind bind-dyndb-ldap
Installing the ipa-server also installs a large number of dependencies, such as 389-ds-base for the LDAP service and krb5-server for the Kerberos service, along with IdM tools.
After the packages are installed, the server instance must be created using the ipa-server-install command. The options for configuring the new server instance are described in Section 3.2, “About ipa-server-install”.

3.2. About ipa-server-install

An IdM server instance is created by running the ipa-server-install script. This script can accept user-defined settings for services, like DNS and Kerberos, that are used by the IdM instance, or it can supply predefined values for minimal input from the administrator.
The IdM setup script creates a server instance, which includes configuring all of the required services for the IdM domain:
  • The network time daemon (ntpd)
  • A 389 Directory Server instance
  • A Kerberos key distribution center (KDC)
  • Apache (httpd)
  • An updated SELinux targeted policy
  • The Active Directory WinSync plug-in
  • A certificate authority
  • Optional. A domain name service (DNS) server
The IdM setup process can be minimal, where the administrator only supplies some required information, or it can be very specific, with user-defined settings for many parts of the IdM services. The configuration is passed using arguments with the ipa-server-install script.

Note

The port numbers and directory locations used by IdM are all defined automatically, as defined in Section 2.4.5, “System Ports” and Section 28.1, “Identity Management Files and Logs”. These ports and directories cannot be changed or customized.
While ipa-server-install can be run without any options, so that it prompts for the required information, it has numerous arguments which allow the configuration process to be easily scripted or to supply additional information which is not requested during an interactive installation.
Table 3.1, “ipa-server-install Options” lists some common arguments used with ipa-server-install. The full list of options are in the ipa-server-install manpage. The ipa-server-install options are versatile enough to be customized to the specific deployment environment to install and configure different services as needed.
Table 3.1. ipa-server-install Options
Argument Description
-a ipa_admin_password The password for the IdM administrator. This is used for the admin user to authenticate to the Kerberos realm.
--hostname=hostname The fully-qualified domain name of the IdM server machine.

Important

This must be a valid DNS name, which means only numbers, alphabetic characters, and hyphens (-) are allowed. Other characters, like underscores, in the hostname will cause DNS failures.
Additionally, the hostname must be all lower-case. No capital letters are allowed.
-n domain_name The name of the LDAP server domain to use for the IdM domain. This is usually based on the IdM server's hostname.
-p directory_manager_password The password for the superuser, cn=Directory Manager, for the LDAP service.
-P kerberos_master_password The password for the KDC administrator. This is randomly generated if no value is given.
-r realm_name The name of the Kerberos realm to create for the IdM domain.
--subject=subject_DN Sets the base element for the subject DN of the issued certificates. This defaults to O=realm.
--forwarder=forwarder Gives a DNS forwarder to use with the DNS service. To specify more than one forwarder, use this option multiple times.
--no-forwarders Uses root servers with the DNS service instead of forwarders.
--no-reverse Does not create a reverse DNS zone when the DNS domain is set up. (If a reverse DNS zone is already configured, then that existing reverse DNS zone is used.) If this option is not used, then the default value is true, which assumes that reverse DNS should be configured by the installation script.
--setup-dns Tells the installation script to set up a DNS service within the IdM domain. Using an integrated DNS service is optional, so if this option is not passed with the installation script, then no DNS is configured.
--idmax=number Sets the upper bound for IDs which can be assigned by the IdM server. The default value is the ID start value plus 199999.
--idstart=number Sets the lower bound (starting value) for IDs which can be assigned by the IdM server. The default value is randomly selected.
--ip-address Specifies the IP address of the server. When added to ipa-server-install, this option only accepts IP addresses associated with the local interface.
The way that an IdM server is installed can be different depending on the network environment, security requirements within the organization, and the desired topology. These examples illustrate some common options when installing the server. These examples are not mutually exclusive; it is entirely possible to use CA options, DNS options, and IdM configuration options in the same server invocation. These are called out separately simply to make it more clear what each configuration area requires.

3.3. Example: Running the Script Interactively and Silently

3.3.1. Basic Interactive Installation

All that is required to set up an IdM server is to run the ipa-server-install script. This launches the script interactively, which prompts for the required information to set up a server, but without more advanced configuration like DNS and CA options.
  1. Run the ipa-server-install script. 
    [root@server ~]# ipa-server-install
  2. Enter the hostname. This is determined automatically using reverse DNS. 
    Server host name [ipaserver.example.com]:
  3. Enter the domain name. This is determined automatically based on the hostname. 
    Please confirm the domain name [example.com]:
  4. Enter the new Kerberos realm name. This is usually based on the domain name. 
    Please provide a realm name [EXAMPLE.COM]:
  5. Enter the password for the Directory Server superuser, cn=Directory Manager. There are password strength requirements for this password, including a minimum password length (eight characters). 
    Directory Manager password:
Password (confirm):
  6. Enter the password for the IdM system user account, admin. This user is created on the machine. 
    IPA admin password:
Password (confirm):
  7. The script then reprints the hostname, IP address, and domain name. Confirm that the information is correct. 
    The IPA Master Server will be configured with
Hostname:    ipaserver.example.com
IP address:  192.168.1.1
Domain name: example.com
Realm name: EXAMPLE.COM
Continue to configure the system with these values? [no]: yes
  8. After that, the script configures all of the associated services for IdM, with task counts and progress bars. 
    Configuring NTP daemon (ntpd) 
[1/4]: stopping ntpd 
...
Done configuring NTP daemon (ntpd). 
Configuring directory server (dirsrv): Estimated time 1 minute 
[1/38]: creating directory server user 
.... 
Configuring certificate server (pki-tomcatd): Estimated time 3 minutes 30 seconds 
[1/20]: creating certificate server user 
... 
Done configuring certificate server (pki-tomcatd). 
Configuring Kerberos KDC (krb5kdc): Estimated time 30 seconds 
[1/10]: adding sasl mappings to the directory 
... 
Done configuring Kerberos KDC (krb5kdc). 
Configuring kadmin 
[1/2]: starting kadmin 
[2/2]: configuring kadmin to start on boot 
Done configuring kadmin. 
Configuring ipa_memcached 
[1/2]: starting ipa_memcached 
[2/2]: configuring ipa_memcached to start on boot 
Done configuring ipa_memcached. 
Configuring ipa-otpd 
[1/2]: starting ipa-otpd 
[2/2]: configuring ipa-otpd to start on boot 
Done configuring ipa-otpd. 
Configuring the web interface (httpd): Estimated time 1 minute 
[1/15]: disabling mod_ssl in httpd 
... 
Done configuring the web interface (httpd). 
Applying LDAP updates 
Restarting the directory server 
Restarting the KDC 
Sample zone file for bind has been created in /tmp/sample.zone.pUfcGp.db 
Restarting the web server 
  
Setup complete
  9. Restart the SSH service to retrieve the Kerberos principal and to refresh the name server switch (NSS) configuration file: 
    [root@server ~]# service sshd restart
  10. Authenticate to the Kerberos realm using the admin user's credentials to ensure that the user is properly configured and the Kerberos realm is accessible. 
    [root@server ~]# kinit admin
Password for admin@EXAMPLE.COM:
  11. Test the IdM configuration by running a command like ipa user-find. For example: 
    [root@server ~]# 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
----------------------------

3.3.2. Silent (Non-Interactive) Installation

As shown in Section 3.3.1, “Basic Interactive Installation”, only a few pieces of information are required to configure an IdM server. While the setup script can prompt for this information in interactive mode, this information can also be passed with the setup command to allow automated and unattended configuration:
  • Passwords for the IdM administrative user and the Directory Server super user (Directory Manager)
  • The server hostname
  • The Kerberos realm name
  • The DNS domain name
This information can be passed with the ipa-server-install, along with the -U to force it to run without requiring user interaction.

Example 3.1. Basic Installation without Interaction

[root@server ~]# ipa-server-install -a secret12 --hostname=ipaserver.example.com -r EXAMPLE.COM -p secret12 -n example.com -U
The script then prints the submitted values: 
To accept the default shown in brackets, press the Enter key.

The IPA Master Server will be configured with
Hostname:    ipaserver.example.com
IP address:  192.168.1.1
Domain name: example.com
The server name must be a valid DNS name, which means only numbers, alphabetic characters, and hyphens (-) are allowed. Other characters, like underscores, in the hostname will cause DNS failures. Additionally, the hostname must be all lower-case. No capital letters are allowed.
Then the script runs through the configuration progress for each IdM service, as in Section 3.3.1, “Basic Interactive Installation”.

3.4. Examples: Installing with Different CA Configurations

Identity Management uses an integrated certificate authority (CA) to create the certificates and keytabs used by users and hosts within the domain. Even internal domain services, such as the LDAP server and the Apache server for the Identity Management web UI, require server certificates to establish secure connections with each other.
A Dogtag Certificate System CA is almost always installed with the IdM server. That CA uses a CA signing certificate to create and sign all of the server and user certificates created within the IdM domain. That CA certificate itself has to be signed by the CA which issued it, and there are two different ways that a CA can sign the Dogtag Certificate System CA signing certificate:
  • The Dogtag Certificate System can sign its own certificate. This means that the Dogtag Certificate System instance is a root CA. There are no higher CAs, and the root CA cna set its own certificate policies.
    This is the default configuration.
  • The Dogtag Certificate System CA can be signed by an externally-hosted CA (such as Verisign). In that case, the external CA is the root CA, and the configured Dogtag Certificate System CA is subordinate to that root. This means that the certificates issued within the IdM domain are potentially subject to restrictions set by the root CA for attributes like the validity period.
    Referencing an external CA still uses a Dogtag Certificate System instance to issue all of the IdM domain certficates; the only difference is that the initial domain CA certificate is issued by a different CA.
There is one other option: installing without a CA at all. This requires that all certificates used within the IdM domain be created, uploaded, and renewed manually. There may be some environments where the additional maintenance burden is sustainable because of other restrictions within the infrastructure, but, in general, most deployments will use an integrated Dogtag Certificate System instance (and certmonger) to manage IdM domain certificates.

Important

It is not possible to change the CA configuration after the domain is created and it is not possible to migrate from one configuration to another. It is crucial that the CA requirements be considered before beginning the installation process.

3.4.1. Installing with an Internal Root CA

The default configuration is to install a Dogtag Certificate System which signs its own root CA certificate. There are no additional parameters or configuration steps required when the ipa-server-install command is run. 
[root@server ~]# ipa-server-install
... &< ...

The IPA Master Server will be configured with:
Hostname:      server.example.com
IP address:    10.1.1.1
Domain name:   example.com
Realm name:    EXAMPLE.COM

Continue to configure the system with these values? [no]: yes

The following operations may take some minutes to complete.
Please wait until the prompt is returned.

... &< ...

Configuring directory server for the CA (pkids): Estimated time 30 seconds
  [1/3]: creating directory server user
  [2/3]: creating directory server instance
  [3/3]: restarting directory server
Done configuring directory server for the CA (pkids).
Configuring certificate server (pki-cad): Estimated time 3 minutes 30 seconds
  [1/21]: creating certificate server user
...
Done configuring certificate server (pki-cad).

... &< ...

3.4.2. Installing Using an External CA

The IdM server can use a certificate issued by an external CA. This can be a corporate CA or a third-party CA like Verisign or Thawte. As with a normal setup process, using an external CA still uses a Dogtag Certificate System instance for the IdM server for issuing all of its client and replica certificates; the initial CA certificate is simply issued by a different CA.
When using an external CA, there are two additional steps that must be performed: submit the generated certificate request to the external CA and then load the CA certificate and issued server certificate to complete the setup.

Important

The CA signing certificate generated for the Identity Management server must be a valid CA certificate. This requires either that the Basic Constraint option be set to CA=TRUE or that the Key Usage Extension be set on the signing certificate to allow it to sign certificates.

Important

It is not possible to change the CA configuration after the domain is created and it is not possible to migrate from one configuration to another. It is crucial that the CA requirements be considered before beginning the installation process.

Example 3.2. Using an External CA

  1. Run the ipa-server-install script, using the --external-ca option. 
    [root@server ~]# ipa-server-install -a secret12 -r EXAMPLE.COM -P password -p secret12 -n ipaserver.example.com --external-ca
  2. The script sets up the NTP and Directory Server services as normal.
  3. The script completes the CA setup and returns information about where the certificate signing request (CSR) is located, /root/ipa.csr. This request must be submitted to the external CA. 
    Configuring certificate server: Estimated time 6 minutes
  [1/4]: creating certificate server user
  [2/4]: creating pki-ca instance
  [3/4]: restarting certificate server
  [4/4]: configuring certificate server instance
The next step is to get /root/ipa.csr signed by your CA and re-run ipa-server-install.
  4. Submit the request to the CA. The process differs for every service.
    It may be necessary to request the appropriate extensions for the certificate. The CA signing certificate generated for the Identity Management server must be a valid CA certificate. This requires either that the Basic Constraint be set to CA=true or that the Key Usage Extension be set on the signing certificate to allow it to sign certificates.
  5. Retrieve the issued certificate and the CA certificate chain for the issuing CA. Again, the process differs for every certificate service, but there is usually a download link on a web page or in the notification email that allows administrators to download all the required certificates. Be sure to get the full certificate chain for the CA, not just the CA certificate.
  6. Rerun ipa-server-install, specifying the locations and names of the certificate and CA chain files. For example: 
    [root@server ~]# ipa-server-install --external_cert_file=/tmp/servercert20110601.p12 --external_ca_file=/tmp/cacert.p12
  7. Complete the setup process and verify that everything is working as expected, as in Section 3.3.1, “Basic Interactive Installation”.

3.4.3. Installing without a CA

In very rare cases, it may not be possible to install certificate services with the Identity Management server. In that case, it is possible to install Identity Management without an integrated Certificate System instance, as long as all required certificates are created and installed independently.
For installation, three certificates are required:
  • An LDAP server certificate
  • An Apache server certificate
  • An LDAP server certificate
This certificates must be requested from a third-party authority before beginning the installation process.
There are some important limitations with how certificates can be managed when there is no integrated Dogtag Certificate System instance:
  • certmonger is not used to track certificates, so there is no expiration warning.
  • There is no way to renew certificates through Identity Management.
  • The certificate management tools (ipa cert-*) cannot be used to view or manage certificates.
  • All host certificates and any service certificates must be requested, generated, and uploaded manually. This also affects how host management tools like ipa host-add function.
  • If a certificate is removed from an entry, it is not automatically revoked.

Important

It is not possible to change the CA configuration after the domain is created and it is not possible to migrate from one configuration to another. It is crucial that the CA requirements be considered before beginning the installation process.

Example 3.3. Installing Identity Management Without a CA

There are five options required when installing without a CA, to pass the required certificates directly to the setup process:
  • LDAP server certificate
    • --dirsrv_pkcs12, with the PKCS#12 certificate file for the LDAP server certificate
    • --dirsrv_pin, with the password to access the PKCS#12 file
  • Apache server certificate
    • --http_pkcs12, with the PKCS#12 certificate file for the Apache server certificate
    • --http_pin, with the password to access the PKCS#12 file
  • Root CA certificate (to allow the Apache and LDAP server certificates to be trusted across the domain) 
[root@server ~]# ipa-server-install --http_pkcs12 /tmp-http-server.p12 --http_pin secret1 --dirsrv_pkcs12 /tmp/ldap-server.p12 --dirsrv_pin secret2 ...

3.5. Example: Configuring DNS Services within the IdM Domain

IdM can be configured to manage its own DNS or use an existing DNS (which is the default). Running the setup script alone does not configure DNS; this requires the --setup-dns option.

Warning

DNS records are vital for nearly all IdM domain functions, including running LDAP directory services, Kerberos, and Active Directory integration.
Be extremely cautious and ensure that you have a tested and functional DNS service available if the IdM domain will not use an IdM-hosted DNS server. It is critical that you have properly configured A and PTR records.
As with a basic setup, the DNS setup can either prompt for the required information or the DNS information can be passed with the script to allow an automatic or unattended setup process.

3.5.1. DNS Notes

  • Wildcards cannot be used when configuring DNS names. Only explicit DNS domain names are supported.
  • The rndc service is not configured by the --setup-dns option. This service must be configured manually after the IdM server is configured.

3.5.2. Installing with an Integrated DNS

Example 3.4. Interactive DNS Setup

  1. Run the ipa-server-install script, using the --setup-dns option. 
    [root@server ~]# ipa-server-install -a secret12 -r EXAMPLE.COM -P password -p secret12 -n ipaserver.example.com --setup-dns
  2. The script configures the hostname and domain name as normal.
  3. The script then prompts for DNS forwarders. If forwarders will be used, enter yes, and then supply the list of DNS servers. If IdM will manage its own DNS service, then enter no. 
    Do you want to configure DNS forwarders? [yes]: no
No DNS forwarders configured
  4. The script sets up the NTP, Directory Server, Certificate System, Kerberos, and Apache services.
  5. Before completing the configuration, the script prompts to ask whether it should configure reverse DNS services. If you select yes, then it configures the named service. 
    Do you want to configure the reverse zone? [yes]: yes
Configuring DNS (named) 
[1/11]: adding DNS container 
[2/11]: setting up our zone 
[3/11]: setting up reverse zone 
[4/11]: setting up our own record 
[5/11]: setting up records for other masters 
[6/11]: setting up CA record 
[7/11]: setting up kerberos principal 
[8/11]: setting up named.conf 
[9/11]: restarting named 
[10/11]: configuring named to start on boot 
[11/11]: changing resolv.conf to point to ourselves 
Done configuring DNS (named). 
==============================================================================
Setup complete
  6. The ipa-dns-install command (which is run with the install script when the --setup-dns option is used) does not automatically configure the system's rndc service. This must be configured manually, after DNS is configured for IdM.
    1. Create the rndc configuration file and key. 
      [root@server ~]# /usr/sbin/rndc-confgen -a
[root@server ~]# /sbin/restorecon /etc/rndc.key
      This may require some user input to create entropy while the key is being created.
    2. Change the owner and permissions of the rndc key file. 
      [root@server ~]# chown root:named /etc/rndc.key
[root@server ~]# chmod 0640 /etc/rndc.key
  7. Verify that everything is working as expected, as in Section 3.3.1, “Basic Interactive Installation”.
If DNS is used with IdM, then two pieces of information are required: any DNS forwarders that will be used and whether to use reverse DNS. To perform a non-interactive setup, this information can be passed using the --forwarder or --no-forwarders option and --no-reverse option.

Example 3.5. Setting up DNS Non-Interactively

To set up a DNS server and domain for the IdM server, use the --setup-dns option. To configure additional forwarders, use the --forwarder option; for multiple forwarders, use multiple invocations of --forwarder. 
[root@server ~]# ipa-server-install ... --setup-dns --forwarder=1.2.3.0 --forwarder=1.2.255.0
Some kind of forwarder information is required. If no external forwarders will be used with the IdM DNS service, then use the --no-forwarders option to indicate that only root servers will be used.
The script always assumes that reverse DNS is configured along with DNS, so it is not necessary to use any options to enable reverse DNS. To disable reverse DNS, use the --no-reverse option; if a reverse DNS zone is already configured, then using the --no-reverse option means that existing reverse DNS zone is used. 
[root@server ~]# ipa-server-install ... --setup-dns --no-reverse
The ipa-dns-install command (which is run with the install script when the --setup-dns option is used) does not automatically configure the system's rndc service. This must be configured manually, after DNS is configured for IdM.
  1. Create the rndc configuration file and key. 
    [root@server ~]# /usr/sbin/rndc-confgen -a
[root@server ~]# /sbin/restorecon /etc/rndc.key
    This may require some user input to create entropy while the key is being created.
  2. Change the owner and permissions of the rndc key file. 
    [root@server ~]# chown root:named /etc/rndc.key
[root@server ~]# chmod 0640 /etc/rndc.key

Chapter 4. Setting up IdM Replicas

Replicas are essentially clones of existin Identity Management servers, and they share identical core configuration. The replica installation process, then, has two major parts: copying the existing, required server configuration and then installing the replica based on that information.

4.1. Planning the Server/Replica Topologies

In the IdM domain, there are three types of machines:
  • Servers, which manage all of the services used by domain members
  • Replicas, which are essentially copies of servers (and, once copied, are identical to servers)
  • Clients, which belong to the Kerberos domains, receive certificates and tickets issued by the servers, and use other centralized services for authentication and authorization
A replica is a clone of a specific IdM server. The server and replica share the same internal information about users, machines, certificates, and configured policies. These data are copied from the server to the replica in a process called replication. The two Directory Server instances used by an IdM server — the Directory Server instance used by the IdM server as a data store and the Directory Server instance used by the Dogtag Certificate System to store certificate information — are replicated over to corresponding consumer Directory Server instances used by the IdM replica. The different Directory Server instances recognize each other through replication agreements. An initial replication agreement is created between a master server and replica when the replica is created; additional agreements can be added to other servers or replicas using the ipa-replica-manage command.
Server and Replica Agreements

Figure 4.1. Server and Replica Agreements

Once they are installed, replicas are functionally identical to servers.
There are some guidelines with multi-master replication which place restrictions on the overall server/replica topology.
  • No more than four replication agreements can be configured on a single server/replica.
  • No more than 20 servers and replicas should be involved in a single Identity Management domain.
  • Every server/replica should have a minimum of two replication agreements to ensure that there are no orphan servers or replicas cut out of the IdM domain if another server fails.
One of the most resilient topologies is to create a cell configuration for the servers/replicas, where there are a small number of servers in a cell which all have replication agreements with each other (a tight cell), and then each server has one replication agreement with another server outside the cell, loosely coupling that cell to every other cell in the overall domain.
Example Topology

Figure 4.2. Example Topology

There are some recommendations on how to accomplish this easily:
  • 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.
  • Rather than using a server or replica, small offices can use SSSD to cache credentials and use an off-site IdM server as its data backend.

4.2. Prerequisites for Installing a Replica Server

Replicas are functionally the same as IdM servers, so they have the same installation requirements and packages. However, replicas are also copies of existing servers, so they must also mirror the originating server configuration.
  • Make sure that the machine meets all of the prerequisites listed in Chapter 2, Prerequisites for Installation.
  • The replica and the master server must be running the same version of IdM.
    The replica essentially is a copy of a server, based off the existing server configuration. Therefore, the server and the replica (its copy) must be running the same version of Identity Management so that the configuration can be properly copied from the server to the replica.
    If the master server is running on Red Hat Enterprise Linux 6, IdM version 3.0, then the replica must also run on Red Hat Enterprise Linux 6 and use the IdM 3.0 packages.

    Important

    Creating a replica of a different version than the master is not supported. Attempting to create a replica using a different version fails when attempting to configure the 389 Directory Server instance.
  • Apart from the ports listed in Table 2.1, “IdM Ports”, installing a replica also requires port 22 to be free during the replica setup process. This port is required in order to use SSH to connect to the master server.
    Port 7389 must be free if there is an existing Dogtag Certificate System or Red Hat Certificate System instance on the replica machine during and after the replica configuration. This port is used by the master IdM server to communicate with the replica.

    Note

    The ipa-replica-install script includes the ipa-replica-conncheck utility that verifies the status of the required ports. You can also run ipa-replica-conncheck separately for troubleshooting purposes. For information on how to use the utility, see the ipa-replica-conncheck(1) man page.
  • The replica must use the same CA configuration as the server and must have the same root CA. For example, if the server is its own root CA (using Dogtag Certificate System), then that must be the root CA for the replica. If the server used an external CA to issue its certificates, than the replica must use that same external CA.

4.3. Installing the Replica Packages

Since the replica is an IdM server (based on the configuration of an existing server), it is installed from the IdM server packages, ipa-server. If the replica will also host DNS services, then include the bind and bind-dyndb-ldap packages. 
[root@server ~]# yum install ipa-server bind bind-dyndb-ldap

Important

Do not run the ipa-server-install script.

4.4. Creating the Replica

  1. On the master server, create a replica information file. This contains realm and configuration information taken from the master server which will be used to configure the replica server.
    Run the ipa-replica-prepare utility on the master IdM server. The utility requires the fully-qualified domain name of the replica machine.
    Using the --ip-address option automatically creates DNS entries for the replica, including the A and PTR records for the replica to the DNS.

    Important

    Only pass the --ip-address option if the IdM server was configured with integrated DNS. Otherwise, there is no DNS record to update, and the attempt to create the replica fails when the DNS record operation fails.

    Note

    The ipa-replica-prepare script does not validate the IP address or verify if the IP address of the replica is reachable by other servers. 
    [root@server ~]# ipa-replica-prepare ipareplica.example.com --ip-address 192.168.1.2 

Directory Manager (existing master) password: 
Preparing replica for ipareplica.example.com from ipaserver.example.com 
Creating SSL certificate for the Directory Server 
Creating SSL certificate for the dogtag Directory Server 
Saving dogtag Directory Server port 
Creating SSL certificate for the Web Server 
Exporting RA certificate 
Copying additional files 
Finalizing configuration 
Packaging replica information into /var/lib/ipa/replica-info-ipareplica.example.com.gpg 
Adding DNS records for ipareplica.example.com 
Using reverse zone 1.168.192.in-addr.arpa. 
The ipa-replica-prepare command was successful
    This must be a valid DNS name, which means only numbers, alphabetic characters, and hyphens (-) are allowed. Other characters, like underscores, in the hostname will cause DNS failures. Additionally, the hostname must be all lower-case. No capital letters are allowed.
    Each replica information file is created in the /var/lib/ipa/ directory as a GPG-encrypted file. Each file is named specifically for the replica server for which it is intended, such as replica-info-ipareplica.example.com.gpg.

    Note

    A replica information file cannot be used to create multiple replicas. It can only be used for the specific replica and machine for which it was created.

    Warning

    Replica information files contain sensitive information. Take appropriate steps to ensure that they are properly protected.
    For more options with ipa-replica-prepare, see the ipa-replica-prepare(1) man page.
  2. Copy the replica information file to the replica server: 
    [root@server ~]# scp /var/lib/ipa/replica-info-ipareplica.example.com.gpg root@ipaserver:/var/lib/ipa/
  3. On the replica server, run the replica installation script, referencing the replication information file. There are other options for setting up DNS, much like the server installation script. Additionally, there is an option to configure a CA for the replica; while CA's are installed by default for servers, they are optional for replicas.
    Some information about DNS forwarders is required. A list can be given of configured DNS forwarders using a --forwarder option for each one, or forwarder configuration can be skipped by specifying the --no-forwarders option.
    For example: 
    [root@ipareplica ~]# ipa-replica-install --setup-ca --setup-dns --no-forwarders /var/lib/ipa/replica-info-ipareplica.example.com.gpg

Directory Manager (existing master) password:

Warning: Hostname (ipareplica.example.com) not found in DNS
Run connection check to master
Check connection from replica to remote master 'ipareplica. example.com':
   Directory Service: Unsecure port (389): OK
   Directory Service: Secure port (636): OK
   Kerberos KDC: TCP (88): OK
   Kerberos Kpasswd: TCP (464): OK
   HTTP Server: Unsecure port (80): OK
   HTTP Server: Secure port (443): OK

The following list of ports use UDP protocol and would need to be
checked manually:
   Kerberos KDC: UDP (88): SKIPPED
   Kerberos Kpasswd: UDP (464): SKIPPED

Connection from replica to master is OK.
Start listening on required ports for remote master check
Get credentials to log in to remote master
admin@EXAMPLE.COM password:

Execute check on remote master
admin@example.com's password:
Check connection from master to remote replica 'ipareplica. example.com':
   Directory Service: Unsecure port (389): OK
   Directory Service: Secure port (636): OK
   Kerberos KDC: TCP (88): OK
   Kerberos KDC: UDP (88): OK
   Kerberos Kpasswd: TCP (464): OK
   Kerberos Kpasswd: UDP (464): OK
   HTTP Server: Unsecure port (80): OK
   HTTP Server: Secure port (443): OK

Connection from master to replica is OK.

Connection check OK
    The replica installation script runs a test to ensure that the replica file being installed matches the current hostname. If they do not match, the script returns a warning message and asks for confirmation. This could occur on a multi-homed machine, for example, where mismatched hostnames may not be an issue.
    Additional options for the replica installation script are listed in the ipa-replica-install(1) man page.

    Note

    One of the options ipa-replica-install accepts is the --ip-address option. When added to ipa-replica-install, this option only accepts IP addresses associated with the local interface.
  4. Enter the Directory Manager password when prompted. The script then configures a Directory Server instance based on information in the replica information file and initiates a replication process to copy over data from the master server to the replica, a process called initialization.
  5. Verify that the proper DNS entries were created so that IdM clients can discover the new server. DNS entries are required for required domain services:
    • _ldap._tcp
    • _kerberos._tcp
    • _kerberos._udp
    • _kerberos-master._tcp
    • _kerberos-master._udp
    • _ntp._udp
    If the initial IdM server was created with DNS enabled, then the replica is created with the proper DNS entries. For example: 
    [root@ipareplica ~]# DOMAIN=example.com
[root@ipareplica ~]# NAMESERVER=ipareplica
[root@ipareplica ~]# for i in _ldap._tcp _kerberos._tcp _kerberos._udp _kerberos-master._tcp _kerberos-master._udp _ntp._udp; do echo ""; dig @${NAMESERVER} ${i}.${DOMAIN} srv +nocmd +noquestion +nocomments +nostats +noaa +noadditional +noauthority; done | egrep -v "^;" | egrep _

_ldap._tcp.example.com. 86400   IN      SRV     0 100 389 ipaserver1.example.com.
_ldap._tcp.example.com. 86400   IN      SRV     0 100 389 ipaserver2.example.com.
_kerberos._tcp.example.com. 86400 IN    SRV     0 100 88  ipaserver1.example.com.
...8<...
    If the initial IdM server was created without DNS enabled, then each DNS entry, including both TCP and UDP entries for some services, should be added manually. For example: 
    [root@ipareplica ~]# kinit admin
[root@ipareplica ~]# ipa dnsrecord-add example.com _ldap._tcp --srv-rec="0 100 389 ipareplica.example.com."
  6. Optional. Set up DNS services for the replica. These are not configured by the setup script, even if the master server uses DNS.
    Use the ipa-dns-install command to install the DNS manually, then use the ipa dnsrecord-add command to add the required DNS records. For example: 
    [root@ipareplica ~]# ipa-dns-install

[root@ipareplica ~]# ipa dnsrecord-add example.com @ --ns-rec ipareplica.example.com.

    Important

    Use the fully-qualified domain name of the replica, including the final period (.), otherwise BIND will treat the hostname as relative to the domain.

4.5. Alternate Options for Creating a Replica

Much of the core configuration of the replica is identical to that of the server from which it was created, such as the realm name and directory settings. However, while the settings need to match, it is not required that a replica manage the same services as the server. This is true for major services (DNS and CAs) and for minor services (NTP and OpenSSH).
The difference settings can be defined in the ipa-replica-prepare command or in the ipa-replica-install command.

4.5.1. Different DNS Settings

For DNS, the ipa-replica-prepare command can be used to configure DNS settings specific to the replica, meaning its IP address and reverse zone. For example: 
[root@server ~]# ipa-replica-prepare ipareplica.example.com --ip-address=192.68.0.0 --no-reverse
If the server does not host any DNS services, then the replica can be set up to host DNS services for the Identity Management domain. As with installing a server, this is done with the --setup-dns option, and then settings for forward and reverse zones. For example, to configure DNS services for the replica with no forwarders and using an existing reverse zone: 
[root@server ~]# ipa-replica-install  ipareplica.example.com --setup-dns --no-forwarders --no-reverse --no-host-dns ...
The DNS options are described in the ipa-replica-prepare and ipa-replica-install manpages.

4.5.2. Different CA Settings

The CA configuration of the replica must echo the CA configuration of the server. If the server is configured with an integrated Dogtag Certificate System instance (regardless of whether it is a root CA or whether it is subordinate to an external CA), then the replica can either create its own integrated CA which is subordinate to the server CA or it can forgo having a CA at all, and forward all requests to the server's CA.
If the replica will have its own CA, then it uses the --setup-ca option. The rest of the configuration is taken from the server's configuration. 
[root@ipareplica ~]# ipa-replica-install ipareplica.example.com --setup-ca ...
However, if the server was installed without any CA at all, then is nowhere to forward certificate opterations — including the ability to request certificates for the new replica instance. All of the certificates for the replica, as with the server, must be requested and retrieved before installing the replica and then submitted with the installation command. The only exception is the root CA certificate; this is retrieved from the server as part of the replica setup. 
[root@ipareplica ~]# ipa-replica-install ipareplica.example.com --dirsrv_pkcs12=/tmp/dirsrv-cert.p12 --dirsrv_pin=secret1 --http_pkcs12=/tmp/http-cert.p12 --http_pin=secret2 ...

4.5.3. Different Services

There are three support services that are installed on both servers and replicas by default: NTP, OpenSS client, and OpenSSH server. Any or all of this can be disabled on a replica. For example: 
[root@server ~]# ipa-replica-install ... --no-ntp --no-ssh --no-sshd ...

Chapter 5. Setting up Systems as IdM Clients

A client is any system which is a member of the Identity Management domain. While this is frequently a Red Hat Enterprise Linux system (and IdM has special tools to make configuring Red Hat Enterprise Linux clients very simple), machines with other operating systems can also be added to the IdM domain.
One important aspect of an IdM client is that only the system configuration determines whether the system is part of the domain. (The configuration includes things like belonging to the Kerberos domain, DNS domain, and having the proper authentication and certificate setup.)

Note

IdM does not require any sort of agent or daemon running on a client for the client to join the domain. However, for the best management options, security, and performance, clients should run the System Security Services Daemon (SSSD).
For more information on SSSD, see the SSSD chapter in the Deployment Guidethe SSSD project page.
This chapter explains how to configure a system to join an IdM domain.

Note

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

5.1. What Happens in Client Setup

Whether the client configuration is performed automatically on Red Hat Enterprise Linux systems using the client setup script or manually on other systems, the general process of configuring a machine to serve as an IdM client is mostly the same, with slight variation depending on the platform:
  • Retrieve the CA certificate for the IdM CA.
  • Create a separate Kerberos configuration to test the provided credentials.
    This enables a Kerberos connection to the IdM XML-RPC server, necessary to join the IdM client to the IdM domain. This Kerberos configuration is ultimately discarded.
    Setting up the Kerberos configuration includes specifying the realm and domain details, and default ticket attributes. Forwardable tickets are configured by default, which facilitates connection to the administration interface from any operating system, and also provides for auditing of administration operations. For example, this is the Kerberos configuration for Red Hat Enterprise Linux systems: 
    [libdefaults]
default_realm = EXAMPLE.COM
dns_lookup_realm = false
dns_lookup_kdc = false
rdns = false
forwardable = yes
ticket_lifetime = 24h

[realms]
EXAMPLE.COM = {
      kdc = server.example.com:88
      admin_server = server.example.com:749
      }
[domain_realm]
.example.com = EXAMPLE.COM
example.com = EXAMPLE.COM
  • Run the ipa-join command to perform the actual join.
  • Obtain a service principal for the host service and installs it into /etc/krb5.keytab. For example, host/ipa.example.com@EXAMPLE.COM.
  • Enable certmonger, retrieve an SSL server certificate, and install the certificate in /etc/pki/nssdb.
  • Disable the nscd daemon.
  • Configure SSSD or LDAP/KRB5, including NSS and PAM configuration files.
  • Configure an OpenSSH server and client, as well as enabling the host to create DNS SSHFP records.
  • Configure NTP.

5.2. System Ports

IdM uses a number of ports to communicate with its services. IdM clients require the same ports as IdM servers, except for port 7389. You do not have to keep port 7389 open and available for clients in most usual deployments.
For the list of ports required by IdM and for information on how to make sure they are available, see Section 2.4.5, “System Ports”.

5.3. Configuring a Linux System as an IdM Client

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

5.3.1. Installing the Client (Full Example)

  1. Install the client packages. These packages provide a simple way to configure the system as a client; they also install and configure SSSD.
    For a regular user system, this requires only the ipa-client package: 
    [root@client ~]# yum install ipa-client
    An administrator machine requires the ipa-admintools package, as well: 
    [root@client ~]# yum install ipa-client ipa-admintools
  2. If the IdM server is configured as the DNS server and is in the same domain as the client, add the server's IP address as the first entry in the list of name servers in the client's /etc/resolv.conf file.

    Note

    If every machine in the domain will be an IdM client, then add the IdM server address to the DHCP configuration.
  3. Run the client setup command. 
    [root@client ~]# ipa-client-install --enable-dns-updates
    The --enable-dns-updates option updates DNS with the client machine's IP address. This option should only be used if the IdM server was installed with integrated DNS or if the DNS server on the network accepts DNS entry updates with the GSS-TSIG protocol.
    Options for ipa-client-install are listed in the ipa-client-install manpage.
  4. If prompted, enter the domain name for the IdM DNS domain. 
    DNS discovery failed to determine your DNS domain
Please provide the domain name of your IPA server (ex: example.com): example.com
  5. If prompted, enter the fully-qualified domain name of the IdM server. Alternatively, use the --server option with the client installation script to supply the fully-qualified domain name of the IdM server. 
    DNS discovery failed to find the IPA Server
Please provide your IPA server name (ex: ipa.example.com): server.example.com

    Important

    This must be a valid DNS name, which means only numbers, alphabetic characters, and hyphens (-) are allowed. Other characters, like underscores, in the hostname will cause DNS failures.
  6. The client script then prompts for a Kerberos identity to use to contact and then join the Kerberos realm. When these credentials are supplied, then the client is able to join the IdM Kerberos domain and then complete the configuration: 
    Continue to configure the system with these values? [no]: y 
User authorized to enroll computers: admin 
Synchronizing time with KDC... 
Password for admin@EXAMPLE.COM: 
Successfully retrieved CA cert 
Subject: CN=Certificate Authority,O=EXAMPLE.COM 
Issuer: CN=Certificate Authority,O=EXAMPLE.COM 
Valid From: Tue Aug 13 09:29:07 2013 UTC 
Valid Until: Sat Aug 13 09:29:07 2033 UTC 
Enrolled in IPA realm EXAMPLE.COM 
Created /etc/ipa/default.conf 
New SSSD config will be created 
Configured /etc/sssd/sssd.conf 
Configured /etc/krb5.conf for IPA realm EXAMPLE.COM 
Failed to update DNS records. 
Adding SSH public key from /etc/ssh/ssh_host_rsa_key.pub 
Adding SSH public key from /etc/ssh/ssh_host_dsa_key.pub 
Could not update DNS SSHFP records. 
SSSD enabled 
Configured /etc/openldap/ldap.conf 
NTP enabled 
Configured /etc/ssh/ssh_config 
Configured /etc/ssh/sshd_config 
Client configuration complete.
  7. Test that the client can connect successfully to the IdM domain and can perform basic tasks. For example, check that the IdM tools can be used to get user and group information: 
    [jsmith@client ~]$ id
[jsmith@client ~]$ getent passwd admin
[jsmith@client ~]$ getent group admins
  8. If an NFS server is already configured, then set NFS on the client system to work with Kerberos.
    An NFS server must already be configured within the domain. This is covered in Section 18.2, “Configuring Automount”.

    Note

    To help troubleshoot potential NFS setup errors, enable debug information in the /etc/sysconfig/nfs file. 
    RPCGSSDARGS="-vvv"
RPCSVCGSSDARGS="-vvv"
    1. On an IdM server, add an NFS service principal for the NFS client. 
      [root@client ~]# kinit admin
[root@client ~]# ipa service-add nfs/ipaclient.example.com@EXAMPLE

      Note

      This must be run from a machine with the ipa-admintools package installed so that the ipa command is available.
    2. On the IdM server, obtain a keytab for the NFS service principal. 
      [root@client ~]# ipa-getkeytab -s server.example.com -p nfs/ipaclient.example.com@EXAMPLE -k /tmp/krb5.keytab
    3. Copy the keytab from the IdM server to the IdM client. For example: 
      [root@client ~]# scp /tmp/krb5.keytab root@client.example.com:/etc/krb5.keytab
    4. Configure the /etc/exports file on the NFS server. 
      /ipashare       gss/krb5p(rw,no_root_squash,subtree_check,fsid=0)
    5. Create the mount point. 
      [root@client ~]# mkdir /mnt/ipashare
    6. On the client, mount the NFS share. Use the same -o sec setting as is used in the /etc/exports file for the NFS server. 
      [root@client ~]# mount -v -t nfs4 -o sec=krb5p nfs.example.com:/ /mnt/ipashare

5.3.2. Examples of Other Client Installation Options

There are a number of different configuration options with the ipa-client-install command which can be used to configure the client system in different ways, depending on the infrastructure requirements.

Example 5.1. Enabling DNS Updates

Depending on the DHCP configuration, the IP addresses of clients can change with some regularity. If the IP address changes, this can cause discrepancies between the DNS records in the IdM server and the actual IP addresses in use, which could affect policies set within IdM and communications between clients and services.
The --enable-dns-updates option sets the System Security Services Daemon to update the DNS entries whenever the IP address for a client changes. 
[root@client ~]# ipa-client-install --enable-dns-updates

Example 5.2. Specifying Domain Information

When just running the client installation command, the script prompts for required IdM domain information, including the name of an IdM server to register with, the DNS domain name, and the Kerberos realm and principal.
All of the basic information can be passed with the installation command (which is useful for automated installations).
  • --domain for the DNS domain name (which is only used if the IdM server is configured to host DNS services)
  • --server for the IdM server to register with (which can be any server or replica in the topology)
    This must be a valid DNS name, which means only numbers, alphabetic characters, and hyphens (-) are allowed. Other characters, like underscores, in the hostname will cause DNS failures.
  • --realm for the Kerbero realm name and, optionally, -p for a Kerberos principal name 
[root@client ~]# ipa-client-install --domain EXAMPLE.COM --server server.example.com --realm EXAMPLE -p host/server.example.com

Example 5.3. Setting a Specific IdM Server

There can be multiple servers and replicas within the IdM server topology. When a client needs to connect to a server for updates or to retrieve user information, it (by default) uses a service scan to discover available servers and replicas in the domain. This means that the actual server to which the client connects is random, depending on the results of the discovery scan.
It is possible to set a specific server within the IdM domain which is used for client updates; if for some reason, connecting to that server fails, then the client can discover another server within the domain for failover.
The preferred server is set in the --fixed-primary option. 
[root@client ~]# ipa-client-install --fixed-primary server.example.com

Example 5.4. Disabling System Authentication Tools

Red Hat Enterprise Linux uses the authconfig tool to set and update authentication clients and settings for a local system. Identity Management uses the System Security Services Daemon (SSSD) to store IdM server configuration and to retrieve policy information, users, passwords, and groups configured within the IdM domain.
It is strongly recommended that you use authconfig and SSSD to manage your user, group, and other IdM client configuration.
There may be some situations where an administrator wants to disable dynamic changes to system authentication configuration. In that case, it is possible to disable IdM from making updates to authconfig or SSSD.
The --noac option prevents any changes through authconfig. The --no-sssd option prevents IdM from using SSSD. 
[root@client ~]# ipa-client-install --noac --no-sssd
A related option is --preserve-sssd. While this allows the client to change the SSSD configuration file to configure the IdM domain, it saves the old SSSD configuration.

Example 5.5. Disabling Password Caching

One of the primary functions of SSSD is password caching. Normally, when a system uses an external password store, authentication fails if that password store is ever inaccessible. However, SSSD can cache passwords after a successful authentication attempt and store those passwords locally. This allows users to log in and access domain services (which they have previously accessed) even if the IdM server is inaccessible.
In highly-secure environments, it may be necessary to prevent password caching to prevent potentially unauthorized access. In that case, the --no-krb5-offline-passwords option can be used to prevent passwords from being cached in SSSD. 
[root@client ~]# ipa-client-install --no-krb5-offline-passwords

5.4. Manually Configuring a Linux Client

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

5.4.1. Setting up an IdM Client (Full Procedure)

  1. Install SSSD, if it is not already installed.
  2. Optional. Install the IdM tools so that administrative tasks can be performed from the host. 
    [root@client ~]# yum install ipa-admintools
  3. On an IdM server. Create a host entry for the client. 
    [jsmith@client ~]$ kinit admin
[jsmith@client ~]$ ipa host-add --force --ip-address=192.168.166.31 ipaclient.example.com
    Creating hosts manually is covered in Section 5.4.2, “Other Examples of Adding a Host Entry”.
  4. On an IdM server. Create keytabs for the client.
    1. Log in as IdM administrator. 
      [jsmith@client ~]$ kinit admin
    2. Set the client host to be managed by the server. 
      [jsmith@client ~]$ ipa host-add-managedby --hosts=server.example.com ipaclient.example.com
    3. Generate the keytab for the client. 
      [jsmith@client ~]$ ipa-getkeytab -s server.example.com -p host/ipaclient.example.com -k /tmp/ipaclient.keytab
  5. Copy the keytab to the client machine and rename it /etc/krb5.keytab.

    Note

    If there is an existing /etc/krb5.keytab that should be preserved, the two files can be combined using ktutil.
  6. Set the correct user permissions for the /etc/krb5.keytab file. 
    [root@client ~]# chown root:root /etc/krb5.keytab 
[root@client ~]# chmod 0600 /etc/krb5.keytab
  7. Set the SELinux contexts for the /etc/krb5.keytab file. 
    [root@client ~]# chcon system_u:object_r:krb5_keytab_t:s0 /etc/krb5.keytab
  8. Configure SSSD by editing the /etc/sssd/sssd.conf file to point to the IdM domain. 
    [root@client ~]# touch /etc/sssd/sssd.conf
[root@client ~]# vim /etc/sssd/sssd.conf

[sssd]
config_file_version = 2
services = nss, pam

domains = example.com
[nss]

[pam]

[domain/example.com]
cache_credentials = True
krb5_store_password_if_offline = True
ipa_domain = example.com
id_provider = ipa
auth_provider = ipa
access_provider = ipa
ipa_hostname = ipaclient.example.com
chpass_provider = ipa
ipa_server = server.example.com
ldap_tls_cacert = /etc/ipa/ca.crt
  9. Configure NSS to use SSSD for passwords, groups, users, and netgroups. 
    [root@client ~]# vim /etc/nsswitch.conf

...
passwd:     files sss
shadow:     files sss
group:      files sss
...
netgroup:   files sss
...
  10. Configure the /etc/krb5.conf file to point to the IdM KDC. 
    [logging]
 default = FILE:/var/log/krb5libs.log
 kdc = FILE:/var/log/krb5kdc.log
 admin_server = FILE:/var/log/kadmind.log

[libdefaults]
 default_realm = EXAMPLE.COM
 dns_lookup_realm = false
 dns_lookup_kdc = false
 rdns = false
 ticket_lifetime = 24h
 forwardable = yes
 allow_weak_crypto = true

[realms]
 EXAMPLE.COM = {
  kdc = server.example.com:88
  admin_server = server.example.com:749
  default_domain = example.com
}

[domain_realm]
 .example.com = EXAMPLE.COM
 example.com = EXAMPLE.COM
  11. Update the /etc/pam.d configuration to use the pam_sss.so modules.
    • For /etc/pam.d/fingerprint-auth: 
      ...
account     [default=bad success=ok user_unknown=ignore] pam_sss.so
...
session     optional      pam_sss.so
    • For /etc/pam.d/system-auth: 
      ...
auth        sufficient    pam_sss.so use_first_pass
...
account     [default=bad success=ok user_unknown=ignore] pam_sss.so
...
password    sufficient    pam_sss.so use_authtok
...
session     optional      pam_sss.so
    • For /etc/pam.d/password-auth: 
      ...
auth        sufficient    pam_sss.so use_first_pass
...
account     [default=bad success=ok user_unknown=ignore] pam_sss.so
...
password    sufficient    pam_sss.so use_authtok
...
session     optional      pam_sss.so
    • Enrollment_with_Separation_of_DutiesFor /etc/pam.d/smartcard-auth: 
      ...
account     [default=bad success=ok user_unknown=ignore] pam_sss.so
...
session     optional      pam_sss.so
  12. Install the IdM server's CA certificate.
    1. Obtain the certificate from the server. 
      [root@ipaclient ~]# wget -O /etc/ipa/ca.crt http://ipa.example.com/ipa/config/ca.crt
    2. Install the certificate in the system's NSS database. 
      [root@ipaclient ~]# certutil -A -d /etc/pki/nssdb -n "IPA CA" -t CT,C,C -a -i /etc/ipa/ca.crt
  13. Set up a host certificate for the host in IdM.
    1. Make sure certmonger is running. 
      [root@ipaclient ~]# service certmonger start

      Note

      Configure chkconfig so that the certmonger service starts by default. 
      [root@ipaclient ~]# chkconfig certmonger on
    2. Use the ipa-getcert command, which creates and manages the certificate through certmonger. The options are described more in Section B.1, “Requesting a Certificate with certmonger”. 
      [root@ipaclient ~]# ipa-getcert request -d /etc/pki/nssdb -n Server-Cert -K HOST/ipaclient.example.com -N 'CN=ipaclient.example.com,O=EXAMPLE.COM'
    If administrative tools were not installed on the client, then the certificate can be generated on an IdM server, copied over to the host, and installed using certutil.
  14. Set up NFS to work with Kerberos.

    Note

    To help troubleshoot potential NFS setup errors, enable debug information in the /etc/sysconfig/nfs file. 
    RPCGSSDARGS="-vvv"
RPCSVCGSSDARGS="-vvv"
    1. On an IdM server, add an NFS service principal for the NFS client. 
      [root@ipaclient ~]# ipa service-add nfs/ipaclient.example.com@EXAMPLE

      Note

      This must be run from a machine with the ipa-admintools package installed so that the ipa command is available.
    2. On the IdM server, obtain a keytab for the NFS service principal. 
      [root@ipaclient ~]# ipa-getkeytab -s server.example.com -p nfs/ipaclient.example.com@EXAMPLE -k /tmp/krb5.keytab

      Note

      Some versions of the Linux NFS implementation have limited encryption type support. If the NFS server is hosted on a version older than Red Hat Enterprise Linux 6, use the -e des-cbc-crc option to the ipa-getkeytab command for any nfs/<FQDN> service keytabs to set up, both on the server and on all clients. This instructs the KDC to generate only DES keys.
      When using DES keys, all clients and servers that rely on this encryption type need to have the allow_weak_crypto option enabled in the [libdefaults] section of the /etc/krb5.conf file. Without these configuration changes, NFS clients and servers are unable to authenticate to each other, and attempts to mount NFS filesystems may fail. The client's rpc.gssd and the server's rpc.svcgssd daemons may log errors indicating that DES encryption types are not permitted.
    3. Copy the keytab from the IdM server to the NFS server. For example, if the IdM and NFS servers are on different machines: 
      [root@ipaclient ~]# scp /tmp/krb5.keytab root@nfs.example.com:/etc/krb5.keytab
    4. Copy the keytab from the IdM server to the IdM client. For example: 
      [root@ipaclient ~]# scp /tmp/krb5.keytab root@client.example.com:/etc/krb5.keytab
    5. Configure the /etc/exports file on the NFS server. 
      /ipashare       gss/krb5p(rw,no_root_squash,subtree_check,fsid=0)
    6. On the client, mount the NFS share.
      • Always specify the share as nfs_server:/ /mountpoint.
      • Use the same -o sec setting as is used in the /etc/exports file for the NFS server. 
      [root@client ~]# mount -v -t nfs4 -o sec=krb5p nfs.example.com:/ /mnt/ipashare

5.4.2. Other Examples of Adding a Host Entry

Section 5.4.1, “Setting up an IdM Client (Full Procedure)” covers the full procedure for configuring an IdM client manually. One of those steps is creating a host entry, and there are several different ways and options to perform that.
5.4.2.1. Adding Host Entries from the Web UI
  1. Open the Identity tab, and select the Hosts subtab.
  2. Click the Add link at the top of the hosts list.
  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.
    DNS zones can be created in IdM, which is described in Section 17.6.1, “Adding Forward 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 checkbox to add the host DNS record, even if the hostname cannot be resolved.
    This is useful for hosts which use DHCP and do not have a static IP address. 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.
  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.
5.4.2.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 hostname 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 5.6. 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're 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 5.7. 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

5.5. Setting up a Linux Client Through Kickstart

A kickstart enrollment automatically adds a new system to the IdM domain at the time it is provisioned.
This requires pre-creating the hosts on the IdM server, with a predefined password that can be used to authenticate to complete the enrollment operation.
  1. Create the host entry on the IdM server and set a temporary Kerberos password for the entry.
    When the ipa-client-install script is run normally (interactively), it prompts for authentication credentials to access the IdM domain. However, when the script is run automatically, the system has to have some way to access the IdM domain without using an existing IdM user; this is done by setting the host principal in the script and using a Kerberos password (configured for the host account) to access the IdM domain.
    For example: 
    [jsmith@server ~]$ ipa host-add kickstart-server.example.com --password=secret
    The password expires after the first authentication attempt. After enrollment completes, the host is authenticated using its keytab.
  2. Include the ipa-client package with the other install packages. 
    %packages
@ X Window System 
@ Desktop 
@ Sound and Video					
ipa-client
...
  3. Create a post-install instruction that ensures SSH keys are generated before enrollment, runs the ipa-client-install script, passes all the required information to access and configure the IdM domain services, and specifies the pre-set password. Use the --unattended option to instruct the script to run non-interactively. 
    %post --log=/root/ks-post.log

# Generate SSH keys to ensure that ipa-client-install uploads them to the IdM server
/usr/bin/ssh-keygen -q -t rsa -f /etc/ssh/ssh_host_rsa_key -C '' -N ''
chmod 600 /etc/ssh/ssh_host_rsa_key
chmod 644 /etc/ssh/ssh_host_rsa_key.pub
/sbin/restorecon /etc/ssh/ssh_host_rsa_key.pub

/usr/bin/ssh-keygen -q -t rsa1 -f /etc/ssh/ssh_host_key -C '' -N ''
chmod 600 /etc/ssh/ssh_host_key
chmod 644 /etc/ssh/ssh_host_key.pub
/sbin/restorecon /etc/ssh/ssh_host_key.pub

/usr/bin/ssh-keygen -q -t dsa -f /etc/ssh/ssh_host_dsa_key -C '' -N ''
chmod 600 /etc/ssh/ssh_host_dsa_key
chmod 644 /etc/ssh/ssh_host_dsa_key.pub
/sbin/restorecon /etc/ssh/ssh_host_dsa_key.pub

# Get the hostname to set as the host principal	
/bin/hostname > /tmp/hostname.txt

# Run the client install script
/usr/sbin/ipa-client-install --domain=EXAMPLEDOMAIN --enable-dns-updates --mkhomedir -w secret --realm=EXAMPLEREALM --server=server.example.com --unattended

    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.
  4. Run the kickstart script.

5.6. Performing a Two-Administrator Enrollment

Enrolling machines as clients in the IdM domain is a two-part process. A host entry is created for the client (and stored in the 389 Directory Server instance), and then a keytab is created to provision the client.
Both parts are performed automatically by the ipa-client-install command. It is also possible to perform those steps separately; this allows for administrators to prepare machines and the IdM server configuration in advance of actually configuring the clients. This allows more flexible setup scenarios, including bulk deployments.
When performing a manual enrollment, the host entry is created separately, and then enrollment is completed when the client script is run, which creates the requisite keytab.

Note

There are two ways to set the password. You can either supply your own or have IdM generate a random one.
There may be a situation where an administrator in one group is prohibited from creating a host entry and, therefore, from simply running the ipa-client-install command and allowing it to create the host. However, that administrator may have the right to run the command after a host entry exists. In that case, one administrator can create the host entry manually, then the second administrator can complete the enrollment by running the ipa-client-install command.
  1. An administrator creates the host entry, as described in Section 5.4.2, “Other Examples of Adding a Host Entry”.
  2. The second administrator installs the IdM client packages on the machine, as in Section 5.3, “Configuring a Linux System as an IdM Client”.
  3. When the second administrator runs the setup script, he must pass his Kerberos password and username (principal) with the ipa-client-install command. For example: 
    $ ipa-client-install -w secret -p admin2
  4. The keytab is generated on the server and provisioned to the client machine, so that the client machine is not able to connect to the IdM domain. The keytab is saved with root:root ownership and 0600 permissions.

5.7. Manually Unconfiguring Client Machines

A machine may need to be removed from one IdM domain and moved to another domain or a virtual machine may be copied. There are a number of different situations where an IdM client needs to be reconfigured. The easiest solution is to uninstall the client and then configure it afresh. Use the --updatedns option, as when installing a client, to update the domain DNS configuration automatically. 
[root@server ~]# ipa-client-install --uninstall --updatedns
If it is not possible to uninstall the client directly, then the IdM configuration can be manually removed from the client system.

Warning

When a machine is unenrolled, the procedure cannot be undone. The machine can only be enrolled again.
  1. On the client, remove the old hostname from the main keytab. This can be done by removing every principal in the realm or by removing specific principals. For example, to remove all principals: 
    [jsmith@client ~]$ ipa-rmkeytab -k /etc/krb5.keytab -r EXAMPLE.COM
    To remove specific principals: 
    [jsmith@client ~]$ ipa-rmkeytab -k /etc/krb5.keytab -p host/server.example.com@EXAMPLE.COM
  2. On the client system, disable tracking in certmonger for every certificate. Each certificate must be removed from tracking individually.
    First, list every certificate being tracked, and extract the database and nickname for each certificate. The number of certificates depends on the configured services for the host. 
    [jsmith@client ~]$ ipa-getcert list
    Then, disable tracking for each. For example: 
    [jsmith@client ~]$ ipa-getcert stop-tracking -n "Server-Cert" -d /etc/httpd/alias
  3. On the IdM server, remove the old host from the IdM DNS domain. While this is optional, it cleans up the old IdM entries associated with the system and allows it to be re-enrolled cleanly at a later time. 
    [jsmith@server ~]$ kinit admin
[jsmith@server ~]$ ipa host-del server.example.com
  4. If the system should be re-added to a new IdM domain — such as a virtual machine which was moved from one location to another — then the system can be rejoined to IdM using the ipa-join command on the client system. 
    [jsmith@client ~]$ ipa-join

Chapter 6. Upgrading Identity Management

Identity Management is generally updated whenever a system is upgraded to a new release. Upgrades should be transparent and do not require any user or administrative intervention.

6.1. Upgrade Notes

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) and TLSv1.1. 
    NSSProtocol TLSv1.0,TLSv1.1
  2. Restart the httpd service. 
    # service httpd restart
  • The update process automatically updates all schema and LDAP configuration, Apache configuration, and other services configuration, and restarts all IdM-associated services.
  • When a replica is created, it must be the same version as the master it is based on. This means that replicas should not be created on an older bersion of Identity Management while the servers are in the process of being upgraded. Wait until the upgrade process is completed, and then create new replicas.
  • Schema changes are replicated between servers. So once one master server is updated, all servers and replicas will have the updated schema, even if their packages are not yet updated. This ensures that any new entries which use the new schema can still be replicated among all the servers in the IdM domain.
    The LDAP upgrade operation is logged in the upgrade log at /var/log/ipaupgrade-log. If any LDAP errors occur, then they are recorded in that log. Once any errors are resolved, the LDAP update process can be manually initiated by running the updater script: 
    [root@server ~]# ipa-ldap-updater --upgrade
  • Clients do not need to have new packages installed. The client packages used to configure a Red Hat Enterprise Linux system do not impact the enrollment of the client within the domain.
  • Updating client packages could bring in updated packages for other dependencies, such as certmonger which contain bug fixes, but this is not required to maintain client functionality or behavior within the IdM domain.

6.2. Upgrading Packages

The IdM server packages are updated when the system packages are updated: 
[root@ipaserver ~]# yum update
This is the easiest way to upgrade the server because it automatically pulls in updates for related services, like SSSD, which provide Identity Management functionality.
To upgrade the IdM server packages specifically, run yum on the master server: 
[root@ipaserver ~]# yum update ipa-server
It can take several seconds for the update process to apply all of the changes.

Note

It is not necessary to update all servers and replicas at precisely the same time; the IdM servers will still work with each other and replicate data successfully. The older IdM servers will simply lack the new features.

6.3. Removing Browser Configuration for Ticket Delegation (For Upgrading from 6.2)

As part of establishing Kerberos authentication, a principal is given a ticket granting ticket (TGT). Whenever that principal attempts to contact a service or application within the Kerberos domain, the service checks for an active TGT and then requests its own service-specific ticket from the TGT for that principal to access that service.
As part of configuring the web browser used to access the IdM web UI (and any other Kerberos-aware web applications), previous versions of Identity Management required that the TGT delegation be forwarded to the IdM server. This required adding the delegation-uris parameter to the about:config setup in Firefox: 
network.negotiate-auth.delegation-uris .example.com
In Red Hat Enterprise Linux 6.3, Identity Management uses the Kerberos Services for User to Proxy (S4U2Proxy), so this additional delegation step is no longer required.
Updating Existing Configured Browsers

For browsers which have already been configured to use the Identity Management web UI, the delegation-uris setting can be cleared after upgrading to ipa-server-3.0.0 or ipa-client-3.0.0.

There is no need to restart the browser after changing the delegation-uris setting.
Updating configure.jar for New Browser Configuration

The browser configuration is defined in the configure.jar file. This JAR file is generated when the server is installed and it is not updated with other files when IdM is updated. Any browsers configured will still have the delegation-uris parameter set unnecessarily, even after the IdM server is upgraded. However, the configure.jar file can be updated.

The preferences.html file in configure.jar sets the delegation-uris parameter. The updated preferences.html file can be added to configure.jar, and then configure.jar can be re-signed and re-deployed on the IdM servers.

Note

Only update the configure.jar file on the initial IdM server. This is the master server, and it is the only server which has a signing certificate. Then propagate the updated file to the other servers and replicas.
  1. Update the packages on the initial IdM master server (the first instance). This will bring in the 3.0 UI packages, including the configure.jar file.
  2. Back up the existing configure.jar file. 
    [root@ipaserver ~]# mv /usr/share/ipa/html/configure.jar /usr/share/ipa/html/configure.jar.old
  3. Create a temporary working directory. 
    [root@ipaserver ~]# mkdir /tmp/sign
  4. Copy the updated preferences.html file to the working directory. 
    [root@ipaserver ~]# cp /usr/share/ipa/html/preferences.html /tmp/sign
  5. Use the signtool command (one of the NSS utilities) to add the new preferences.html file and re-sign the configure.jar file. 
    [root@ipaserver ~]# signtool -d /etc/httpd/alias -k Signing-Cert -Z /usr/share/ipa/html/configure.jar -e ".html" -p `cat /etc/httpd/alias/pwdfile.txt` /tmp/sign
    The -e option tells the tool to sign only files with a .html extension. The -Z option creates a new JAR file.
  6. Copy the regenerated configure.jar file to all other IdM servers and replicas.

6.4. Testing Before Upgrading the IdM Server (Recommended)

It can be beneficial, and safer, to test newer versions of Identity Management before upgrading production systems. There is a relatively simple way to do this by creating a sacrificial replica and testing on that system.
  1. Set up a replica based on one of the production servers, with the same version of IdM as is running in production, as described in Chapter 4, Setting up IdM Replicas. For this example, this is called Test Replica. Make sure that Test Replica can successfully connect to the production server and domain.
  2. After verifying that Test Replica has been successfully added to the production domain, disconnect Test Replica from the network.
  3. Remove the replication agreements for Test Replica from the original IdM server and from Test Replica.
  4. Reconnect Test Replica to the network.
  5. Upgrade the packages on Test Replica using yum or whatever package update tool is appropriate for your system. For example: 
    [root@ipareplica ~]# yum update ipa*
  6. Test common things on Test Replica, like getting Kerberos credentials, opening the server UI, and running commands.

Chapter 7. Uninstalling IdM Servers and Replicas

To uninstall both an IdM server and an IdM replica, pass the --uninstall option to the ipa-server-install command: 
[root@ipareplica ~]# ipa-server-install --uninstall

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

All of the access to Identity Management, both through the web UI and through the command line, is done by a user authenticating to the IdM domain. This chapter covers the basics of setting up browsers to handle Kerberos authentication, logging into Identity Management, and troubleshooting some common connection issues.

8.1. Starting and Stopping the IdM Domain

When an IdM server is installed, there are a number of different services which can be installed and configured with it in any combination, including (but not limited to) a Directory Server, a certificate authority, a web server, DNS, NTP, certmonger, and Kerberos.
All of these serveris work together in concert. Because there are dependencies between the services, the order in which services are started and stopped is critical.
When changes are made to a single service (such as the LDAP directory or the web server), then that individual service can be started and stopped using the service command. However, when multiple domain services need to be restarted (or the entire IdM server), then use the ipactl command, which always starts and stops services in the appropriate order.
Which services are configured for a specific IdM server are defined in the 389 Directory Server configuration, based on the hostname of the IdM server.[1] The 389 Directory Server service is always the first service started and the last service stopped. The rest of the run order depends on the configured services.
The ipactl command can start, stop, and restart services. 
ipactl start | stop | restart
The chkconfig command sets what services to start automatically when the system restarts. The ipactl command can be used to start the domain services in the proper order, without having to configure each one individually in the chkconfig run order. 
[root@server ~]# chkconfig ipactl on

8.2. About the IdM Client Tools

IdM creates a domain of recognized services, host machines, and users with universally-applied authentication sources and common policies. From the perspective of a client machine and an IdM user, the domain itself is fairly transparent after the initial configuration. All users need to do is log into the domain using Kerberos, and that's it.
However, an administrator has two ongoing tasks: add principals to the IdM Kerberos domain and set the domain policies and server configuration that govern domain interactions. Identity Management has both command-line and web-based interfaces for administrators to use to manage the domain, services, and IdM entries.
The most common method to maintain the domain is using the command-line tools. Identity Management has an incredibly broad set of scripts and commands that are available to administrators. The entry management functions of the domain are carried out with a single script: ipa. This script is a parent or control script for associated subcommands; each subcommand relates to a specific entry type.
The command-line scripts offer a number of benefits:
  • The scripts allow management tasks to be automated and performed repeatedly in a consistent way without manual intervention.
  • Entries can be added with all possible attributes configured (or a desired subset of attributes) in a single step. The web UI frequently requires two steps to fully configure an entry: the first to create the entry and the next to add optional attributes.
  • The command-line scripts support adding additional attributes which may not be available in the UI or even custom attributes to entries, if the schema is configured.

8.2.1. The Structure of the ipa Command

The ipa command is essentially a big plug-in container. It supports dozens of subcommands; these subcommands are actually plug-ins which manage specific types of objects in Identity Management.
The first type of a subcommand identifies the object type (such as user, sudo, group, host, or dns), and the second part identifies the operation being performed on that object. 
ipa objectType-operation objectName --option=value
For example, adding a user is done using the user-add subcommand: 
ipa user-add entryName options
Related subcommands are grouped together into plug-in modules. Commands for managing DNS entries like dnszone-add and dnsrecord-add all belong to the dns module or topic. All of the information for managing a specific area, with all of the supported commands and examples for each, are available by viewing the help for that topic: 
ipa help topic

Note

To get a list of all available topics: 
ipa help topics
All topic or command areas follow a consistent pattern for how entries are managed.
8.2.1.1. Adding, Editing, and Deleting Entries with ipa
New entries are added using an *-add command. For example: 
$ ipa user-add jsmith
For add operations, commands usually prompt for any required configuration attributes, which can be passed as command-line options or using --set/addattr options (Section 8.2.3, “Managing Entry Attributes with --setattr, --addattr, and --delattr”). 
$ ipa user-add
First name: John
Last name: Smith
User login [jsmith]: jsmith
--------------------
Added user "jsmith"
--------------------
...
Likewise, entries are usually edited through a *-mod commands, and then any new or edited attributes are listed as options after it. 
$ ipa user-mod jsmith --title="Editor III"
Last, entries can be deleted using the *-del command and the entry's name. 
$ ipa user-del jsmith
8.2.1.2. Finding and Displaying Entries with ipa
Entries for an entire type are searched for using the *-find command and an optional search criterion. The criterion is a string which can either be an exact match or a substring of any of the search attribute values. For example, this searches both for the exact match on the string smith (such as an sn value of Smith) and a substring search for values such as a username of jsmith or a longer surname, such as Smithson. 
ipa user-find smith
All searches are automatically substring searches; it is not necessary to specify a wildcard.
With no search criterion, every entry of that type is displayed.
Searches (any *-find command) have certain limits imposed as part of the server configuration, specifically how many entries are returned (size limits) and how long a search will run (time limits). This is covered in Section 9.11.3.1.2, “Setting IdM Search Limits”. Part of the server configuration is setting global defaults for size and time limits on searches. While these limits are always enforced in the web UI, they can be overridden with any *-find command with the --sizelimit and --timelimit options. For example, if the default time limit is 60 seconds and a search is going to take longer, the time limit can be increased to 120 seconds: 
[jsmith@ipaserver ~]$ ipa user-find smith --timelimit=120
Not every possible attribute in an entry type can be searched for. A certain subset of attributes are predefined and indexed for searches. (This list is configurable for users and groups, but not for other types of entries.)
When entries are returned, only certain default attributes are displayed with the entry; to return all attributes currently set for entries, use the --all option.
To display a specific entry, use the *-show command and the entry name. As with searches, only a subset of attributes is displayed with the entry unless the --all option is used.
8.2.1.3. Adding Members to Groups and Containers with ipa
Group members are added and removed with separate commands, apart from simply modifying an entry. Member commands essentially create a relationship between different IdM entries. While this is obvious in traditional group-member roles, it is also true for some policy entries (like SELinux and sudo policies) where entries are associated with another entry.
Most commonly, the command format for adding a member entry is *-add-member, although the command may specify an entry type, such as *-add-user.
Likewise, entries are removed as members (not deleted) using a *-remove-member or *-remove-type command.

8.2.2. Positional Elements in ipa Commands

Usually, ipa subcommands have only two elements: the name of the entry being modified (the object) and then any options available for the subcommand: 
ipa command entryName --options=values
With a few types of entries, however, not only the entry name itself needs to be specified; the entry's parent must also be specified. This is the case with automount commands, for example. With automount, the location must be included whenever a new key or map is created.
The parent entry name is given first, and then the child entry name. For example, for automount, the location is given first, and then the map or key entry name. 
ipa command parentEntryName childEntryName --childOptions=childValues

8.2.3. Managing Entry Attributes with --setattr, --addattr, and --delattr

All identities and configuration in Identity Management are stored as LDAP entries, with standard attribute-value assertions (AVAs). Whether an entry is created through the UI or the CLI, there are certain attributes which are required and others which are available, depending on the default and custom object classes for that entry type.
For the most common attributes, the ipa command uses specified command-line arguments to set values. For example, adding a mail attribute to a user can be done with the --mail argument; enabling dynamic updates for a DNS zone can be done with the --allow-dynupdate option with zone commands; and a map key for an automount map is given in the --key option.
However, entries can also allow attributes that may not have command-line (or UI) options for setting them. Partially, this is because the underlying LDAP schema is very rich, particularly for user entries, with many possible allowed attributes. Additionally, Identity Management allows schema extensions for users and groups, and those custom schema elements are not necessarily reflected in the UI or command-line tools.
Any supported attribute can be added or edited to an entry using the --setattr and --addattr options.

Important

The value of the attribute being added is not validated by the modify command or the --setattr or --addattr options.
Both options have this format: 
--setattr=attribute=value
The --setattr option sets one value for the given attribute; any existing values are overwritten, even for multi-valued attributes.
The --addattr option adds a new value for an attribute; for a multi-valued attribute, it adds the new value while preserving any existing values.
Both --setattr option and --addattr can be used multiple times in the same command invocation. For example: 
$ ipa user-mod jsmith --addattr=mail=johnnys@me.com --addattr=mail=jsmith@example.com --setattr=description="backup IT manager for the east coast branch"
Likewise, an attribute or specific attribute value can be removed from an entry using the --delattr option. For a single-valued attribute, this removes the attribute; for a multi-valued attribute, it removes only the specified value. For example: 
$ ipa user-mod jsmith --delattr=mail=johnnys@me.com

Note

Deleting attributes is evaluated last, after adding or editing attributes. If the same attribute is added and deleted in the same modify operation, it is a no-op. 
$ ipa user-mod jsmith --addattr=mail=johnnys@me.com --delattr=mail=johnnys@me.com

8.2.4. Using Special Characters with IdM Tools

The IdM command-line tools are run as any other utilities in a shell. If there are special characters in the command — such as angle brackets (> and <), ampersands (&), asterisks (*), and pipes (|) — the characters must be escaped. Otherwise, the command fails because the shell cannot properly parse the unescaped characters.

8.2.5. Logging into the IdM Domain Before Running

Before running any IdM commands (with the exception of the installation scripts, such as ipa-server-install), the user must first authenticate to the IdM domain by obtaining a Kerberos ticket. This is done using kinit: 
[jsmith@ipaserver ~]$ kinit admin
Different login options are described in Section 8.3, “Logging into IdM”.

8.3. Logging into IdM

Users are authenticated to IdM services, including the command-line tools and the web UI, using Kerberos authentication. This means that logging into Identity Management requires running kinit.
Running kinit issues the user a Kerberos ticket. This ticket is checked by any IdM or Kerberos-aware service, so that a user only needs to log in once to access all domain services. Domain services include the IdM web UI, mounted file shares, wikis, or any other application which uses IdM as its identity/authentication store.

8.3.1. Logging into IdM

Logging into Identity Management requires running kinit on a client within the IdM domain. 
$ kinit
The kinit command must be run from a machine which has been configured as a client within the IdM domain, so that the client authenticates with the IdM KDC.
Simply running kinit logs into IdM as the currently logged-in user account. This user account must also be an IdM user for them to authenticate to the IdM Kerberos domain successfully. For example, if you are logged into the machine as user: 
$ kinit
Password for user@EXAMPLE.COM:

Note

If SSSD or pam_krb5 is configured on the IdM client machine, then when a user logs into the machine, a ticket is created which can be used for machine services which require authentication, such as sudo.

8.3.2. Logging in When an IdM User Is Different Than the System User

A person's system user name is different from the IdM user name. To specify an IdM user name or to switch accounts, simply run the kinit command again and specify the new user. For example: 
$ kinit userName 
Password for userName@EXAMPLE.COM:
When the server is first set up, an administrative user, admin, is created to perform normal administrative activities. To authenticate as the admin user, use the name admin when running kinit: 
$ kinit admin

Note

Only one set of tickets can be stored per logged-in user. The current stored credentials are the ones that will be used when accessing IdM services.
If you were already connected to the IdM web UI as another user, refresh the browser to display the updated details for the new user.

8.3.3. Checking the Current Logged in User

Use the klist command to verify the identity and the ticket granting ticket (TGT) from the server: 
$ klist
Ticket cache: FILE:/tmp/krb5cc_500
Default principal: ipaUser@EXAMPLE.COM

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

Kerberos 4 ticket cache: /tmp/tkt500
klist: You have no tickets cached
It's important to know who the authenticated user is because the currently-authenticated user is the only one who can access the IdM services. The Kerberos client libraries for kinit have some limitation, one of them being that the current ticket is overwritten with any new invocation of kinit. Authenticating as User A and then authenticating as User B overwrites User A's ticket.
To allow there to be multiple authenticated users on a machine, set the KRB5CCNAME environment variable. This variable keeps credential caches separate in different shells.

8.3.4. Caching User Kerberos Tickets

Only one set of tickets can be stored per logged-in user. The current stored credentials are the ones that will be used when accessing IdM services.
For example, if you authenticated as admin, added a new user, set the password, and then tried to authenticate as that user, the administrator's ticket is lost.
To keep separate credential caches in different shells, a special environment variable, KRB5CCNAME, can be used.

8.4. Using the IdM Web UI

In order to use the web UI, the user must be authenticated with the IdM Kerberos domain and have an active Kerberos ticket, see Section 8.3, “Logging into IdM”. Generally, the web UI can only be accessed from an IdM server or client machine and the user must be locally authenticated. There are a couple of ways to work around this, either by configuring Kerberos on a non-domain machine to connect to the Kerberos domain, see Section 8.4.4, “Using a Browser on Another System”, or by password authentication to the UI.

8.4.1. About the Web UI

The web UI has three major functional areas which correspond to each of the major functions of IdM: identity management, policy management, and domain configuration.
Table 8.1. Configuration Areas Per Tab
Main Menu Tab Configuration Areas
Identity
  • User entries
  • User groups entries
  • Host/client entries
  • Host group entries
  • Netgroups entries
  • Domain services entries
  • DNS (if configured)
Policy
  • Host-based access control
  • Sudo rules
  • Automount
  • User password policies
  • Kerberos ticket policy
IdM Server (access controls within Identity Management)
  • Role-based access control (permissions based on group membership)
  • Self permissions
  • Delegations (user access control over other users)
The main menu at the top of every page has three tabs which correspond to the functional areas listed in Table 8.1, “Configuration Areas Per Tab”. When a tab is selected, there is a submenu of the different configuration areas. Some configuration areas may have multiple possible entries; for example, role-based access controls define user roles/groups, the areas that access can be granted or denied (privileges), and then the permissions granted to those areas. Each separate configuration entry has its own task area beneath the primary configuration area.
The Main Menu

Figure 8.1. The Main Menu

8.4.2. Opening the IdM Web UI

The browser must be properly configured, as described in Section 8.4.3, “Configuring the Browser”, to support Kerberos authentication so that the user can connect to the UI.
To open the web UI:
  1. Get a valid Kerberos ticket using kinit, as in Section 8.3, “Logging into IdM”.
  2. Open the IdM URL. The full URL is https://IPAserver-FQDN/ipa/ui, but this service is also accessed simply by opening https://IPAserver-FQDN. For example: 
    https://server.example.com
https://server.example.com/ipa/ui

8.4.3. Configuring the Browser

Supported web browsers for connecting to the web UI are Firefox, starting with version 17, and Google Chrome. For information on the browser configuration, see the appropriate section:
8.4.3.1. Configuring Firefox
Firefox can use Kerberos credentials to authenticate to the IdM UI, but Kerberos negotiation needs to be configured to use the IdM domain. At the first log-in attempt, if Firefox has not been configured to support Kerberos authentication, then an error message appears.
Kerberos Authentication Error

Figure 8.2. Kerberos Authentication Error

If you see that error, then the IdM web UI can perform the required configuration:
  1. Click the follow these directions link.
  2. Click the link to import the CA certificate for the IdM server.
  3. Set the web site and software developer (first and last) trust bits for the CA certificate.
  4. Click the Configure Firefox button. This automatically fills out all the negotiate settings in the Firefox configuration to use the IdM domain settings.
    When the process is complete, a success box pops up saying that Firefox has been configured for single sign-on. From there, you are redirected to the IdM web UI.
This procedure can also be done manually:
  1. Start Firefox.
  2. Type about:config in the address bar.
  3. In the Search field, type negotiate to filter out the Kerberos-related parameters.
  4. On Red Hat Enterprise Linux, enter the domain name for the URI parameters, including the preceding period (.) and set the gsslib parameter to true: 
    network.negotiate-auth.trusted-uris  .example.com
network.negotiate-auth.using-native-gsslib true
    On Windows, set the trusted URIs and library path, and disable the built-in Microsoft Kerberos for authentication: 
    network.negotiate-auth.trusted-uris .example.com
network.auth.use-sspi false 
network.negotiate-auth.gsslib: C:\Program Files\MIT\Kerberos\bin\gssapi32.dll
    On a 64-bit system, the library location is in C:\Program Files(x86)\MIT\Kerberos\bin\gssapi32.dll.
  5. Open the web UI by going to the fully-qualified domain name of the IdM server such as http://ipaserver.example.com. Make sure that you can open the web UI and that there are no Kerberos authentication errors.
  6. Next, download the IdM server's CA certificate from http://ipa.example.com/ipa/config/ca.crt.
  7. In the Downloading Certificate window that appears, select the first (Trust this CA to identify web sites) and third (Trust this CA to identify software developers) check boxes.
8.4.3.2. Configuring Chrome
  1. Import CA Certificate
    1. Download the CA certificate from http://my.ipa.server/ipa/config/ca.crt. Alternatively, if the host is also an IdM client, you can find the certificate in /etc/ipa/ca.crt.
    2. Click the menu button with the Customize and control Google Chrome tooltip, which is by default in the top right-hand corner of Chrome, and click Settings.
    3. Click Show advanced settings to display more options, and then click the Manage certificates button located under the HTTPS/SSL heading.
    4. In the Authorities tab, click the Import button at the bottom.
    5. Select the CA certificate file that you downloaded in the first step.
  2. Enable SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) to Use Kerberos Authentication in Chrome
    1. Make sure you have the necessary directory created by running 
      [root@client]# mkdir -p /etc/opt/chrome/policies/managed/
    2. Create a new /etc/opt/chrome/policies/managed/mydomain.json file with write privileges limited to the system administrator or root, and include the following line: 
      { "AuthServerWhitelist": "*.example.com" }
      You can do this by running 
      [root@server]# echo '{ "AuthServerWhitelist": "*.example.com" }' > /etc/opt/chrome/policies/managed/mydomain.json

8.4.4. Using a Browser on Another System

It is possible to connect to the Identity Management web UI from a system which is not a member of the IdM domain. In this case, it is possible to specify an IdM-specific Kerberos configuration file on the external (non-IdM) machine before running kinit, and then the user can authenticate against the IdM server domain.
This is especially useful there are multiple realms or overlapping domains across your infrastructure.
  1. Copy the /etc/krb5.conf file from the IdM server. 
    # scp /etc/krb5.conf root@externalmachine.example.com:/etc/krb5_ipa.conf

    Warning

    Do not overwrite the existing krb5.conf file.
  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 Firefox on the external machine as in Section 8.4.3, “Configuring the Browser”.

8.4.5. Logging in with Simple Username/Password Credentials

If Kerberos authentication fails, then browser login also fails. That prevents access to the IdM web UI. Simple authentication for the UI allows users to log in even if there are problems with the Kerberos service or if the system is outside the IdM domain.
When the IdM server cannot find a valid Kerberos ticket for the user attempting to log into the web UI, it splashes an error message. Since the preferred method of connecting to IdM domain services (including the UI) is using Kerberos authentication, the error first says to renew the Kerberos credentials or to configure the browser to support Kerberos authentication.
The second part of the message offers the alternative of using simple authentication. The form-based authentication link opens a login page.
IdM Form-Based Login Option

Figure 8.3. IdM Form-Based Login Option

Then simply supply the UID and password for a configured IdM user.
IdM Password Prompt

Figure 8.4. IdM Password Prompt

8.4.6. Using the UI with Proxy Servers

Proxy servers can be used to access the web UI without any additional configuration in IdM.
Port forwarding is not supported with the IdM server. However, because it is possible to use proxy servers with IdM, an operation similar to port forwarding can be configured using proxy forwarding with OpenSSH and the SOCKS option.

8.5. Configuring an IdM Server to Run in a TLS 1.2 Environment

See Configuring TLS 1.2 for Identity Management in RHEL 6.9 in Red Hat Knowledgebase for details.

[1] The hostname used in the directory lookup can be controlled in the /etc/ipa/default.conf configuration file.

Chapter 9. Identity: Managing Users and User Groups

Users in Identity Management are able to access services and servers within the domain through Kerberos authentication. This chapter covers general management tasks for users, groups, password policies, and other configuration for users.

9.1. Setting up User Home Directories

A home directory is required for any IdM user. Without a home directory in the expected location, a user may be unable to log into the domain. While systems administrators can manage home directories outside of IdM, it is also possible to use a PAM module to create home directories automatically on both IdM servers and clients.

9.1.1. About Home Directories

IdM, as part of managing users, can manage user home directories. However, IdM has certain defined parameters for any managed home directories:
  • The default prefix for users' home directories is /home.
  • IdM does not automatically create home directories when users log in. Automatically creating home directories requires either the pam_oddjob_mkhomedir module or the pam_mkhomedir module. This module can be configured as part of client installation or after installation, as described in Section 9.1.2, “Enabling the PAM Home Directory Module”.
    The home directory process for IdM first attempts to use the pam_oddjob_mkhomedir module because this requires fewer user privileges and access to create the home directories, as well as integrating smoothly with SELinux. If this module is not available, then the process falls back to the pam_mkhomedir module.

    Note

    On Red Hat Enterprise Linux 5 clients, the client installation script uses the pam_mkhomedir module even if the pam_oddjob_mkhomedir module is available. To use the pam_oddjob_mkhomedir module on Red Hat Enterprise Linux 5, edit the PAM configuration manually.
  • It is possible to use an NFS file server that provides /home that can be made available to all machines in the domain and then automounted on the IdM server.
    There are potential issues when using NFS, such as security issues related to granting root access to the NFS user, performance issues with loading the entire /home tree, and network performance issues for using remote servers for home directories. There are some general guidelines for using NFS with Identity Management:
    • Use automount to mount only the user's home directory and only when the user logs in, rather than loading 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 that user. Since 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.
    • Use a mechanism, such as the pam_oddjob_mkhomedir module, to create the home directory as that user.
    Using automounts for home directories is described in Section 9.1.3, “Manually Mounting Home Directories”.
  • If a suitable directory and mechanism are not available to create home directories, users may not be able to log in.

9.1.2. Enabling the PAM Home Directory Module

For a home directory to be created automatically when a user logs in, IdM can use either the pam_oddjob_mkhomedir module or the pam_mkhomedir module. Because it requires fewer permissions and works well with SELinux, IdM preferentially uses the pam_oddjob_mkhomedir module. If that module is not installed, then it falls back to the pam_mkhomedir module.

Note

IdM does not require the pam_oddjob_mkhomedir module or pam_mkhomedir module. This is because the *_mkhomedir module may try to create home directories even when the shared storage is not available. If the module is unable to create the home directory, then users can be blocked from logging into the IdM domain.
The system administrator must activate this module on each client or server as needed.
There are two ways to enable the pam_oddjob_mkhomedir (or pam_mkhomedir) module:
  • The --mkhomedir option can be used with the ipa-client-install command. While this is possible for clients, this option is not available to servers when they are set up.
  • The pam_oddjob_mkhomedir module can be enabled using the system's authconfig command. For example: 
    authconfig --enablemkhomedir --update
    This option can be used for both server and client machines post-installation.

Note

On Red Hat Enterprise Linux 5 clients, the client installation script uses the pam_mkhomedir module even if the pam_oddjob_mkhomedir module is available. To use the pam_oddjob_mkhomedir module on Red Hat Enterprise Linux 5, edit the PAM configuration manually.

9.1.3. Manually Mounting Home Directories

While PAM modules can be used to create home directories for users automatically, this may not be desirable behavior in every environment. In that case, home directories can be manually added to the IdM server from separate locations using NFS shares and automount.
  1. Create a new location for the user directory maps: 
    [bjensen@server ~]$ ipa automountlocation-add userdirs
Location: userdirs
  2. Add a direct map to the new location's auto.direct file. In this example, the mount point is /share: 
    [bjensen@server ~]$ ipa automountkey-add userdirs auto.direct --key=/share --info="-ro,soft, ipaserver.example.com:/home/share"

Key: /share
Mount information: -ro,soft, ipaserver.example.com:/home/share
Using automounts with IdM is described in detail in Chapter 18, Policy: Using Automount.

9.2. Managing User Entries

9.2.1. About Username Formats

The default length for usernames is 32 characters.
IdM supports a wide range of username formats, based on this regular expression: 
[a-zA-Z0-9_.][a-zA-Z0-9_.-]{0,252}[a-zA-Z0-9_.$-]?

Note

The trailing $ symbol is permitted for Samba 3.x machine support.
Any system limits — such as starting a username with a number on Unix systems — apply to the usernames in IdM.

Note

Usernames are case insensitive when they are created, meaning that any case letter can be entered but case is ignored when the username is saved.
Username are automatically normalized to be all lower case, even if the user is created with mixed case or upper case letters.

9.2.2. Adding Users

9.2.2.1. From the Web UI
  1. Open the Identity tab, and select the Users subtab.
  2. Click the Add link at the top of the users list.
  3. Fill in the user's first and last names. The user login (UID) is automatically generated based on the user's full name, but this can be set manually by clicking the Optional field link.

    Note

    Usernames are case insensitive when they are created, meaning that case is ignored. Username are automatically normalized to be all lower case, even if the user is created with mixed case or upper case letters.
  4. Click the Add and Edit button to go directly to the expanded entry page and fill in more attribute information, as in Section 9.2.3.1, “From the Web UI”. The user entry is created with some basic information already filled in, based on the given user information and the user entry template.
9.2.2.2. From the Command Line
New user entries are added with the user-add command. Attributes (listed in Table 9.2, “Default Identity Management User Attributes”) can be added to the entry with specific values or the command can be run with no arguments. 
[bjensen@server ~]$ ipa user-add [username] [attributes]
When no arguments are used, the command prompts for the required user account information and uses the defaults for the other attributes, with the defaults printed below. For example: 
[bjensen@server ~]$ ipa user-add
First name: John 
Last name: Smith 
User login [jsmith]: jsmith 
-------------------- 
Added user "jsmith" 
-------------------- 
User login: jsmith 
First name: John 
Last name: Smith 
Full name: John Smith 
Display name: John Smith 
Initials: JS 
Home directory: /home/jsmith 
GECOS: John Smith 
Login shell: /bin/sh 
Kerberos principal: jsmith@EXAMPLE.COM 
Email address: jsmith@example.com 
UID: 882600007 
GID: 882600007 
Password: False 
Member of groups: ipausers 
Kerberos keys available: False
Any of the user attributes can be passed with the command. This will either set values for optional attributes or override the default values for default attributes. 
[bjensen@server ~]$ ipa user-add jsmith --first=John --last=Smith --manager=bjensen --email=johnls@example.com --homedir=/home/work/johns --password

Note

Usernames are case insensitive when they are created, meaning that case is ignored. Username are automatically normalized to be all lower case, even if the user is created with mixed case or upper case letters.

Important

When a user is created without specifying a UID or GID number, then the user account is automatically assigned an ID number that is next available in the server or replica range. (Number ranges are described more in Section 9.9, “Managing Unique UID and GID Number Assignments”.) This means that a user always has a unique number for its UID number and, if configured, for its private group.
If a number is manually assigned to a user entry, the server does not validate that the uidNumber is unique. It will allow duplicate IDs; this is expected (though discouraged) behavior for POSIX entries.
If two entries are assigned the same ID number, only the first entry is returned in a search for that ID number. However, both entries will be returned in searches for other attributes or with ipa user-find --all.

9.2.3. Editing Users

9.2.3.1. From the Web UI
  1. Open the Identity tab, and select the Users subtab.
  2. Click the name of the user to edit.
  3. There are a number of different types of attributes that can be edited for the user. All of the default attributes are listed in Table 9.2, “Default Identity Management User Attributes”. Most of the attributes in the Identity Settings and Account Settings areas have default values filled in for them, based on the user information or on the user entry template.
  4. Edit the fields or, if necessary, click the Add link by an attribute to create the attribute on the entry.
  5. When the edits are done, click the Update link at the top of the page.
9.2.3.2. From the Command Line
The user-mod command edits user accounts by adding or changing attributes. At its most basic, the user-mod specifies the user account by login ID, the attribute to edit, and the new value: 
[bjensen@server ~]$ ipa user-mod loginID --attributeName=newValue
For example, to change a user's work title from Editor II to Editor III: 
[bjensen@server ~]$ ipa user-mod jsmith --title="Editor III"
Identity Management allows multi-valued attributes, based on attributes in LDAP that are allowed to have multiple values. For example, a person may have two email addresses, one for work and one for personal, that are both stored in the mail attribute. Managing multi-valued attributes can be done using the --addattr option.
If an attribute allows multiple values — like mail — simply using the command-line argument will overwrite the value with the new value. This is also true for using --setattr. However, using --addattr will add a new attribute; for a multi-valued attribute, it adds the new value in addition to any existing values.

Example 9.1. Multiple Mail Attributes

A user is created first using his work email account. 
[bjensen@server ~]$ ipa user-add jsmith --first=John --last=Smith --email=johnls@example.com
Then, his personal email account is added. 
[bjensen@server ~]$ ipa user-mod jsmith --addattr=mail=johnnys@me.com
Both email addresses are listed for the user. 
[bjensen@server ~]$ ipa user-find jsmith --all
--------------
1 user matched
--------------
  dn: uid=jsmith,cn=users,cn=accounts,dc=example,dc=com
  User login: jsmith
  .....
  Email address: jsmith@example.com, jsmith@new.com
To set two values at the same time, use the --addattr option twice: 
[bjensen@server ~]$ ipa user-add jsmith --first=John --last=Smith --email=johnls@example.com --addattr=mail=johnnys@me.com --addattr=mail=admin@example.com

9.2.4. Deleting Users

Deleting a user account permanently removes the user entry and all its information from IdM, including group memberships and passwords. External configuration — like a system account and home directory — will still exist on any server or local machine where they were created, but they cannot be accessed through IdM.
Deleting a user account is permanent. The information cannot be recovered; a new account must be created.

Note

If all admin users are deleted, then you must use the Directory Manager account to create a new administrative user.
Alternatively, any user who belongs in the group management role can also add a new admin user.
9.2.4.1. With the Web UI
  1. Open the Identity tab, and select the Users subtab.
  2. Select the checkboxes by the names of the users to delete.
  3. Click the Delete link at the top of the task area.
  4. When prompted, confirm the delete action.
9.2.4.2. From the Command Line
Users are deleted using the user-del command and then the user login. For example, a single user: 
[bjensen@server ~]$ ipa user-del jsmith
To delete multiple users, simply list the users, separated by spaces. 
[bjensen@server ~]$ ipa user-del jsmith bjensen mreynolds cdickens
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 stdout when the command completes. If --continue is not used, then the command proceeds with deleting users until it encounters an error, and then it exits.

9.3. Managing Public SSH Keys for Users

OpenSSH uses public-private key pairs to authenticate users. A user attempts to access some network resource and presents its key pair. The first time the user authenticates, the administrator on the target machine has to approve the request manually. The machine then stores the user's public key in an authorized_keys file. Any time that the user attempts to access the resource again, the machine simply checks its authorized_keys file and then grants access automatically to approved users.
There are a couple of problems with this system:
  • SSH keys have to be distributed manually and separately to all machines in an environment.
  • Administrators have to approve user keys to add them to the configuration, but it is difficult to verify either the user 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 user SSH keys so that applications and services only have to look in one location for user 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 user SSH keys.

9.3.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 id_rsa.pub, a key entry is identified by its type, then the key itself, and then an additional comment or identifier. For example, for an RSA key associated with a specific hostname: 
"ssh-rsa ABCD1234...== ipaclient.example.com"
All three parts from the key file can be uploaded to and viewed for the user entry, or only the key itself can be uploaded.

9.3.2. Uploading User SSH Keys Through the Web UI

  1. Generate a user key. For example, using the OpenSSH tools: 
    [jsmith@server ~]$ ssh-keygen -t rsa -C jsmith@example.com
Generating public/private rsa key pair.
Enter file in which to save the key (/home/jsmith/.ssh/id_rsa):
Created directory '/home/jsmith/.ssh'.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/jsmith/.ssh/id_rsa.
Your public key has been saved in /home/jsmith/.ssh/id_rsa.pub.
The key fingerprint is:
a5:fd:ac:d3:9b:39:29:d0:ab:0e:9a:44:d1:78:9c:f2 jsmith@example.com
The key's randomart image is:
+--[ RSA 2048]----+
|                 |
|     + .         |
|    + =   .      |
|     =   +       |
|    . E S..      |
|   .    . .o     |
|    . .  . oo.   |
|   . o .  +.+o   |
|    o  .o..o+o   |
+-----------------+
  2. Copy the public key from the key file. The full key entry has the form type key== comment. Only the key== is required, but the entire entry can be stored. 
    [jsmith@server ~]$ cat  /home/jsmith/.ssh/id_rsa.pub
						
ssh-rsa AAAAB3NzaC1yc2E...tJG1PK2Mq++wQ== jsmith@example.com
  3. Open the Identity tab, and select the Users subtab.
  4. Click the name of the user to edit.
  5. In the Account Settings area of the Settings tab, click the SSH public keys: Add link.
  6. Click the Add link by the SSH public keys field.
  7. Paste in the public key for the user, and click the Set button.
    The SSH public keys field now shows New: key set. Clicking the Show/Set key link opens the submitted key.
  8. To upload multiple keys, click the Add link below the list of public keys, and upload the other keys.
  9. When all the keys have been submitted, click the Update link at the top of the user'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].
Saved Public Key

Figure 9.1. Saved Public Key

After uploading the user keys, configure SSSD to use Identity Management as one of its identity domains and set up OpenSSH to use SSSD for managing user keys. This is covered in the Deployment Guide.

9.3.3. Uploading User SSH Keys Through the Command Line

The --sshpubkey option uploads the 64 bit-encoded public key to the user entry. For example: 
[jsmith@server ~]$ ipa user-mod jsmith --sshpubkey="ssh-rsa 12345abcde= ipaclient.example.com"
With a real key, the key is longer and usually ends with an equals sign (=).
To upload multiple keys, pass a comma-separated list of keys with a single --sshpubkey option: 
--sshpubkey="12345abcde==,key2==,key3=="
After uploading the user keys, configure SSSD to use Identity Management as one of its identity domains and set up OpenSSH to use SSSD for managing user keys. This is covered in the Red Hat Enterprise Linux Deployment Guide.

9.3.4. Deleting User Keys

  1. Open the Identity tab, and select the Users subtab.
  2. Click the name of the user to edit.
  3. Open the Account Settings area of the Settings tab.
  4. Click the Delete link by the fingerprint of the key to remove.
  5. Click the Update link at the top of the user's page to save the changes.
The command-line tools can be used to remove all keys. This is done by running ipa user-mod with the --sshpubkey= set to a blank value; this removes all public keys for the user. For example: 
[jsmith@server ~]$ kinit admin
[jsmith@server ~]$ ipa user-mod --sshpubkey= jsmith

9.4. Changing Passwords

Password policies (Chapter 19, Policy: Defining Password Policies) and minimal access restrictions can be applied to a password change operation:
  • Regular, non-administrative users can change only their personal passwords, and all passwords are constrained by the IdM password policies.
    This allows administrators to create intro passwords or to reset passwords easily, while still keeping the final password confidential. Since any password sent by an administrator to the user is temporary, there is little security risk.
  • Changing a password as the IdM admin user overrides any IdM password policies, but the password expires immediately. This requires the user to change the password at the next login. Similarly, any user who has password change rights can change a password and no password policies are applied, but the other user must reset the password at the next login.
  • Changing a password as the LDAP Directory Manager user, using LDAP tools, overrides any IdM password policies.

9.4.1. From the Web UI

  1. Open the Identity tab, and select the Users subtab.
  2. Click the name of the user for whom to reset the password. All users can change their own password; only administrators or users with delegated permissions can change other user's passwords.
  3. Scroll to the Account Settings area.
  4. Click the Reset Password link.
  5. In the pop-up box, enter and confirm the new password.

9.4.2. From the Command Line

Changing a password — your own or another user's — is done using the user-mod command, as with other user account changes. 
[bjensen@ipaserver ~]$ kinit admin
[bjensen@ipaserver ~]$ ipa user-mod jsmith --password

9.5. Enabling and Disabling User Accounts

User accounts can be deactivated or disabled. A disabled user cannot log into IdM or its related services (like Kerberos) and he cannot perform any tasks. However, the user account still exists within Identity Management and all of the associated information remains unchanged.

Note

Any existing connections remain valid until the Kerberos TGT and other tickets expire. Once the ticket expires, the user cannot renew the ticket.

9.5.1. From the Web UI

Multiple users can be disabled from the full users list by selecting the checkboxes by the desired users and then clicking the Disable link at the top of the list.
Disable/Enable Options at the Top of the Users List

Figure 9.2. Disable/Enable Options at the Top of the Users List

A user account can also be disabled from the user's individual entry page.
  1. Open the Identity tab, and select the Users subtab.
  2. Click the name of the user to deactivate or activate.
  3. In the actions drop-down menu, select the Disable item.
  4. Click the Accept button.
When a user account is disabled, it is signified by a minus (-) icon for the user status in the user list and by the username on the entry page. Additionally, the text for the user is gray (to show it is inactive) instead of black.
Disable Icon for User Status

Figure 9.3. Disable Icon for User Status

9.5.2. From the Command Line

Users are enabled and disabled using user-enable and user-disable commands. All that is required is the user login. For example: 
[bjensen@server ~]$ ipa user-disable jsmith

9.6. Unlocking User Accounts After Password Failures

If a user attempts to log in and uses the wrong password a certain number of times, then that user account is locked. The exact number of failed attempts that locks an account and the duration of the lockout is defined as part of the password policy (Section 19.6, “Setting Account Lockout Policies”).
A password policy can implicitly define a reset period, where the account unlocks naturally after a certain amount of time lapses. However, if the duration is fairly long or if the deployment requires stronger security checks before unlocking an account, then an administrator can unlock an account manually.
An account is unlocked using the user-unlock command. For example: 
[bjensen@ipaserver ~]$ kinit admin
[bjensen@ipaserver ~]$ ipa user-unlock jsmith

9.7. Smart Cards

Authentication based on smart cards is an alternative to passwords. User credentials are stored on the smart card, and special software and hardware is used to access them. In order to authenticate this way, the user must place the smart card into a reader and then supply the PIN code for the smart card.
Red Hat Enterprise Linux 6 clients can use local smart card authentication if they run SSSD and are enrolled with an Identity Management server based on Red Hat Enterprise Linux 7.3 or later.

9.7.1. Smart Card and Smart Card Reader Support in Identity Management

If your smart card is supported by the coolkey package, the required PKCS #11 module is already present in the central /etc/pki/nssdb/ NSS database after the installation of these packages.
If your smart card is not supported, run the following steps:
  1. Add the required PKCS #11 module manually using the modutil utility. For example: 
    [root@ipaclient ~]# modutil -dbdir /etc/pki/nssdb/ -add "My PKCS#11 module" -libfile libmypkcs11.so
...
Module "My PKCS#11 Module" added to database.
    For detailed information on using modutil, see the modutil(1) man page.
  2. Add all certificate authority (CA) certificates to the NSS database that are required to validate the certificate on the smart card. For example, to add the CA certificate in the ca_certificate.pem file to the NSS database: 
    [root@ipaclient ~]# certutil -A -d /etc/pki/nssdb/ -n 'CA certificate' -t CT,C,C -a -i ca_certificate.pem
    For detailed information on using certutil, see the certutil(1) man page.

9.7.2. Exporting a Certificate From a Smart Card

  1. Place the smart card into the reader.
  2. Run the following command to list the certificates on the smart card: 
    [user@ipaclient ~]$ certutil -L -d /etc/pki/nssdb/ -h all
Certificate Nickname         Trust Attributes
                             SSL,S/MIME,JAR/XPI

my_certificate               CT,C,C
    In the output, locate the certificate to use for authentication, and note its nickname.
  3. To extract the certificate in Base64 format to user.crt, use the nickname from the previous step: 
    [user@ipaclient ~]$ certutil -L -d /etc/pki/nssdb/ -n 'my_certificate' -r | base64 -w 0 > user.crt
    The base64 utility is part of the coreutils package.

9.7.3. Storing Smart Card Certificates for IdM Users

To store a smart card certificate for a user, add the certificate on a Red Hat Enterprise Linux 7 server. See Managing Certificates Issued by External CAs in the Linux Domain Identity, Authentication, and Policy Guide.

9.7.4. Smart Card Authentication on Identity Management Clients

Red Hat Identity Management (IdM) supports two smart card-based authentication options:
Local authentication
  • Text console
  • Graphical console, such as the Gnome Display Manager (GDM)
  • Local authentication services, like su, or sudo
Remote authentication with ssh
Certificates on a smart card are stored together with the PIN-protected SSH private key.

Note

IdM only supports the above-mentioned local authentication services and ssh for smart card authentication. Other services, such as FTP, are not supported.
With SSSD-based smart card authentication configured, the system prompts for the smart card PIN code after the user attempts to log in. The user is successfully authenticated if the supplied PIN is correct, the certificate on the smart card is valid,and belongs to the user attempting to log in, and other configurable criteria are met.
9.7.4.1. Configuring Smart Card Authentication on an IdM Client
To be able to authenticate using smart cards on a client, run the following steps:
  1. To enable smart card support, allow SSSD to prompt for password, one-time password (OTP), or the smart card PIN. To do this, modify the auth lines of the /etc/pam.d/password-auth and /etc/pam.d/system-auth PAM configuration files.
    1. Remove the following lines of the default /etc/pam.d/password-auth: 
      auth        required      pam_env.so
auth        sufficient    pam_unix.so nullok try_first_pass
auth        requisite     pam_succeed_if.so uid >= 500 quiet
auth        sufficient    pam_sss.so use_first_pass
auth        required      pam_deny.so
      Replace them with these lines: 
      auth        required      pam_env.so
auth        [default=1 success=ok] pam_localuser.so
auth        [success=done ignore=ignore default=die] pam_unix.so nullok try_first_pass
auth        requisite     pam_succeed_if.so uid >= 500 quiet
auth        sufficient    pam_sss.so forward_pass
auth        required      pam_deny.so
    2. Similarly, remove the following lines of the default /etc/pam.d/system-auth: 
      auth        required      pam_env.so
auth        sufficient    pam_unix.so nullok try_first_pass
auth        requisite     pam_succeed_if.so uid >= 500 quiet
auth        sufficient    pam_sss.so use_first_pass
auth        required      pam_deny.so
      Replace them with these lines: 
      auth        required      pam_env.so
auth        [default=1 success=ok] pam_localuser.so
auth        [success=done ignore=ignore default=die] pam_unix.so nullok try_first_pass
auth        requisite     pam_succeed_if.so uid >= 500 quiet
auth        sufficient    pam_sss.so forward_pass
auth        required      pam_deny.so
  2. Set the following option in your /etc/sssd/sssd.conf to true: 
    [pam]
pam_cert_auth=true
  3. Restart SSSD: 
    [root@ipaclient ~]# systemctl restart sssd
9.7.4.2. SSH Log in Using a Smart Card
If you are logging in with ssh when authenticating with a smart card, you have to additionally specify the following path to the smart card reader module. For example: 
$ ssh -I /usr/lib/libmypkcs11.so -l user@example.com host.example.com
Enter PIN for 'Smart Card':

9.8. Managing User Private Groups

On Red Hat Enterprise Linux systems, every time a user is created, a corresponding, secret user group is automatically created with that new user as its only member. This is a user private group. Using user private groups makes it simpler and safer to manage file and directory permissions because umask defaults only have to restrict user access, not group access.
When a new user is created in the IdM domain, it is also created with a corresponding private group, following the Red Hat Enterprise Linux convention. For most environments, this is an acceptable default behavior, but there may be certain users or types of users which do not require a private group or the environment may already have those GIDs[3] assigned to NIS groups or other system groups.

9.8.1. Listing User Private Groups

User private groups are specific to a single user and are only used by the system. They are private, so they are not viewable in the IdM UI. However, not every user has a private group, depending on the options when a user is created, so it can be useful to get a list of configured private groups within the IdM user domain. Private groups can be searched and listed by using the --private option with the group-find command. For example: 
[root@server ~]# ipa group-find --private
---------------
1 group matched
---------------
  Group name: jsmith
  Description: User private group for jsmith
  GID: 1084600001
----------------------------
Number of entries returned 1
----------------------------

9.8.2. Disabling Private Groups for a Specific User

Private group creation can be disabled when a user is created by using the --noprivate option.
There is one thing to note when adding a user without a private group: the Linux system still expects a user GID for the new user. However, the one default user group (ipausers) is a non-POSIX group and, therefore, does not have an associated GID. So that the add operation does not fail, it is necessary either to set an explicit user GID with the --gid option or to create a group with a GID and add the user to that group using an automembership rule (covered in Chapter 25, Policy: Defining Automatic Group Membership for Users and Hosts). 
[jsmith@server ~]$ ipa user-add jsmith --first=John --last=Smith --noprivate --gid 10000

9.8.3. Disabling Private Groups Globally

User private groups are managed through the Managed Entries Plug-in in 389 Directory Server. This plug-in can be disabled, which effectively disables private group creation for all new users.
This is done using the ipa-managed-entries command.
  1. Use the ipa-managed-entries command to list possible Managed Entries Plug-in definitions. By default, there are two, one for new users (UPG) and one for netgroups (NGP). 
    [root@ipaserver ~]# ipa-managed-entries --list -p DMpassword
Available Managed Entry Definitions:
UPG Definition
NGP Definition
  2. Disable the desired Managed Entries Plug-in instance. For example: 
    [root@ipaserver ~]# ipa-managed-entries -e "UPG Definition" -p DMpassword disable
Disabling Plugin
  3. Restart the 389 Directory Server to load the new plug-in configuration. 
    [root@ipaserver ~]# service dirsrv restart
Managed Entries Plug-in instances can be re-enabled with the enable option.

9.9. Managing Unique UID and GID Number Assignments

An IdM server must generate random UID and GID values and simultaneously ensure that replicas never generate the same UID or GID value. The need for unique UID and GID numbers might even cross IdM domains, if a single organization has multiple disparate domains.

9.9.1. About ID Number Ranges

The UID and GID numbers are divided into ranges. By keeping separate numeric ranges for individual servers and replicas, the chances are minimal that any numbers issued by one server or replica will duplicate those from another. Ranges are updated and shared intelligently between servers and replicas through the Dynamic Numeric Assignment (DNA) Plug-in, as part of the backend 389 Directory Server instance for the domain. The same range is used for user IDs (uidNumber) and group IDs (gidNumber). A user and a group may have the same ID, but since the ID is set in different attributes, there is no conflict. Using the same ID number for both a user and a group also allows an administrator to configure user private groups, where a unique system group is created for each user and the ID number is the same for both the user and the group.
When a user is created interactively or without specifying a UID or GID number, then the user account is created with an ID number that is next available in the server or replica range. This means that a user always has a unique number for its UID number and, if configured, for its private group.

Important

If a number is manually assigned to a user entry, the server does not validate that the uidNumber is unique. It will allow duplicate IDs; this is expected (though discouraged) behavior for POSIX entries. The same is true for group entries: a duplicate gidNumber can be manually assigned to the entry.
If two entries are assigned the same ID number, only the first entry is returned in a search for that ID number. However, both entries will be returned in searches for other attributes or with ipa user-find --all.

9.9.2. About ID Range Assignments During Installation

The IdM administrator can initially define a range during server installation, using the --idstart and --idmax options with ipa-server-install. These options are not required, so the setup script can assign random ranges during installation.
If no range is set manually when the first IdM server is installed, a range of 200,000 IDs is randomly selected. There are 10,000 possible ranges. Selecting a random range from that number provides a high probability of non-conflicting IDs if two separate IdM domains are ever merged in the future.
With a single IdM server, IDs are assigned to entries in order through the range. With replicas, the initial server ID range is split and distributed.
When a replica is installed, it is configured with an invalid range. It also has a directory entry (that is shared among replicas) that instructs the replica where it can request a valid range. When the replica starts, or as its current range is depleted so that less than 100 IDs are available, it can contact one of the available servers for a new range allotment. A special extended operation splits the range in two, so that the original server and the replica each have half of the available range.

9.9.3. A Note on Conflicting ID Ranges

It is possible for an administrator to define an ID number range using the min_id and max_id options in the sssd.conf file. The default min_id value is 1. However, Red Hat recommends to set this value to 1000 in order to avoid conflicts with UID and GID numbers that are reserved for system use.

9.9.4. Adding New Ranges

If the range for the entire domain is close to depletion, a new range can be manually selected and assigned to one of the master servers. All replicas then request ID ranges from the master as necessary.
The changes to the range are done by editing the 389 Directory Server configuration to change the DNA Plug-in instance. The range is defined in the dnaNextRange parameter. For example: 
ldapmodify -x -D "cn=Directory Manager" -W -h server.example.com -p 389
Enter LDAP Password: *******
dn: cn=POSIX IDs,cn=Distributed Numeric Assignment Plugin,cn=plugins,cn=config
changetype: modify
add: dnaNextRange
dnaNextRange: 123400000-123500000

Note

This command only adds the specified range of values; it does not check that the values in that range are actually available. This check is performed when an attempt is made to allocate those values. If a range is added that contains mostly values that were already allocated, the system will cycle through the entire range searching for unallocated values, and then the operation ultimately fails if none are available.

9.9.5. Repairing Changed UID and GID Numbers

When a user is created, the user is automatically assigned a user ID number and a group ID number.
When the user logs into an IdM system or service, SSSD on that system caches that username with the associated UID/GID numbers. The UID number is then used as the identifying key for the user. If a user with the same name but a different UID attempts to log into the system, then SSSD treats it as two different users with a name collision.
What this means is that SSSD does not recognize UID number changes. It interprets it as a different and new user, not an existing user with a different UID number. If an existing user changes the UID number, that user is prevented from logging into SSSD and associated services and domains. This also has an impact on any client applications which use SSSD for identity information; the user with the conflict will not be found or accessible to those applications.

Important

UID/GID changes are not supported in Identity Management or in SSSD.
If a user for some reason has a changed UID/GID number, then the SSSD cache must be cleared for that user before that user can log in again. For example: 
[root@server ~]# sss_cache -u jsmith

9.10. Managing 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 9.1. Default Identity Management User Object Classes
Description Object Classes
IdM object classes
ipaobject
ipasshuser
Person object classes
person
organizationalperson
inetorgperson
inetuser
posixaccount
Kerberos object classes
krbprincipalaux
krbticketpolicyaux
Managed entries (template) object classes mepOriginEntry
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 9.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 9.10.4, “Specifying Default User and Group Attributes”.
Table 9.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[c] --uid Default
Group ID number[c] --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
[a] Required attributes must be set for every entry. Optional attributes may be set, while default attributes are automatically added with a pre-defined value unless a specific value is given.
[b] The script prompts for the new password, rather than accepting a value with the argument.
[c] When a user is created without specifying a UID number, then the user account is automatically assigned an ID number that is next available in the server or replica range. (Number ranges are described more in Section 9.9, “Managing Unique UID and GID Number Assignments”.) This means that a user always has a unique number for its UID number and, if configured, for its private group.
If a number is manually assigned to a user entry, the server does not validate that the uidNumber is unique. It will allow duplicate IDs; this is expected (though discouraged) behavior for POSIX entries.
If two entries are assigned the same ID number, only the first entry is returned in a search for that ID number. However, both entries will be returned in searches for other attributes or with ipa user-find --all.

9.10.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 (Section 9.10, “Managing 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.

9.10.2. Applying Custom Object Classes to New User Entries

User and group accounts are created with a pre-defined 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 may have custom object classes with custom attributes which should be applied to user entries.
9.10.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.
  5. At the bottom of the users area, click the Add link to add 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 the Update link at the top of the Configuration page.
9.10.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.
    For example: 
    [bjensen@server ~]$ ipa config-mod --userobjectclasses=top,person,organizationalperson,inetorgperson,inetuser,posixaccount, krbprincipalaux,krbticketpolicyaux,ipaobject,ipasshuser,employeeinfo

9.10.3. Applying Custom Object Classes to New Group Entries

As with user entries, administrators may have custom object classes with custom attributes which should be applied to group entries. These can be added automatically by adding the object classes to the IdM server configuration.
9.10.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.
  5. Click the Add link to add 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 the Update link at the top of the Configuration page.
9.10.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.
    For example: 
    [bjensen@server ~]$ ipa config-mod --groupobjectclasses=top,groupofnames,nestedgroup,ipausergroup,ipaobject,ipasshuser,employeegroup

9.10.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 username 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 9.3. Default User Parameters
Field Command-Line Option Descriptions
Maximum username length --maxusername Sets the maximum number of characters for usernames. The default value is eight.
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 Sets a list of object classes that are used to create IdM user accounts.
Default group object classes --groupobjectclasses Sets a list of object classes that are used to create IdM group accounts.
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.
9.10.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.
9.10.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

9.11. Managing User Groups

User groups are a way of centralizing control over important management tasks, particularly access control and password policies. Four groups are created during the installation, specifically for use by IdM operations:
  • ipausers, which contains all users.
  • admins, which contains administrative users. The initial admin user belongs to this group.
  • trusted admins, which contains administrative users used to manage Active Directory trusts.
  • editors, which is a special group for users working through the web UI. This group allows users to edit other users' entries, though without all of the rights of the admin user.

Note

Some operating systems limit the number of groups that can be assigned to system users. For example, Solaris and AIX systems both limit users to 16 groups per user. This can be an issue when using nested groups, when a user may be automatically added to multiple groups.

9.11.1. Types of Groups in IdM

All groups in Identity Management are essentially static groups, meaning that the members of the group are manually and explicitly added to the group. Tangentially, IdM allows nested groups, where a group is a member of another group. In that case, all of the group members of the member group automatically belong to the parent group, as well.
Automembership rules allow new users to be added to groups automatically, using attributes in the user entry to determine what groups the user should belong to. Automembership rules are covered in Chapter 25, Policy: Defining Automatic Group Membership for Users and Hosts.
The way groups are defined in IdM is simple, but there are different configuration options for groups which can change what kinds of members can be added.
Some types of groups in IdM are based not on how members are added, but rather where the member entries originate:
  • Internal groups (the default), where all members belong to the IdM domain.
  • External groups, where some or all of the members exist in an identity store outside of the IdM domain. This can be a local system, an Active Directory domain, or a directory service.
Another difference is whether groups are created with POSIX attributes. Most Linux users require some kind of POSIX attributes, but groups which interact with Active Directory or Samba must be non-POSIX. By default, IdM creates non-POSIX groups, but there is an explicit option to create a POSIX group (adding the posixgroup object class).
Because groups are easy to create, it is possible to be very flexible in what groups to create and how they are organized. Groups can be defined around organizational divisions like departments, physical locations, or IdM or infrastructure usage guidelines for access controls.

9.11.2. Group Object Classes

When a group entry is created, it is automatically assigned certain LDAP object classes. (LDAP object classes and attributes are discussed in detail in the Directory Server Deployment Guide and the Directory Server Schema Reference.) For groups, only two attributes truly matter: the name and the description.
Table 9.4. Default Identity Management Group Object Classes
Description Object Classes
IdM object classes
ipaobject
ipausergroup
nestedgroup
Group object classes groupofnames
9.11.2.1. Creating User Groups
9.11.2.1.1. With the Web UI
  1. Open the Identity tab, and select the User Groups subtab.
  2. Click the Add link at the top of the groups list.
  3. Enter all of the information for the group.
    • A unique name. This is the identifier used for the group in the IdM domain, and it cannot be changed after it is created. The name cannot contain spaces, but other separators like an underscore (_) are allowed.
    • A text description of the group.
    • Whether the group is a POSIX group, which adds Linux-specific information to the entry. By default, all groups are POSIX groups unless they are explicitly configured not to be. Non-POSIX groups can be created for interoperability with Windows or Samba.
    • Optionally, the GID number for the group. All POSIX groups require a GID number, but IdM automatically assigns the GID number.
      Setting a GID number is not necessary because of the risk of collisions. If a GID number is given manually, IdM will not override the specified GID number, even if it is not unique.
  4. Click the Add and Edit button to go immediately to the member selection page.
  5. Select the members, as described in Section 9.11.2.2.1, “With the Web UI (Group Page)”.
9.11.2.1.2. With the Command Line
New groups are created using the group-add command. (This adds only the group; members are added separately.)
Two attributes are always required: the group name and the group description. If those attributes are not given as arguments, then the script prompts for them. 
[bjensen@server ~]$ ipa group-add groupName --desc="description" [--nonposix]
Additionally, there is one other configuration option, --nonposix. (By default, all groups are created as POSIX groups.) To enable interoperability with Windows users and groups and programs like Samba, it is possible to create non-POSIX groups by using the --nonposix option. This option tells the script not to add the posixGroup object class to the entry.
For example: 
[bjensen@server ~]$ ipa group-add examplegroup --desc="for examples" --nonposix

----------------------
Added group "examplegroup"
----------------------
  Group name: examplegroup
  Description: for examples
  GID: 855800010
When no arguments are used, the command prompts for the required group account information: 
[bjensen@server ~]$ ipa group-add
Group name: engineering
Description: for engineers
-------------------------
Added group "engineering"
-------------------------
  Group name: engineering
  Description: for engineers
  GID: 387115842

Important

When a group is created without specifying a GID number, then the group entry is assigned the ID number that is next available in the server or replica range. (Number ranges are described more in Section 9.9, “Managing Unique UID and GID Number Assignments”.) This means that a group always has a unique number for its GID number.
If a number is manually assigned to a group entry, the server does not validate that the gidNumber is unique. It will allow duplicate IDs; this is expected (though discouraged) behavior for POSIX entries.
If two entries are assigned the same ID number, only the first entry is returned in a search for that ID number. However, both entries will be returned in searches for other attributes or with ipa group-find --all.

Note

You cannot edit the group name. The group name is the primary key, so changing it is the equivalent of deleting the group and creating a new one.
9.11.2.2. Adding Group Members
9.11.2.2.1. With the Web UI (Group Page)

Note

This procedure adds a user to a group. User groups can contain other user groups as their members. These are nested groups.
It can take up to several minutes for the members of the child group to show up as members of the parent group. This is especially true on virtual machines where the nested groups have more than 500 members.
When creating nested groups, be careful not to create recursive groups. For example, if GroupA is a member of GroupB, do not add GroupB as a member of GroupA. Recursive groups are not supported and can cause unpredictable behavior.
  1. Open the Identity tab, and select the User Groups subtab.
  2. Click the name of the group to which to add members.
  3. Click the Add link at the top of the task area.
  4. Click the checkbox by the names of the users to add, and click the right arrows button, >>, to move the names to the selection box.
  5. Click the Add button.
Group members can be users or other user groups. It can take up to several minutes for the members of the child group to show up as members of the parent group. This is especially true on virtual machines where the nested groups have more than 500 members.
9.11.2.2.2. With the Web UI (User's Page)
Users can also be added to a group through the user's page.
  1. Open the Identity tab, and select the Users subtab.
  2. Click the name of the user to edit.
  3. Open the User Groups tab on the user entry page.
  4. Click the Add link at the top of the task area.
  5. Click the checkbox by the names of the groups for the user to join, and click the right arrows button, >>, to move the groups to the selection box.
  6. Click the Add button.
9.11.2.2.3. With the Command Line
Members are added to a group using the group-add-member command. This command can add both users as group members and other groups as group members.
The syntax of the group-add-member command requires only the group name and a comma-separated list of users to add: 
[bjensen@server ~]$ ipa group-add-member groupName [--users=list] [--groups=list]
For example, this adds three users to the engineering group: 
[bjensen@server ~]$ ipa group-add-member engineering --users=jsmith,bjensen,mreynolds
  Group name: engineering
  Description: for engineers
  GID: 387115842
  Member users: jsmith,bjensen,mreynolds
-------------------------
Number of members added 3
-------------------------
Likewise, other groups can be added as members, which creates nested groups: 
[bjensen@server ~]$ ipa group-add-member engineering --groups=dev,qe1,dev2
  Group name: engineering
  Description: for engineers
  GID: 387115842
  Member groups: dev,qe1,dev2
  -------------------------
  Number of members added 3
  -------------------------
When displaying nested groups, members are listed as members and the members of any member groups are listed as indirect members. For example: 
[bjensen@server ~]$ ipa group-show examplegroup
  Group name: examplegroup
  Description: for examples
  GID: 93200002
  Member users: jsmith,bjensen,mreynolds
  Member groups: californiausers
  Indirect Member users: sbeckett,acalavicci
It can take up to several minutes for the members of the child group to show up as members of the parent group. This is especially true on virtual machines where the nested groups have more than 500 members.

Note

When creating nested groups, be careful not to create recursive groups. For example, if GroupA is a member of GroupB, do not add GroupB as a member of GroupA. Recursive groups are not supported and can cause unpredictable behavior.
A group member is removed using the group-remove-member command. 
[bjensen@server ~]$ ipa group-remove-member engineering --users=jsmith

  Group name: engineering
  Description: for engineers
  GID: 855800009
  Member users: bjensen,mreynolds
---------------------------
Number of members removed 1
---------------------------
9.11.2.2.4. Viewing Direct and Indirect Members of a Group
User groups can contain other user groups as members. This is called a nested group. This also means that a group has two types of members:
  • Direct members, which are added explicitly to the group
  • Indirect members, which are members of the group because they are members of another user group which is a member of the group
The IdM web UI has an easy way to view direct and indirect members of a group. The members list is filtered by member type, and this can be toggled by selecting the Direct and Indirect radio buttons at the top right corner of the members list.
Indirect and Direct Members

Figure 9.4. Indirect and Direct Members

Being able to track indirect members makes it easier to assign group membership properly, without duplicating membership.
9.11.2.3. Deleting User Groups
When a user group is deleted, only the group is removed. The user accounts of group members (including nested groups) are not affected. Additionally, any access control delegations that apply to that group are removed.

Warning

Deleting a group is immediate and permanent. If any group configuration (such as delegations) is required, it must be assigned to another group or a new group created.
9.11.2.3.1. With the Web UI
  1. Open the Identity tab, and select the User Groups subtab.
  2. Select the checkbox by the name of the group to delete.
  3. Click the Delete link at the top of the task area.
  4. When prompted, confirm the delete action.
9.11.2.3.2. With the Command Line
The group-del command to deletes the specified group. For example: 
[bjensen@server ~]$ ipa group-del examplegroup

9.11.3. Searching for Users and Groups

The user searches in IdM can be run against simple (full word) or partial search strings. The range of attributes that are searched is configured as part of the default IdM configuration, as in Section 9.10.4, “Specifying Default User and Group Attributes”.
9.11.3.1. Setting Search Limits
9.11.3.1.1. Types of Search Limits and Where They Apply
Some searches can result in a large number of entries being returned, possibly even all entries. Search limits improve overall server performance by limiting how long the server spends in a search and how many entries are returned.
Search limits have a dual purpose to improve server performance by reducing the search load and to improve usability by returning a smaller — and therefore easier to browse — set of entries.
The IdM server has several different limits imposed on searches:
  • The search limit configuration for the IdM server. This is a setting for the IdM server itself, which is applied to all requests sent to the server from all IdM clients, the IdM CLI tools, and the IdM web UI for normal page display.
    By default, this limit is 100 entries.
  • The time limit configuration for the IdM server. Much like the search size limit, the time limit sets a maximum amount of time that the IdM server, itself, waits for searches to run. Once it reaches that limit, the server stops the search and returns whatever entries were returned in that time.
    By default, this limit is two seconds.
  • The page size limit. Although not strictly a search limit, the page size limit does limit how many entries are returned per page. The server returns the set of entries, up to the search limit, and then sorts and displays 20 entries per page. Paging results makes the results more understandable and more viewable.
    This is hard-coded to 20 for all searches.
  • The LDAP search limit (--pkey option). All searches performed in the UI, and CLI searches which use the --pkey option, override the search limit set in the IdM server configuration and use the search limit set in the underlying LDAP directory.
    By default, this limit is 2000 entries. It can be edited by editing the 389 Directory Server configuration.
9.11.3.1.2. Setting IdM Search Limits
Search limits set caps on the number of records returned or the time spent searching when querying the database for user or group entries. There are two types of search limits: time limits and size (number) limits.
With the default settings, users are limited to two-second searches and no more than 100 records returned per search.

Important

Setting search size or time limits too high can negatively affect IdM server performance.
9.11.3.1.2.1. With the Web UI
  1. Open the IPA Server tab.
  2. Select the Configuration subtab.
  3. Scroll to the Search Options area.
  4. Change the search limit settings.
    • Search size limit, the maximum number of records to return in a search.
    • Search time limit, the maximum amount of time, in seconds, to spend on a search before the server returns results.

    Note

    Setting the time limit or size limit value to -1 means that there are no limits on searches.
  5. When the changes are complete, click the Update link at the top of the Configuration page.
9.11.3.1.2.2. With the Command Line
The search limits can be changed using the config-mod command. 
[bjensen@server ~]$ ipa config-mod --searchtimelimit=5 --searchrecordslimit=500

  Max. username length: 32
  Home directory base: /home
  Default shell: /bin/sh
  Default users group: ipausers
  Default e-mail domain for new users: example.com
  Search time limit: 5
  Search size limit: 50
  User search fields: uid,givenname,sn,telephonenumber,ou,title
  Group search fields: cn,description
  Enable migration mode: FALSE
  Certificate Subject base: O=EXAMPLE.COM
  Password Expiration Notification (days): 4

Note

Setting the time limit or size limit value to -1 means that there are no limits on searches.
9.11.3.1.3. Overriding the Search Defaults
Part of the server configuration is setting global defaults for size and time limits on searches. While these limits are always enforced in the web UI, they can be overridden with any *-find command run through the command line.
The --sizelimit and --timelimit options set alternative size and time limits, respectively, for that specific command run. The limits can be higher or lower, depending on the kinds of results you need.
For example, if the default time limit is 60 seconds and a search is going to take longer, the time limit can be increased to 120 seconds: 
[jsmith@ipaserver ~]$ ipa user-find smith --timelimit=120
9.11.3.2. Setting Search Attributes
A search for users or groups does not automatically search every possible attribute for that attribute. Rather, it searches a specific subset of attributes, and that list is configurable.
When adding attributes to the user or group search fields, make sure that there is a corresponding index within the LDAP directory for that attribute. Searches are performed based on indexes. Most standard LDAP attributes have indexes, but any custom attributes must have indexes created for them. Creating indexes is described in the indexes chapter in the Directory Server Administrator's Guide.
9.11.3.2.1. Default Attributes Checked by Searches
By default, there are six attributes that are indexed for user searches and two that are indexed for group searches. These are listed in Table 9.5, “Default Search Attributes”. All search attributes are searched in a user/group search.
Table 9.5. Default Search Attributes
User Search Attributes
First name Last name
Login ID Job title
Organizational unit Phone number
Group Search Attributes
Name Description
The attributes which are searched in user and group searches can be changed, as described in Section 9.11.3.2, “Setting Search Attributes” and Section 9.11.3.2.3, “Changing Group Search Attributes”.
9.11.3.2.2. Changing User Search Attributes
9.11.3.2.2.1. From the Web UI
  1. Open the IPA Server tab.
  2. Select the Configuration subtab.
  3. Scroll to the User Options area.
  4. Add any additional search attributes, in a comma-separated list, in the User search fields field.
  5. When the changes are complete, click the Update link at the top of the Configuration page.
9.11.3.2.2.2. From the Command Line
To change the search attributes, use the --usersearch option to set the attributes for user searches. 
[bjensen@server ~]$ ipa config-mod --usersearch=uid,givenname,sn,telephonenumber,ou,title

Note

Always give the complete list of search attributes. Whatever values are passed with the configuration argument overwrite the previous settings.
9.11.3.2.3. Changing Group Search Attributes
A search for users or groups does not automatically search every possible attribute for that attribute. Rather, it searches a specific subset of attributes, and that list is configurable.
When adding attributes to the user or group search fields, make sure that there is a corresponding index within the LDAP directory for that attribute. Searches are performed based on indexes. Most standard LDAP attributes have indexes, but any custom attributes must have indexes created for them. Creating indexes is described in the indexes chapter in the Directory Server Administrator's Guide.
9.11.3.2.3.1. From the Web UI
  1. Open the IPA Server tab.
  2. Select the Configuration subtab.
  3. Scroll to the Group Options area.
  4. Add any additional search attributes, in a comma-separated list, in the Group search fields field.
  5. When the changes are complete, click the Update link at the top of the Configuration page.
9.11.3.2.3.2. From the Command Line
To change the search attributes, use the --groupsearch options to set the attributes for group searches. 
[bjensen@server ~]$ ipa config-mod --groupsearch=cn,description

Note

Always give the complete list of search attributes. Whatever values are passed with the configuration argument overwrite the previous settings.
9.11.3.2.4. Limits on Attributes Returned in Search Results
Searches can be performed on attributes that are not displayed in the UI. This means that entries can be returned in a search that do not appear to match the given filter. This is especially common if the search information is very short, which increases the likelihood of a match.

[2] The key type is determined automatically from the key itself, if it is not included in the uploaded key.
[3] See Section 9.9, “Managing Unique UID and GID Number Assignments” for information on changing GID/UID assignment ranges.

Chapter 10. Identity: 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, like changing the client hostname.
This chapter describes how to manage identity services that relate directly to the client machine:
  • DNS entries and settings
  • Machine authentication
  • Hostname changes (which affect domain services)

10.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. 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:
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 Section 1.2, “Bringing Linux Services Together”) provides three main services specifically for machines:
  • DNS
  • Kerberos
  • Certificate management
Machines are treated as another identity that is managed by IdM. Clients use DNS to identify IdM servers, services, and domain members — which, like user identities are stored in the 389 Directory Server instance for the IdM server. Like users, machines can be authenticated to the domain using Kerberos or certificates to verify the machine's identity.
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 10.4, “Managing Public SSH Keys for Hosts” and the Red Hat Enterprise Linux Deployment Guide.
  • 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 20, Policy: 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, which is described in Appendix B, Working with certmonger.

10.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, its MAC address, and keys and certificates.
This information can be set when the host entry is created if it is created manually; otherwise, most of that information needs to be added to the host entry after the host is enrolled in the domain.
Table 10.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 hostname 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 An attribute switch which sets whether the host can dynamically update its DNS entries if its IP address changes.

10.3. 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.

10.3.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.

10.3.2. Re-enabling Hosts

Disabling a host essentially kills its current, active keytabs. Removing the keytabs effectively removes the host from the IdM domain without otherwise touching its configuration entry.
To re-enable a host, simply use the ipa-getkeytab command. The -s option sets which IdM server to request the keytab, -p gives the principal name, and -k gives the file to which to save the keytab.
For example, requesting a new host keytab: 
[jsmith@ipaserver ~]$  ipa-getkeytab -s ipaserver.example.com -p host/server.example.com -k /etc/krb5.keytab -D fqdn=server.example.com,cn=computers,cn=accounts,dc=example,dc=com -w password
If the ipa-getkeytab command is run on an active IdM client or server, then it can be run without any LDAP credentials (-D and -w). The IdM user uses Kerberos credentials to authenticate to the domain. To run the command directly on the disabled host, then supply LDAP credentials to authenticate to the IdM server. The credentials should correspond to the host or service which is being re-enabled.

10.4. 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, hostname, 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.

10.4.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 hostname 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.

10.4.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.

10.4.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:
4f:61:ee:2c:f7:d7:da:41:17:93:de:1d:19:ac:2e:c8 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 hostname,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== [hostname,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.
  5. In the Host Settings area of the Settings tab, click the SSH public keys: Add link.
  6. The UI opens a new link, New: key not set Show/Set key. Click the Show/Set key link.
  7. Paste in the public key for the host, and click the Set button.
    The SSH public keys field now shows New: key set. Clicking the Show/Set key link opens the submitted key.
  8. To upload multiple keys, click the Add link below the list of public keys, and upload the other keys.
  9. When all the keys have been submitted, click the Update link 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[4].
Saved Public Key

Figure 10.1. Saved Public Key

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.
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. This is covered in the Red Hat Enterprise Linux Deployment Guide.

10.4.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 64 bit-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 12345abcde==" --updatedns host1.example.com
    With a real key, the key is longer and usually ends with an equals sign (=).
    To upload multiple keys, pass a comma-separated list of keys with a single --sshpubkey option: 
    --sshpubkey="12345abcde==,key2==,key3=="

    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. This is covered in the Red Hat Enterprise Linux Deployment Guide.

10.4.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.
  3. Open the Host Settings area of the Settings tab.
  4. Click the Delete link by the fingerprint of the key to remove.
  5. Click the Update link 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

10.5. Setting Ethers Information for a Host

NIS can host an ethers table which can be used 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 ~]# getnt ethers server.example.com

10.6. Renaming Machines and Reconfiguring IdM Client Configuration

The hostname of a system is critical for the correct operation of Kerberos and SSL. Both of these security mechanisms rely on the hostname to ensure that communication is occurring between the specified hosts. Infrastructures which use virtual machines or clustered servers will commonly have hosts which are renamed because systems are copied, moved, or renamed.
Red Hat Enterprise Linux does not provide a simple rename command to facilitate the renaming of an IdM host. Renaming a host in an IdM domain involves deleting the entry in IdM, uninstalling the client software, changing the hostname, and re-enrolling using the new name. Additionally, part of renaming hosts requires regenerating service principals.
To reconfigure the client:
  1. Identify which services are running on the machine. These need to be re-created when the machine is re-enrolled. 
    # ipa service-find server.example.com
    Each host has a default service which does not appear in the list of services. This service can be referred to as the "host service". The service principal for the host service is host/<hostname>, such as host/server.example.com. This principal can also be referred to as the host principal.
  2. Identify all host groups to which the machine belongs. 
    [root@client ~]# kinit admin
[root@client ~]# ipa hostgroup-find server.example.com
  3. Identify which of the services have certificates associated with them. This can be done using the ldapsearch command to check the entries in the IdM LDAP database directly: 
    [root@client ~]# ldapsearch -x -b "cn=accounts,dc=example,dc=com" "(&(objectclass=ipaservice)(userCertificate=*))" krbPrincipalName -D "cn=directory manager" -w secret -h ipaserver.example.com -p 389
  4. For any service principals (in addition to the host principal), determine the location of the corresponding keytabs on server.example.com. The keytab location is different for each service, and IdM does not store this information.
    Each service on the client system has a Kerberos principal in the form service_name/hostname@REALM, such as ldap/server.example.com@EXAMPLE.COM.
  5. Unenroll the client machine from the IdM domain: 
    [root@client ~]# ipa-client-install --uninstall
  6. For each identified keytab other than /etc/krb5.keytab, remove the old principals: 
    [root@client ~]# ipa-rmkeytab -k /path/to/keytab -r EXAMPLE.COM
  7. On an IdM server, as an IdM administrator, remove the host entry. This removes all services and revokes all certificates issued for that host: 
    [root@server ~]# kinit admin
[root@server ~]# ipa host-del server.example.com
    At this point, the host is completely removed from IdM.
  8. Rename the machine.
  9. Re-enroll the system with IdM: 
    [root@client ~]# ipa-client-install
    This generates a host principal for with the new hostname in /etc/krb5.keytab.
  10. On an IdM server, add a new keytab for every service: 
    [root@server ~]# ipa service-add serviceName/new-hostname
  11. To generate certificates for services, use either certmonger or the IdM administration tools.
  12. Re-add the host to any applicable host groups.

10.7. Managing Host Groups

Host groups are a way of centralizing control over important management tasks, particularly access control.
All groups in Identity Management are essentially static groups, meaning that the members of the group are manually and explicitly added to the group. Tangentially, IdM allows nested groups, where a group is a member of another group. In that case, all of the group members of the member group automatically belong to the parent group, as well.
Because groups are easy to create, it is possible to be very flexible in what groups to create and how they are organized. Groups can be defined around organizational divisions like departments, physical locations, or IdM or infrastructure usage guidelines for access controls.

10.7.1. Creating Host Groups

10.7.1.1. Creating Host Groups from the Web UI
  1. Open the Identity tab, and select the Host Groups subtab.
  2. Click the Add link at the top of the groups list.
  3. Enter the name and a description for the group.
  4. Click the Add and Edit button to go immediately to the member selection page.
  5. Select the members, as described in Section 10.7.2.2, “Adding Host Group Members from the Web UI”.
10.7.1.2. Creating Host Groups from the Command Line
New groups are created using the hostgroup-add command. (This adds only the group; members are added separately.)
Two attributes are always required: the group name and the group description. If those attributes are not given as arguments, then the script prompts for them. 
$ ipa hostgroup-add groupName --desc="description"

10.7.2. Adding Host Group Members

10.7.2.1. Showing and Changing Group Members
Members can be added to a group through the group configuration. There are tabs for all the member types which can belong to the group, and an administrator picks all of the matching entries and adds them as members.
However, it is also possible for an entity to be added to a group through its own configuration. Each entry has a list of tabs that displays group types that the entry can join. The list of all groups of that type is displayed, and the entity can be added to multiple groups at the same time.
Member Of...

Figure 10.2. Member Of...

10.7.2.2. Adding Host Group Members from the Web UI
  1. Open the Identity tab, and select the Host Groups subtab.
  2. Click the name of the group to which to add members.
  3. Click the Add link at the top of the task area.
  4. Click the checkbox by the names of the hosts to add, and click the right arrows button, >>, to move the hosts to the selection box.
  5. Click the Add button.
10.7.2.3. Adding Host Group Members from the Command Line
Members are added to a host group using the hostgroup-add-member command. This command can add both hosts as group members and other groups as group members.
The syntax of the hostgroup-add-member command requires only the group name and a comma-separated list of hosts to add: 
$ ipa hostgroup-add-member groupName [--hosts=list] [--hostgroups=list]
For example, this adds three hosts to the caligroup group: 
$ ipa hostgroup-add-member caligroup --hosts=ipaserver.example.com,client1.example.com,client2.example.com
  Group name: caligroup
  Description: for machines in california
  GID: 387115842
  Member hosts: ipaserver.example.com,client1.example.com,client2.example.com
-------------------------
Number of members added 3
-------------------------
Likewise, other groups can be added as members, which creates nested groups: 
$ ipa hostgroup-add-member caligroup --groups=mountainview,sandiego
  Group name: caligroup
  Description: for machines in california
  GID: 387115842
  Member groups: mountainview,sandiego
  -------------------------
  Number of members added 2
  -------------------------

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

Chapter 11. Identity: 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 Section 1.2, “Bringing Linux Services Together”) provides three main services specifically for machines:
  • DNS
  • Kerberos
  • Certificate management

11.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.

11.1.1. Adding Services and Keytabs from the Web UI

  1. Open the Identity tab, and select the Services subtab.
  2. Click the Add link 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 hostname of the IdM host on which the service is running. The hostname 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 hostname 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.

    Warning

    Creating a new key resets the secret for the specified principal. This means that all other keytabs for that principal are rendered invalid.

11.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 hostname 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.

    Warning

    The ipa-getkeytab command resets the secret for the specified principal. This means that all other keytabs for that principal are rendered invalid.

11.2. Adding Services and Certificates for Services

While services can use keytabs, some services require certificates for access. In that case, a service can be added (or modified) to include a certificate with its service entry.

11.2.1. Adding Services and Certificates from the Web UI

  1. Open the Identity tab, and select the Services subtab.
  2. Click the Add link 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 hostname of the IdM host on which the service is running. The hostname is used to construct the full service principal name.
  5. Click the Add and Edit button to go directly to the service entry page.
  6. Scroll to the bottom of the page, to the Service Certificate section.
  7. Click the New Certificate button to create the service certificate.

11.2.2. Adding Services and Certificates from the Command Line

  1. Create the service principal. The service is recognized through a name like service/FQDN: 
    [jsmith@ipaserver ~]$ kinit admin
[jsmith@ipaserver ~]$ 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 a certificate for the service. Be sure to copy the keytab to the appropriate directory for the service.
    For example: 
    $ ipa cert-request --principal=HTTP/web.example.com example.csr

    Note

    Use the --add option to create the service automatically when requesting the certificate.
    Alternatively, use the getcert command, which creates and manages the certificate through certmonger. The options are described more in Section B.1, “Requesting a Certificate with certmonger”. 
    $ ipa-getcert request -d /etc/httpd/alias -n Server-Cert -K HTTP/client1.example.com -N 'CN=client1.example.com,O=EXAMPLE.COM'

11.3. Storing Certificates in NSS Databases

When services use certificates, the certificates and keys can be stored in NSS databases (which may also be used by the services themselves, as well as Identity Management).
  1. Create the NSS databases. 
    $ certutil -N -d /path/to/database/dir
  2. Request the certificate using certutil, an NSS tool. 
    $ certutil -R -s "CN=client1.example.com,O=EXAMPLE.COM" -d /path/to/database/dir -a > example.csr
If the IdM domain is using Certificate System for its CA, only the CN of the subject name is used. With a self-signed CA, the subject must match the configured certificate subject base. The IdM server rejects requests with a subject base that differs from this value.

11.4. 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 hostnames 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.

11.5. 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.

11.6. Disabling and Re-enabling Service Entries

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

11.6.1. Disabling Service Entries

Disabling a service prevents domain users from access it without permanently removing it from the domain. This can be done by using the service-disable command.
For a service, specify the principal for the service. For example: 
[jsmith@ipaserver ~]$ kinit admin
$ ipa service-disable http/server.example.com

Important

Disabling a host entry not only disables that host. It disables every configured service on that host as well.

11.6.2. Re-enabling and Services

Disabling a service essentially kills its current, active keytabs. Removing the keytabs effectively removes the service from the IdM domain without otherwise touching its configuration entry.
To re-enable a service, simply use the ipa-getkeytab command. The -s option sets which IdM server to request the keytab, -p gives the principal name, and -k gives the file to which to save the keytab.
For example, requesting a new HTTP keytab: 
[root@ipaserver ~]# ipa-getkeytab -s ipaserver.example.com -p HTTP/server.example.com -k /etc/httpd/conf/krb5.keytab -e aes256-cts
If the ipa-getkeytab command is run on an active IdM client or server, then it can be run without any LDAP credentials (-D and -w). The IdM user uses Kerberos credentials to authenticate to the domain. To run the command directly on a disabled host, then supply LDAP credentials to authenticate to the IdM server. The credentials should correspond to the host or service which is being re-enabled.

Chapter 12. Identity: Delegating Access to Hosts and Services

As discussed in Section 1.3, “Relationships Between Servers and Clients”, within the IdM domain, manage means being able to retrieve a keytab and certificates for another host or service. Every host and service has a managedby entry which lists what hosts or services can manage it. By default, a host can manage itself and all of its services. It is also possible to allow a host to manage other hosts, or services on other hosts, by updating the appropriate delegations or providing a suitable managedby entry.
An IdM service can be managed from any IdM host, as long as that host has been granted, or delegated, permission to access the service. Likewise, hosts can be delegated permissions to other hosts within the domain.
Host and Service Delegation

Figure 12.1. Host and Service Delegation

Note

If a host is delegated authority to another host through a managedBy entry, it does not mean that the host has also been delegated management for all services on that host. Each delegation has to be performed independently.

12.1. Delegating Service Management

A host is delegated control over a service using the service-add-host command. There are two parts to delegating the service: specifying the principal and identifying the hosts (in a comma-separated list) with control: 
# ipa service-add-host principal --hosts=hostnames
For example: 
# ipa service-add-host http/web.example.com --hosts=client1.example.com
Once the host is delegated authority, the host principal can be used to manage the service: 
# kinit -kt /etc/krb5.keytab host/`hostname`
# ipa-getkeytab -s `hostname` -k /tmp/test.keytab -p http/web.example.com
Keytab successfully retrieved and stored in: /tmp/test.keytab
To create a ticket for this service, create a certificate request on the host with the delegated authority and use the cert-request command to create a service entry and load the certification information: 
# ipa cert-request --add --principal=http/web.example.com web.csr
  Certificate: MIICETCCAXqgA...[snip]
  Subject: CN=web.example.com,O=EXAMPLE.COM
  Issuer: CN=EXAMPLE.COM Certificate Authority
  Not Before: Tue Feb 08 18:51:51 2011 UTC
  Not After: Mon Feb 08 18:51:51 2016 UTC
  Fingerprint (MD5): c1:46:8b:29:51:a6:4c:11:cd:81:cb:9d:7c:5e:84:d5
  Fingerprint (SHA1):
  01:43:bc:fa:b9:d8:30:35:ee:b6:54:dd:a4:e7:d2:11:b1:9d:bc:38
  Serial number: 1005

12.2. Delegating Host Management

Hosts are delegated authority over other hosts through the host-add-managedby command. This creates a managedby entry. Once the managedby entry is created, then the host can retrieve a keytab for the host it has delegated authority over.
  1. Log in as the admin user. 
    # kinit admin
  2. Add the managedby entry. For example, this delegates authority over client2 to client1. 
    # ipa host-add-managedby client2.example.com --hosts=client1.example.com
  3. Obtain a ticket as the host client1 and then retrieve a keytab for client2: 
    # kinit -kt /etc/krb5.keytab host/`hostname`
# ipa-getkeytab -s `hostname` -k /tmp/client2.keytab -p host/client2.example.com
Keytab successfully retrieved and stored in: /tmp/client2.keytab

12.3. Delegating Host or Service Management in the Web UI

Each host and service entry has a configuration tab that indicates what hosts have been delegated management control over that host or service.
  1. Open the Identity tab, and select the Hosts or Services subtab.
  2. Click the name of the host or service that you are going to grant delegated management to.
  3. Click the Hosts subtab on the far right of the host/service entry. This is the tab which lists hosts which can manage the selected host/service.
  4. Click the Add link at the top of the list.
  5. Click the checkbox by the names of the hosts to which to delegate management for the host/service. Click the right arrows button, >>, to move the hosts to the selection box.
  6. Click the Add button to close the selection box and to save the delegation settings.

12.4. Accessing Delegated Services

For both services and hosts, if a client has delegated authority, it can obtain a keytab for that principal on the local machine. For services, this has the format service/hostname@REALM. For hosts, the service is host.
With kinit, use the -k option to load a keytab and the -t option to specify the keytab.
For example, to access a host: 
# kinit -kt /etc/krb5.keytab host/ipa.example.com@EXAMPLE.COM
To access a service: 
# kinit -kt /etc/httpd/conf/krb5.keytab http/ipa.example.com@EXAMPLE.COM

Chapter 13. Identity: Integrating with NIS Domains and Netgroups

Network information service (NIS) is one of the most common ways to manage identities and authentication on Unix networks. It is simple and easy to use, but it also has inherent security risks and a lack of flexibility that can make administering NIS domains problematic.
Identity Management supplies a way to integrate netgroups and other NIS data into the IdM domain, which incorporates the stronger security structure of IdM over the NIS configuration. Alternatively, administrators can simply migrate user and host identities from a NIS domain into the IdM domain.

13.1. About NIS and Identity Management

Network information service (NIS) centrally manages authentication and identity information such as users and passwords, hosts and IP addresses, and POSIX groups. This was originally called Yellow Pages (abbreviated YP) because of its simple focus on identity and authentication lookups.
NIS is considered too insecure for most modern network environments because it provides no host authentication mechanisms and it transmits all of its information over the network unencrypted, including password hashes. Still, while NIS has been falling out of favor with administrators, it is still actively used by many system clients. There are ways to work around those insecurities by integrating NIS with other protocols which offer enhanced security.
In Identity Management, NIS objects are integrated into IdM using the underlying LDAP directory. LDAP services offer support for NIS objects (as defined in RFC 2307), which Identity Management customizes to provide better integration with other domain identities. The NIS object is created inside the LDAP service and then a module like nss_ldap or SSSD fetches the object using an encrypted LDAP connection.
NIS entities are stored in netgroups. A netgroup allows nesting (groups inside groups), which standard Unix groups don't support. Also, netgroups provide a way to group hosts, which is also missing in Unix group.
NIS groups work by defining users and hosts as members of a larger domain. A netgroup sets a trio of information — host, user, domain. This is called a triple. 
host,user,domain
A netgroup triple associates the user or the host with the domain; it does not associate the user and the host with each other. Therefore, a triple usually defines a host or a user for better clarity and management. 
host.example.com,,nisdomain.example.com
-,jsmith,nisdomain.example.com
NIS distributes more than just netgroup data. It stores information about users and passwords, groups, network data, and hosts, among other information. Identity Management can use a NIS listener to map passwords, groups, and netgroups to IdM entries.
In IdM LDAP entries, the users in a netgroup can be a single user or a group; both are identified by the memberUser parameter. Likewise, hosts can be either a single host or a host group; both are identified by the memberHost attribute. 
dn: ipaUniqueID=d4453480-cc53-11dd-ad8b-0800200c9a66,cn=ng,cn=accounts,...
objectclass: top
objectclass: ipaAssociation
objectclass: ipaNISNetgroup
ipaUniqueID: d4453480-cc53-11dd-ad8b-0800200c9a66
cn: netgroup1
memberHost: fqdn=host1.example.com,cn=computers,cn=accounts,...
memberHost: cn=VirtGuests,cn=hostgroups,cn=accounts,...
memberUser: cn=jsmith,cn=users,cn=accounts,...
memberUser: cn=bjensen,cn=users,cn=accounts,...
memberUser: cn=Engineering,cn=groups,cn=accounts,...
nisDomainName: nisdomain.example.com
In Identity Management, these netgroup entries are handled using the netgroup-* commands, which show the basic LDAP entry: 
# ipa netgroup-show netgroup1
Netgroup name: netgroup1
Description: my netgroup
NIS domain name: nisdomain
Member User: jsmith
Member User: bjensen
Member User: Engineering
Member Host: host1.example.com
Member Host: VirtGuests
When a client attempts to access the NIS netgroup, then Identity Management translates the LDAP entry into a traditional NIS map and sends it to a client over the NIS protocol (using a NIS plug-in) or it translates it into an LDAP format that is compliant with RFC 2307 or RFC 2307bis.

13.2. Setting the NIS Port for Identity Management

The IdM server binds to its NIS services over a random port that is selected when the server starts. It sends that port assignment to the portmapper so that NIS clients know what port to use to contact the IdM server.
Administrators may need to open a firewall for NIS clients or may have other services that need to know the port number in advance and need that port number to remain the same. In that case, an administrator can specify the port to use.

Note

Any available port number below 1024 can be used for the NIS Plug-in setting.
The NIS configuration is in the NIS Plug-in in Identity Management's internal Directory Server instance. To specify the port:
  1. Enable the NIS listener and compatibility plug-ins: 
    [root@ipaserver ~]# ipa-nis-manage enable
[root@ipaserver ~]# ipa-compat-manage enable
  2. Edit the plug-in configuration and add the port number as an argument. For example, to set the port to 514: 
    [root@ipaserver ~]# ldapmodify -x -D 'cn=directory manager' -w secret
	
dn: cn=NIS Server,cn=plugins,cn=config 
changetype: modify
add: nsslapd-pluginarg0
nsslapd-pluginarg0: 514

modifying entry "cn=NIS Server,cn=plugins,cn=config"
  3. Restart the Directory Server to load the new plug-in configuration. 
    [root@ipaserver ~]# service dirsrv restart

13.3. Creating Netgroups

All netgroups in Identity Management are essentially static groups, meaning that the members of the group are manually and explicitly added to the group. Tangentially, IdM allows nested groups, where a group is a member of another group. In that case, all of the group members of the member group automatically belong to the parent group, as well.
Netgroups are added in two steps: the group itself is created, and then members are added to it.

13.3.1. Adding Netgroups

13.3.1.1. With the Web UI
  1. Open the Identity tab, and select the Netgroups subtab.
  2. Click the Add link at the top of the netgroups list.
  3. Enter both a unique name and a description for the netgroup. Both the name and description are required.
    The group name is the identifier used for the netgroup in the IdM domain, and it cannot be changed after it is created. The name cannot contain spaces, but other separators like an underscore (_) are allowed.
  4. Click the Add and Edit button to go immediately to the netgroup's edit pages.
  5. Optionally, set the NIS domain for the netgroup. This defaults to the IdM domain, but it can be changed.
    1. Click the Settings tab.
    2. Enter the name of the alternate NIS domain in the NIS domain name field.
      The NIS domain name field sets the domain that appears in the netgroup triple. It does not affect which NIS domain the Identity Management listener responds to.
  6. Add members, as described in Section 13.3.2.1, “With the Web UI”.
13.3.1.2. With the Command Line
New netgroups are added using the netgroup-add command. This adds only the group; members are added separately. Two attributes are always required: the group name and the group description. If those attributes are not given as arguments, then the script prompts for them. There is also an option to set the NIS domain name to use for the group; this defaults to the IdM domain, but it can be set to something different, depending on the network configuration. 
$ ipa netgroup-add --desc="description"  [--nisdomain=domainName]  groupName
For example: 
# ipa netgroup-add --desc="my new netgroup" example-netgroup
# ipa netgroup-add-member --hosts=ipa.example.com example-netgroup
# ypcat -d example.com -h ipa.example.com netgroup
(ipa.example.com,-,example.com)

Note

The --nisdomain option sets the domain that appears in the netgroup triple. It does not affect which NIS domain the Identity Management listener responds to.

13.3.2. Adding Netgroup Members

Note

Netgroups can contain user groups, host groups, and other netgroups as their members. These are nested groups.
It can take up to several minutes for the members of the child group to show up as members of the parent group. This is especially true on virtual machines where the nested groups have more than 500 members.
When creating nested groups, be careful not to create recursive groups. For example, if GroupA is a member of GroupB, do not add GroupB as a member of GroupA. Recursive groups are not supported and can cause unpredictable behavior.
13.3.2.1. With the Web UI
  1. Open the Identity tab, and select the Netgroups subtab.
  2. Click the name of the netgroup to which to add members.
  3. Select the tab for the type of netgroup member to add. Netgroups can have users, user groups, hosts, host groups, and other netgroups as members.
  4. Click the Add link at the top of the task area.
  5. Click the checkbox by the names of the users to add, and click the right arrows button, >>, to move the names to the selection box.
  6. Click the Add button.
13.3.2.2. With the Command Line
Once the group is configured, begin adding netgroup members with the netgroup-add-member command. Users, groups, hosts, host groups, and other netgroups can all be added to the netgroup entry. The entry name of the NIS group being edited usually comes at the end of the command: 
# ipa netgroup-add-member --users=users --groups=groups --hosts=hosts --hostgroups=hostGroups --netgroups=netgroups  groupName
To set more than one member, use a comma-separated list with the option. For example, this sets two users and two hosts with the other configuration: 
# ipa netgroup-add-member --users=jsmith,bjensen --groups=ITadmin --hosts=host1.example.com,host2.example.com --hostgroups=EngDev --netgroups=nisgroup2 example-group

13.4. Exposing Automount Maps to NIS Clients

When the NIS service is enabled on a system, the IdM server is automatically configured to set the NIS domain to the IdM domain's name, and to include IdM users, groups, and netgroups as passwd, group, and netgroup maps in the NIS domain.
If any automount maps are already defined, these maps need to be manually added to the NIS configuration in Identity Management for them to be exposed to NIS clients. The NIS server is managed by a special plug-in entry in the IdM LDAP directory; this is a container entry, and each NIS domain and map used by the NIS server is configured as a child entry beneath that container. The NIS domain entry in the must have the name of the NIS domain, the name of the NIS map, how to find the directory entries to use as the NIS map's contents, and which attributes to use as the NIS map's key and value. Most of these settings will be the same for every map.
The IdM server stores the automount maps, grouped by automount location, in the cn=automount branch of the IdM directory tree.
The NIS domain and map is added using LDAP tools, like ldapadd, and editing the directory directly. For example, this adds an automount map that is named auto.example in a location named default and for a server named nisserver: 
[root@server ~]# ldapadd -h nisserver.example.com -x -D "cn=Directory Manager" -w secret

dn: nis-domain=example.com+nis-map=auto.example,cn=NIS Server,cn=plugins,cn=config
objectClass: extensibleObject
nis-domain: example.com
nis-map: auto.example
nis-filter: (objectclass=automount)
nis-key-format: %{automountKey}
nis-value-format: %{automountInformation}
nis-base: automountmapname=auto.example,cn=default,cn=automount,dc=example,dc=com
A similar add operation needs to be run for every map that is configured.

13.5. Migrating from NIS to IdM

There is no direct migration path from NIS to Identity Management. This is a manual process with three major steps: setting up netgroup entries in IdM, exporting the existing data from NIS, and importing that data into IdM. There are several options for how to set up the IdM environment and how to export data; the best option depends on the type of data and the overall network environment that you have.

13.5.1. Preparing Netgroup Entries in IdM

The first step is to identify what kinds of identities are being managed by NIS. Frequently, a NIS server is used for either user entries or host entries, but not for both, which can simplify the data migration process.
For user entries

Determine what applications are using the user information in the NIS server. While some clients (like sudo) require NIS netgroups, many clients can use Unix groups instead. If no netgroups are required, then simply create corresponding user accounts in IdM and delete the netgroups entirely. Otherwise, create the user entries in IdM and then create an IdM-managed netgroup and add those users as members. This is described in Section 13.3, “Creating Netgroups”.

For host entries

Whenever a host group is created in IdM, a corresponding shadow NIS group is automatically created. These netgroups can then be managed using the ipa-host-net-manage command.

For a direct conversion

It may be necessary to have an exact conversion, with every NIS user and host having an exact corresponding entry in IdM. In that case, each entry can be created using the original NIS names:

  1. Create an entry for every user referenced in a netgroup.
  2. Create an entry for every host referenced in a netgroup.
  3. Create a netgroup with the same name as the original netgroup.
  4. Add the users and hosts as direct members of the netgroup. Alternatively, add the users and hosts into IdM groups or other netgroups, and then add those groups as members to the netgroup.

13.5.2. Enabling the NIS Listener in Identity Management

The IdM Directory Server can function as a limited NIS server. The slapi-nis plug-in sets up a special NIS listener that receives incoming NIS requests and manages the NIS maps within the Directory Server. Identity Management uses three NIS maps:
  • passwd
  • group
  • netgroup
Using IdM as an intermediate NIS server offers a reasonable way to handle NIS requests while migrating NIS clients and data.
The slapi-nis plug-in is not enabled by default. To enable NIS for Identity Management:
  1. Obtain new Kerberos credentials as an IdM admin user. 
    [root@ipaserver ~]# kinit admin
  2. Enable the NIS listener and compatibility plug-ins: 
    [root@ipaserver ~]# ipa-nis-manage enable
[root@ipaserver ~]# ipa-compat-manage enable
  3. Restart the DNS and Directory Server service: 
    [root@server ~]# service rpcbind restart
[root@server ~]# service dirsrv restart

13.5.3. Exporting and Importing the Existing NIS Data

NIS can contain information for users, groups, DNS and hosts, netgroups, and automount maps. Any of these entry types can be migrated over to the IdM server.
Migration is performed by exporting the data using ypcat and then looping through that output and creating the IdM entries with the corresponding ipa *-add commands. While this could be done manually, it is easiest to script it. These examples use a shell script.
13.5.3.1. Importing User Entries
The /etc/passwd file contains all of the NIS user information. These entries can be used to create IdM user accounts with UID, GID, gecos, shell, home directory, and name attributes that mirror the NIS entries.
For example, this is nis-user.sh: 
#!/bin/sh
# 1 is the nis domain, 2 is the nis master server
ypcat -d $1 -h $2 passwd > /dev/shm/nis-map.passwd 2>&1 
  
IFS=$'\n' 
for line in $(cat /dev/shm/nis-map.passwd); do  
        IFS=' ' 
        username=$(echo $line|cut -f1 -d:)  
        # Not collecting encrypted password because we need cleartext password to create kerberos key     
        uid=$(echo $line|cut -f3 -d:)  
        gid=$(echo $line|cut -f4 -d:)  
        gecos=$(echo $line|cut -f5 -d:)  
        homedir=$(echo $line|cut -f6 -d:)  
        shell=$(echo $line|cut -f7 -d:)  
                          
        # Now create this entry  
        echo passw0rd1|ipa user-add $username --first=NIS --last=USER --password --gidnumber=$gid --uid=$uid --gecos=$gecos --homedir=$homedir --shell=$shell 
        ipa user-show $username 
done
This can be run for a given NIS domain: 
[root@nis-server ~]# kinit admin
[root@nis-server ~]# ./nis-user.sh nisdomain nis-master.example.com

Note

This script does not migrate user passwords. Rather, it creates a temporary password which users are then prompted to change when they next log in.
13.5.3.2. Importing Group Entries
The /etc/group file contains all of the NIS group information. These entries can be used to create IdM user group accounts with the GID, gecos, shell, home directory, and name attributes that mirror the NIS entries.
For example, this is nis-group.sh: 
#!/bin/sh
# 1 is the nis domain, 2 is the nis master server
ypcat -d $1 -h $2 group > /dev/shm/nis-map.group 2>&1 
  
IFS=$'\n' 
for line in $(cat /dev/shm/nis-map.group); do  
        IFS=' ' 
        groupname=$(echo $line|cut -f1 -d:)  
        # Not collecting encrypted password because we need cleartext password to create kerberos key     
        gid=$(echo $line|cut -f3 -d:)  
        members=$(echo $line|cut -f4 -d:)  
                          
        # Now create this entry  
        ipa group-add $groupname --desc=NIS_GROUP_$groupname --gid=$gid 
        if [ -n "$members" ]; then 
                ipa group-add-member $groupname --users=$members 
        fi 
        ipa group-show $groupname 
done
This can be run for a given NIS domain: 
[root@nis-server ~]# kinit admin
[root@nis-server ~]# ./nis-group.sh nisdomain nis-master.example.com
13.5.3.3. Importing Host Entries
The /etc/hosts file contains all of the NIS host information. These entries can be used to create IdM host accounts that mirror the NIS entries.
For example, this is nis-hosts.sh: 
#!/bin/sh
# 1 is the nis domain, 2 is the nis master server
ypcat -d $1 -h $2 hosts | egrep -v "localhost|127.0.0.1" > /dev/shm/nis-map.hosts 2>&1 
 
IFS=$'\n' 
for line in $(cat /dev/shm/nis-map.hosts); do  
        IFS=' ' 
        ipaddress=$(echo $line|awk '{print $1}') 
        hostname=$(echo $line|awk '{print $2}') 
        master=$(ipa env xmlrpc_uri |tr -d '[:space:]'|cut -f3 -d:|cut -f3 -d/) 
        domain=$(ipa env domain|tr -d '[:space:]'|cut -f2 -d:) 
        if [ $(echo $hostname|grep "\." |wc -l) -eq 0 ]; then 
                hostname=$(echo $hostname.$domain) 
        fi  
        zone=$(echo $hostname|cut -f2- -d.) 
        if [ $(ipa dnszone-show $zone 2>/dev/null | wc -l) -eq 0 ]; then 
                ipa dnszone-add --name-server=$master --admin-email=root.$master 
        fi 
        ptrzone=$(echo $ipaddress|awk -F. '{print $3 "." $2 "." $1 ".in-addr.arpa."}')  
        if [ $(ipa dnszone-show $ptrzone 2>/dev/null|wc -l) -eq 0 ]; then   
                ipa dnszone-add  $ptrzone --name-server=$master --admin-email=root.$master 
        fi 
        # Now create this entry  
        ipa host-add $hostname --ip-address=$ipaddress 
        ipa host-show $hostname 
done
This can be run for a given NIS domain: 
[root@nis-server ~]# kinit admin
[root@nis-server ~]# ./nis-hosts.sh nisdomain nis-master.example.com

Note

This script example does not account for special host scenarios, such as using aliases.
13.5.3.4. Importing Netgroup Entries
The /etc/netgroup file contains all of the NIS netgroup information. These entries can be used to create IdM netgroup accounts that mirror the NIS entries.
For example, this is nis-netgroup.sh: 
#!/bin/sh
# 1 is the nis domain, 2 is the nis master server
ypcat -k -d $1 -h $2 netgroup > /dev/shm/nis-map.netgroup 2>&1 
 
IFS=$'\n' 
for line in $(cat /dev/shm/nis-map.netgroup); do  
        IFS=' ' 
        netgroupname=$(echo $line|awk '{print $1}') 
        triples=$(echo $line|sed "s/^$netgroupname //") 
        echo "ipa netgroup-add $netgroupname --desc=NIS_NG_$netgroupname" 
        if [ $(echo $line|grep "(,"|wc -l) -gt 0 ]; then 
                echo "ipa netgroup-mod $netgroupname --hostcat=all" 
        fi 
        if [ $(echo $line|grep ",,"|wc -l) -gt 0 ]; then 
                echo "ipa netgroup-mod $netgroupname --usercat=all" 
        fi 
 
        for triple in $triples; do 
                triple=$(echo $triple|sed -e 's/-//g' -e 's/(//' -e 's/)//') 
                if [ $(echo $triple|grep ",.*,"|wc -l) -gt 0 ]; then 
                        hostname=$(echo $triple|cut -f1 -d,) 
                        username=$(echo $triple|cut -f2 -d,) 
                        domain=$(echo $triple|cut -f3 -d,) 
                        hosts=""; users=""; doms=""; 
                        [ -n "$hostname" ] && hosts="--hosts=$hostname" 
                        [ -n "$username" ] && users="--users=$username" 
                        [ -n "$domain"   ] && doms="--nisdomain=$domain" 
                        echo "ipa netgroup-add-member $hosts $users $doms" 
                else 
                        netgroup=$triple 
                        echo "ipa netgroup-add $netgroup --desc=NIS_NG_$netgroup" 
                fi 
        done 
done
As explained briefly in Section 13.1, “About NIS and Identity Management”, NIS entries exist in a set of three values, called a triple. The triple is host,user,domain, but not every component is required; commonly, a triple only defines a host and domain or user and domain. The way this script is written, the ipa netgroup-add-member command always adds a host, user, and domain triple to the netgroup. 
if [ $(echo $triple|grep ",.*,"|wc -l) -gt 0 ]; then 
        hostname=$(echo $triple|cut -f1 -d,) 
        username=$(echo $triple|cut -f2 -d,) 
        domain=$(echo $triple|cut -f3 -d,) 
        hosts=""; users=""; doms=""; 
        [ -n "$hostname" ] && hosts="--hosts=$hostname" 
        [ -n "$username" ] && users="--users=$username" 
        [ -n "$domain"   ] && doms="--nisdomain=$domain" 
        echo "ipa netgroup-add-member $hosts $users $doms"
Any missing element is added as a blank, so the triple is properly migrated. For example, for the triple server,,domain the options with the member add command are --hosts=server --users="" --nisdomain=domain.
This can be run for a given NIS domain by specifying the NIS domain and NIS server: 
[root@nis-server ~]# kinit admin
[root@nis-server ~]# ./nis-hosts.sh nisdomain nis-master.example.com
13.5.3.5. Importing Automount Maps
Automount maps are actually a series of nested and inter-related entries that define the location (the parent entry), and then associated keys and maps.
While the data are the same in the NIS and IdM entries, the way that data are defined is different. The NIS information is exported and then used to construct an LDAP entry for the automount location and associated map; it then creates an entry for every configured key for the map.
Unlike the other NIS migration script examples, this script takes options to create an automount location and a map name, along with the migrated NIS domain and server. 
#!/bin/sh
# 1 is for the automount entry in ipa

ipa automountlocation-add $1 
 
# 2 is the nis domain, 3 is the nis master server, 4 is the map name 
ypcat -k -d $2 -h $3 $4 > /dev/shm/nis-map.$4 2>&1 
 
ipa automountmap-add $1 $4 
 
basedn=$(ipa env basedn|tr -d '[:space:]'|cut -f2 -d:) 
cat > /tmp/amap.ldif <<EOF 
dn: nis-domain=nisdomain.example.com+nis-map=$4,cn=NIS Server,cn=plugins,cn=config 
objectClass: extensibleObject 
nis-domain: $3 
nis-map: $4 
nis-base: automountmapname=$4,cn=nis,cn=automount,$basedn 
nis-filter: (objectclass=*) 
nis-key-format: %{automountKey} 
nis-value-format: %{automountInformation}        
EOF 
ldapadd -x -h $3 -D "cn=directory manager" -w secret -f /tmp/amap.ldif 
 
IFS=$'\n' 
for line in $(cat /dev/shm/nis-map.$4); do  
        IFS=" " 
        key=$(echo "$line" | awk '{print $1}') 
        info=$(echo "$line" | sed -e "s#^$key[ \t]*##") 
        ipa automountkey-add nis $4 --key="$key" --info="$info" 
done
This can be run for a given NIS domain: 
[root@nis-server ~]# kinit admin
[root@nis-server ~]# ./nis-hosts.sh location nisdomain nis-master.example.com map

13.5.4. Setting Weak Password Encryption for NIS User Authentication to IdM

A NIS server can handle CRYPT password hashes. Once an existing NIS server is migrated to IdM (and its underlying LDAP database), it may still be necessary to preserve the NIS-supported CRYPT passwords. However, the LDAP server does not use CRYPT hashes by default. It uses salted SHA (SSHA) or SSHA-256. If the 389 Directory Server password hash is not changed, then NIS users cannot authenticate to the IdM domain, and kinit fails with password failures.
To set the underlying 389 Directory Server to use CRYPT as the password hash, change the passwordStorageScheme attribute using ldapmodify: 
[root@server ~]# ldapmodify -D "cn=directory server" -w secret -p 389 -h ipaserver.example.com

dn: cn=config
changetype: modify
replace: passwordStorageScheme
passwordStorageScheme: crypt

Note

Changing the password storage scheme only applies the scheme to new passwords; it does not retroactively change the encryption method used for existing passwords.
If weak crypto is required for password hashes, it is better to change the setting as early as possible so that more user passwords use the weaker password hash.

Chapter 14. Identity: Integrating with Active Directory Through Cross-forest Trust (Technology Preview)

Kerberos implements a concept of a trust. In a trust, a principal from one Kerberos realm can request a ticket to a service in another Kerberos realm. Using this ticket, the principal can authenticate against resources on machines belonging to the other realm.
Kerberos also has the ability to create a relationship between two otherwise separate Kerberos realms: a cross-realm trust. Realms that are part of a trust use a shared pair of a ticket and key; a member of one realm then counts as a member of both realms.
Both Active Directory and Identity Management manage a variety of core services such as Kerberos, LDAP, DNS, or certificate services. Therefore, establishing Kerberos cross-realm trust is not enough to allow users from one realm to access resources in a different realm; support is required at other levels of communication as well. For this purpose, IdM enables configuring a cross-forest trust between an IdM domain and an AD domain. Cross-forest trust is a trust established between two separate forest root domains, allowing users and services from different forests to communicate.

Note

Multiple AD domains can be organized together into an Active Directory forest. A root domain of the forest is the first domain created in the forest. The IdM domain cannot be part of an existing AD forest, thus it is always seen as a separate forest.
Cross-forest Trust As Technology Preview in Red Hat Enterprise Linux 6
In Red Hat Enterprise Linux 6, the cross-forest trust feature is offered as a Technology Preview. Note that Red Hat recommends to connect Red Hat Enterprise Linux 6 IdM clients to a Red Hat Enterprise Linux 7 IdM server for cross-forest trust capability. Trusts are fully supported on servers running Red Hat Enterprise Linux 7. Configuration with Red Hat Enterprise Linux 6 clients connected to a Red Hat Enterprise Linux 7 server for cross-forest trust is fully supported as well. In such setups, it is recommended to use the latest version of Red Hat Enterprise Linux 6 on the client side and the latest version of Red Hat Enterprise Linux 7 on the server side.
Red Hat will not upgrade the cross-forest trust feature within Red Hat Enterprise Linux 6 from the Technology Preview status to Supported. If a certain AD deployment does not work with cross-forest trust in Red Hat Enterprise Linux 6, consider trying the latest Red Hat Enterprise Linux 7 IdM version to identify whether a particular configuration requires improvement in Red Hat Enterprise Linux 7.
For documentation on cross-forest trust in Red Hat Enterprise Linux 7, including a more detailed description of what cross-forest trust is, see the Red Hat Enterprise Linux 7 Windows Integration Guide.
Overview of Cross-forest Trust in Red Hat Enterprise Linux 6
The cross-forest trust feature in Red Hat Enterprise Linux 6 includes the ability to:
  • Establish a trust to a single AD forest.
  • Allow access to IdM resources for users from the root domain of a trusted AD forest.
The cross-forest trust feature in Red Hat Enterprise Linux 6 does not include the ability to:
  • Override default attributes of AD users, such as the login shell or home directory, in a centralized way. To achieve this, deploy ID views using IdM in Red Hat Enterprise Linux 7.
  • Expose AD users and groups using the compatibility tree for legacy clients. To provide legacy clients with access to AD users and groups, use IdM in Red Hat Enterprise Linux 7.
Trusts vs Synchronization
Trusts and synchronization are fundamentally different approaches to integrating an IdM domain and an AD domain. Both approaches offer the advantage of managing Linux systems and policies related to those systems centrally while enabling users from AD domains to transparently access Linux systems and services.
For a comparison of the trust-based and synchronization-based solutions, see the Red Hat Enterprise Linux 7 Windows Integration Guide. For information on integrating with AD using synchronization in Red Hat Enterprise Linux 6, see Chapter 15, Identity: Integrating with Microsoft Active Directory Through Synchronization.

Chapter 15. Identity: Integrating with Microsoft Active Directory Through Synchronization

Identity Management uses active synchronization to integrate user data stored in an Active Directory domain and the user data stored in the IdM domain. Critical user attributes, including passwords, are synchronized between the services.
The capability to sync Active Directory and IdM domains is inherent when an IdM server is first installed. The synchronization process is configured by creating agreements between the IdM server and the Active Directory domain controller.
This chapter describes how to configure synchronization, how to configure Active Directory for integration with IdM, and how to configure Windows systems within the Active Directory domain to be aware of the IdM domain.

15.1. Supported Windows Platforms

Entry synchronization is performed through a process similar to replication, which uses hooks to connect to and retrieve directory data from the Windows server.
Password synchronization is performed through a Windows service which is installed on the Windows server and then communicates to the Identity Management server.
Both entry and password synchronization are supported with these Windows servers:
  • Windows Server 2008 R2
  • Windows Server 2012 R2
The version of the password sync service which works with Windows is 1.1.5. This is available in the Red Hat Directory Server downloads part of Red Hat Network.

15.2. About Active Directory and Identity Management

Within the IdM domain, information is shared among servers and replicas by copying that information, reliably and predictably, between data masters (servers and replicas). This process is replication.
A similar process can be used to share data between the IdM domain and a Microsoft Active Directory domain. This is synchronization.
Synchronization is the process of copying user data back and forth between Active Directory and Identity Management.
Synchronization is defined in an agreement between an IdM server and an Active Directory domain controller. The sync agreement defines all of the information required to identify sync-able user entries (like the subtree to synchronize and requisite object classes in the user entries) as well as defining how account attributes are handled. The sync agreements are created with default values which can be tweaked to meet the needs of a specific domain. When two servers are involved in synchronization, they are called peers.
Synchronization is most commonly bi-directional. Information is sent back and forth between the IdM domain and the Windows domain in a process that is very similar to how IdM servers and replicas share information among themselves. It is possible to configure synchronization to only sync one way. That is uni-directional synchronization.
To prevent the risk of data conflicts, synchronization is configured between one Identity Management server and one Active Directory domain controller. The Identity Management server propagates changes back to the IdM domain, while the domain controller propagates changes back to the Windows domain.
There are some key features to IdM synchronization:
  • A synchronization operation runs every five minutes.
  • Synchronization can only be configured with one Active Directory domain. Multiple domains are not supported.
  • Synchronization can only be configured with one Active Directory domain controller.
  • Only user information is synchronized.
  • Both user attributes and passwords can be synchronized.
  • While modifications are bi-directional (going both from Active Directory to IdM and from IdM to Active Directory), creating or adding accounts are only uni-directional, from Active Directory to Identity Management. New accounts created in Active Directory are synchronized over to IdM automatically. However, user accounts created in IdM must also be created in Active Directory before they will be synchronized.
  • Account lock information is synchronized by default, so a user account which is disabled in one domain is disabled in the other.
  • Password synchronization changes take effect immediately.
When Active Directory users are synchronized over to IdM, certain attributes (including Kerberos and POSIX attributes) will have IPA attributes are automatically added to the user entries. These attributes are used by IdM within its domain. They are not synchronized back over the corresponding Active Directory user entry.
Some of the data in synchronization can be modified as part of the synchronization process. For examples, certain attributes can be automatically added to Active Directory user accounts when they are synced over to the IdM domain. These attribute changes are defined as part of the synchronization agreement and are described in Section 15.5.3, “Changing the Behavior for Syncing User Account Attributes”.

15.3. About Synchronized Attributes

Identity Management synchronizes a subset of user attributes between IdM and Active Directory user entries. Any other attributes present in the entry, either in Identity Management or in Active Directory, are ignored by synchronization.

Note

Most POSIX attributes are not synchronized.
Although there are significant schema differences between the Active Directory LDAP schema and the 389 Directory Server LDAP schema used by Identity Management, there are many attributes that are the same. These attributes are simply synchronized between the Active Directory and IdM user entries, with no changes to the attribute name or value format.

User Schema That Are the Same in Identity Management and Windows Servers

  • cn[5]
  • physicalDeliveryOfficeName
  • description
  • postOfficeBox
  • destinationIndicator
  • postalAddress
  • facsimileTelephoneNumber
  • postalCode
  • givenname
  • registeredAddress
  • homePhone
  • sn
  • homePostalAddress
  • st
  • initials
  • street
  • l
  • telephoneNumber
  • mail
  • teletexTerminalIdentifier
  • mobile
  • telexNumber
  • o
  • title
  • ou
  • usercertificate
  • pager
  • x121Address
Some attributes have different names but still have direct parity between IdM (which uses 389 Directory Server) and Active Directory. These attributes are mapped by the synchronization process.
Table 15.1. User Schema Mapped between Identity Management and Active Directory
Identity Management Active Directory
cn[a] name
nsAccountLock userAccountControl
ntUserDomainId sAMAccountName
ntUserHomeDir homeDirectory
ntUserScriptPath scriptPath
ntUserLastLogon lastLogon
ntUserLastLogoff lastLogoff
ntUserAcctExpires accountExpires
ntUserCodePage codePage
ntUserLogonHours logonHours
ntUserMaxStorage maxStorage
ntUserProfile profilePath
ntUserParms userParameters
ntUserWorkstations userWorkstations
[a] The cn is mapped directly (cn to cn) when syncing from Identity Management to Active Directory. When syncing from Active Directory cn is mapped from the name attribute in Active Directory to the cn attribute in Identity Management.

15.3.1. User Schema Differences between Identity Management and Active Directory

Even though attributes may be successfully synced between Active Directory and IdM, there may still be differences in how Active Directory and Identity Management define the underlying X.500 object classes. This could lead to differences in how the data are handled in the different LDAP services.
This section describes the differences in how Active Directory and Identity Management handle some of the attributes which can be synchronized between the two domains.
15.3.1.1. Values for cn Attributes
In 389 Directory Server, the cn attribute can be multi-valued, while in Active Directory this attribute must have only a single value. When the Identity Management cn attribute is synchronized, then, only one value is sent to the Active Directory peer.
What this means for synchronization is that,potentially, if a cn value is added to an Active Directory entry and that value is not one of the values for cn in Identity Management, then all of the Identity Management cn values are overwritten with the single Active Directory value.
One other important difference is that Active Directory uses the cn attribute as its naming attribute, where Identity Management uses uid. This means that there is the potential to rename the entry entirely (and accidentally) if the cn attribute is edited in the Identity Management. If that cn change is written over to the Active Directory entry, then the entry is renamed, and the new named entry is written back over to Identity Management.
15.3.1.2. Values for street and streetAddress
Active Directory uses the attribute streetAddress for a user's postal address; this is the way that 389 Directory Server uses the street attribute. There are two important differences in the way that Active Directory and Identity Management use the streetAddress and street attributes, respectively:
  • In 389 Directory Server, streetAddress is an alias for street. Active Directory also has the street attribute, but it is a separate attribute that can hold an independent value, not an alias for streetAddress.
  • Active Directory defines both streetAddress and street as single-valued attributes, while 389 Directory Server defines street as a multi-valued attribute, as specified in RFC 4519.
Because of the different ways that 389 Directory Server and Active Directory handle streetAddress and street attributes, there are two rules to follow when setting address attributes in Active Directory and Identity Management:
  • The synchronization process maps streetAddress in the Active Directory entry to street in Identity Management. To avoid conflicts, the street attribute should not be used in Active Directory.
  • Only one Identity Management street attribute value is synced to Active Directory. If the streetAddress attribute is changed in Active Directory and the new value does not already exist in Identity Management, then all street attribute values in Identity Management are replaced with the new, single Active Directory value.
15.3.1.3. Constraints on the initials Attribute
For the initials attribute, Active Directory imposes a maximum length constraint of six characters, but 389 Directory Server does not have a length limit. If an initials attribute longer than six characters is added to Identity Management, the value is trimmed when it is synchronized with the Active Directory entry.
15.3.1.4. Requiring the surname (sn) Attribute
Active Directory allows person entries to be created without a surname attribute. However, RFC 4519 defines the person object class as requiring a surname attribute, and this is the definition used in Directory Server.
If an Active Directory person entry is created without a surname attribute, that entry will not be synced over to IdM since it fails with an object class violation.

15.3.2. Active Directory Entries and RFC 2307 Attributes

Windows uses unique, random security IDs (SIDs) to identify users. These SIDs are assigned in blocks or ranges, identifying different system user types within the Windows domain. When users are synchronized between Identity Management and Active Directory, Windows SIDs for users are mapped to the Unix UIDs used by the Identity Management entry. Another way of saying this is that the Windows SID is the only ID within the Windows entry which is used as an identifier in the corresponding Unix entry, and then it is used in a mapping.
When Active Directory domains interact with Unix-style applications or domains, then the Active Directory domain may use Services for Unix or IdM for Unix to enable Unix-style uidNumber and gidNumber attributes. This allows Windows user entries to follow the specifications for those attributes in RFC 2307.
However, the uidNumber and gidNumber attributes are not actually used as the uidNumber and gidNumber attributes for the Identity Management entry. The Identity Management uidNumber and gidNumber attributes are generated when the Windows user is synced over.

Note

The uidNumber and gidNumber attributes defined and used in Identity Management are not the same uidNumber and gidNumber attributes defined and used in the Active Directory entry, and the numbers are not related.

15.4. Setting up Active Directory for Synchronization

Synchronizing user accounts alone is enabled within IdM, so all that is necessary is to set up a sync agreement (Section 15.5.2, “Creating Synchronization Agreements”). However, the Active Directory does need to be configured in a way that allows the Identity Management server to connect to it.

15.4.1. Creating an Active Directory User for Sync

On the Windows server, it is necessary to create the user that the IdM server will use to connect to the Active Directory domain.
The process for creating a user in Active Directory is covered in the Windows server documentation at http://technet.microsoft.com/en-us/library/cc732336.aspx. The new user account must have the proper permissions:
  • Grant the sync user account Replicating directory changes rights to the synchronized Active Directory subtree. Replicator rights are required for the sync user to perform synchronization operations.
    Replicator rights are described in http://support.microsoft.com/kb/303972.
  • Add the sync user as a member of the Account Operator and Enterprise Read-Only Domain controller groups. It is not necessary for the user to belong to the full Domain Admin group.

15.4.2. Setting up an Active Directory Certificate Authority

The Identity Management server connects to the Active Directory server using a secure connection. This requires that the Active Directory server have an available CA certificate or CA certificate chain available, which can be imported into the Identity Management security databases, so that the Windows server is a trusted peer.
While this could technically be done with an external (to Active Directory) CA, most deployments should use the Certificate Services available with Active Directory.
The procedure for setting up and configuring certificate services on Active Directory is covered in the Microsoft documentation at http://technet.microsoft.com/en-us/library/cc772393(v=WS.10).aspx.

15.5. Managing Synchronization Agreements

15.5.1. Trusting the Active Directory and IdM CA Certificates

Both Active Directory and Identity Management use certificates for server authentication. For the Active Directory and IdM SSL server certificates to be trusted by each other, both servers need to trust the CA certificate for the CA which issued those certificates. This means that the Active Directory CA certificate needs to be imported into the IdM database, and the IdM CA certificate needs to be imported into the Active Directory database.
  1. On the Active Directory server, download the IdM server's CA certificate from http://ipa.example.com/ipa/config/ca.crt.
  2. Install the IdM CA certificate in the Active Directory certificate database. This can be done using the Microsoft Management Console or the certutil utility. For example: 
    certutil -installcert -v -config "ipaserver.example.com\Example Domain CA" c:\path\to\ca.crt
    For more details, see the Active Directory documentation.
  3. Export the Active Directory CA certificate.
    1. In My Network Places, open the CA distribution point.
    2. Double-click the security certificate file (.crt file) to display the Certificate dialog box.
    3. On the Details tab, click Copy to File to start the Certificate Export Wizard.
    4. Click Next, and then select Base-64 encoded X.509 (.CER).
    5. Specify a suitable directory and file name for the exported file. Click Next to export the certificate, and then click Finish.
  4. Copy the Active Directory certificate over to the IdM server machine.
  5. Download the IdM server's CA certificate from http://ipa.example.com/ipa/config/ca.crt.
  6. Copy both the Active Directory CA certificate and the IdM CA certificate into the /etc/openldap/cacerts/ directory.
  7. Update the hash symlinks for the certificates. 
    cacertdir_rehash /etc/openldap/cacerts/
  8. Edit the /etc/openldap/ldap.conf file, and add the information to point to and use the certificates in the /etc/openldap/cacerts/ directory. 
    TLS_CACERTDIR /etc/openldap/cacerts/
TLS_REQCERT allow

15.5.2. Creating Synchronization Agreements

Synchronization agreements are created on the IdM server using the ipa-replica-manage connect command because it creates a connection to the Active Directory domain. The options to create the synchronization agreement are listed in Table 15.2, “Synchronization Agreement Options”.
  1. Make sure that the Active Directory and IdM servers trust each other's CA certificates, as in Section 15.5.1, “Trusting the Active Directory and IdM CA Certificates”.
  2. Remove any existing Kerberos credentials on the IdM server. 
    $ kdestroy
  3. Use the ipa-replica-manage command to create a Windows synchronization agreement. This requires the --winsync option. If passwords will be synchronized as well as user accounts, then also use the --passsync option and set a password to use for Password Sync.
    The --binddn and--bindpwd options give the username and password of the system account on the Active Directory server that IdM will use to connect to the Active Directory server. 
    $ ipa-replica-manage connect --winsync 
	--binddn cn=administrator,cn=users,dc=example,dc=com 
	--bindpw Windows-secret 
	--passsync secretpwd 
	--cacert /etc/openldap/cacerts/windows.cer  
	adserver.example.com -v
  4. When prompted, enter the Directory Manager password.
  5. Optional. Configure Password Synchronization, as in Section 15.6.2, “Setting up Password Synchronization”.
Table 15.2. Synchronization Agreement Options
Option Description
--winsync Identifies this as a synchronization agreement.
--binddn Gives the full user DN of the synchronization identity. This is the user DN that the IdM LDAP server uses to bind to Active Directory. This user must exist in the Active Directory domain and must have replicator, read, search, and write permissions on the Active Directory subtree.
--bindpw Gives the password for the sync user.
--passsync Gives the password for the Windows user account which is involved in synchronization.
--cacert Gives the full path and file name of the Active Directory CA certificate. This certificate is exported in Section 15.5.1, “Trusting the Active Directory and IdM CA Certificates”.
--win-subtree Gives the DN of the Windows subtree containing the users to synchronize. The default value is cn=Users,$SUFFIX.
AD_server_name Gives the hostname of the Active Directory domain controller.

15.5.3. Changing the Behavior for Syncing User Account Attributes

When the sync agreement is created, it has certain default behaviors defined for how the synchronization process handles the user account attributes during synchronization. The types of behaviors are things like how to handle lockout attributes or how to handle different DN formats. This behavior can be changed by editing the synchronization agreement. The list of attribute-related parameters are in Table 15.3, “Synced Attribute Settings”.
The sync agreement exists as a special plug-in entry in the LDAP server and each attribute behavior is set through an LDAP attribute. To change the sync behavior, use the ldapmodify command to modify the LDAP server entry directly.
For example, account lockout attributes are synchronized between IdM and Active Directory by default, but this can be disabled by editing the ipaWinSyncAcctDisable attribute. (Changing this means that if an account is disabled in Active Directory, it is still active in IdM and vice versa.) 
[jsmith@ipaserver ~]$ ldapmodify -x -D "cn=directory manager" -w password

dn: cn=ipa-winsync,cn=plugins,cn=config
changetype: modify
replace: ipaWinSyncAcctDisable
ipaWinSyncAcctDisable: none

modifying entry "cn=ipa-winsync,cn=plugins,cn=config"
Table 15.3. Synced Attribute Settings
Parameter Description Possible Values
General User Account Parameters  
ipaWinSyncNewEntryFilter Sets the search filter to use to find the entry which contains the list of object classes to add to new user entries. The default is (cn=ipaConfig).
ipaWinSyncNewUserOCAttr Sets the attribute in the configuration entry which actually contains the list of object classes to add to new user entries. The default is ipauserobjectclasses.
ipaWinSyncHomeDirAttr Identifies which attribute in the entry contains the default location of the POSIX home directory. The default is ipaHomesRootDir.
ipaWinSyncUserAttr Sets an additional attribute with a specific value to add to Active Directory users when they are synced over from the Active Directory domain. If the attribute is multi-valued, then it can be set multiple times, and the sync process adds all of the values to the entry.

Note

This only sets the attribute value if the entry does not already have that attribute present. If the attribute is present, then the entry's value is used when the Active Directory entry is synced over.
ipaWinSyncUserAttr: attributeName attributeValue
ipaWinSyncForceSync Sets whether to check existing IdM users which match an existing Active Directory user should be automatically edited so they can be synchronized. If an IdM user account has a uid parameter which is identical to the samAccountName in an existing Active Directory user, then that account is not synced by default. This attribute tells the sync service to add the ntUser and ntUserDomainId to the IdM user entries automatically, which allows them to be synchronized. true | false
User Account Lock Parameters  
ipaWinSyncAcctDisable Sets which way to synchronize account lockout attributes. It is possible to control which account lockout settings are in effect. For example, to_ad means that when account lockout attribute is set in IdM, its value is synced over to Active Directory and overrides the local Active Directory value. By default, account lockout attributes are synced from both domains.
  • both (default)
  • to_ad
  • to_ds
  • none
ipaWinSyncInactivatedFilter Sets the search filter to use to find the DN of the group used to hold inactivated (disabled) users. This does not need to be changed in most deployments. The default is (&(cn=inactivated)(objectclass=groupOfNames)).
ipaWinSyncActivatedFilter Sets the search filter to use to find the DN of the group used to hold active users. This does not need to be changed in most deployments. The default is (&(cn=activated)(objectclass=groupOfNames)).
Group Parameters  
ipaWinSyncDefaultGroupAttr Sets the attribute in the new user account to reference to see what the default group for the user is. The group name in the entry is then used to find the gidNumber for the user account. The default is ipaDefaultPrimaryGroup.
ipaWinSyncDefaultGroupFilter Sets the search filter to map the group name to the POSIX gidNumber. The default is (&(gidNumber=*)(objectclass=posixGroup)(cn=groupAttr_value)).
Realm Parameters  
ipaWinSyncRealmAttr Sets the attribute which contains the realm name in the realm entry. The default is cn.
ipaWinSyncRealmFilter Sets the search filter to use to find the entry which contains the IdM realm name. The default is (objectclass=krbRealmContainer).

15.5.4. Changing the Synchronized Windows Subtree

Creating a synchronization agreement automatically sets the two subtrees to use as the synchronized user database. In IdM, the default is cn=users,cn=accounts,$SUFFIX, and for Active Directory, the default is CN=Users,$SUFFIX.
The value for the Active Directory subtree can be set to a non-default value when the sync agreement is created by using the --win-subtree option. After the agreement is created, the Active Directory subtree can be changed by using the ldapmodify command to edit the nsds7WindowsReplicaSubtree value in the sync agreement entry.
  1. Get the name of the sync agreement, using ldapsearch. This search returns only the values for the dn and nsds7WindowsReplicaSubtree attributes instead of the entire entry. 
    [jsmith@ipaserver ~]$ ldapsearch -xLLL -D "cn=directory manager" -w password -p 389 -h ipaserver.example.com -b cn=config objectclass=nsdswindowsreplicationagreement dn nsds7WindowsReplicaSubtree

dn: cn=meToWindowsBox.example.com,cn=replica,cn=dc\3Dexample\2Cdc\3Dcom,cn=mapping tree,cn=config
nsds7WindowsReplicaSubtree: cn=users,dc=example,dc=com

... 8< ...
  2. Modify the sync agreement 
    [jsmith@ipaserver ~]$ ldapmodify -x -D "cn=directory manager" -W -p 389 -h ipaserver.example.com <<EOF
 dn: cn=meToWindowsBox.example.com,cn=replica,cn=dc\3Dexample\2Cdc\3Dcom,cn=mapping tree,cn=config
 changetype: modify
 replace: nsds7WindowsReplicaSubtree
 nsds7WindowsReplicaSubtree: cn=alternateusers,dc=example,dc=com
 EOF

 modifying entry "cn=meToWindowsBox.example.com,cn=replica,cn=dc\3Dexample\2Cdc\3Dcom,cn=mapping tree,cn=config"
The new subtree setting takes effect immediately. If a sync operation is currently running, then it takes effect as soon as the current operation completes.

15.5.5. Configuring Uni-Directional Sync

By default, all modifications and deletions are bi-directional. A change in Active Directory is synced over to Identity Management, and a change to an entry in Identity Management is synced over to Active Directory. This is essentially an equitable, multi-master relationship, where both Active Directory and Identity Management are equal peers in synchronization and are both data masters.
However, there can be some data structure or IT designs where only one domain should be a data master and the other domain should accept updates. This changes the sync relationship from a multi-master relationship (where the peer servers are equal) to a master-consumer relationship.
This is done by setting the oneWaySync parameter on the sync agreement. The possible values are fromWindows (for Active Directory to Identity Management sync) and toWindows (for Identity Management to Active Directory sync).
For example, to sync changes from Active Directory to Identity Management: 
[jsmith@ipaserver ~]$ ldapmodify -x -D "cn=directory manager" -w password -p 389 -h ipaserver.example.com

dn: cn=windows.example.com,cn=replica,cn=dc\3Dexample\2Cdc\3Dcom,cn=mapping tree,cn=config
changetype: modify
add: oneWaySync
oneWaySync: fromWindows

Important

Enabling uni-directional sync does not automatically prevent changes on the un-synchronized server, and this can lead to inconsistencies between the sync peers between sync updates. For example, uni-directional sync is configured to go from Active Directory to Identity Management, so Active Directory is (in essence) the data master. If an entry is modified or even deleted on the Identity Management, then the Identity Management information is different then the information and those changes are never carried over to Active Directory. During the next sync update, the edits are overwritten on the Directory Server and the deleted entry is re-added.

15.5.6. Deleting Synchronization Agreements

Synchronization can be stopped by deleting the sync agreement which disconnects the IdM and Active Directory servers. In the inverse of creating a sync agreement, deleting a sync agreement uses the ipa-replica-manage disconnect command and then the hostname of the Active Directory server.
  1. Delete the sync agreement. 
    # ipa-replica-manage disconnect adserver.example.com
  2. Remove the Active Directory CA certificate from the IdM server database: 
    # certutil -D -d /etc/dirsrv/slapd-EXAMPLE.COM/ -n "Imported CA"

15.5.7. Winsync Agreement Failures

Creating the sync agreement fails because it cannot connect to the Active Directory server.

One of the most common sync agreement failures is that the IdM server cannot connect to the Active Directory server: 

"Update failed! Status: [81  - LDAP error: Can't contact LDAP server]

This can occur if the wrong Active Directory CA certificate was specified when the agreement was created. This creates duplicate certificates in the IdM LDAP database (in the /etc/dirsrv/slapd-DOMAIN/ directory) with the name Imported CA. This can be checked using certutil: 
$ certutil -L -d /etc/dirsrv/slapd-DOMAIN/

Certificate Nickname                                         Trust Attributes
SSL,S/MIME,JAR/XPI

CA certificate                                               CTu,u,Cu
Imported CA                                                  CT,,C
Server-Cert                                                  u,u,u
Imported CA                                                  CT,,C
To resolve this issue, clear the certificate database: 
# certutil -d /etc/dirsrv/slapd-DOMAIN-NAME -D -n "Imported CA"
This deletes the CA certificate from the LDAP database.
There are errors saying passwords are not being synced because it says the entry exists

For some entries in the user database, there may be an informational error message that the password is not being reset because the entry already exists: 

"Windows PassSync entry exists, not resetting password"
This is not an error. This message occurs when an exempt user, the Password Sync user, is not being changed. The Password Sync user is the operational user which is used by the service to change the passwords in IdM.

15.6. Managing Password Synchronization

Synchronizing user entries is configured with the sync agreement. However, passwords in both Active Directory and Identity Management are hashed when they are stored, and cannot be decrypted as part of the user synchronization process. A separate client must be installed on the Active Directory servers to capture passwords as user accounts are created or passwords are changed, and then to forward that password information with the sync updates.

Important

Note that IdM currently does not support initial password synchronization for user accounts. The user first needs to manually change the password before the password can be synchronized over to IdM.

15.6.1. Setting up the Windows Server for Password Synchronization

Synchronizing passwords requires two things:
  • Active Directory must be running in SSL.
  • The Password Sync Service must be installed on each Active Directory domain controller.
The Password Sync Service records password changes and synchronizes them, over a secure connection, to the IdM entry.

Note

Install the Microsoft Certificate System in Enterprise Root Mode. Active Directory will then automatically enroll to retrieve its SSL server certificate.
  1. Make sure that the Active Directory password complexity policies are enabled so that the Password Sync service will run.
    1. Run secpol.msc from the command line.
    2. Select Security Settings.
    3. Open Account Policies, and then open Password Policy.
    4. Enable the Password must meet complexity requirements option and save.
  2. If SSL is not already enabled, set up SSL on the Active Directory server. Setting up LDAPS is explained in more detail in the Microsoft knowledgebase at http://support.microsoft.com/kb/321051.
    1. Install a certificate authority in the Windows Components section in Add/Remove Programs.
    2. Select the Enterprise Root CA option.
    3. Reboot the Active Directory server. If IIS web services are running, the CA certificate can be accessed by opening http://servername/certsrv.
    4. Set up the Active Directory server to use the SSL server certificate.
      1. Create a certificate request .inf, using the fully-qualified domain name of the Active Directory as the certificate subject. For example: 
        ;----------------- request.inf ----------------- 

[Version] 

Signature="$Windows NT$ 

[NewRequest]

Subject = "CN=ad.server.example.com, O=Engineering, L=Raleigh, S=North Carolina, C=US"
KeySpec = 1 
KeyLength = 2048 
Exportable = TRUE 
MachineKeySet = TRUE 
SMIME = False 
PrivateKeyArchive = FALSE 
UserProtected = FALSE 
UseExistingKeySet = FALSE 
ProviderName = "Microsoft RSA SChannel Cryptographic Provider" 
ProviderType = 12
RequestType = PKCS10 
KeyUsage = 0xa0 

[EnhancedKeyUsageExtension] 

OID=1.3.6.1.5.5.7.3.1 

;-----------------------------------------------
        For more information on the .inf request file, see the Microsoft documentation, such as http://technet.microsoft.com/en-us/library/cc783835.aspx.
      2. Generate the certificate request. 
        certreq -new request.inf request.req
      3. Submit the request to the Active Directory CA. For example: 
        certreq -submit request.req certnew.cer

        Note

        If the command-line tool returns an error message, then use the Web browser to access the CA and submit the certificate request. If IIS is running, then the CA URL is http://servername/certsrv.
      4. Accept the certificate request. For example: 
        certreq -accept certnew.cer
      5. Make sure that the server certificate is present on the Active Directory server.
        In the File menu, click Add/Remove, then click Certificates and Personal>Certificates.
      6. Import the CA certificate from Directory Server into Active Directory. Click Trusted Root CA, then Import, and browse for the Directory Server CA certificate.
    5. Reboot the domain controller.

15.6.2. Setting up Password Synchronization

Install the Password Sync Service on every domain controller in the Active Directory domain in order to synchronize Windows passwords.
  1. Download the PassSync.msi file to the Active Directory machine.
    1. Log into the Customer Portal.
    2. Click the Downloads tab.
    3. Click the Red Hat Enterprise Linux downloads button in the middle of the page.
    4. Filter the downloads by using a search term such as Directory Server, and then expand one of the Red Hat Enterprise Linux versions.
    5. Click the Directory Server link.
    6. On the Directory Server page, download the appropriate version of the WinSync Installer. This is the Password Sync MSI file (RedHat-PassSync-1.1.5-arch.msi).

    Note

    Regardless of the Red Hat Enterprise Linux architecture, there are two PassSync packages available, one for 32-bit Windows servers and one for 64-bit. Make sure to select the appropriate packages for your Windows platform.
  2. Double-click the Password Sync MSI file to install it.
  3. The Password Sync Setup window appears. Hit Next to begin installing.
  4. Fill in the information to establish the connection to the IdM server.
    • The IdM server connection information, including the hostname and secure port number.
    • The username of the system user which Active Directory uses to connect to the IdM machine. This account is configured automatically when sync is configured on the IdM server. The default account is uid=passsync,cn=sysaccounts,cn=etc,dc=example,dc=com.
    • The password set in the --passsync option when the sync agreement was created.
    • The search base for the people subtree on the IdM server. The Active Directory server connects to the IdM server similar to an ldapsearch or replication operation, so it has to know where in the IdM subtree to look for user accounts. The user subtree is cn=users,cn=accounts,dc=example,dc=com.
    • The certificate token is not used at this time, so that field should be left blank.
    Hit Next, then Finish to install Password Sync.
  5. Import the IdM server's CA certificate into the Active Directory certificate store.
    1. Download the IdM server's CA certificate from http://ipa.example.com/ipa/config/ca.crt.
    2. Copy the IdM CA certificate to the Active Directory server.
    3. Open the command prompt, using Run as Administrator.
    4. Install the IdM CA certificate in the Password Sync database. For example: 
      cd "C:\Program Files\Red Hat Directory Password Synchronization"
	
certutil.exe -d . -A -n "IPASERVER.EXAMPLE.COM IPA CA" -t CT,, -a -i ipaca.crt
      cd "C:\Program Files\389 Directory Password Synchronization"
	
certutil.exe -d . -A -n "IPASERVER.EXAMPLE.COM IPA CA" -t CT,, -a -i ipaca.crt
  6. Reboot the Windows machine to start Password Sync.

    Note

    The Windows machine must be rebooted. Without the rebooting, PasswordHook.dll is not enabled, and password synchronization will not function.
The first attempt to synchronize passwords, which happened when the Password Sync application is installed, will always fail because of the SSL connection between the Directory Server and Active Directory sync peers. The tools to create the certificate and key databases is installed with the .msi.

15.6.3. Allowing Users to Change Other Users' Passwords Cleanly

By default, every time an administrator changes a user password, that user is required to reset the password at the next login. However, this behavior can be changed to allow administrators to reset a password without requiring an immediate password reset.
The passSyncManagersDNs attribute lists administrator accounts which are allowed to perform password change operations and which will not then require a password reset.

Important

This is required for password synchronization because, otherwise, whenever a password is synchronized, the IdM server would interpret that as a password change operation and then require a password change at the next login.
Edit the password synchronization entry, cn=ipa_pwd_extop,cn=plugins,cn=config, and add the passSyncManagersDNs attribute with the name of the user. This attribute is multi-valued. For example: 
$ ldapmodify -x -D "cn=Directory Manager" -w secret -h ldap.example.com -p 389

dn: cn=ipa_pwd_extop,cn=plugins,cn=config
changetype: modify
add: passSyncManagersDNs
passSyncManagersDNs: uid=admin,cn=users,cn=accounts,dc=example,dc=com

Warning

Be careful to limit the listed DNs only to administrator accounts which require the ability to set user passwords. Any user listed here is given access to all user passwords, which is extremely powerful.

[5] The cn is treated differently than other synced attributes. It is mapped directly (cn to cn) when syncing from Identity Management to Active Directory. When syncing from Active Directory to Identity Management, however, cn is mapped from the name attribute on Windows to the cn attribute in Identity Management.

Chapter 16. Identity: ID Views and Migrating Existing Environments to Trust

The ID Views mechanism that is part of Red Hat Identity Management enables the administrator to specify POSIX attributes for users or groups. When a new ID view is created, the administrator can define what user or group attributes it should override; these newly defined attributes are then applied to the user or group. By allowing this, ID views provide a solution to preserve existing environments during migration from other identity management and system integration solutions.

Important

The client must be enrolled with an IdM server based on Red Hat Enterprise Linux 7.1 or later to benefit from this functionality.
ID views can only be used on Red Hat Enterprise Linux 6 clients running Red Hat Enterprise Linux 6.7 or later.
The administrator can only manage ID views on the server side; no configuration is available on Red Hat Enterprise Linux 6 clients. This chapter describes ID views from the client side. For complete information about ID views including the server-side functionality, see the Windows Integration Guide for Red Hat Enterprise Linux 7.
After running the ipa-adtrust-install command on the IdM server, the Default Trust View is created. The Default Trust View is always applied to Active Directory users and groups, which allows the administrator to define POSIX attributes for AD users and groups regardless of how AD itself defined them. If you add a host-specific ID view that overrides the AD users or groups, the attributes from the host-specific ID view are applied on top of the Default Trust View. While the new ID view overrides the Default Trust View, the default view itself cannot be deleted. If no specific ID view is applied to a client, the Default Trust View always applies.

Note

If ipa-adtrust-install is not run, you can still use the ID Views feature in a pure IdM environment to manage ID views and overrides for IdM users.
In a setup with a synchronization-based AD integration, all users are copied to the IdM server with generated POSIX attributes, such as login name, UID, GID, or shell. By enabling the administrator to modify the POSIX attributes that AD previously generated for AD users, the ID Views feature provides a solution to migrate existing environments to a trust-based AD integration.

Note

For a comparison of the synchronization-based and the trust-based approach, see the Red Hat Enterprise Linux 7 Windows Integration Guide.
Use cases covered by ID Views include:
Store POSIX attributes and SSH keys for AD users
Define POSIX attributes or SSH keys and SSH login information for AD users, and let them be applied when an AD user authenticates to clients running SSSD with ID Views support or when the AD user authenticates using a compat LDAP tree, which offers a simplified LDAP tree with user and group data for legacy clients.
This capability is useful for migration from a synchronization-based solution or in a situation when a Linux administrator would like to manually define POSIX attributes for AD users but the AD policy does not allow it.
Migrate from a synchronization-based to a trust-based integration
Configure the POSIX attributes for users that are in a synchronization-based environment by creating an ID view override specifying previously used UID or other tools. Then move the users back to AD.
Perform per-host group override of the IdM user POSIX attributes
NIS-based infrastructure that is being migrated to an IdM integration with AD still often requires that the original POSIX data remain unchanged on some NIS domains or the company policies might prevent setting the original POSIX data in AD directly. In these situations, you can use ID Views to configure the POSIX data directly on the Identity Management server.
Set different POSIX attributes or SSH keys for different environments
Set different POSIX attributes or different user SSH public keys for different production environments – such as development, testing, or production – depending on the corresponding host groups.

16.1. User Overrides and Group Overrides

Every ID view is a collection of user overrides and group overrides that applies to specified hosts. An override provides a new user or group attribute that overrides the previous one; this enables you to, for example, replace a previously generated attribute with a new one. Every override is related to an AD or IdM user or group.

Note

Non-IdM integration systems can generate the UID and GID attributes using an algorithm that is different from the algorithm used in IdM. By overriding the previously generated attributes so that they are in compliance with the IdM system, a client that used to be a member of another integration system can be fully integrated with IdM.
The following user attributes can be overridden in an ID view:
  • uid: user login name
  • uidNumber: user UID number
  • gidNumber: user GID number
  • loginShell: user login shell
  • gecos: user GECOS entry
  • homeDirectory: user home directory
  • ipaSshPubkey: user SSH public key or keys
The following group attributes can be overridden in an ID view:
  • cn: group name
  • gidNumber: group GID number

Note

IdM uses ID ranges to avoid collisions of POSIX IDs from different domains. POSIX IDs in ID Views do not use a special range type because IdM must allow overlaps with other kinds of ID ranges: for example, AD users created through synchronization have POSIX IDs from the same ID range as IdM users. If a collision occurs, it can be easily fixed by changing the conflicting IDs because POSIX IDs are managed manually in ID Views on the IdM side.

16.2. Managing ID Views on the Server Side

Important

The administrator can only manage ID views on the server side; no configuration is available on Red Hat Enterprise Linux 6 clients. This chapter describes ID views from the client side. For complete information about ID views including the server-side functionality, see the Windows Integration Guide for Red Hat Enterprise Linux 7.
From the server, ID views can be added, modified, or deleted. The administrator can define what ID attributes an ID view should override and to which client hosts it should apply.

16.3. ID Views on the Client Side

Important

ID views can only be used on Red Hat Enterprise Linux 6 clients running Red Hat Enterprise Linux 6.7 or later.
The client must be enrolled with an IdM server based on Red Hat Enterprise Linux 7.1 or later to benefit from this functionality.
On the client side, the client itself determines to which ID view it belongs after the client system is started or restarted. The client then begins to use the data defined by the applied ID view. Because ID views are applied on the client side, clients running Red Hat Enterprise Linux 7.0 and earlier versions of IdM only see the Default Trust View. If a client requires a different ID view, update SSSD on the client to a version with ID View support or have the client use the compat LDAP tree.
Whenever the administrator applies another ID view on a client, the client and all the other clients applying this ID view must restart the SSSD service.

Note

Applying an ID view can have a negative impact on SSSD performance because certain optimizations and ID views cannot run at the same time.
For example, ID views prevent SSSD from optimizing the process of looking up groups on the server. With ID views, SSSD must check every member on the returned list of group member names if the group name is overridden. Without ID views, SSSD can only collect the user names from the member attribute of the group object. This negative effect will most likely become apparent when the SSSD cache is empty or when all entries are invalid, that is, after clearing the cache.

16.4. Migrating from the Synchronization-Based to the Trust-Based Solution

ID views can be used to migrate from the synchronization-based integration to the trust-based integration. The migration can be performed on the IdM server and is described in the Windows Integration Guide for Red Hat Enterprise Linux 7.

Chapter 17. Identity: Managing DNS

If the IdM server was installed with DNS configured, then all of the DNS entries for the domain — host entries, locations, records — can be managed using the IdM tools.

17.1. About DNS in IdM

DNS is one of the services that can be configured and maintained by the IdM domain. DNS is critical to the performance of the IdM domain; DNS is used for the Kerberos services and SSL connections for all servers and clients and for connections to domain services like LDAP.
While IdM can use an external DNS service, there is a lot more flexibility and control over IdM — DNS interactions when the DNS service is configured within the domain. For example, DNS records and zones can be managed within the domain using IdM tools, and clients can update their own DNS records dynamically. When a host is added to IdM, a DNS record is automatically created in IdM's DNS service for that host machine.
IdM stores all DNS information as LDAP entries. Every resource record for each machine is stored for the domain. For example, the client1 resource has three IPv4 (A) records and one IPv6 (AAAA) record: 
dn: idnsname=client1,idnsname=example.com,cn=dns,dc=example,dc=com
idnsname: client1
arecord: 10.0.0.1
arecord: 10.0.0.2
arecord: 10.0.0.3
aaaarecord: fc00::1
objectclass: top
objectclass: idnsrecord
The schema used to define the DNS entries is in the /usr/share/ipa/60basev2.ldif schema file[6].
The BIND service communicates with the Directory Server using the system bind-dyndb-ldap plug-in. When Identity Management is configured to manage DNS, IdM creates a dynamic-db configuration section in the /etc/named.conf file for the BIND service. This configures the bind-dyndb-ldap plug-in for the BIND (named) service.
When this plug-in is properly configured, it delivers the DNS records from the Directory Server to the named service. The configuration can be changed to adapt the behavior of the plug-in and, therefore, the LDAP-BIND interactions.

17.2. Using IdM and DNS Service Discovery with an Existing DNS Configuration

To help create and configure a suitable DNS setup, the IdM installation script creates a sample zone file. During the installation, IdM displays a message similar to the following: 
Sample zone file for bind has been created in /tmp/sample.zone.F_uMf4.db
If a DNS server is already configured in the network, then the configuration in the IdM-generated file can be added to the existing DNS zone file. This allows IdM clients to find . For example, this DNS zone configuration is created for an IdM server with the KDC and DNS servers all on the same machine in the EXAMPLE.COM realm:

Example 17.1. Default IdM DNS File

; ldap servers
_ldap._tcp              IN SRV 0 100 389        ipaserver.example.com.

;kerberos realm
_kerberos               IN TXT EXAMPLE.COM

; kerberos servers
_kerberos._tcp          IN SRV 0 100 88         ipaserver.example.com.
_kerberos._udp          IN SRV 0 100 88         ipaserver.example.com.
_kerberos-master._tcp   IN SRV 0 100 88         ipaserver.example.com.
_kerberos-master._udp   IN SRV 0 100 88         ipaserver.example.com.
_kpasswd._tcp           IN SRV 0 100 464        ipaserver.example.com.
_kpasswd._udp           IN SRV 0 100 464        ipaserver.example.com.

Note

If DNS services are hosted by a server outside the IdM domain, then an administrator can add the lines in Example 17.1, “Default IdM DNS File” to the existing DNS zone file. This allows IdM clients and servers to continue to use DNS service discovery to find the LDAP and Kerberos servers (meaning, the IdM servers) that are required for them to participate in the IdM domain.

17.3. DNS Notes

  • Wildcards cannot be used when configuring DNS names. Only explicit DNS domain names are supported.
  • The rndc service is not configured by the --setup-dns option. This service must be configured manually after the IdM server is configured.

17.4. Adding or Updating DNS Services After Installation

DNS can be configured as part of the IdM server installation, simply by using the --setup-dns option. If DNS is not configured then, it can be configured later using the ipa-dns-install command.
The ipa-dns-install command also updates the DNS services on the IdM server. 
[root@server ~]# ipa-dns-install -p secret --ip-address=1.2.34.56 --no-forwarders
  • -p gives the password for the Directory Manager user in the 389 Directory Server. All of the DNS entries are stored in the LDAP directory, so this directory must be accessed to add the DNS configuration.
  • --ip-address gives the IP address for the master DNS server.
  • --no-forwarders means that there are no forwarders used with the DNS service, only root servers. Alternatively, use the --forwarder option to define a forward to use; to specify multiple forwarders, use the --forwarder option multiple times.
  • Reverse DNS is configured automatically. It is possible to disable reverse DNS by using the --no-reverse option.
    If an existing reverse DNS zone is already configured, using the --no-reverse option uses the existing reverse zone rather than creating a new reverse zone.
  • The IdM server, unless it is explicitly disabled, leaves a persistent search open with its Directory Server and capture any new zone changes immediately.

17.5. Setting up the rndc Service

The ipa-dns-install command does not automatically configure the system's rndc service. This must be configured manually, after DNS is configured for IdM.
  1. Create the rndc configuration file and key. 
    [root@server ~]# /usr/sbin/rndc-confgen -a
[root@server ~]# /sbin/restorecon /etc/rndc.conf
    This may require some user input to create entropy while the key is being created.
  2. Change the owner and permissions of the rndc key file. 
    [root@server ~]# chown root:named /etc/rndc.key
[root@server ~]# chmod 0640 /etc/rndc.key

17.6. Managing DNS Zone Entries

17.6.1. Adding Forward DNS Zones

17.6.1.1. From the Web UI
  1. Open the Identity tab, and select the DNS subtab.
  2. Click the Add link at the top of the list of DNS zones.
  3. Fill in the information about the new DNS zone. The Zone Name is required; this is the actual domain name. The other information about the administrator email and the authoritative name server are optional.

    Note

    If an email is given for the administrator, then replace the at symbol (@) with a period (.) to maintain compatibility with the zone file.
  4. Click the Add and Edit button to go directly to the DNS zone page. In the Settings tab, it is possible to reset the default zone configuration to enable dynamic binds (Section 17.6.5.1, “Enabling Dynamic DNS Updates in the Web UI”) or change other default records information (Section 17.6.2.2, “Editing the Zone Configuration in the Web UI”). It is also possible to begin adding new DNS resource records (Section 17.7.1.1, “Adding DNS Resource Records from the Web UI”) in the DNS Resource Records tab.
17.6.1.2. From the Command Line
The ipa dnszone-add command adds a new zone to the DNS domain. At a minimum, this requires the name of the new subdomain: 
$ ipa dnszone-add domainName
If the name is not given, the script prompts for it. Other command-line options can also be passed with the ipa dnszone-add command.
To add a zone entry:
  1. Add the new zone. For example: 
    [root@server ~]# ipa dnszone-add newserver.example.com --admin-email=admin@example.com --minimum=3000 --dynamic-update
  2. Reload the name service. 
    [root@server ~]# rndc reload

    Note

    To make new resource records immediately resolvable without restarting the name service, enable persistent searches with the named service or configure the BIND service to poll the Directory Server automatically for zone changes. See Section 17.8.2, “Disabling Persistent Searches”.

17.6.2. Adding Additional Configuration for DNS Zones

A zone is created with a certain amount of configuration for things like its refresh periods, transfer settings, and cache settings, set to default values.

Example 17.2. Default DNS Zone Entry Settings

[root@server ~]# ipa dnszone-show server.example.com 
Zone name: server.example.com 
Authoritative nameserver: dns.example.com 
Administrator e-mail address: admin.example.com. 
SOA serial: 1377691702 
SOA refresh: 3600 
SOA retry: 900 
SOA expire: 1209600 
SOA minimum: 3000 
Active zone: TRUE 
Allow query: any; 
Allow transfer: none;
17.6.2.1. DNS Zone Configuration Attributes
All of the possible zone settings are listed in Table 17.1, “Zone Attributes”. Along with setting the actual information for the zone, the settings define how the DNS server handles the start of authority (SOA) record entries and how it updates its records from the DNS name server.
Table 17.1. Zone Attributes
Attribute Command-Line Option Description
Zone name --name Sets the name of the zone.
Authoritative nameserver --name-server Sets the fully-qualified domain name of the DNS name server.
Administrator e-mail address --admin-email Sets the email address to use for the zone administrator. This defaults to the root account on the host.
SOA serial --serial Sets a version number for the SOA record file.
SOA refresh --refresh Sets the interval, in seconds, for a secondary DNS server to wait before requesting updates from the primary DNS server.
SOA retry --retry Sets the time, in seconds, to wait before retrying a failed refresh operation.
SOA expire --expire Sets the time, in seconds, that a secondary DNS server will try to perform a refresh update before ending the operation attempt.
SOA minimum --minimum Sets the minimum amount of time, in seconds, that data are kept in cache.
SOA time to live --ttl Sets the maximum time, in seconds, that information is kept in the data cache.
SOA class --class Sets the type of record. This is almost always IN, which stands for Internet.
BIND update policy --update-policy Sets the permissions allowed to clients in the DNS zone.
Dynamic update --dynamic-update=TRUE|FALSE Enables dynamic updates to DNS records for clients.

Important

If this is set to false, IdM client machines will not be able to add or update their IP address. See Section 17.6.5, “Enabling Dynamic DNS Updates” for more information.
Name server --ip-address Adds the DNS name server by its IP address.
Allow transfer --allow-transfer=string Gives a semi-colon-separated list of IP addresses or network names which are allowed to transfer the given zone.
Allow query --allow-query Gives a semi-colon-separated list of IP addresses or network names which are allowed to issue DNS queries.
Allow PTR sync --allow-sync-ptr=1|0 Sets whether A or AAAA records (forward records) for the zone will be automatically synchronized with the PTR (reverse) records.
Zone forwarders --forwarder=string Specifies a forwarder specifically configured for the DNS zone. This is separate from any global forwarders used in the IdM domain.
To specificy multiple forwarders, use the option multiple times.
Forward policy --forward-policy=only|first Sets whether the zone will only forward requests to configured the DNS name servers (a forward-only zone) or whether it will check the forwarders first for DNS records and then check its own local records.
17.6.2.2. Editing the Zone Configuration in the Web UI
  1. Open the Identity tab, and select the DNS subtab.
  2. Click the name of the DNS zone to edit.
  3. Open the Settings tab.
  4. Change any of the DNS zone settings. The full list of attributes is described in Table 17.1, “Zone Attributes”. There are some common attributes to change:
    • Authoritative name server, the fully-qualified domain name of the DNS name server.
    • Dynamic update, to enable dynamic updates to DNS records for clients.
    • SOA refresh, the interval, in seconds, for a secondary DNS server to wait before requesting updates from the primary DNS server.
  5. Click the Update link at the top of the settings page.
17.6.2.3. Editing the Zone Configuration in the Command Line
The zone can be created with additional attributes and values different from the default by passing additional options with the dnszone-add command. Likewise, attributes can be added or modified in the zone entry by passing the same attribute options with the dnszone-mod command. These are listed in Table 17.1, “Zone Attributes”.
If an attribute does not exist in the DNS zone entry, then the dnszone-mod command adds the attribute. If the attribute exists, then it overwrites the current value with the specified value.
For example, setting a time to live for SOA records, adds a new attribute to the DNS zone entry (since there was no previous default value): 
[jsmith@server ~]$ kinit admin
[jsmith@server ~]$ ipa dnszone-mod server.example.com --ttl=1800

Zone name: server.example.com 
Authoritative nameserver: dns.example.com 
Administrator e-mail address: admin.example.com. 
SOA serial: 1377691702 
SOA refresh: 3600 
SOA retry: 900 
SOA expire: 1209600 
SOA minimum: 3000 
SOA time to live: 1800 
Active zone: TRUE 
Allow query: any; 
Allow transfer: none;

17.6.3. Adding Reverse DNS Zones

The process to add a reverse zone is the same as for a forward zone, as described in Section 17.6.1, “Adding Forward DNS Zones”. However, the required information is different.
There are two ways to identify a reverse DNS zone:
  • By zone name, in the format reverse_ip_address.in-addr.arpa.
  • By network address, in the format network_ip_address/subnet_mask_bit_count
When creating a reverse zone by the zone name, set it up exactly as creating a forward zone, only reverse the order of the components of the IP address. For example, if the IP address is 1.2.3.4, then the reverse zone name is 3.2.1.in-addr.arpa. (with the trailing period).
In the web UI, this is set in the Zone name field.
Creating a Reverse Zone by Name

Figure 17.1. Creating a Reverse Zone by Name

With the command-line tools, the zone is created by name like this: 
[bjensen@server ~]$ kinit
[bjensen@server]$ ipa dnszone-add 206.65.10.in-addr.arpa.
To create the reverse zone by its IP network, set the network information to the (forward-style) IP address, with the subnet mask bit count. The bit count must be a multiple of eight for IPv4 addresses or a multiple of four for IPv6 addresses.
In the web UI, this is set in the Reverse zone IP network field.
Creating a Reverse Zone by IP Network

Figure 17.2. Creating a Reverse Zone by IP Network

With the command-line tools, the zone is created by IP network like this: 
[bjensen@server ~]$ kinit
[bjensen@server]$ ipa dnszone-add 10.65.206.0/24

17.6.4. Enabling and Disabling Zones

Active zones can have clients added to them, are available for lookups, and are used by IdM services like Kerberos. Deleting a DNS zone removes the zone entry and all the associated configuration.
There can be situations when it is necessary to remove a zone from activity without permanently removing the zone. This is done by disabling the zone.
17.6.4.1. Disabling Zones in the Web UI
  1. Open the Identity tab, and select the DNS subtab.
  2. Click the name of the DNS zone to edit.
  3. Open the Settings tab.
  4. Scroll down to the Active zone field. To disable the zone, set the value to Disabled.
  5. Click the Update link at the top of the settings page.
17.6.4.2. Disabling Zones in the Command Line
Disabling a zone is done by using the dnszone-disable command.
For example: 
[jsmith@server ~]$ kinit admin
[jsmith@server ~]$ ipa dnszone-disable server.example.com
----------------------------------------- 
Disabled DNS zone "server.example.com" 
-----------------------------------------
When the zone needs to be brought back online, it can be re-enabled using the dnszone-enable command.

17.6.5. Enabling Dynamic DNS Updates

Dynamic DNS updates are not enabled by default for new DNS zones in IdM. If dynamic updates are not allowed, then it may not be possible for the ipa-client-install script to join a client to the domain because it cannot add a DNS record pointing to the new client.
17.6.5.1. Enabling Dynamic DNS Updates in the Web UI
  1. Open the Identity tab, and select the DNS subtab.
  2. Click the name of the DNS zone to edit.
  3. Open the Settings tab.
  4. Scroll down to the Dynamic update field, and set the value to True.
  5. Click the Update link at the top of the settings page.
17.6.5.2. Enabling Dynamic DNS Updates in the Command Line
To allow dynamic updates to the DNS zones, set the --dynamic-update option. 
$ ipa dnszone-mod server.example.com --dynamic-update=TRUE

17.6.6. Configuring Forwarders and Forward Policy

A DNS forwarder is a server which passes DNS queries on to another, external DNS name server for resolution. Within the IdM DNS domain, there are three configuration properties that define how forwarders are used:
  • A list of global forwarders which are used by all zones in IdM
  • A list of forwarders which are used by a single, specific zone (as part of the zone configuration)
  • A policy which defines how the zone sends requests to the forwarders
17.6.6.1. Configuring Forwarders in the UI
As with the other DNS zone settings (Section 17.6.2.2, “Editing the Zone Configuration in the Web UI”), the forwarder configuration is in the Settings tab for the given DNS zone.
There are two areas to edit:
  • To add a forwarder, fill in the field or click Add to add a new IP address to the forwarder list.
  • By default, the zone uses the forwarders only for servicing name resolution requests; this is called a forward-only zone. A forward-only zone does not check its own name records. Only the forwarder server records are checked. If the record does not exist on the configured forwarders, then the zone returns a negative response to the client. Alternatively, the zone can check the forwarder records first, and then fallback on its own resource records. This has a first policy.
Forwarders in the DNS Zone Configuration

Figure 17.3. Forwarders in the DNS Zone Configuration

17.6.6.2. Configuring Forwarders in the Command Line
The forwarder settings can be edited by using the dnszone-mod command to update the zone settings. This can be used to set the list of DNS forwarders and the forwarding policy, as in the UI.
Additionally, the dnsconfig command can be used to set a global list of forwarders for all zones by editing the DNS configuration files.

Example 17.3. Configuring Global Forwarders

Global forwarders are configured as part of the IdM server configuration itself. Forwarders are (optionally) set up when the server is installed with the setup-dns option or when the ipa-dns-install script is used.
After server configuration, the list of global forwarders can be edited using the dnsconfig-mod command. For example: 
[jsmith@server ~]$ ipa dnsconfig-mod --forwarder=0.9.8.7
  Global forwarders: 0.9.8.7

Example 17.4. Configuring Zone Forwarders

Forwarders can be configured to be used with a specific DNS zone as part of the zone configuration. The --forwarder option can be used multiple times to create a list of forwarders to use with the zone.
For example: 
[jsmith@server ~]$ ipa dnszone-mod --forwarder=192.0.2.0 --forwarder=198.51.100.0 example.com

  Zone name: example.com
...
  Zone forwarders: 192.0.2.0, 198.51.100.0

Note

DNS forwarders must be specified as IP addresses, not as hostnames.

Example 17.5. Configuring Forwarder Policy for a Zone

Once forwarders are configured, there are different ways that the zone can use them to service requests.
The zone can use the forwarders only for servicing name resolution requests; this is called a forward-only zone. A forward-only zone does not check its own name records. Only the forwarder server records are checked. If the record does not exist on the configured forwarders, then the zone returns a negative response to the client.
Alternatively, the zone can check the forwarder records first, and then fallback on its own resource records. This has a first policy.
This configuration is set in the --forward-policy option, using a policy of either only or first. For example: 
[jsmith@server ~]$ ipa dnszone-mod --forward-policy=only example.com

  Zone name: example.com
...
  Zone forwarders: 1.2.3.4;5.6.7.8
  Forward policy: only

17.6.7. Enabling Zone Transfers

Name servers maintain authoritative data for the zones; as changes are made to the zones, those changes must be sent to and distributed among the name servers for the DNS domain. A zone transfer moves resource records from one name server to another. An authoritative transfer (AXFR) is a zone transfer which includes that authoritative data for the zone (as opposed to an incremental transfer, which only delivers the most immediate zone change).
Zone transfers are defined in RFC 1034 and RFC 5936.
17.6.7.1. Enabling Zone Transfers in the UI
As with the other DNS zone settings (Section 17.6.2.2, “Editing the Zone Configuration in the Web UI”), the zone transfer configuration is in the Settings tab for the given DNS zone.
Set a list of name servers to which the zone records can be transferred. Fill in the field or click Add to add a new IP address to the name server list.
DNS Zone Transfer Settings

Figure 17.4. DNS Zone Transfer Settings

17.6.7.2. Enabling Zone Transfers in the Command Line
Zone transfers can be enabled when the zone is created or when it is modified by using the --allow-transfer option to set a list of name servers to which the zone records can be transferred.
For example: 
[jsmith@server ~]$ ipa dnszone-mod --allow-transfer="0.0.0.0;1.2.3.4;5.6.7.8" example-zone
The default is any, which the zone to be transferred anywhere in the DNS domain.
Once it is enabled in the bind service, IdM DNS zones can be transferred, by name, by clients like dig: 
[root@server ~]# dig @ipa-server zone_name AXFR

17.6.8. Defining DNS Queries

To resolve hostnames within the DNS domain, a DNS client issues a query to the DNS name server. For some security contexts or for performance, it may be advisable to restrict what clients can query DNS records in the zone.
DNS queries can be configured when the zone is created or when it is modified by using the --allow-query option to set a list of clients which are allowed to issue queries.
For example: 
[jsmith@server ~]$ ipa dnszone-mod --allow-query=0.0.0.0;1.2.3.4;5.6.7.8 example-zone
The default is any, which allows the zone to be queried by any client.

17.6.9. Synchronizing Forward and Reverse Zone Entries

Forward entries (A and AAAA) are configured separately from reverse entries (PTR). Because these entries are configured independently, it is possible for forward entries to exist without corresponding reverse entries, and vice versa.
There are some DNS setting requirements for PTR synchronization to work:
  • Both forward and reverse zones must be managed by the IdM server.
  • Both zones must have dynamic updates enabled.
    Enabling dynamic updates is covered in Section 17.6.5, “Enabling Dynamic DNS Updates”.
  • The PTR record will be updated only if the name of the requesting client matches the name in the PTR record.

Important

Changes made through the IdM web UI, through the IdM command-line tools, or by editing the LDAP entry directly do not update the PTR record. Only changes made by the DNS service itself trigger PTR record synchronization.

Warning

A client system can update its own IP address. This means that a compromised client can be used to overwrite PTR records by changing its IP address.
17.6.9.1. Configuring Zone Entry Sync in the UI

Note

This is set on the forward zone server, not the reverse DNS server.
As with the other DNS zone settings (Section 17.6.2.2, “Editing the Zone Configuration in the Web UI”), the zone transfer configuration is in the Settings tab for the given DNS zone.
The PTR synchronization is enabled by selecting the Allow PTR Sync checkbox.
DNS Zone Sync Settings

Figure 17.5. DNS Zone Sync Settings

17.6.9.2. Configuring Zone Entry Sync in the Command Line
A DNS zone can be configured to allow its forward and reverse entries to be synchronized automatically, by setting the --allow-sync-ptr option to 1. This can be done when the zone is created or when it is edited.

Note

This is set on the forward zone server, not the reverse DNS server.
For example, for editing an existing entry: 
[jsmith@server ~]$ ipa dnszone-mod --allow-sync-ptr=1 example-zone
The default is 0, which disables synchronization and has better server performance.

17.6.10. Setting DNS Access Policies

The IdM DNS domain can define access controls, based on grant/deny rules, for zones. This creates an update-policy statement in the /etc/named.conf file, which defines the DNS access rule.

Important

If the update policy is set to false, IdM client machines will not be able to add or update their IP address. See Section 17.6.5, “Enabling Dynamic DNS Updates” for more information.
17.6.10.1. Setting DNS Access Policies in the UI
A zone access policy is an access control instruction which sets a general grant or deny rule over a very specific part of the DNS zone. The full statement covers the zone name and how clients are allowed to edit specific records and record types within the zone. 
grant|deny zoneName policyName recordName recordType
As with the other DNS zone settings (Section 17.6.2.2, “Editing the Zone Configuration in the Web UI”), the zone transfer configuration is in the Settings tab for the given DNS zone.
The access policies are set in a semi-colon separated list in the BIND update policy text box.
DNS Update Policy Settings

Figure 17.6. DNS Update Policy Settings

The full list of supported record types is in Table 17.2, “DNS Record Types”.
17.6.10.2. Setting DNS Access Policies in the Command Line
When using the command-line tools, the policy is set using the --update-policy option, with the access control rule in a statement after it. 
--update-policy "grant|deny zoneName policyName recordName recordType"
  • zoneName is the IdM DNS zone to which to apply the rule.
  • policyName is the name to use for the BIND rule.
  • recordName sets the resource records to which to apply the rule. Using an asterisk (*) is used for self rules.
  • recordType is the record type the rule applies to. Update access rules are applied individually for each record type, even within the same DNS zone entry.
    The full list of supported record types is in Table 17.2, “DNS Record Types”.
For example, to grant the EXAMPLE.COM zone the ability to edit its own A and AAAA resource record entries: 
$ ipa dnszone-mod example.com --update-policy="grant EXAMPLE.COM krb5-self * A; grant EXAMPLE.COM krb5-self * AAAA;"

17.7. Managing DNS Record Entries

17.7.1. Adding Records to DNS Zones

IdM supports several different types of DNS records, listed in Table 17.2, “DNS Record Types”.
Table 17.2. DNS Record Types
A CERT KX NS SIG
AAAA CNAME LOC NSEC SRV
A6 DNAME MX PTR SSHFP
AFSDB DS NAPTR RRSIG TXT
17.7.1.1. Adding DNS Resource Records from the Web UI

Note

To make new resource records immediately resolvable without restarting the name service, enable persistent searches with the named service or configure the BIND service to poll the Directory Server automatically for zone changes. See Section 17.8.2, “Disabling Persistent Searches”.
  1. Open the Identity tab, and select the DNS subtab.
  2. Click the name of the DNS zone to which to add records.
  3. In the DNS Resource Records tab, click the Add link.
  4. Select the type of record to create in the Record Type drop-down menu. The required data is different, depending on the record type. For example, a CNAME record requires a hostname. The data field name updates automatically to indicate what kind of information to supply.
    Although IdM supports many different record types, there are four frequent record types that are used:
    • A. This is a basic map for a hostname and an ordinary IPv4 address. The Record Name is a hostname, such as www. The IP Address value is a standard IPv4 address, such as 192.168.1.2.
      More information about A records is in RFC 1035.
    • AAAA. This is a basic map for a hostname and an IPv6 address. The Record Name is a hostname, such as www. The IP Address value is a standard hexadecimal IPv6 address, such as fe80::20c:29ff:fe02:a1b3.
      More information about AAAA records is in RFC 3596.
    • SRV. Service (SRV) resource records map service names to the DNS name of the server that is providing that particular service. The Record Name has the format _service._protocol, such as _ldap._tcp. There are individual fields to set the priority, weight, port number, and hostname for the target service.
      More information about SRV records is in RFC 2782.
    • PTR. A pointer record type (PTR) record adds a reverse DNS record, which maps an IP address to a domain name. In this case, the Record Name is the record ID number for the DNS entry of the resource and the Hostname value is the hostname with a terminal period, such as server.example.com..
      More information about PTR records is in RFC 1035.
  5. Click the Add button to save the new resource record.
17.7.1.2. Adding DNS Resource Records from the Command Line
The same script, ipa dnsrecord-add, is used to add resource records of any type, but the options for the script and the required data are different, based on the resource record type.
17.7.1.2.1. About the Commands to Add DNS Records
The ipa dnsrecord-add command adds records to DNS zones, based on the type. Adding a record has the same basic command format: 
$ ipa dnsrecord-add zoneName recordName --recordType-option=data
The zoneName is the name of the DNS zone to which the record is being added. The recordName is an identifier for the new DNS resource record.
Table 17.3, “Common dnsrecord-add Options” lists options for the most common resource record types: A (IPv4), AAAA (IPv6), SRV, and PTR. Options for other supported record types are listed in the ipa dnsrecord-add help and manpages.

Note

The ipa dnsrecord-add command only creates forward entries, not reverse entries.
Table 17.3. Common dnsrecord-add Options
General Record Options
Option Description
--ttl=number Sets the time to live for the record.
--class=IN | CS | CH | HS Sets the class of the record. This is usually IN, for Internet protocol.
--structured Parses the raw DNS records and returns them in a structured format.
Table 17.3. Common dnsrecord-add Options
"A" Record Options
Option Description
--a-rec=ARECORD Passes a comma-separated list of A records.
--a-ip-address=string Gives the IP address for the record.
Table 17.3. Common dnsrecord-add Options
"AAAA" Record Options
Option Description
--aaaa-rec=AAAARECORD Passes a comma-separated list of AAAA (IPv6) records.
--aaaa-ip-address=string Gives the IPv6 address for the record.
Table 17.3. Common dnsrecord-add Options
"PTR" Record Options
Option Description
--ptr-rec=PTRRECORD Passes a comma-separated list of PTR records.
--ptr-hostname=string Gives the hostname for the record.
Table 17.3. Common dnsrecord-add Options
"SRV" Record Options
Option Description
--srv-rec=SRVRECORD Passes a comma-separated list of SRV records.
--srv-priority=number Sets the priority of the record. There can be multiple SRV records for a service type. The priority (0 - 65535) sets the rank of the record; the lower the number, the higher the priority. A service has to use the record with the highest priority first.
--srv-weight=number Sets the weight of the record. This helps determine the order of SRV records with the same priority. The set weights should add up to 100, representing the probability (in percentages) that a particular record is used.
--srv-port=number Gives the port for the service on the target host.
--srv-target=string Gives the domain name of the target host. This can be a single period (.) if the service is not available in the domain.
17.7.1.2.2. Examples of Adding DNS Resource Records

Note

To make new resource records immediately resolvable without restarting the name service, enable persistent searches with the named service or configure the BIND service to poll the Directory Server automatically for zone changes. See Section 17.8.2, “Disabling Persistent Searches”.

Example 17.6. IPv4 Record

Type A resource records map hostnames to IPv4 addresses. The record value for these commands, then, is a standard IPv4 address. The URL label is usually www. 
$ ipa dnsrecord-add example.com www --a-rec 10.64.14.165
This creates the record www.example.com with the IP address 10.64.14.165.
More information about A records is in RFC 1035.

Example 17.7. Modifying IPv4 Record

There are two options that specify an A record value. When creating a record, the option is --a-record. However, when modifying an A record, the --a-record option shows the old value for the A record. The new value is set with the --ip-address option. 
$ ipa dnsrecord-mod example.com www --a-rec 10.1.1.1 --ip-address 10.1.1.2

Example 17.8. IPv6 Record

Type AAAA resource records (quad-A records) map hostnames to IPv6 addresses. The record value for these commands is an IPv6 address. As with Type A records, the URL label is usually www. 
$ ipa dnsrecord-add example.com www --aaaa-rec fe80::20c:29ff:fe02:a1b3
This creates the record www.example.com with the IP address fe80::20c:29ff:fe02:a1b3. More information about AAAA records is in RFC 3596.

Example 17.9. SRV Record

Service (SRV) resource records map service names to the DNS name of the server that is providing that particular service. For example, this record type can map a service like an LDAP directory to the server which manages it.
As with Type A and Type AAAA records, SRV records specify a way to connect to and identify the service, but the record format is different.
The recordName identifies the service type and the connection protocol, in the format _service._protocol.
The record information has the format "priority weight port target". 
[root@server ~]# ipa dnsrecord-add server.example.com _ldap._tcp --srv-rec="0 51 389 server1.example.com."
[root@server ~]# ipa dnsrecord-add server.example.com _ldap._tcp --srv-rec="1 49 389 server2.example.com."
The set weights should add up to 100, representing the probability (in percentages) that a particular record is used.
More information about SRV records is in RFC 2782.

Example 17.10. PTR Record

A pointer record type (PTR) record adds a reverse DNS record, which maps an IP address to a domain name.
All reverse DNS lookups for IPv4 addresses use reverse entries that are defined in the in-addr.arpa. domain. The reverse address, in human-readable form, is the exact reverse of the regular IP address, with the in-addr.arpa. domain appended to it. For example, for the network address 192.0.2.0/24, the reverse zone is 2.0.192.in-addr.arpa. 
$ ipa dnsrecord-add reverseZone recordName --ptr-rec FQDN
The recordName and reverseZone need to create a valid reverse name when concatenated in the following way: recordName.reverseZone
For example, this adds a reverse DNS entry to the 1.0.192.in-addr.arpa. reverse zone for the host server2.example.com with the IP address 192.0.1.2: 
$ ipa dnsrecord-add 1.0.192.in-addr.arpa. 2 --ptr-rec server2.example.com.
The next example adds a reverse DNS entry to the 0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa. IPv6 reverse zone for the host server2.example.com with the IP address 2001:DB8::1111: 
$ ipa dnsrecord-add 0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa. 1.1.1.0.0.0.0.0.0.0.0.0.0.0.0 --ptr-rec server2.example.com.

Note

For more information on PTR records, see the following resources:
  • RFC 1035 describes the specification for the IPv4 in-addr.arpa domain.
  • RFC 2317 describes IPv4 classless in-addr.arpa delegation
  • RFC 3596 describes extensions to support IPv6

17.7.2. Deleting Records from DNS Zones

17.7.2.1. Deleting Records with the Web UI
To delete only a specific record type from the resource record:
  1. Open the Identity tab, and select the DNS subtab.
  2. Click the name of the DNS zone.
  3. In the DNS Resource Records tab, click the name of the resource record.
  4. Click the checkbox by the name of the record type to delete, and then click the active Delete link at the top of the list.
    This deletes only that record type while leaving the other configuration intact.
Alternatively, delete all of the records for the resource in the zone:
  1. Open the Identity tab, and select the DNS subtab.
  2. Click the name of the DNS zone.
  3. In the DNS Resource Records tab, select the checkbox by the name of the resource record to delete. This deletes the entire record.
  4. Click the Delete link at the top of the zone records page.
17.7.2.2. Deleting Records with the Command Line
Records are removed from the zone using the ipa dnsrecord-del command. As with adding records, records are deleted using an option that specifies the type of record (--recordType-rec) and the record value.
For example, to remove the A type record: 
$ ipa dnsrecord-del example.com www --a-rec 10.64.14.213
If you run the ipa dnsrecord-del command without any options, the command prompts for information about the record to delete.
Alternatively, using the --del-all option removes all associated records for the zone.

17.8. Configuring the bind-dyndb-ldap Plug-in

The bind-dyndb-ldap system plug-in contains a DNS record cache for zones and a history of successful DNS resolutions. Maintaining the cache improves lookup performance in the Directory Server because it is not necessary to query the directory services every time there is a new DNS request.
When this plug-in is installed and IdM is configured to manage DNS, then a new configuration section is added to the plug-in configuration.

Example 17.11. Default dynamic-db Configuration

dynamic-db "ipa" {
        library "ldap.so";
        arg "uri ldapi://%2fvar%2frun%2fslapd-EXAMPLE.socket";
        arg "base cn=dns,dc=example,dc=com";
        arg "fake_mname server.example.com.";
        arg "auth_method sasl";
        arg "sasl_mech GSSAPI";
        arg "sasl_user DNS/server.example.com";
        arg "zone_refresh 0";
        arg "psearch yes";
        arg "serial_autoincrement 1";
};
This configuration uses implied default values for other plug-in behaviors, like how long it maintains the cache. The assumed, default configuration can be changed by adding arguments to the dynamic-db "ipa" entry. 
arg "argument value";
The additional parameters are listed in Table 17.4, “Additional bind-dyndb-ldap Configuration Parameters”.

Note

Both cache updates and new zone detection can be forced by reloading the name server: 
# rndc reload
Table 17.4. Additional bind-dyndb-ldap Configuration Parameters
Parameter Description Default Value
cache_ttl Checks the DNS configuration in the Directory Server for new zones. 120 (seconds); this is defined in the bind-dyndb-ldap plug-in.
zone_refresh Checks frequency, in seconds, that the server checks the DNS configuration in the Directory Server for new zones. 0 (disabled)
psearch Enables persistent searches for the Directory Server so the BIND service immediately receives an update notification when a new DNS zone is added. yes

17.8.1. Changing the DNS Cache Setting

To improve DNS performance, it may be necessary to change the cache setting. By default, DNS records are kept in cache and considered valid for 120 seconds. This means that if a DNS record changes, it will not (necessarily) be propagated to the name server for up to 120 seconds. If the Directory Server has a high traffic volume or if records do not change frequently, then the cache time can be increased to improve performance by adding the cache_ttl parameter. 
dynamic-db "ipa" { 
... 
    arg "cache_ttl 1800"; 
};

17.9. Changing Recursive Queries Against Forwarders

The ipa-client-install script sets a configuration statement in the /etc/named.conf file that allows name resolution against hosts that are outside the IdM DNS domain. (This requires that the IdM server be set up with DNS configured and with forwarders configured.) What this means is that any host is permitted to issue recursive queries against configured forwarders.
By default, any host is permitted to issue recursive queries against configured forwarders. The IdM installation script automatically adds a line to the /etc/named.conf file to allow these recursive queries. 
        forward first;
        forwarders { 10.16.36.29; };
        allow-recursion { any; };
This behavior can be changed in the allow-recursion statement.
  1. Open the /etc/named.conf file.
  2. Reset the allow-recursion statement. This is set to any by default, which allows all hosts to resolve names against all forwarders. 
            forward first;
        forwarders { 10.16.36.29; };
        allow-recursion { any; };
  3. Restart the named service. 
    service named restart
The name server documentation has more details on editing configuration statements.

17.10. Resolving Hostnames in the IdM Domain

It is possible to check the DNS entries for IdM domain members using the dns-resolve command. If the record exists and is properly formatted in the DNS configuration, then the command returns the DNS record. If not, the command returns an error, that the hostname is not recognized within the DNS service. 
$ipa dns-resolve server1.example.com
This can be helpful with troubleshooting connection problems between servers, clients, and services.

[6] Any updated schema files, included updated DNS schema elements, are located in the /usr/share/ipa/updates directory.