Red Hat Training

A Red Hat training course is available for RHEL 8

Configuring and managing Identity Management

Red Hat Enterprise Linux 8

Configuring, managing, and maintaining Identity Management in Red Hat Enterprise Linux 8

Red Hat Customer Content Services

Abstract

This documentation collection provides instructions on how to effectively configure, manage and maintain Identity Management on Red Hat Enterprise Linux 8.

Providing feedback on Red Hat documentation

We appreciate your input on our documentation. Please let us know how we could make it better. To do so:

  • For simple comments on specific passages:

    1. Make sure you are viewing the documentation in the Multi-page HTML format. In addition, ensure you see the Feedback button in the upper right corner of the document.
    2. Use your mouse cursor to highlight the part of text that you want to comment on.
    3. Click the Add Feedback pop-up that appears below the highlighted text.
    4. Follow the displayed instructions.
  • For submitting more complex feedback, create a Bugzilla ticket:

    1. Go to the Bugzilla website.
    2. As the Component, use Documentation.
    3. Fill in the Description field with your suggestion for improvement. Include a link to the relevant part(s) of documentation.
    4. Click Submit Bug.

Chapter 1. Logging in to Identity Management from the command line

Identity Management (IdM) uses the Kerberos protocol to support single sign-on. Single sign-on means that the user enters the correct user name and password only once, and then accesses IdM services without the system prompting for the credentials again.

Important

In IdM, the System Security Services Daemon (SSSD) automatically obtains a ticket-granting ticket (TGT) for a user after the user successfully logs in to the desktop environment on an IdM client machine with the corresponding Kerberos principal name. This means that after logging in, the user is not required to use the kinit utility to access IdM resources.

If you have cleared your Kerberos credential cache or your Kerberos TGT has expired, you need to request a Kerberos ticket manually to access IdM resources. The following sections present basic user operations when using Kerberos in IdM.

1.1. Using kinit to log in to IdM manually

This procedure describes using the kinit utility to authenticate to an Identity Management (IdM) environment manually. The kinit utility obtains and caches a Kerberos ticket-granting ticket (TGT) on behalf of an IdM user.

Note

Only use this procedure if you have destroyed your initial Kerberos TGT or if it has expired. As an IdM user, when logging onto your local machine you are also automatically logging in to IdM. This means that after logging in, you are not required to use the kinit utility to access IdM resources.

Procedure

  1. To log in to IdM

    • under the user name of the user who is currently logged in on the local system, use kinit without specifying a user name. For example, if you are logged in as example_user on the local system:

      [example_user@server ~]$ kinit
      Password for example_user@EXAMPLE.COM:
      [example_user@server ~]$

      If the user name of the local user does not match any user entry in IdM, the authentication attempt fails:

      [example_user@server ~]$ kinit
      kinit: Client 'example_user@EXAMPLE.COM' not found in Kerberos database while getting initial credentials
    • using a Kerberos principal that does not correspond to your local user name, pass the required user name to the kinit utility. For example, to log in as the admin user:

      [example_user@server ~]$ kinit admin
      Password for admin@EXAMPLE.COM:
      [example_user@server ~]$
  2. Optionally, to verify that the login was successful, use the klist utility to display the cached TGT. In the following example, the cache contains a ticket for the example_user principal, which means that on this particular host, only example_user is currently allowed to access IdM services:

    $ klist
    Ticket cache: KEYRING:persistent:0:0
    Default principal: example_user@EXAMPLE.COM
    
    Valid starting     	Expires            	Service principal
    11/10/2019 08:35:45  	11/10/2019 18:35:45  	krbtgt/EXAMPLE.COM@EXAMPLE.COM

1.2. Destroying a user’s active Kerberos ticket

This section describes how to clear the credentials cache that contains the user’s active Kerberos ticket.

Procedure

  1. To destroy your Kerberos ticket:

    [example_user@server ~]$ kdestroy
  2. Optionally, to check that the Kerberos ticket has been destroyed:

    [example_user@server ~]$ klist
    klist: Credentials cache keyring 'persistent:0:0' not found

1.3. Configuring an external system for Kerberos authentication

This section describes how to configure an external system so that Identity Management (IdM) users can log in to IdM from the external system using their Kerberos credentials.

Enabling Kerberos authentication on external systems is especially useful when your infrastructure includes multiple realms or overlapping domains. It is also useful if the system has not been enrolled into any IdM domain through ipa-client-install.

To enable Kerberos authentication to IdM from a system that is not a member of the IdM domain, define an IdM-specific Kerberos configuration file on the external system.

Prerequisites

  • The krb5-workstation package is installed on the external system.

    To find out whether the package is installed, use the following CLI command:

    # yum list installed krb5-workstation
    Installed Packages
    krb5-workstation.x86_64    1.16.1-19.el8     @BaseOS

Procedure

  1. Copy the /etc/krb5.conf file from the IdM server to the external system. For example:

    # scp /etc/krb5.conf root@externalsystem.example.com:/etc/krb5_ipa.conf
    Warning

    Do not overwrite the existing krb5.conf file on the external system.

  2. On the external system, set the terminal session to use the copied IdM Kerberos configuration file:

    $ export KRB5_CONFIG=/etc/krb5_ipa.conf

    The KRB5_CONFIG variable exists only temporarily until you log out. To prevent this loss, export the variable with a different file name.

  3. Copy the Kerberos configuration snippets from the /etc/krb5.conf.d/ directory to the external system.

Users on the external system can now use the kinit utility to authenticate against the IdM server.

Additional resources

  • For details on Kerberos, see the krb5.conf(5), kinit(1), klist(1), and kdestroy(1) man pages.

Chapter 2. Viewing, starting and stopping the Identity Management services

Identity Management (IdM) servers are Red Hat Enterprise Linux systems that work as domain controllers (DCs). A number of different services are running on IdM servers, most notably the Directory Server, Certificate Authority (CA), DNS, and Kerberos.

2.1. Viewing the status of IdM services

To view the status of the IdM services that are configured on your IdM server:

[root@server ~]# ipactl status
Directory Service: RUNNING
krb5kdc Service: RUNNING
kadmin Service: RUNNING
named Service: RUNNING
httpd Service: RUNNING
ntpd Service: RUNNING
pki-tomcatd Service: RUNNING
smb Service: RUNNING
winbind Service: RUNNING
ipa-otpd Service: RUNNING
ipa-dnskeysyncd Service: RUNNING
ipa: INFO: The ipactl command was successful

In the output above:

  • The Kerberos service is divided into two parts, krb5kdc and kadmin. The krb5kdc service is the Kerberos version 5 Authentication service and Key Distribution Center (KDC) deamon. The kadmin service is the Kerberos V5 database administration program.
  • The named service refers to the Internet domain name service (DNS).
  • pki is the Command-Line Interface for accessing Certificate System services. The pki-tomcatd program handles Identity Management operations related to certificates.

The output of the ipactl status command on your server depends on your IdM configuration. For example, if an IdM deployment does not include a DNS server, the named service is not present in the list.

Note

You cannot use the IdM web UI to view the status of all the IdM services running on a particular IdM server. Kerberized services running on different servers can be viewed in the IdentityServices tab of the IdM web UI.

You can start or stop the entire server, or an individual service only.

To start, stop, or restart the entire IdM server, see:

To start, stop, or restart an individual IdM service, see:

To display the version of IdM software, see:

2.2. Starting and stopping the entire Identity Management server: the ipactl utility

Use the ipactl utility to stop, start, or restart the entire IdM server along with all the installed services. Using the ipactl utility ensures all services are stopped, started, or restarted in the appropriate order. You do not need to have a valid Kerberos ticket to run the ipactl commands.

ipactl commands

To start the entire IdM server:

# ipactl start

To stop the entire IdM server:

# ipactl stop

To restart the entire IdM server:

# ipactl restart

To show the status of all the services that make up IdM:

# ipactl status
Important

You cannot use the IdM web UI to perform the ipactl commands.

2.3. Starting and stopping an individual Identity Management service: the systemctl utility

Changing IdM configuration files manually is generally not recommended. However, certain situations require that an administrator performs a manual configuration of specific services. In such situations, use the systemctl utility to stop, start, or restart an individual IdM service.

For example, use systemctl after customizing the Directory Server behavior, without modifying the other IdM services:

# systemctl restart dirsrv@REALM-NAME.service

Also, when initially deploying an IdM trust with Active Directory, modify the /etc/sssd/sssd.conf file, adding:

  • specific parameters to tune the timeout configuration options in an environment where remote servers have a high latency
  • specific parameters to tune the Active Directory site affinity
  • overrides for certain configuration options that are not provided by the global IdM settings

To apply the changes you have made in the /etc/sssd/sssd.conf file:

# systemctl restart sssd.service

Running systemctl restart sssd.service is required because the System Security Services Daemon (SSSD) does not automatically re-read or re-apply its configuration.

Note that for changes that affect IdM identity ranges, a complete server reboot is recommended.

Important

To restart multiple IdM domain services, always use ipactl. Because of dependencies between the services installed with the IdM server, the order in which they are started and stopped is critical. The ipactl utility ensures that the services are started and stopped in the appropriate order.

Useful systemctl commands

To start a particular IdM service:

# systemctl start name.service

To stop a particular IdM service:

# systemctl stop name.service

To restart a particular IdM service:

# systemctl restart name.service

To view the status of a particular IdM service:

# systemctl status name.service
Important

You cannot use the IdM web UI to start or stop the individual services running on IdM servers. You can only use the web UI to modify the settings of a Kerberized service by navigating to IdentityServices and selecting the service.

2.4. Methods for displaying IdM software version

You can display the IdM version number with:

  • the IdM WebUI
  • ipa commands
  • rpm commands

 

Displaying version through the WebUI

In the IdM WebUI, the software version can be displayed by choosing About from the username menu at the top-right.

Checking IdM Software Version
Displaying version with ipa commands

From the command line, use the ipa --version command.

[root@server ~]# ipa --version
VERSION: 4.8.0, API_VERSION: 2.233
Displaying version with rpm commands

If IdM services are not operating properly, you can use the rpm utility to determine the version number of the ipa-server package that is currently installed.

[root@server ~]# rpm -q ipa-server
ipa-server-4.8.0-11.module+el8.1.0+4247+9f3fd721.x86_64

Chapter 3. Introduction to the IdM command-line utilities

The following sections describe the basics of using the Identity Management (IdM) command-line utilities.

Prerequisites

3.1. What is the IPA command line interface

The IPA command line interface (CLI) is the basic command-line interface for Identity Management (IdM) administration.

It supports a lot of subcommands that are used to manage IdM, such as the ipa user-add command to add a new user.

IPA CLI allows you to:

  • Add, manage, or remove users, groups, hosts and other objects in the network.
  • Manage certificates.
  • Search entries.
  • Display and list objects.
  • Set access rights.
  • Get help with the correct command syntax.

3.2. What is the IPA help

The IPA help is a built-in documentation system for the IdM server.

IPA command line interface (CLI) generates available help topics from loaded IdM plugin modules. If you want to run the IPA help successfully, you need to:

  • Have an IdM server installed and running.
  • Be authenticated with a valid Kerberos ticket.

Executing the ipa help command without options displays information about basic help usage and the most common command examples.

Executing help with options has the following syntax:

$ ipa help [TOPIC | COMMAND | topics | commands]
  • [] — Brackets mean that all parameters are optional and you can write just ipa help and the command will be executed.
  • | — The pipe character means or. Therefore, you can use TOPIC or COMMAND or topics or commands with the basic ipa help command.
  • topics — You can run the command ipa help topics and it will execute correctly. The command displays a list of topics that are covered by IPA help, for example, user, cert, server and many others.
  • TOPIC — The TOPIC with capital letters means variable, therefore, you can use the particular topic, for example, ipa help user
  • commands — You can run the command ipa help commands and it will execute correctly. The command displays a list of commands which are covered by the IPA help, for example, user-add, ca-enable, server-show and many others.
  • COMMAND — The COMMAND with capital letters means variable, therefore, you can use the particular command, for example, ipa help user-add

3.3. Using IPA help topics

The following procedure helps you to understand using the IPA help in the command line interface.

Procedure

  1. Open terminal and connect to the IdM server.
  2. Enter ipa help topics to display a list of topics covered by help.

    $ ipa help topics
  3. Select one of the topics and create a command according to the following pattern: ipa help [topic_name], instead of the topic_name string, add one of the topics you listed in the previous step.

    In the example, we use the following topic: user

    $ ipa help user
  4. If the IPA help command is too long and you cannot see the whole text, use the following syntax:

    $ ipa help user | less

    You can then scroll down and read the whole help.

The IPA CLI displays a help page for the user topic. After reading the overview, you can see many examples with patterns for working with topic commands.

3.4. Using IPA help commands

The following procedure helps you to understand creating the IPA help commands in the command line interface.

Procedure

  1. Open terminal and connect to the IdM server.
  2. Enter ipa help commands to display a list of commands covered by help.

    $ ipa help commands
  3. Select one of the commands and create a help command according to the following pattern: ipa help <COMMAND>, instead of the <COMMAND> string, add one of the commands you listed in the previous step.

    $ ipa help user-add

Additional resources

  • For details, see man ipa page.

3.5. Structure of IPA commands

The IPA CLI distinguishes the following types of commands:

  • Built-in commands — Built-in commands are all available in the IdM server.
  • Plug-in provided commands

Structure of IPA commands allows you to manage various types of objects. For example:

  • Users,
  • Hosts,
  • DNS records,
  • Certificates,

and many others.

For most of these objects, the IPA CLI includes commands to:

  • Add (add)
  • Modify (mod)
  • Delete (del)
  • Search (find)
  • Display (show)

Commands have the following structure:

ipa user-add, ipa user-mod, ipa user-del, ipa user-find, ipa user-show

ipa host-add, ipa host-mod, ipa host-del, ipa host-find, ipa host-show

ipa dnsrecord-add, ipa dnsrecord-mod, ipa dnsrecord-del, ipa dnsrecord-find, ipa dnrecord-show

You can create a user with the ipa user-add [options], where [options] are optional. If you use just the ipa user-add command, the script asks you for details one by one.

To change an existing object, you need to define the object, therefore the command includes also object: ipa user-mod USER_NAME [options].

3.6. Using an IPA command to add a user account to IdM

The following describes adding a new user to the Identity Management (IdM) database using command line.

Prerequisites

  • You need to have administrator privileges to add user accounts to the IdM server.

Procedure

  1. Open terminal and connect to the IdM server.
  2. Enter the command for adding a new user:

    $ ipa user-add

    The command runs a script where you can add basic data necessary for creating a user account.

  3. In the First name: field, enter the first name of the new user and press the Enter key.
  4. In the Last name: field, enter the last name of the new user and press the Enter key.
  5. In the User login [suggested user name]: enter the user name or just press the Enter key if the suggested user name works for you.

    User name must be unique for the whole IdM database. If an error occurs, that the user already exists, you need to start from the beginning with the ipa user-add command and try a different user name.

After you successfully added the user name, the user account has been added to the IdM database and the IPA command line interface (CLI) prints on the output the following log:

----------------------
Added user "euser"
----------------------
User login: euser
First name: Example
Last name: User
Full name: Example User
Display name: Example User
Initials: EU
Home directory: /home/euser
GECOS: Example User
Login shell: /bin/sh
Principal name: euser@IDM.EXAMPLE.COM
Principal alias: euser@IDM.EXAMPLE.COM
Email address: euser@idm.example.com
UID: 427200006
GID: 427200006
Password: False
Member of groups: ipausers
Kerberos keys available: False

As you can see, a user password is not set to the user account. If you want to add also password, use the ipa user-add command in the following syntax:

$ ipa user-add --first=Example --last=User --password

The IPA CLI then asks you for adding or confirming a user name and password.

If the user has been already created, you can add only the password with the `ipa user-mod`command.

Additional resources

For more information about parameters, enter the following help command to the command line:

$ ipa help user-add

3.7. Using an IPA command to modify a user account in IdM

You can change many parameters for each user account. For example, you can add a new password to the user.

Basic command syntax is different from the user-add syntax because you need to define the existing user account for which you want to perform changes, for example, add a password.

Prerequisites

  • You need to have administrator privileges to modify user accounts in the IdM server.

Procedure

  1. Open terminal and connect to the IdM server.
  2. Enter the command for adding a password:

    $ ipa user-mod euser --password

    The command runs a script where you can add the new password.

  3. Enter the new password and press the Enter key.

After you successfully added the user name, the user account has been added to the IdM database and the IPA CLI prints on the output the following log:

----------------------
Modified user "euser"
----------------------
User login: euser
First name: Example
Last name: User
Home directory: /home/euser
Principal name: euser@IDM.EXAMPLE.COM
Principal alias: euser@IDM.EXAMPLE.COM
Email address: euser@idm.example.com
UID: 427200006
GID: 427200006
Password: True
Member of groups: ipausers
Kerberos keys available: True

The user password is now set for the account and the user can log into IdM.

Additional resources

For more information about parameters, enter the following help command to the command line:

$ ipa help user-mod

3.8. How to supply a list of values to the IdM utilities

Identity Management (IdM) stores values for multi-valued attributes in lists.

IdM supports the following methods of supplying multi-valued lists:

  • Using the same command-line argument multiple times within the same command invocation:

    $ ipa permission-add --right=read --permissions=write --permissions=delete ...
  • Alternatively, you can enclose the list in curly braces, in which case the shell performs the expansion:

    $ ipa permission-add --right={read,write,delete} ...

Examples above show a command permission-add which adds permissions to an object. The object is not mentioned in the example. Instead of …​ you need to add the object for which you want to add permissions.

When you update such multi-valued attributes from the command line, IdM completely overwrites the previous list of values with a new list. Therefore, when updating a multi-valued attribute, you must specify the whole new list, not just a single value you want to add.

In the command above, the list of permissions includes reading, writing and deleting. When you decide to update the list with the permission-mod command, you must add all values, otherwise those not mentioned will be deleted.

Example 1: — The ipa permission-mod command updates all previously added permissions.

$ ipa permission-mod --right=read --right=write --right=delete ...

or

$ ipa permission-mod --right={read,write,delete} ...

Example 2 — The ipa permission-mod command deletes the --right=delete argument because it is not included in the command:

$ ipa permission-mod --right=read --right=write ...

or

$ ipa permission-mod --right={read,write} ...

3.9. How to use special characters with the IdM utilities

When passing command-line arguments that include special characters to the ipa commands, escape these characters with a backslash (\). For example, common special characters include angle brackets (< and >), ampersand (&), asterisk (*), or vertical bar (|).

For example, to escape an asterisk (*):

$ ipa certprofile-show certificate_profile --out=exported\*profile.cfg

Commands containing unescaped special characters do not work as expected because the shell cannot properly parse such characters.

Chapter 4. Searching Identity Management entries from the command line

The following sections describe how to use IPA commands, which helps you to find or show objects.

4.1. Overview of listing IdM entries

This section describes the ipa *-find commands, which can help you to search for a particular type of IdM entries.

To list all the find commands, use the following ipa help command:

$ ipa help commands | grep find

You may need to check if a particular user is included in the IdM database. You can then list all users with the following command:

$ ipa user-find

To list user groups whose specified attributes contain a keyword:

$ ipa group-find keyword

For example the ipa group-find admin command lists all groups whose names or descriptions include string admin:

----------------
3 groups matched
----------------
   Group name: admins
   Description: Account administrators group
   GID: 427200002

   Group name: editors
   Description: Limited admins who can edit other users
   GID: 427200002

   Group name: trust admins
   Description: Trusts administrators group

When searching user groups, you can also limit the search results to groups that contain a particular user:

$ ipa group-find --user=user_name

To search for groups that do not contain a particular user:

$ ipa group-find --no-user=user_name

4.2. Showing details for a particular entry

Use the ipa *-show command to display details about a particular IdM entry.

Procedure

  • To display details about a host named server.example.com:

    $ ipa host-show server.example.com
    
    Host name: server.example.com
    Principal name: host/server.example.com@EXAMPLE.COM
    ...

4.3. Adjusting the search size and time limit

Some queries, such as requesting a list of IdM users, can return a very large number of entries. By tuning these search operations, you can improve the overall server performance when running the ipa *-find commands, such as ipa user-find, and when displaying corresponding lists in the Web UI.

Search size limit

Defines the maximum number of entries returned for a request sent to the server from a client’s CLI or from a browser accessing the IdM Web UI.

Default: 100 entries.

Search time limit

Defines the maximum time (in seconds) that the server waits for searches to run. Once the search reaches this limit, the server stops the search and returns the entries discovered in that time.

Default: 2 seconds.

If you set the values to -1, IdM will not apply any limits when searching.

Important

Setting search size or time limits too high can negatively affect server performance.

4.3.1. Adjusting the search size and time limit in the command line

The following text describes adjusting search size and time limits in the command line:

  • Globally
  • For a specific entry

Procedure

  1. To display current search time and size limits in CLI, use the ipa config-show command:

    $ ipa config-show
    
    Search time limit: 2
    Search size limit: 100
  2. To adjust the limits globally for all queries, use the ipa config-mod command and add the --searchrecordslimit and --searchtimelimit options. For example:

    $ ipa config-mod --searchrecordslimit=500 --searchtimelimit=5
  3. To adjust the limits only for a specific query, add the --sizelimit or --timelimit options to the command. For example:
$ ipa user-find --sizelimit=200 --timelimit=120

4.3.2. Adjusting the search size and time limit in the Web UI

The following text describes adjusting search size and time limits in the IdM Web UI:

  • Globally
  • For a specific entry

Procedure

To adjust the limits globally for all queries:

  1. Log in to the IdM Web UI.
  2. Click IPA Server.

    web ui ipaserver

  3. On the IPA Server tab, click Configuration.
  4. Set the required values in the Search Options area.

    Default values are:

    • Search size limit: 100 entries
    • Search time limit: 2 seconds
  5. Click Save at the top of the page.

    web ui search limits

After saving the values, search an entry and verify the result.

Chapter 5. Accessing the IdM Web UI in a web browser

The following sections provide an overview of the IdM (Identity Management) Web UI and describe how to access it.

5.1. What is the IdM Web UI

The IdM (Identity Management) Web UI is a web application for IdM administration, a graphical alternative to the IdM command line tools.

You can access the IdM Web UI as:

  • IdM users: A limited set of operations depending on permissions granted to the user in the IdM server. Basically, active IdM users can log in to the IdM server and configure their own account. They cannot change settings of other users or the IdM server settings.
  • Administrators: Full access rights to the IdM server.
  • Active Directory users: A limited set of operations depending on permissions granted to the user.

    Active Directory users cannot be administrators for Identity Management.

5.2. Web browsers supported for accessing the Web UI

IdM (Identity Management) supports the following browsers for connecting to the Web UI:

  • Mozilla Firefox 38 and later
  • Google Chrome 46 and later

5.3. Accessing the Web UI

The following procedure describes the first logging in to the IdM (Identity Management) Web UI with a password.

After the first login you can configure your IdM server to authenticate with:

Procedure

  1. Type an IdM server URL into the browser address bar. The name will look similarly to the following example:

    https://server.example.com

    You just need to change server.example.com with a DNS name of your IdM server.

    This opens the IdM Web UI login screen in your browser.

    web ui login screen

    • If the server does not respond or the login screen does not open, check the DNS settings on the IdM server to which you are connecting.
    • If you use a self-signed certificate, the browser issues a warning. Check the certificate and accept the security exception to proceed with the login.

      To avoid security exceptions, install a certificate signed by a certificate authority.

  2. On the Web UI login screen, enter the administrator account credentials you added during the IdM server installation.

    For details, see Installing an Identity Management server: With integrated DNS, with an integrated CA.

    You can enter your personal account credentials as well if they are already entered in the IdM server.

    web ui login passwd

  3. Click Log in.

After the successful login, you can start configuring the IdM server.

web ui users

Chapter 6. Logging in to IdM in the Web UI: Using a Kerberos ticket

The following sections describe the initial configuration of your environment to enable Kerberos login to the IdM Web UI and accessing IdM using Kerberos authentication.

Prerequisites

6.1. Kerberos authentication in Identity Management

Identity Management (IdM) uses the Kerberos protocol to support single sign-on. Single sign-on authentication allows you to provide the correct user name and password only once, and you can then access Identity Management services without the system prompting for credentials again.

The IdM server provides Kerberos authentication immediately after the installation if the DNS and certificate settings have been configured properly. For details, see Installing Identity Management.

To use Kerberos authentication on hosts, install:

6.2. Using kinit to log in to IdM manually

This procedure describes using the kinit utility to authenticate to an Identity Management (IdM) environment manually. The kinit utility obtains and caches a Kerberos ticket-granting ticket (TGT) on behalf of an IdM user.

Note

Only use this procedure if you have destroyed your initial Kerberos TGT or if it has expired. As an IdM user, when logging onto your local machine you are also automatically logging in to IdM. This means that after logging in, you are not required to use the kinit utility to access IdM resources.

Procedure

  1. To log in to IdM

    • under the user name of the user who is currently logged in on the local system, use kinit without specifying a user name. For example, if you are logged in as example_user on the local system:

      [example_user@server ~]$ kinit
      Password for example_user@EXAMPLE.COM:
      [example_user@server ~]$

      If the user name of the local user does not match any user entry in IdM, the authentication attempt fails:

      [example_user@server ~]$ kinit
      kinit: Client 'example_user@EXAMPLE.COM' not found in Kerberos database while getting initial credentials
    • using a Kerberos principal that does not correspond to your local user name, pass the required user name to the kinit utility. For example, to log in as the admin user:

      [example_user@server ~]$ kinit admin
      Password for admin@EXAMPLE.COM:
      [example_user@server ~]$
  2. Optionally, to verify that the login was successful, use the klist utility to display the cached TGT. In the following example, the cache contains a ticket for the example_user principal, which means that on this particular host, only example_user is currently allowed to access IdM services:

    $ klist
    Ticket cache: KEYRING:persistent:0:0
    Default principal: example_user@EXAMPLE.COM
    
    Valid starting     	Expires            	Service principal
    11/10/2019 08:35:45  	11/10/2019 18:35:45  	krbtgt/EXAMPLE.COM@EXAMPLE.COM

6.3. Configuring the browser for Kerberos authentication

To enable authentication with a Kerberos ticket, you may need a browser configuration.

The following steps help you to support Kerberos negotiation for accessing the IdM domain.

Each browser supports Kerberos in a different way and needs different set up. The IdM Web UI includes guidelines for the following browsers:

  • Firefox
  • Chrome

Procedure

  1. Open the IdM Web UI login dialog in your web browser.
  2. Click the link for browser configuration on the Web UI login screen.

    ipa browser config link

  3. Follow the steps on the configuration page.

    ipa browser config page

After the setup, turn back to the IdM Web UI and click Log in.

6.4. Logging in to the web UI using a Kerberos ticket

This procedure describes logging in to the IdM Web UI using a Kerberos ticket-granting ticket (TGT).

The TGT expires at a predefined time. The default time interval is 24 hours and you can change it in the IdM Web UI.

After the time interval expires, you need to renew the ticket:

  • Using the kinit command.
  • Using IdM login credentials in the Web UI login dialog.

Procedure

  • Open the IdM Web UI.

    If Kerberos authentication works correctly and you have a valid ticket, you will be automatically authenticated and the Web UI opens.

    If the ticket is expired, it is necessary to authenticate yourself with credentials first. However, next time the IdM Web UI will open automatically without opening the login dialog.

    If you see an error message Authentication with Kerberos failed, verify that your browser is configured for Kerberos authentication. See Section 6.3, “Configuring the browser for Kerberos authentication”.

    firefox kerb auth failed

6.5. Configuring an external system for Kerberos authentication

This section describes how to configure an external system so that Identity Management (IdM) users can log in to IdM from the external system using their Kerberos credentials.

Enabling Kerberos authentication on external systems is especially useful when your infrastructure includes multiple realms or overlapping domains. It is also useful if the system has not been enrolled into any IdM domain through ipa-client-install.

To enable Kerberos authentication to IdM from a system that is not a member of the IdM domain, define an IdM-specific Kerberos configuration file on the external system.

Prerequisites

  • The krb5-workstation package is installed on the external system.

    To find out whether the package is installed, use the following CLI command:

    # yum list installed krb5-workstation
    Installed Packages
    krb5-workstation.x86_64    1.16.1-19.el8     @BaseOS

Procedure

  1. Copy the /etc/krb5.conf file from the IdM server to the external system. For example:

    # scp /etc/krb5.conf root@externalsystem.example.com:/etc/krb5_ipa.conf
    Warning

    Do not overwrite the existing krb5.conf file on the external system.

  2. On the external system, set the terminal session to use the copied IdM Kerberos configuration file:

    $ export KRB5_CONFIG=/etc/krb5_ipa.conf

    The KRB5_CONFIG variable exists only temporarily until you log out. To prevent this loss, export the variable with a different file name.

  3. Copy the Kerberos configuration snippets from the /etc/krb5.conf.d/ directory to the external system.
  4. Configure the browser on the external system, as described in Section 6.3, “Configuring the browser for Kerberos authentication”.

Users on the external system can now use the kinit utility to authenticate against the IdM server.

6.6. Web UI login for Active Directory users

To enable Web UI login for Active Directory users, define an ID override for each Active Directory user in the default trust view. For example:

[admin@server ~]$ ipa idoverrideuser-add 'Default Trust View' ad_user@ad.example.com

Chapter 7. Logging in to the Identity Management Web UI using one time passwords

Access to IdM Web UI can be secured using several methods. The basic one is password authentication.

To increase the security of password authentication, you can add a second step and require automatically generated one-time passwords (OTPs). The most common usage is to combine password connected with the user account and a time limited one time password generated by a hardware or software token.

The following sections help you to:

  • Understand how the OTP authentication works in IdM.
  • Configure OTP authentication on the IdM server.
  • Create OTP tokens and synchronize them with the FreeOTP app in your phone.
  • Authenticate to the IdM Web UI with the combination of user password and one time password.
  • Re-synchronize tokens in the Web UI.

7.1. Prerequisites

7.2. One time password (OTP) authentication in Identity Management

One-time passwords bring an additional step to your authentication security. The authentication uses your password + an automatically generated one time password.

To generate one time passwords, you can use a hardware or software token. IdM supports both software and hardware tokens.

Identity Management supports the following two standard OTP mechanisms:

  • The HMAC-Based One-Time Password (HOTP) algorithm is based on a counter. HMAC stands for Hashed Message Authentication Code.
  • The Time-Based One-Time Password (TOTP) algorithm is an extension of HOTP to support time-based moving factor.
Important

IdM does not support OTP logins for Active Directory trust users.

7.3. Enabling the one time password in the Web UI

The IdM Web UI allows you to configure hardware or software device to generate one-time passwords.

The one time password is entered just after the usual password in the dedicated field in the login dialog.

Only administrators can enable OTP authentication in the user settings.

Prerequisites

  • Administration privileges

Procedure

  1. Log in to the IdM Web UI with your username and password.
  2. Open the Identity → Users → Active users tab.

    web ui users

  3. Click your username to open the user settings.
  4. In the User authentication types, select Two factor authentication (password + OTP).
  5. Click Save.

At this point, the OTP authentication is enabled on the IdM server.

Now you or users themselves need to assign a new token ID to the user account.

7.4. Adding OTP tokens in the Web UI

The following section helps you to add token to the IdM Web UI and to your software token generator.

Prerequisites

  • Active user account on the IdM server.
  • Administrator has enabled OTP for the particular user account in the IdM Web UI.
  • A software device generating OTP tokens, for example FreeOTP.

Procedure

  1. Log in to the IdM Web UI with your user name and password.
  2. To create the token in your mobile phone, open the Authentication → OTP Tokens tab.
  3. Click Add.

    web ui tokens tab

  4. In the Add OTP token dialog box, leave everything unfilled and click Add.

    At this stage, the IdM server creates a token with default parameters at the server and opens a page with a QR code.

  5. Copy the QR code into your mobile phone.
  6. Click OK to close the QR code.

Now you can generate one time passwords and log in with them to the IdM Web UI.

freeotp token

7.5. Logging into the Web UI with a one time password

This procedure describes the first login into the IdM Web UI using a one time password (OTP).

Prerequisites

  • OTP configuration enabled on the Identity Management server for the user account you are using for the OTP authentication. Administrators as well as users themselves can enable OTP.

    To enable the OTP configuration, see Section 7.3, “Enabling the one time password in the Web UI”

  • A hardware or software device generating OTP tokens configured.

Procedure

  1. In the Identity Management login screen, enter your user name or a user name of the IdM server administrator account.
  2. Add the password for the user name entered above.
  3. Generate a one time password on your device.
  4. Enter the one time password right after the password (without space).
  5. Click Log in.

    If the authentication fails, synchronize OTP tokens.

    If your CA uses a self-signed certificate, the browser issues a warning. Check the certificate and accept the security exception to proceed with the login.

    If the the IdM Web UI does not open, verify the DNS configuration of your Identity Management server.

After successful login, the IdM Web UI appears.

web ui users

7.6. Synchronizing OTP tokens using the Web UI

If the login with OTP (One Time Password) fails, OTP tokens are not synchronized correctly.

The following text describes token re-synchronization.

Prerequisites

  • A login screen opened.
  • A device generating OTP tokens configured.

Procedure

  1. On the IdM Web UI login screen, click Sync OTP Token.

    web ui login otp link

  2. In the login screen, enter your username and the Identity Management password.
  3. Generate one time password and enter it in the First OTP field.
  4. Generate another one time password and enter it in the Second OTP field.
  5. Optionally, enter the token ID.

    web ui login otp configuration

  6. Click Sync OTP Token.

After the successful synchronization, you can log in to the IdM server.

7.7. Changing expired passwords

Administrators of Identity Management can enforce you having to change your password at the next login. It means that you cannot successfully log in to the IdM Web UI until you change the password.

Password expiration can happen during your first login to the Web UI.

If the expiration password dialog appears, follow the instructions in the procedure.

Prerequisites

  • A login screen opened.
  • Active account to the IdM server.

Procedure

  1. In the password expiration login screen, enter the user name.
  2. Add the password for the user name entered above.
  3. In the OTP field, generate a one time password, if you use the one time password authentication.

    If you do not have enabled the OTP authentication, leave the field empty.

  4. Enter the new password twice for verification.
  5. Click Reset Password.

    web ui passwd expiration

After the successful password change, the usual login dialog displays. Log in with the new password.

Chapter 8. Managing user accounts using the command line

This chapter includes basic description of user life cycle in IdM (Identity Management). The following sections show you how to:

  • Create user accounts
  • Activate stage user accounts
  • Preserve user accounts
  • Delete active, stage, or preserved user accounts
  • Restore preserved user accounts

8.1. User life cycle

IdM (Identity Management) supports three user account states:

  • Stage users are not allowed to authenticate. This is an initial state. Some of the user account properties required for active users cannot be set, for example, group membership.
  • Active users are allowed to authenticate. All required user account properties must be set in this state.
  • Preserved users are former active users that are considered inactive and cannot authenticate to IdM. Preserved users retain most of the account properties they had as active users, but they are not part of any user groups.

84 RHEL IdM 0420 life cycle

You can delete user entries permanently from the IdM database.

Important

Deleted user accounts cannot be restored. When you delete a user account, all the information associated with the account is permanently lost.

A new administrator can only be created by a user with administrator rights, such as the default admin user. If you accidentally delete all administrator accounts, the Directory Manager must create a new administrator manually in the Directory Server.

Warning

Do not delete the admin user. As admin is a pre-defined user required by IdM, this operation causes problems with certain commands. If you want to define and use an alternative admin user, disable the pre-defined admin user with ipa user-disable admin after you granted admin permissions to at least one different user.

8.2. Adding users using the command line

You can add user as:

  • Active — user accounts which can be actively used by their users.
  • Stage — users cannot use these accounts. Use it if you want to prepare new user accounts. When users are ready to use their accounts, then you can activate them.

The following procedure describes adding active users to the IdM server with the ipa user-add command.

Similarly, you can create stage user accounts with the ipa stageuser-add command.

Note

IdM automatically assigns a unique user ID (UID) to the new user accounts. You can also do this manually, however, the server does not validate whether the UID number is unique. Due to this, multiple user entries might have the same ID number assigned. Red Hat recommends to prevent having multiple entries with the same UID.

Prerequisites

Procedure

  1. Open terminal and connect to the IdM server.
  2. Add user login, user’s first name, last name and optionally, you can also add their email address.

    $ ipa user-add user_login --first=first_name --last=last_name --email=email_address

    IdM supports user names that can be described by the following regular expression:

    [a-zA-Z0-9_.][a-zA-Z0-9_.-]{0,252}[a-zA-Z0-9_.$-]?
    Note

    User names ending with the trailing dollar sign ($) are supported to enable Samba 3.x machine support.

    If you add a user name containing uppercase characters, IdM automatically converts the name to lowercase when saving it. Therefore, IdM always requires to enter user names in lowercase when logging in. Additionally, it is not possible to add user names which differ only in letter casing, such as user and User.

    The default maximum length for user names is 32 characters. To change it, use the ipa config-mod --maxusername command. For example, to increase the maximum user name length to 64 characters:

    $ ipa config-mod --maxusername=64
     Maximum username length: 64
     ...

    The ipa user-add command includes a lot of parameters. To list them all, use the ipa help command:

    $ ipa help user-add

    For details about ipa help command, see What is the IPA help.

You can verify if the new user account is successfully created by listing all IdM user accounts:

$ ipa $ ipa user-find

This command lists all user accounts with details.

8.3. Activating users using the command line

To activate a user account by moving it from stage to active, use the ipa stageuser-activate command.

Prerequisites

Procedure

  1. Open terminal and connect to the IdM server.
  2. Activate the user account with the following command:

    $ ipa stageuser-activate user_login
    -------------------------
    Stage user user_login activated
    -------------------------
    ...

You can verify if the new user account is successfully created by listing all IdM user accounts:

$ ipa $ ipa user-find

This command lists all user accounts with details.

8.4. Preserving users using the command line

To preserve a user account, use the ipa user-del or ipa stageuser-del commands.

Prerequisites

Procedure

  1. Open terminal and connect to the IdM server.
  2. Preserve the user account with the following command:

    $ ipa user-del --preserve user_login
    --------------------
    Deleted user "user_login"
    --------------------

8.5. Deleting users using the command line

IdM (Identity Management) enables you to delete users permanently. You can delete:

  • Active users with the following command: ipa user-del
  • Stage users with the following command: ipa stageuser-del
  • Preserved users with the following command: ipa user-del

When deleting multiple users, use the --continue option to force the command to continue regardless of errors. A summary of the successful and failed operations is printed to the stdout standard output stream when the command completes.

$ ipa user-del --continue user1 user2 user3

If you do not use --continue, the command proceeds with deleting users until it encounters an error, after which it stops and exits.

Prerequisites

Procedure

  1. Open terminal and connect to the IdM server.
  2. Delete the user account with the following command:

    $ ipa user-del user_login
    --------------------
    Deleted user "user_login"
    --------------------

The user account has been permanently deleted from IdM.

8.6. Restoring users using the command line

You can restore a preserved users to:

  • Active users: ipa user-undel
  • Stage users: ipa user-stage

Restoring a user account does not restore all of the account’s previous attributes. For example, the user’s password is not restored and must be set again.

Prerequisites

Procedure

  1. Open terminal and connect to the IdM server.
  2. Activate the user account with the following command:

    $ ipa user-undel user_login
    ------------------------------
    Undeleted user account "user_login"
    ------------------------------

    Alternatively, you can restore user accounts as staged:

    $ ipa user-stage user_login
    ------------------------------
    Staged user account "user_login"
    ------------------------------

You can verify if the new user account is successfully created by listing all IdM user accounts:

$ ipa $ ipa user-find

This command lists all user accounts with details.

Chapter 9. Managing user accounts using the IdM Web UI

Identity Management (IdM) provides several stages that can help you to manage various user work life situations:

Creating a user account

Creating a stage user account before an employee starts their career in your company and be prepared in advance for the day when the employee appears in the office and want to activate the account.

You can omit this step and create the active user account directly. The procedure is similar to creating a stage user account.

Activating a user account
Activating the account the first working day of the employee.
Disabling a user account
If the user go to a parental leave for couple of months, you will need to disable the account temporarily.
Enabling a user account
When the user returns, you will need to re-enable the account.
Preserving a user account
If the user wants to leave the company, you will need to delete the account with a possibility to restore it because people can return to the company after some time.
Restoring a user account
Two years later, the user is back and you need to restore the preserved account.
Deleting a user account
If the employee the employee is dismissed you will delete the account without a backup.

9.1. User life cycle

IdM (Identity Management) supports three user account states:

  • Stage users are not allowed to authenticate. This is an initial state. Some of the user account properties required for active users cannot be set, for example, group membership.
  • Active users are allowed to authenticate. All required user account properties must be set in this state.
  • Preserved users are former active users that are considered inactive and cannot authenticate to IdM. Preserved users retain most of the account properties they had as active users, but they are not part of any user groups.

84 RHEL IdM 0420 life cycle

You can delete user entries permanently from the IdM database.

Important

Deleted user accounts cannot be restored. When you delete a user account, all the information associated with the account is permanently lost.

A new administrator can only be created by a user with administrator rights, such as the default admin user. If you accidentally delete all administrator accounts, the Directory Manager must create a new administrator manually in the Directory Server.

Warning

Do not delete the admin user. As admin is a pre-defined user required by IdM, this operation causes problems with certain commands. If you want to define and use an alternative admin user, disable the pre-defined admin user with ipa user-disable admin after you granted admin permissions to at least one different user.

9.2. Adding users in the Web UI

Usually, you need to create a new user account before a new employee starts to work. Such a stage account is not accessible and you need to activate it later.

Note

Alternatively, you can create an active user account directly. For adding active user, follow the procedure below and add the user account in the Active users tab.

Prerequisites

  • Administrator privileges for managing IdM or User Administrator role.

Procedure

  1. Log in to the IdM Web UI.

    For details, see Accessing the IdM Web UI in a web browser.

  2. Go to Users → Stage Users tab.

    Alternatively, you can add the user account in the Users → Active users, however, you cannot add user groups to the account.

  3. Click the + Add icon.
  4. In the Add stage user dialog box, enter First name and Last name of the new user.
  5. [Optional] In the User login field, add a login name.

    If you leave it empty, the IdM server creates the login name in the following pattern: The first letter of the first name and the surname. The whole login name can have up to 32 characters.

  6. [Optional] In the GID drop down menu, select groups in which the user should be included.
  7. [Optional] In the Password and Verify password fields,
  8. Click on the Add button.

    idm user add stage

At this point, you can see the user account in the Stage Users table.

idm users stage

Note

If you click on the user name, you can edit advanced settings, such as adding a phone number, address, or occupation.

9.3. Activating stage users in the IdM Web UI

A stage user account must be activated before the user can log in to IdM and before the user can be added to an IdM group. This section describes how to activate stage user accounts.

Prerequisites

  • Administrator privileges for managing the IdM Web UI or User Administrator role.
  • At least one staged user account in IdM.

Procedure

  1. Log in to the IdM Web UI.

    For details, see Accessing the IdM Web UI in a web browser.

  2. Go to Users → Stage users tab.
  3. Click the check-box of the user account you want to activate.
  4. Click on the Activate button.

    idm users stage

  5. In the Confirmation dialog box, click on the OK button.

If the activation is successfull, the IdM Web UI displays a green confirmation that the user has been activated and the user account has been moved to Active users. The account is active and the user can authenticate to the IdM domain and IdM Web UI. The user is prompted to change their password on the first login.

idm users stage activated

Note

At this stage, you can add the active user account to user groups.

9.4. Disabling user accounts in the Web UI

You can disable active user accounts. Disabling a user account deactivates the account, therefore, user accounts cannot be used to authenticate and using IdM services, such as Kerberos, or perform any tasks.

Disabled user accounts still exist within IdM and all of the associated information remains unchanged. Unlike preserved user accounts, disabled user accounts remain in the active state and can be a member of user groups.

Note

After disabling a user account, any existing connections remain valid until the user’s Kerberos TGT and other tickets expire. After the ticket expires, the user will not be able to renew it.

Prerequisites

  • Administrator privileges for managing the IdM Web UI or User Administrator role.

Procedure

  1. Log in to the IdM Web UI.

    For details, see Accessing the IdM Web UI in a web browser.

  2. Go to Users → Active users tab.
  3. Click the check-box of the user accounts you want to disable.
  4. Click on the Disable button.

    idm users disable

  5. In the Confirmation dialog box, click on the OK button.

If the disabling procedure has been successful, you can verify in the Status column in the Active users table.

idm users disabled

9.5. Enabling user accounts in the Web UI

With IdM you can enable disabled active user accounts. Enabling a user account activates the disabled account.

Prerequisites

  • Administrator privileges for managing the IdM Web UI or User Administrator role.

Procedure

  1. Log in to the IdM Web UI.
  2. Go to Users → Active users tab.
  3. Click the check-box of the user accounts you want to enable.
  4. Click on the Enable button.

    idm users disable

  5. In the Confirmation dialog box, click on the OK button.

If the change has been successful, you can verify in the Status column in the Active users table.

9.6. Preserving active users in the IdM Web UI

Preserving user accounts enables you to remove accounts from the Active users tab, yet keeping these accounts in IdM.

Preserve the user account if the employee leaves the company. If you want to disable user accounts for a couple of weeks or months (parental leave, for example), disable the account. For details, see Section 9.4, “Disabling user accounts in the Web UI”. The preserved accounts are not active and users cannot use them to access your internal network, however, the account stays in the database with all the data.

You can move the restored accounts back to the active mode.

Note

The list of users in the preserved state can provide a history of past user accounts.

Prerequisites

  • Administrator privileges for managing the IdM (Identity Management) Web UI or User Administrator role.

Procedure

  1. Log in to the IdM Web UI.

    For details, see Accessing the IdM Web UI in a web browser.

  2. Go to Users → Active users tab.
  3. Click the check-box of the user accounts you want to preserve.
  4. Click on the Delete button.

    idm users active delete

  5. In the Remove users dialog box, switch the Delete mode radio button to preserve.
  6. Click on the Delete button.

    idm users preserving

As a result, the user account is moved to Preserved users.

If you need to restore preserved users, see the Restoring users in the IdM Web UI.

9.7. Restoring users in the IdM Web UI

IdM (Identity Management) enables you to restore preserved user accounts back in the active state.

Prerequisites

  • Administrator privileges for managing the IdM Web UI or User Administrator role.

Procedure

  1. Log in to the IdM Web UI.

    For details, see Accessing the IdM Web UI in a web browser.

  2. Go to Users → Preserved users tab.
  3. Click the check-box at the user accounts you want to restore.
  4. Click on the Restore button.

    idm users preserved restore

  5. In the Confirmation dialog box, click on the OK button.

The IdM Web UI displays a green confirmation and moves the user accounts to the Active users tab.

9.8. Deleting users in the IdM Web UI

Deleting users is an irreversible operation, causing the user accounts to be permanently deleted from the IdM database, including group memberships and passwords. Any external configuration for the user, such as the system account and home directory, is not deleted, but is no longer accessible through IdM.

You can delete:

  • Active users — the IdM Web UI offers you with the options:

  • Stage users — you can just delete stage users permanently.
  • Preserved users — you can delete preserved users permanently.

The following procedure describes deleting active users. Similarly, you can delete user accounts on:

  • The Stage users tab
  • The Preserved users tab

Prerequisites

  • Administrator privileges for managing the IdM Web UI or User Administrator role.

Procedure

  1. Log in to the IdM Web UI.

    For details, see Accessing the IdM Web UI in a web browser.

  2. Go to Users → Active users tab.

    Alternatively, you can delete the user account in the Users → Stage users or Users → Preserved users.

  3. Click the Delete icon.
  4. In the Remove users dialog box, switch the Delete mode radio button to delete.
  5. Click on the Delete button.

The users accounts have been permanently deleted from IdM.

Chapter 10. Managing user accounts using Ansible playbooks

You can manage users in IdM using Ansible playbooks. This chapter describes using Ansible playbooks for the following operations:

10.1. Ensuring the presence of an IdM user using an Ansible playbook

The following procedure describes ensuring the presence of a user in IdM using an Ansible playbook.

Prerequisites

  • You know the IdM administator password.
  • The ansible-freeipa package is installed on the Ansible controller.

Procedure

  1. Create an inventory file, for example inventory.file, and define ipaserver in it:

    [ipaserver]
    server.idm.example.com
  2. Create an Ansible playbook file with the data of the user whose presence in IdM you want to ensure. To simplify this step, you can copy and modify the example in the /usr/share/doc/ansible-freeipa/playbooks/user/add-user.yml file. For example, to create user named idm_user and add Password123 as the user password:

    ---
    - name: Playbook to handle users
      hosts: ipaserver
      become: true
    
      tasks:
      - name: Create user idm_user
        ipauser:
          ipaadmin_password: MySecret123
          name: idm_user
          first: Alice
          last: Acme
          uid: 1000111
          gid: 10011
          phone: "+555123457"
          email: idm_user@acme.com
          passwordexpiration: "2023-01-19 23:59:59"
          password: "Password123"
          update_password: on_create

    You must use the following options to add a user:

    • name: the login name
    • first: the first name string
    • last: the last name string

    For the full list of available user options, see the /usr/share/doc/ansible-freeipa/README-user.md Markdown file.

    Note

    If you use the update_password: on_create option, Ansible only creates the user password when it creates the user. If the user is already created with a password, Ansible does not generate a new password.

  3. Run the playbook:

    $ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/add-IdM-user.yml

Verification steps

  • You can verify if the new user account exists in IdM by using the ipa user-show command:

    1. Log into ipaserver as admin:

      $ ssh admin@server.idm.example.com
      Password:
      [admin@server /]$
    2. Request a Kerberos ticket for admin:

      $ kinit admin
      Password for admin@IDM.EXAMPLE.COM:
    3. Request information about idm_user:

      $ ipa user-show idm_user
        User login: idm_user
        First name: Alice
        Last name: Acme
        ....

    The user named idm_user is present in IdM.

10.2. Ensuring the presence of multiple IdM users using Ansible playbooks

The following procedure describes ensuring the presence of multiple users in IdM using an Ansible playbook.

Prerequisites

  • You know the IdM administator password.
  • You have installed the ansible-freeipa package on the Ansible controller.

Procedure

  1. Create an inventory file, for example inventory.file, and define ipaserver in it:

    [ipaserver]
    server.idm.example.com
  2. Create an Ansible playbook file with the data of the users whose presence you want to ensure in IdM. To simplify this step, you can copy and modify the example in the /usr/share/doc/ansible-freeipa/playbooks/user/ensure-users-present.yml file. For example, to create users idm_user_1, idm_user_2, and idm_user_3, and add Password123 as the password of idm_user_1:

    ---
    - name: Playbook to handle users
      hosts: ipaserver
      become: true
    
      tasks:
      - name: Create user idm_users
        ipauser:
          ipaadmin_password: MySecret123
          users:
          - name: idm_user_1
            first: Alice
            last: Acme
            uid: 10001
            gid: 10011
            phone: "+555123457"
            email: idm_user@acme.com
            passwordexpiration: "2023-01-19 23:59:59"
            password: "Password123"
          - name: idm_user_2
            first: Bob
            last: Acme
            uid: 100011
            gid: 10011
          - name: idm_user_3
            first: Eve
            last: Acme
            uid: 1000111
            gid: 10011
    Note

    If you do not specify the update_password: on_create option, Ansible re-sets the user password every time the playbook is run: if the user has changed the password since the last time the playbook was run, Ansible re-sets password.

  3. Run the playbook:

    $ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/add-users.yml

Verification steps

  • You can verify if the user account exists in IdM by using the ipa user-show command:

    1. Log into ipaserver as administrator:

      $ ssh administrator@server.idm.example.com
      Password:
      [admin@server /]$
    2. Display information about idm_user_1:

      $ ipa user-show idm_user_1
        User login: idm_user_1
        First name: Alice
        Last name: Acme
        Password: True
        ....

    The user named idm_user_1 is present in IdM.

10.3. Ensuring the presence of multiple IdM users from a JSON file using Ansible playbooks

The following procedure describes how you can ensure the presence of multiple users in IdM using an Ansible playbook. The users are stored in a JSON file.

Prerequisites

  • You know the IdM administator password.
  • You have installed the ansible-freeipa package on the Ansible controller.

Procedure

  1. Create an inventory file, for example inventory.file, and define ipaserver in it:

    [ipaserver]
    server.idm.example.com
  2. Create an Ansible playbook file with the necessary tasks. Reference the JSON file with the data of the users whose presence you want to ensure. To simplify this step, you can copy and modify the example in the /usr/share/doc/ansible-freeipa/ensure-users-present-ymlfile.yml file:

    ---
    - name: Ensure users' presence
      hosts: ipaserver
      become: true
    
      tasks:
      - name: Include users.json
        include_vars:
          file: users.json
    
      - name: Users present
        ipauser:
          ipaadmin_password: Secret123
          users: "{{ users }}"
  3. Create the users.json file, and add the IdM users into it. To simplify this step, you can copy and modify the example in the /usr/share/doc/ansible-freeipa/playbooks/user/users.json file. For example, to create users idm_user_1, idm_user_2, and idm_user_3, and add Password123 as the password of idm_user_1:

    {
      "users": [
       {
        "name": "idm_user_1",
        "first": "Alice",
        "last": "Acme",
        "password": "Password123"
       },
       {
        "name": "idm_user_2",
        "first": "Bob",
        "last": "Acme"
       },
       {
        "name": "idm_user_3",
        "first": "Eve",
        "last": "Acme"
       }
      ]
    }
  4. Run the Ansible playbook specifying the playbook file and the inventory file:

    $ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-users-present-jsonfile.yml

Verification steps

  • You can verify if the user accounts are present in IdM using the ipa user-show command:

    1. Log into ipaserver as administrator:

      $ ssh administrator@server.idm.example.com
      Password:
      [admin@server /]$
    2. Display information about idm_user_1:

      $ ipa user-show idm_user_1
        User login: idm_user_1
        First name: Alice
        Last name: Acme
        Password: True
        ....

    The user named idm_user_1 is present in IdM.

10.4. Ensuring the absence of users using Ansible playbooks

The following procedure describes how you can use an Ansible playbook to ensure that specific users are absent from IdM.

Prerequisites

  • You know the IdM administator password.
  • You have installed the ansible-freeipa package on the Ansible controller.

Procedure

  1. Create an inventory file, for example inventory.file, and define ipaserver in it:

    [ipaserver]
    server.idm.example.com
  2. Create an Ansible playbook file with the users whose absence from IdM you want to ensure. To simplify this step, you can copy and modify the example in the /usr/share/doc/ansible-freeipa/playbooks/user/ensure-users-present.yml file. For example, to delete users idm_user_1, idm_user_2, and idm_user_3:

    ---
    - name: Playbook to handle users
      hosts: ipaserver
      become: true
      gather_facts: false
    
      tasks:
      - name: Delete users idm_user_1, idm_user_2, idm_user_3
        ipauser:
          ipaadmin_password: MySecret123
          users:
          - name: idm_user_1
          - name: idm_user_2
          - name: idm_user_3
          state: absent
  3. Run the Ansible playbook specifying the playbook file and the inventory file:

    $ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/delete-users.yml

Verification steps

You can verify that the user accounts do not exist in IdM by using the ipa user-show command:

  1. Log into ipaserver as administrator:

    $ ssh administrator@server.idm.example.com
    Password:
    [admin@server /]$
  2. Request information about idm_user_1:

    $ ipa user-show idm_user_1
    ipa: ERROR: idm_user_1: user not found

    The user named idm_user_1 does not exist in IdM.

Additional resources

  • You can see sample Ansible playbooks for other IdM user-related actions such as preserving, deleting, enabling, disabling, unlocking and undeleting users in the README-user.md Markdown file available in the /usr/share/doc/ansible-freeipa/ directory. The file also contains the definitions of ipauser variables.
  • You can also see sample Ansible playbooks in the /usr/share/doc/ansible-freeipa/playbooks/user directory.

Chapter 11. Managing user groups in IdM CLI

This chapter introduces user groups management using the IdM CLI.

A user group is a set of users with common privileges, password policies, and other characteristics.

A user group in Identity Management (IdM) can include:

  • IdM users
  • other IdM user groups
  • external users, which are users that exist outside of IdM

11.1. The different group types in IdM

IdM supports the following types of groups:

POSIX groups (the default)

POSIX groups support Linux POSIX attributes for their members. Note that groups that interact with Active Directory cannot use POSIX attributes.

POSIX attributes identify users as separate entities. Examples of POSIX attributes relevant to users include uidNumber, a user number (UID), and gidNumber, a group number (GID).

Non-POSIX groups

Non-POSIX groups do not support POSIX attributes. For example, these groups do not have a GID defined.

All members of this type of group must belong to the IdM domain.

External groups

Use external groups to add group members that exist in an identity store outside of the IdM domain, such as:

  • A local system
  • An Active Directory domain
  • A directory service

External groups do not support POSIX attributes. For example, these groups do not have a GID defined.

Table 11.1. User groups created by default

Group nameDefault group members

ipausers

All IdM users

admins

Users with administrative privileges, including the default admin user

editors

This is a legacy group that no longer has any special privileges

trust admins

Users with privileges to manage the Active Directory trusts

When you add a user to a user group, the user gains the privileges and policies associated with the group. For example, to grant administrative privileges to a user, add the user to the admins group.

Warning

Do not delete the admins group. As admins is a pre-defined group required by IdM, this operation causes problems with certain commands.

In addition, IdM creates user private groups by default whenever a new user is created in IdM. For more information about private groups, see Adding users without a private group.

11.2. Direct and indirect group members

User group attributes in IdM apply to both direct and indirect members: when group B is a member of group A, all users in group B are considered indirect members of group A.

For example, in the following diagram:

  • User 1 and User 2 are direct members of group A.
  • User 3, User 4, and User 5 are indirect members of group A.

Figure 11.1. Direct and Indirect Group Membership

84 RHEL IdM 0420 user group

If you set a password policy for user group A, the policy also applies to all users in user group B.

11.3. Adding a user group using IdM CLI

This section describes how to add a user group using IdM CLI.

Prerequisites

Procedure

  • Add a user group by using the ipa group-add group_name command. For example, to create group_a:

    $ ipa group-add group_a
    ---------------------
    Added group "group_a"
    ---------------------
      Group name: group_a
      GID: 1133400009

    By default, ipa group-add adds a POSIX user group. To specify a different group type, add options to ipa group-add:

    You can specify a custom GID when adding a user group by using the --gid=custom_GID option. If you do this, be careful to avoid ID conflicts. If you do not specify a custom GID, IdM automatically assigns a GID from the available ID range.

11.4. Searching for user groups using IdM CLI

This section describes how to search for existing user groups using IdM CLI.

Procedure

  • Display all user groups by using the ipa group-find command. To specify a group type, add options to ipa group-find:

    • Display all POSIX groups using the ipa group-find --posix command.
    • Display all non-POSIX groups using the ipa group-find --nonposix command.
    • Display all external groups using the ipa group-find --external command.

      For more information on different group types, see The different group types in IdM.

11.5. Deleting a user group using IdM CLI

This section describes how to delete a user group using IdM CLI. Note that deleting a group does not delete the group members from IdM.

Prerequisites

Procedure

  • Delete a user group by using the ipa group-del group_name command. For example, to delete group_a:

    $ ipa group-del group_a
    --------------------------
    Deleted group "group_a"
    --------------------------

11.6. Adding a member to a user group using IdM CLI

This section describes how to add a member to a user group using IdM CLI. You can add both users and user groups as members of a user group. For more information, see The different group types in IdM and Direct and indirect group members.

Prerequisites

Procedure

  • Add a member to a user group by using the ipa group-add-member command.

    Specify the type of member using these options:

    • --users adds an IdM user
    • --external adds a user that exists outside the IdM domain, in the format of DOMAIN\user_name or user_name@domain
    • --groups adds an IdM user group

    For example, to add group_b as a member of group_a:

    $ ipa group-add-member group_a --groups=group_b
    Group name: group_a
    GID: 1133400009
    Member users: user_a
    Member groups: group_b
    Indirect Member users: user_b
    -------------------------
    Number of members added 1
    -------------------------

    Members of group_b are now indirect members of group_a.

Important

When adding a group as a member of another group, do not create recursive groups. For example, if Group A is a member of Group B, do not add Group B as a member of Group A. Recursive groups can cause unpredictable behavior.

Note

After you add a member to a user group, the update may take some time to spread to all clients in your Identity Management environment. This is because when any given host resolves users, groups and netgroups, the System Security Services Daemon (SSSD) first looks into its cache and performs server lookups only for missing or expired records.

11.7. Adding users without a user private group

By default, IdM creates user private groups (UPGs) whenever a new user is created in IdM. UPGs are a specific group type:

  • The UPG has the same name as the newly created user.
  • The user is the only member of the UPG. The UPG cannot contain any other members.
  • The GID of the private group matches the UID of the user.

However, it is possible to add users without creating a UPG.

11.7.1. Users without a user private group

If a NIS group or another system group already uses the GID that would be assigned to a user private group, it is necessary to avoid creating a UPG.

You can do this in two ways:

In both cases, IdM will require specifying a GID when adding new users, otherwise the operation will fail. This is because IdM requires a GID for the new user, but the default user group ipausers is a non-POSIX group and therefore does not have an associated GID. The GID you specify does not have to correspond to an already existing group.

Note

Specifying the GID does not create a new group. It only sets the GID attribute for the new user, because the attribute is required by IdM.

11.7.2. Adding a user without a user private group when private groups are globally enabled

You can add a user without creating a user private group (UPG) even when UPGs are enabled on the system. This requires manually setting a GID for the new user. For details on why this is needed, see Section 11.7.1, “Users without a user private group”.

Procedure

  • To prevent IdM from creating a UPG, add the --noprivate option to the ipa user-add command.

    Note that for the command to succeed, you must specify a custom GID. For example, to add a new user with GID 10000:

    $ ipa user-add jsmith --first=John --last=Smith --noprivate --gid 10000

11.7.3. Disabling user private groups globally for all users

You can disable user private groups (UPGs) globally. This prevents the creation of UPGs for all new users. Existing users are unaffected by this change.

Procedure

  1. Obtain administrator privileges:

    $ kinit admin
  2. IdM uses the Directory Server Managed Entries Plug-in to manage UPGs. List the instances of the plug-in:

    $ ipa-managed-entries --list
  3. To ensure IdM does not create UPGs, disable the plug-in instance responsible for managing user private groups:

    $ ipa-managed-entries -e "UPG Definition" disable
    Disabling Plugin
    Note

    To re-enable the UPG Definition instance later, use the ipa-managed-entries -e "UPG Definition" enable command.

  4. Restart Directory Server to load the new configuration.

    $ sudo systemctl restart dirsrv.target

    To add a user after UPGs have been disabled, you need to specify a GID. For more information, see Adding a user when user private groups are globally disabled

Verification steps

  • To check if UPGs are globally disabled, use the disable command again:

    $ ipa-managed-entries -e "UPG Definition" disable
    Plugin already disabled

11.7.4. Adding a user when user private groups are globally disabled

When user private groups (UPGs) are disabled globally, IdM does not assign a GID to a new user automatically. To successfully add a user, you must assign a GID manually or by using an automember rule. For details on why this is required, see Section 11.7.1, “Users without a user private group”.

Prerequisities

Procedure

  • To make sure adding a new user succeeds when creating UPGs is disabled, choose one of the following:

    • Specify a custom GID when adding a new user. The GID does not have to correspond to an already existing user group.

      For example, when adding a user from the command line, add the --gid option to the ipa user-add command.

    • Use an automember rule to add the user to an existing group with a GID.

11.8. Viewing group members using IdM CLI

This section describes how to view members of a group using IdM CLI. You can view both direct and indirect group members. For more information, see Direct and indirect group members.

Procedure:

  • To list members of a group, use the ipa group-show group_name command. For example:

    $ ipa group-show group_a
      ...
      Member users: user_a
      Member groups: group_b
      Indirect Member users: user_b
    Note

    The list of indirect members does not include external users from trusted Active Directory domains. The Active Directory trust user objects are not visible in the Identity Management interface because they do not exist as LDAP objects within Identity Management.

11.9. Removing a member from a user group using IdM CLI

This section describes how to remove a member from a user group using IdM CLI.

Prerequisites

Procedure

  1. Optional. Use the ipa group-show command to confirm that the group includes the member you want to remove.
  2. Remove a member from a user group by using the ipa group-remove-member command.

    Specify members to remove using these options:

    • --users removes an IdM user
    • --external removes a user that exists outside the IdM domain, in the format of DOMAIN\user_name or user_name@domain
    • --groups removes an IdM user group

    For example, to remove user1, user2, and group1 from a group called group_name:

    $ ipa group-remove-member group_name --users=user1 --users=user2 --groups=group1

Chapter 12. Managing user groups in IdM Web UI

This chapter introduces user groups management using the IdM web UI.

A user group is a set of users with common privileges, password policies, and other characteristics.

A user group in Identity Management (IdM) can include:

  • IdM users
  • other IdM user groups
  • external users, which are users that exist outside of IdM

12.1. The different group types in IdM

IdM supports the following types of groups:

POSIX groups (the default)

POSIX groups support Linux POSIX attributes for their members. Note that groups that interact with Active Directory cannot use POSIX attributes.

POSIX attributes identify users as separate entities. Examples of POSIX attributes relevant to users include uidNumber, a user number (UID), and gidNumber, a group number (GID).

Non-POSIX groups

Non-POSIX groups do not support POSIX attributes. For example, these groups do not have a GID defined.

All members of this type of group must belong to the IdM domain.

External groups

Use external groups to add group members that exist in an identity store outside of the IdM domain, such as:

  • A local system
  • An Active Directory domain
  • A directory service

External groups do not support POSIX attributes. For example, these groups do not have a GID defined.

Table 12.1. User groups created by default

Group nameDefault group members

ipausers

All IdM users

admins

Users with administrative privileges, including the default admin user

editors

This is a legacy group that no longer has any special privileges

trust admins

Users with privileges to manage the Active Directory trusts

When you add a user to a user group, the user gains the privileges and policies associated with the group. For example, to grant administrative privileges to a user, add the user to the admins group.

Warning

Do not delete the admins group. As admins is a pre-defined group required by IdM, this operation causes problems with certain commands.

In addition, IdM creates user private groups by default whenever a new user is created in IdM. For more information about private groups, see Adding users without a private group.

12.2. Direct and indirect group members

User group attributes in IdM apply to both direct and indirect members: when group B is a member of group A, all users in group B are considered indirect members of group A.

For example, in the following diagram:

  • User 1 and User 2 are direct members of group A.
  • User 3, User 4, and User 5 are indirect members of group A.

Figure 12.1. Direct and Indirect Group Membership

84 RHEL IdM 0420 user group

If you set a password policy for user group A, the policy also applies to all users in user group B.

12.3. Adding a user group using IdM Web UI

This section describes how to add a user group using the IdM Web UI.

Prerequisites

  • You are logged in to the IdM Web UI.

Procedure

  1. Click Identity → Groups, and select User Groups in the left sidebar.
  2. Click Add to start adding the group.
  3. Fill out the information about the group. For more information about user group types, see The different group types in IdM.

    You can specify a custom GID for the group. If you do this, be careful to avoid ID conflicts. If you do not specify a custom GID, IdM automatically assigns a GID from the available ID range.

    user group add dialog
  4. Click Add to confirm.

12.4. Deleting a user group using IdM Web UI

This section describes how to delete a user group using the IdM Web UI. Note that deleting a group does not delete the group members from IdM.

Prerequisites

  • You are logged in to the IdM Web UI.

Procedure

  1. Click Identity → Groups and select User Groups.
  2. Select the group to delete.
  3. Click Delete.
  4. Click Delete to confirm.

12.5. Adding a member to a user group using IdM Web UI

You can add both users and user groups as members of a user group. For more information, see The different group types in IdM and Direct and indirect group members.

Prerequisites

  • You are logged in to the IdM Web UI.

Procedure

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

    groups add member updated
  4. Click Add.
  5. Select the check box next to one or more members you want to add.
  6. Click the rightward arrow to move the selected members to the group.

    groups add member dialog
  7. Click Add to confirm.

12.6. Viewing group members using IdM Web UI

This section describes how to view members of a group using the IdM Web UI. You can view both direct and indirect group members. For more information, see Direct and indirect group members.

Prerequisites

  • You are logged in to the IdM Web UI.

Procedure

  1. Select Identity → Groups.
  2. Select User Groups in the left sidebar.
  3. Click the name of the group you want to view.
  4. Switch between Direct Membership and Indirect Membership.

    groups menu clean

12.7. Removing a member from a user group using IdM Web UI

This section describes how to remove a member from a user group using the IdM Web UI.

Prerequisites

  • You are logged in to the IdM Web UI.

Procedure

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

    groups add member updated
  4. Select the check box next to the member you want to remove.
  5. Click Delete.
  6. Click Delete to confirm.

Chapter 13. Ensuring the presence of IdM groups and group members using Ansible playbooks

The following procedure describes ensuring the presence of IdM groups and group members - both users and user groups - using an Ansible playbook.

Prerequisites

Procedure

  1. Create an inventory file, for example inventory.file, and define ipaserver in it:

    [ipaserver]
    server.idm.example.com
  2. Create an Ansible playbook file with the necessary user and group information. To simplify this step, you can copy and modify the examples in the /usr/share/doc/ansible-freeipa/playbooks/user/ directory. For example, to ensure the presence of groups named ops, sysops and appops, the presence of a user named idm_user in sysops, and the presence of the sysops and appops groups in ops, you can combine the add-group.yml and add-groups-to-group.yml playbooks into a new playbook:

    ---
    - name: Playbook to handle groups
      hosts: ipaserver
      become: true
    
      tasks:
      - name: Create group ops with gid 1234
        ipagroup:
          ipaadmin_password: Secret123
          name: ops
          gidnumber: 1234
    
      - name: Create group sysops
        ipagroup:
          ipaadmin_password: Secret123
          name: sysops
          user:
          - idm_user
    
      - name: Create group appops
        ipagroup:
          ipaadmin_password: Secret123
          name: appops
    
      - name: Add group members sysops and appops to group ops
        ipagroup:
          ipaadmin_password: Secret123
          name: ops
          group:
          - sysops
          - appops
  3. Run the playbook:

    $ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/add-group-members.yml

Verification steps

You can verify if the ops group contains sysops and appops as direct members and idm_user as an indirect member by using the ipa group-show command:

  1. Log into ipaserver as administrator:

    $ ssh admin@server.idm.example.com
    Password:
    [admin@server /]$
  2. Display information about ops:

    ipaserver]$ ipa group-show ops
      Group name: ops
      GID: 1234
      Member groups: sysops, appops
      Indirect Member users: idm_user

    The appops and sysops groups - the latter including the idm_user user - exist in IdM.

Additional resources

  • For more information about ensuring the presence of user groups using Ansible, see the /usr/share/doc/ansible-freeipa/README-group.md Markdown file.

Chapter 14. Automating group membership using IdM CLI

Using automatic group membership allows you to assign users and hosts to groups automatically based on their attributes. For example, you can:

  • Divide employees' user entries into groups based on the employees' manager, location, or any other attribute.
  • Divide hosts based on their class, location, or any other attribute.
  • Add all users or all hosts to a single global group.

This chapter covers the following topics:

14.1. Benefits of automatic group membership

Using automatic membership for users allows you to:

  • Reduce the overhead of manually managing group memberships

    You no longer have to assign every user and host to groups manually.

  • Improve consistency in user and host management

    Users and hosts are assigned to groups based on strictly defined and automatically evaluated criteria.

  • Simplify the management of group-based settings

    Various settings are defined for groups and then applied to individual group members, for example sudo rules, automount, or access control. Adding users and hosts to groups automatically makes managing these settings easier.

14.2. Automember rules

When configuring automatic group membership, the administrator defines automember rules. An automember rule applies to a specific user or host target group. It cannot apply to more than one group at a time.

After creating a rule, the administrator adds conditions to it. These specify which users or hosts get included or excluded from the target group:

  • Inclusive conditions

    When a user or host entry meets an inclusive condition, it will be included in the target group.

  • Exclusive conditions

    When a user or host entry meets an exclusive condition, it will not be included in the target group.

The conditions are specified as regular expressions in the Perl-compatible regular expressions (PCRE) format. For more information on PCRE, see the pcresyntax(3) man page.

Note

IdM evaluates exclusive conditions before inclusive conditions. In case of a conflict, exclusive conditions take precedence over inclusive conditions.

An automember rule applies to every entry created in the future. These entries will be automatically added to the specified target group. If an entry meets the conditions specified in multiple automember rules, it will be added to all the corresponding groups.

Existing entries are not affected by the new rule. If you want to change existing entries, see Applying automember rules to existing entries using IdM CLI.

14.3. Adding an automember rule using IdM CLI

This section describes adding an automember rule using the IdM CLI. For information about automember rules, see Automember rules.

After adding an automember rule, you can add conditions to it using the procedure described in Adding a condition to an automember rule.

Note

Existing entries are not affected by the new rule. If you want to change existing entries, see Applying automember rules to existing entries using IdM CLI.

Prerequisites

Procedure

  1. Enter the ipa automember-add command to add an automember rule.
  2. When prompted, specify:

    • Automember rule. This is the target group name.
    • Grouping Type. This specifies whether the rule targets a user group or a host group. To target a user group, enter group. To target a host group, enter hostgroup.

    For example, to add an automember rule for a user group named user_group:

    $ ipa automember-add
    Automember Rule: user_group
    Grouping Type: group
    --------------------------------
    Added automember rule "user_group"
    --------------------------------
        Automember Rule: user_group

Verification steps

14.4. Adding a condition to an automember rule using IdM CLI

This section describes how to add a condition to an automember rule using the IdM CLI. For information about automember rules, see Automember rules.

Prerequisites

Procedure

  1. Define one or more inclusive or exclusive conditions using the ipa automember-add-condition command.
  2. When prompted, specify:

    • Automember rule. This is the target rule name. See Automember rules for details.
    • Attribute Key. This specifies the entry attribute to which the filter will apply. For example, uid for users.
    • Grouping Type. This specifies whether the rule targets a user group or a host group. To target a user group, enter group. To target a host group, enter hostgroup.
    • Inclusive regex and Exclusive regex. These specify one or more conditions as regular expressions. If you only want to specify one condition, press Enter when prompted for the other.

    For example, the following condition targets all users with any value (.*) in their user login attribute (uid).

    $ ipa automember-add-condition
    Automember Rule: user_group
    Attribute Key: uid
    Grouping Type: group
    [Inclusive Regex]: .*
    [Exclusive Regex]:
    ----------------------------------
    Added condition(s) to "user_group"
    ----------------------------------
      Automember Rule: user_group
      Inclusive Regex: uid=.*
    ----------------------------
    Number of conditions added 1
    ----------------------------

    As another example, you can use an automembership rule to target all Windows users synchronized from Active Directory (AD). To achieve this, create a condition that that targets all users with ntUser in their objectClass attribute, which is shared by all AD users:

    $ ipa automember-add-condition
    Automember Rule: ad_users
    Attribute Key: objectclass
    Grouping Type: group
    [Inclusive Regex]: ntUser
    [Exclusive Regex]:
    -------------------------------------
    Added condition(s) to "ad_users"
    -------------------------------------
      Automember Rule: ad_users
      Inclusive Regex: objectclass=ntUser
    ----------------------------
    Number of conditions added 1
    ----------------------------

Verification steps

14.5. Viewing existing automember rules using IdM CLI

This section describes how to view existing automember rules using the IdM CLI.

Prerequisites

Procedure

  1. Enter the ipa automember-find command.
  2. When prompted, specify the Grouping type:

    • To target a user group, enter group.
    • To target a host group, enter hostgroup.

      For example:

    $ ipa automember-find
    Grouping Type: group
    ---------------
    1 rules matched
    ---------------
      Automember Rule: user_group
      Inclusive Regex: uid=.*
    ----------------------------
    Number of entries returned 1
    ----------------------------

14.6. Deleting an automember rule using IdM CLI

This section describes how to delete an automember rule using the IdM CLI.

Deleting an automember rule also deletes all conditions associated with the rule. To remove only specific conditions from a rule, see Removing a condition from an automember rule using IdM CLI.

Prerequisites

Procedure

  1. Enter the ipa automember-del command.
  2. When prompted, specify:

    • Automember rule. This is the rule you want to delete.
    • Grouping rule. This specifies whether the rule you want to delete is for a user group or a host group. Enter group or hostgroup.

14.7. Removing a condition from an automember rule using IdM CLI

This section describes how to remove a specific condition from an automember rule.

Prerequisites

Procedure

  1. Enter the ipa automember-remove-condition command.
  2. When prompted, specify:

    • Automember rule. This is the name of the rule from which you want to remove a condition.
    • Attribute Key. This is the target entry attribute. For example, uid for users.
    • Grouping Type. This specifies whether the condition you want to delete is for a user group or a host group. Enter group or hostgroup.
    • Inclusive regex and Exclusive regex. These specify the conditions you want to remove. If you only want to specify one condition, press Enter when prompted for the other.

      For example:

    $ ipa automember-remove-condition
    Automember Rule: user_group
    Attribute Key: uid
    Grouping Type: group
    [Inclusive Regex]: .*
    [Exclusive Regex]:
    -----------------------------------
    Removed condition(s) from "user_group"
    -----------------------------------
      Automember Rule: user_group
    ------------------------------
    Number of conditions removed 1
    ------------------------------

14.8. Applying automember rules to existing entries using IdM CLI

Automember rules apply automatically to user and host entries created after the rules were added. They are not applied retroactively to entries that existed before the rules were added.

To apply automember rules to previously added entries, you have to manually rebuild automatic membership. Rebuilding automatic membership re-evaluates all existing automember rules and applies them either to all user or hosts entries, or to specific entries.

Note

Rebuilding automatic membership does not remove user or host entries from groups, even if the entries no longer match the group’s inclusive conditions. To remove them manually, see Removing a member from a user group using IdM CLI or Removing IdM host group members using the CLI.

Prerequisites

Procedure

  • To rebuild automatic membership, enter the ipa automember-rebuild command. Use the following options to specify the entries to target:

    • To rebuild automatic membership for all users, use the --type=group option:

      $ ipa automember-rebuild --type=group
      --------------------------------------------------------
      Automember rebuild task finished. Processed (9) entries.
      --------------------------------------------------------
    • To rebuild automatic membership for all hosts, use the --type=hostgroup option.
    • To rebuild automatic membership for a specified user or users, use the --users=target_user option:

      $ ipa automember-rebuild --users=target_user1 --users=target_user2
      --------------------------------------------------------
      Automember rebuild task finished. Processed (2) entries.
      --------------------------------------------------------
    • To rebuild automatic membership for a specified host or hosts, use the --hosts=client.idm.example.com option.

14.9. Configuring a default automember group using IdM CLI

When you configure a default automember group, new user or host entries that do not match any automember rule are automatically added to this default group.

Prerequisites

Procedure

  1. Enter the ipa automember-default-group-set command to configure a default automember group.
  2. When prompted, specify:

    • Default (fallback) Group, which specifies the target group name.
    • Grouping Type, which specifies whether the target is a user group or a host group. To target a user group, enter group. To target a host group, enter hostgroup.

      For example:

      $ ipa automember-default-group-set
      Default (fallback) Group: default_user_group
      Grouping Type: group
      ---------------------------------------------------
      Set default (fallback) group for automember "default_user_group"
      ---------------------------------------------------
        Default (fallback) Group: cn=default_user_group,cn=groups,cn=accounts,dc=example,dc=com
    Note

    To remove the current default automember group, enter the ipa automember-default-group-remove command.

Verification steps

  • To verify that the group is set correctly, enter the ipa automember-default-group-show command. The command displays the current default automember group. For example:

    $ ipa automember-default-group-show
    Grouping Type: group
      Default (fallback) Group: cn=default_user_group,cn=groups,cn=accounts,dc=example,dc=com

Chapter 15. Automating group membership using IdM Web UI

Using automatic group membership enables you to assign users and hosts to groups automatically based on their attributes. For example, you can:

  • Divide employees' user entries into groups based on the employees' manager, location, or any other attribute.
  • Divide hosts based on their class, location, or any other attribute.
  • Add all users or all hosts to a single global group.

This chapter covers the following topics:

15.1. Benefits of automatic group membership

Using automatic membership for users allows you to:

  • Reduce the overhead of manually managing group memberships

    You no longer have to assign every user and host to groups manually.

  • Improve consistency in user and host management

    Users and hosts are assigned to groups based on strictly defined and automatically evaluated criteria.

  • Simplify the management of group-based settings

    Various settings are defined for groups and then applied to individual group members, for example sudo rules, automount, or access control. Adding users and hosts to groups automatically makes managing these settings easier.

15.2. Automember rules

When configuring automatic group membership, the administrator defines automember rules. An automember rule applies to a specific user or host target group. It cannot apply to more than one group at a time.

After creating a rule, the administrator adds conditions to it. These specify which users or hosts get included or excluded from the target group:

  • Inclusive conditions

    When a user or host entry meets an inclusive condition, it will be included in the target group.

  • Exclusive conditions

    When a user or host entry meets an exclusive condition, it will not be included in the target group.

The conditions are specified as regular expressions in the Perl-compatible regular expressions (PCRE) format. For more information on PCRE, see the pcresyntax(3) man page.

Note

IdM evaluates exclusive conditions before inclusive conditions. In case of a conflict, exclusive conditions take precedence over inclusive conditions.

An automember rule applies to every entry created in the future. These entries will be automatically added to the specified target group. If an entry meets the conditions specified in multiple automember rules, it will be added to all the corresponding groups.

Existing entries are not affected by the new rule. If you want to change existing entries, see Applying automember rules to existing entries using IdM Web UI.

15.3. Adding an automember rule using IdM Web UI

This section describes adding an automember rule using the IdM Web UI. For information about automember rules, see Automember rules.

Note

Existing entries are not affected by the new rule. If you want to change existing entries, see Applying automember rules to existing entries using IdM Web UI.

Prerequisites

  • You are logged in to the IdM Web UI.
  • You must be a member of the admins group.
  • The target group of the new rule exists in IdM.

Procedure

  1. Click Identity → Automember, and select either User group rules or Host group rules.
  2. Click Add.
  3. In the Automember rule field, select the group to which the rule will apply. This is the target group name.

    automember rule add
  4. Click Add to confirm.
  5. Optional: You can add conditions to the new rule using the procedure described in Adding a condition to an automember rule using IdM Web UI.

15.4. Adding a condition to an automember rule using IdM Web UI

This section describes how to add a condition to an automember rule using the IdM Web UI. For information about automember rules, see Automember rules.

Prerequisites

  • You are logged in to the IdM Web UI.
  • You must be a member of the admins group.
  • The target rule exists in IdM.

Procedure

  1. Click Identity → Automember, and select either User group rules or Host group rules.
  2. Click on the rule to which you want to add a condition.
  3. In the Inclusive or Exclusive sections, click Add.

    automember condition add
  4. In the Attribute field, select the required attribute, for example uid.
  5. In the Expression field, define a regular expression.
  6. Click Add.

    For example, the following condition targets all users with any value (.*) in their user ID (uid) attribute.

    automember add

15.5. Viewing existing automember rules and conditions using IdM Web UI

This section describes how to view existing automember rules and conditions using the IdM Web UI.

Prerequisites

  • You are logged in to the IdM Web UI.
  • You must be a member of the admins group.

Procedure

  1. Click Identity → Automember, and select either User group rules or Host group rules to view the respective automember rules.
  2. Optional: Click on a rule to see the conditions for that rule in the Inclusive or Exclusive sections.

    automember conditions

15.6. Deleting an automember rule using IdM Web UI

This section describes how to delete an automember rule using the IdM Web UI.

Deleting an automember rule also deletes all conditions associated with the rule. To remove only specific conditions from a rule, see Removing a condition from an automember rule using IdM Web UI.

Prerequisites

  • You are logged in to the IdM Web UI.
  • You must be a member of the admins group.

Procedure

  1. Click Identity → Automember, and select either User group rules or Host group rules to view the respective automember rules.
  2. Select the check box next to the rule you want to remove.
  3. Click Delete.

    automember rule delete
  4. Click Delete to confirm.

15.7. Removing a condition from an automember rule using IdM Web UI

This section describes how to remove a specific condition from an automember rule using the IdM Web UI.

Prerequisites

  • You are logged in to the IdM Web UI.
  • You must be a member of the admins group.

Procedure

  1. Click Identity → Automember, and select either User group rules or Host group rules to view the respective automember rules.
  2. Click on a rule to see the conditions for that rule in the Inclusive or Exclusive sections.
  3. Select the check box next to the conditions you want to remove.
  4. Click Delete.

    automember condition remove
  5. Click Delete to confirm.

15.8. Applying automember rules to existing entries using IdM Web UI

Automember rules apply automatically to user and host entries created after the rules were added. They are not applied retroactively to entries that existed before the rules were added.

To apply automember rules to previously added entries, you have to manually rebuild automatic membership. Rebuilding automatic membership re-evaluates all existing automember rules and applies them either to all user or hosts entries, or to specific entries.

Note

Rebuilding automatic membership does not remove user or host entries from groups, even if the entries no longer match the group’s inclusive conditions. To remove them manually, see Removing a member from a user group using IdM Web UI or Removing host group members in the IdM Web UI.

15.8.1. Rebuilding automatic membership for all users or hosts

This section describes how to rebuild automatic membership for all user or host entries.

Prerequisites

  • You are logged in to the IdM Web UI.
  • You must be a member of the admins group.

Procedure

  1. Select IdentityUsers or Hosts.
  2. Click ActionsRebuild auto membership.

    automember rebuild

15.8.2. Rebuilding automatic membership for a single user or host only

This section describes how to rebuild automatic membership for a specific user or host entry.

Prerequisites

  • You are logged in to the IdM Web UI.
  • You must be a member of the admins group.

Procedure

  1. Select IdentityUsers or Hosts.
  2. Click on the required user or host name.
  3. Click ActionsRebuild auto membership.

    automember rebuild single

15.9. Configuring a default user group using IdM Web UI

When you configure a default user group, new user entries that do not match any automember rule are automatically added to this default group.

Prerequisites

  • You are logged in to the IdM Web UI.
  • You must be a member of the admins group.
  • The target user group you want to set as default exists in IdM.

Procedure

  1. Click Identity → Automember, and select User group rules.
  2. In the Default user group field, select the group you want to set as the default user group.

    Setting a default user group

15.10. Configuring a default host group using IdM Web UI

When you configure a default host group, new host entries that do not match any automember rule are automatically added to this default group.

Prerequisites

  • You are logged in to the IdM Web UI.
  • You must be a member of the admins group.
  • The target host group you want to set as default exists in IdM.

Procedure

  1. Click Identity → Automember, and select Host group rules.
  2. In the Default host group field, select the group you want to set as the default host group.

    Setting a default host group

Chapter 16. Adjusting ID ranges manually

An IdM master generates unique user ID (UID) and group ID (GID) numbers. By creating and assigning different ID ranges to replicas, it also ensures that they never generate the same ID numbers. By default, this process is automatic. However, you can manually adjust the IdM ID range during the IdM master installation, or manually define a replica’s DNA ID range.

16.1. ID ranges

ID numbers are divided into ID ranges. Keeping separate numeric ranges for individual servers and replicas eliminates the chance that an ID number issued for an entry is already used by another entry on another server or replica.

Note that there are two distinct types of ID ranges:

  • The IdM ID range, which is assigned during the IdM master installation. This range cannot be modified after it is created. However, if you need to, you can create a new IdM ID range in addition to the original one. For more information, see Automatic ID ranges assignment and Adding a new IdM ID range.
  • The Distributed Numeric Assignment (DNA) ID ranges, which can be modified by the user. These have to fit within an existing IdM ID range. For more information, see Adjusting DNA ID ranges manually.

    Replicas can also have a next DNA ID range assigned. A replica uses its next range when it runs out of IDs in its current range. Next ranges are assigned automatically when a replica is deleted or you can set them manually.

The ranges are updated and shared between the master and replicas by the DNA plug-in, as part of the back end 389 Directory Server instance for the domain.

The DNA range definition is set by two attributes: the server’s next available number (the low end of the DNA range) and its maximum value (the top end of the DNA range). The initial bottom range is set during the plug-in instance configuration. After that, the plug-in updates the bottom value. Breaking the available numbers into ranges allows the servers to continually assign numbers without overlapping with each other.

16.2. Automatic ID ranges assignment

By default, an IdM ID range is automatically assigned during the IdM master installation. The ipa-server-install command randomly selects and assigns a range of 200,000 IDs from a total of 10,000 possible ranges. Selecting a random range in this way significantly reduces the probability of conflicting IDs in case you decide to merge two separate IdM domains in the future.

Note

This IdM ID range cannot be modified after it is created. You can only manually adjust the Distributed Numeric Assignment (DNA) ID ranges, using the commands described in Adjusting DNA ID ranges manually. A DNA range matching the IdM ID range is automatically created during installation.

If you have a single IdM server installed, it controls the whole DNA ID range. When you install a new replica and the replica requests its own DNA ID range, the initial ID range for the master splits and is distributed between the master and replica: the replica receives half of the remaining DNA ID range that is available on the initial master. The master and replica then use their respective portions of the original ID range for new user or group entries. Also, if the replica is close to depleting its allocated ID range and fewer than 100 IDs remain, the replica contacts the other available servers to request a new DNA ID range.

Important

When you install a replica, it does not immediately receive an ID range. A replica receives an ID range the first time the DNA plug-in is used, for example when you first add a user. Until then, the replica has no ID range defined.

If the initial master stops functioning before the replica requests a DNA ID range from it, the replica is unable to contact the master to request the ID range. Attempting to add a new user on the replica then fails. In such situations, you can find out what ID range is assigned to the disabled master, and assign an ID range to the replica manually.

16.3. Assigning the IdM ID range manually during server installation

You can override the default behavior and set an IdM ID range manually instead of having it assigned randomly.

Important

Do not set ID ranges that include UID values of 1000 and lower; these values are reserved for system use. Also, do not set an ID range that would include the 0 value; the SSSD service does not handle the 0 ID value.

Procedure

  • You can define the IdM ID range manually during server installation by using the following two options with ipa-server-install:

    • --idstart gives the starting value for UID and GID numbers.
    • --idmax gives the maximum UID and GID number; by default, the value is the --idstart starting value plus 199,999.

Verification steps

  • To check if the ID range was assigned correctly, you can display the assigned IdM ID range by using the ipa idrange-find command:

    # ipa idrange-find
    ---------------
    1 range matched
    ---------------
      Range name: IDM.EXAMPLE.COM_id_range
      First Posix ID of the range: 882200000
      Number of IDs in the range: 200000
      Range type: local domain range
    ----------------------------
    Number of entries returned 1
    ----------------------------

16.4. Adding a new IdM ID range

In some cases, you may want to create a new IdM ID range in addition to the original one; for example, when a replica has run out of IDs and the original IdM ID range is depleted.

Important

Adding a new IdM ID range does not create new DNA ID ranges automatically. You need to assign new DNA ID ranges manually as needed. For more information on how to do this, see Adjusting DNA ID ranges manually.

Procedure

  • To create a new IdM ID range, use the ipa idrange-add command. You need to specify the new range name, the first ID number of the range and the range size:
# ipa idrange-add IDM.EXAMPLE.COM_new_range --base-id=1000000 --range-size=200000
------------------------------------------
Added ID range "IDM.EXAMPLE.COM_new_range"
------------------------------------------
  Range name: IDM.EXAMPLE.COM_new_range
  First Posix ID of the range: 1000000
  Number of IDs in the range: 200000
  Range type: local domain range

Verification steps

  • You can check if the new range is set correctly by using the ipa idrange-find command:
# ipa idrange-find
----------------
2 ranges matched
----------------
  Range name: IDM.EXAMPLE.COM_id_range
  First Posix ID of the range: 882200000
  Number of IDs in the range: 200000
  Range type: local domain range

  Range name: IDM.EXAMPLE.COM_new_range
  First Posix ID of the range: 1000000
  Number of IDs in the range: 200000
  Range type: local domain range
----------------------------
Number of entries returned 2
----------------------------

16.5. Displaying currently assigned DNA ID ranges

You can display both the currently active Distributed Numeric Assignment (DNA) ID range on a server, as well as its next DNA range if it has one assigned.

Procedure

  • To display which DNA ID ranges are configured for the servers in the topology, use the following commands:

    • ipa-replica-manage dnarange-show displays the current DNA ID range that is set on all servers or, if you specify a server, only on the specified server, for example:

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

      # ipa-replica-manage dnanextrange-show
      masterA.example.com: 2001-2500
      masterB.example.com: No on-deck range set
      masterC.example.com: No on-deck range set
      
      # ipa-replica-manage dnanextrange-show masterA.example.com
      masterA.example.com: 2001-2500

16.6. Automatic DNA ID range extension

When you delete a functioning replica, the ipa-replica-manage del command retrieves the DNA ID ranges that were assigned to the replica and adds them as a next range to another available IdM replica. This ensures that DNA ID ranges are used efficiently.

After you delete a replica, you can verify which DNA ID ranges are configured for other servers by using the commands described in Displaying currently assigned DNA ID ranges.

16.7. Manual DNA ID range adjustment

In certain situations, it is necessary to manually adjust a Distributed Numeric Assignment (DNA) ID range, for example when:

  • A replica has run out of IDs and the IdM ID range is depleted

    A replica has exhausted the DNA ID range that was assigned to it, and requesting additional IDs failed because no more free IDs are available in the IdM range.

    To solve this situation, extend the DNA ID range assigned to the replica. You can do this in two ways:

    • Shorten the DNA ID range assigned to a different replica, then assign the newly available values to the depleted replica.
    • Create a new IdM ID range, then set a new DNA ID range for the replica within this created IdM range.

      For information on how to create a new IdM ID range, see Adding a new IdM ID range.

  • A replica stopped functioning

    A replica’s DNA ID range is not automatically retrieved when the replica dies and needs to be deleted, which means the DNA ID range previously assigned to the replica becomes unavailable. You want to recover the DNA ID range and make it available for other replicas.

    If you want to recover a DNA ID range belonging to a replica that stopped functioning and assign it to another server, you first need to find out what the ID range values are, before manually assigning that range to a different server. Also, to avoid duplicate UIDs or GIDs, make sure that no ID value from the recovered range was previously assigned to a user or group; you can do this by examining the UIDs and GIDs of existing users and groups.

You can manually adjust a DNA ID range for a replica using the commands in Adjusting DNA ID ranges manually.

Note

If you assign a new DNA ID range, the UIDs of the already existing entries on the server or replica stay the same. This does not pose a problem because even if you change the current DNA ID range, IdM keeps a record of what ranges were assigned in the past.

16.8. Adjusting DNA ID ranges manually

In some cases, you may need to manually adjust Distributed Numeric Assignment (DNA) ID ranges for existing replicas, for example to reassign a DNA ID range assigned to a non-functioning replica. For more information, see Manual DNA ID range adjustment.

When adjusting a DNA ID range manually, make sure that the newly adjusted range is included in the IdM ID range; you can check this using the ipa idrange-find command. Otherwise, the command will fail.

Important

Be careful not to create overlapping ID ranges. If any of the ID ranges you assign to servers or replicas overlap, it could result in two different servers assigning the same ID value to different entries.

Prerequisites

Procedure

  • To define the current DNA ID range for a specified server, use the ipa-replica-manage dnarange-set:

    # ipa-replica-manage dnarange-set masterA.example.com 1250-1499
  • To define the next DNA ID range for a specified server, use the ipa-replica-manage dnanextrange-set:

    # ipa-replica-manage dnanextrange-set masterB.example.com 1500-5000

Verification steps

Chapter 17. Configuring IdM for external provisioning of users

As a system administrator, you can configure Identity Management (IdM) to support the provisioning of users by an external solution for managing identities.

Rather than use the ipa utility, the administrator of the external provisioning system can access the IdM LDAP using the ldapmodify utility. The administrator can add individual stage users from the CLI using ldapmodify or using an LDIF file.

The assumption is that you, as an IdM administrator, fully trust your external provisioning system to only add validated users. However, at the same time you do not want to assign the administrators of the external provisioning system the IdM role of User Administrator to enable them to add new active users directly.

You can configure a script to automatically move the staged users created by the external provisioning system to active users automatically.

This chapter contains these sections:

  1. Preparing Identity Management (IdM) to use an external provisioning system to add stage users to IdM.
  2. Creating a script to move the users added by the external provisioning system from stage to active users.
  3. Using an external provisioning system to add an IdM stage user. You can do that in two ways:

Additional materials

For examples and templates for using ldapmodify as a full IdM administrator to perform user and group management operations that require higher privileges, see Using ldapmodify.

17.1. Preparing IdM accounts for automatic activation of stage user accounts

This procedure shows how to configure two IdM user accounts to be used by an external provisioning system. By adding the accounts to a group with an appropriate password policy, you enable the external provisioning system to manage user provisioning in IdM. In the following, the user account to be used by the external system to add stage users is named provisionator. The user account to be used to automatically activate the stage users is named activator.

Prerequisites

  • The host on which you perform the procedure is enrolled into IdM.

Procedure

  1. Log in as IdM administrator:

    $ kinit admin
  2. Create a user named provisionator with the privileges to add stage users.

    1. Add the provisionator user account:
    $ ipa user-add provisionator --first=provisioning --last=account --password
    1. Grant the provisionator user the required privileges.

      1. Create a custom role, System Provisioning, to manage adding stage users:

        $ ipa role-add --desc "Responsible for provisioning stage users" "System Provisioning"
      2. Add the Stage User Provisioning privilege to the role. This privilege provides the ability to add stage users:

        $ ipa role-add-privilege "System Provisioning" --privileges="Stage User Provisioning"
      3. Add the provisionator user to the role:

        $ ipa role-add-member --users=provisionator "System Provisioning"
      4. Verify that the provisionator exists in IdM:
      $ ipa user-find provisionator --all --raw
      --------------
      1 user matched
      --------------
        dn: uid=provisionator,cn=users,cn=accounts,dc=idm,dc=example,dc=com
        uid: provisionator
        [...]
  3. Create a user, activator, with the privileges to manage user accounts.

    1. Add the activator user account:

      $ ipa user-add activator --first=activation --last=account --password
    2. Grant the activator user the required privileges by adding the user to the default User Administrator role:

      $ ipa role-add-member --users=activator "User Administrator"
  4. Create a user group for application accounts:

    $ ipa group-add application-accounts
  5. Update the password policy for the group. The following policy prevents password expiration and lockout for the account but compensates the potential risks by requiring complex passwords:

    $ ipa pwpolicy-add application-accounts --maxlife=10000 --minlife=0 --history=0 --minclasses=4 --minlength=8 --priority=1 --maxfail=0 --failinterval=1 --lockouttime=0
  6. (Optional) Verify that the password policy exists in IdM:

    $ ipa pwpolicy-show application-accounts
      Group: application-accounts
      Max lifetime (days): 10000
      Min lifetime (hours): 0
      History size: 0
    [...]
  7. Add the provisioning and activation accounts to the group for application accounts:

    $ ipa group-add-member application-accounts --users={provisionator,activator}
  8. Change the passwords for the user accounts:

    $ kpasswd provisionator
    $ kpasswd activator

    Changing the passwords is necessary because new IdM users passwords expire immediately.

Additional resources:

17.2. Configuring automatic activation of IdM stage user accounts

This procedure shows how to create a script for activating stage users. The system runs the script automatically at specified time intervals. This ensures that new user accounts are automatically activated and available for use shortly after they are created.

Important

The procedure assumes that the owner of the external provisioning system has already validated the users and that they do not require additional validation on the IdM side before the script adds them to IdM.

It is sufficient to enable the activation process on only one of your IdM servers.

Prerequisites

Procedure

  1. Generate a keytab file for the activation account:

    # ipa-getkeytab -s server.idm.example.com -p "activator" -k /etc/krb5.ipa-activation.keytab

    If you want to enable the activation process on more than one IdM server, generate the keytab file on one server only. Then copy the keytab file to the other servers.

  2. Create a script, /usr/local/sbin/ipa-activate-all, with the following contents to activate all users:

    #!/bin/bash
    
    kinit -k -i activator
    
    ipa stageuser-find --all --raw | grep "  uid:" | cut -d ":" -f 2 | while read uid; do ipa stageuser-activate ${uid}; done
  3. Edit the permissions and ownership of the ipa-activate-all script to make it executable:

    # chmod 755 /usr/local/sbin/ipa-activate-all
    # chown root:root /usr/local/sbin/ipa-activate-all
  4. Create a systemd unit file, /etc/systemd/system/ipa-activate-all.service, with the following contents:

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

    [Unit]
    Description=Scan IdM every minute for any stage users that must be activated
    
    [Timer]
    OnBootSec=15min
    OnUnitActiveSec=1min
    
    [Install]
    WantedBy=multi-user.target
  6. Reload the new configuration:

    # systemctl daemon-reload
  7. Enable ipa-activate-all.timer:

    # systemctl enable ipa-activate-all.timer
  8. Start ipa-activate-all.timer:

    # systemctl start ipa-activate-all.timer
  9. (Optional) Verify that the ipa-activate-all.timer daemon is running:

    # systemctl status ipa-activate-all.timer
    ● ipa-activate-all.timer - Scan IdM every minute for any stage users that must be activated
       Loaded: loaded (/etc/systemd/system/ipa-activate-all.timer; enabled; vendor preset: disabled)
       Active: active (waiting) since Wed 2020-06-10 16:34:55 CEST; 15s ago
      Trigger: Wed 2020-06-10 16:35:55 CEST; 44s left
    
    Jun 10 16:34:55 server.idm.example.com systemd[1]: Started Scan IdM every minute for any stage users that must be activated.

17.3. Adding an IdM stage user defined in an LDIF file

This section describes how an administrator of an external provisioning system can access IdM LDAP and use an LDIF file to add stage users. While the example below shows adding one single user, multiple users can be added in one file in bulk mode.

Prerequisites

  • IdM administrator has created the provisionator account and a password for it. For details, see Preparing IdM accounts for automatic activation of stage user accounts.
  • You as the external administrator know the password of the provisionator account.
  • You can SSH to the IdM server from your LDAP server.
  • You are able to supply the minimal set of attributes that an IdM stage user must have to allow the correct processing of the user life cycle, namely:

    • The distinguished name (dn)
    • The common name (cn)
    • The last name (sn)
    • The uid

Procedure

  1. On the external server, create an LDIF file that contains information about the new user:

    dn: uid=stageidmuser,cn=staged users,cn=accounts,cn=provisioning,dc=idm,dc=example,dc=com
    changetype: add
    objectClass: top
    objectClass: inetorgperson
    uid: stageidmuser
    sn: surname
    givenName: first_name
    cn: full_name
  2. Transfer the LDIF file from the external server to the IdM server:

    $ scp add-stageidmuser.ldif provisionator@server.idm.example.com:/provisionator/
    Password:
    add-stageidmuser.ldif                                                                                          100%  364   217.6KB/s   00:00
  3. Use the SSH protocol to connect to the IdM server as provisionator:

    $ ssh provisionator@server.idm.example.com
    Password:
    [provisionator@server ~]$
  4. On the IdM server, obtain the Kerberos ticket-granting ticket (TGT) for the provisionator account:

    [provisionator@server ~]$ kinit provisionator
  5. Enter the ldapadd command with the -f option and the name of the LDIF file. Specify the name of the IdM server and the port number:

    ~]$ ldapadd -h server.idm.example.com -p 389 -f  add-stageidmuser.ldif
    SASL/GSSAPI authentication started
    SASL username: provisionator@IDM.EXAMPLE.COM
    SASL SSF: 256
    SASL data security layer installed.
    adding the entry "uid=stageidmuser,cn=staged users,cn=accounts,cn=provisioning,dc=idm,dc=example,dc=com"

17.4. Adding an IdM stage user directly from the CLI using ldapmodify

This section describes how an administrator of an external provisioning system can access the Identity Management (IdM) LDAP and use the ldapmodify utility to add a stage user.

Prerequisites

  • The IdM administrator has created the provisionator account and a password for it. For details, see Preparing IdM accounts for automatic activation of stage user accounts.
  • You as the external administrator know the password of the provisionator account.
  • You can SSH to the IdM server from your LDAP server.
  • You are able to supply the minimal set of attributes that an IdM stage user must have to allow the correct processing of the user life cycle, namely:

    • The distinguished name (dn)
    • The common name (cn)
    • The last name (sn)
    • The uid

Procedure

  1. Use the SSH protocol to connect to the IdM server using your IdM identity and credentials:

    $ ssh provisionator@server.idm.example.com
    Password:
    [provisionator@server ~]$
  2. Obtain the TGT of the provisionator account, an IdM user with a role to add new stage users:

    $ kinit provisionator
  3. Enter the ldapmodify command and specify Generic Security Services API (GSSAPI) as the Simple Authentication and Security Layer (SASL) mechanism to use for authentication. Specify the name of the IdM server and the port:

    # ldapmodify -h server.idm.example.com -p 389 -Y GSSAPI
    SASL/GSSAPI authentication started
    SASL username: provisionator@IDM.EXAMPLE.COM
    SASL SSF: 56
    SASL data security layer installed.
  4. Enter the dn of the user you are adding:

    dn: uid=stageuser,cn=staged users,cn=accounts,cn=provisioning,dc=idm,dc=example,dc=com
  5. Enter add as the type of change you are performing:

    changetype: add
  6. Specify the LDAP object class categories required to allow the correct processing of the user life cycle:

    objectClass: top
    objectClass: inetorgperson

    You can specify additional object classes.

  7. Enter the uid of the user:

    uid: stageuser
  8. Enter the cn of the user:

    cn: Babs Jensen
  9. Enter the last name of the user:

    sn: Jensen
  10. Press Enter again to confirm that this is the end of the entry:

    [Enter]
    
    adding new entry "uid=stageuser,cn=staged users,cn=accounts,cn=provisioning,dc=idm,dc=example,dc=com"
  11. Exit the connection using Ctrl + C.

Verification steps

Verify the contents of the stage entry to make sure your provisioning system added all required POSIX attributes and the stage entry is ready to be activated.

  • To display the new stage user’s LDAP attributes, enter the ipa stageuser-show --all --raw command:

    $ ipa stageuser-show stageuser --all --raw
      dn: uid=stageuser,cn=staged users,cn=accounts,cn=provisioning,dc=idm,dc=example,dc=com
      uid: stageuser
      sn: Jensen
      cn: Babs Jensen
      has_password: FALSE
      has_keytab: FALSE
      nsaccountlock: TRUE
      objectClass: top
      objectClass: inetorgperson
      objectClass: organizationalPerson
      objectClass: person
    1. Note that the user is explicitly disabled by the nsaccountlock attribute.

Chapter 18. Using ldapmodify to manage IdM users externally

You can modify Identity Management (IdM) LDAP directly from the command-line interface (CLI) using the ldapmodify and ldapdelete utilities. The utilities provide full functionality for adding, editing, and deleting your directory contents. You can use these utilities to manage both the configuration entries of the server and the data in the user entries. The utilities can also be used to write scripts to perform bulk management of one or more directories.

18.1. Templates for managing IdM user accounts externally

This section describes templates for various user management operations in IdM. The templates show which attributes you must modify using ldapmodify to achieve the following goals:

  • Adding a new stage user
  • Modifying a user’s attribute
  • Enabling a user
  • Disabling a user
  • Preserving a user

The templates are formatted in the LDAP Data Interchange Format (LDIF). LDIF is a standard plain text data interchange format for representing LDAP directory content and update requests.

Using the templates, you can configure the LDAP provider of your provisioning system to manage IdM user accounts.

For detailed example procedures, see the following sections:

Templates for adding a new stage user

  • A template for adding a user with UID and GID assigned automatically. The distinguished name (DN) of the created entry must start with uid=user_login:

    dn: uid=user_login,cn=staged users,cn=accounts,cn=provisioning,dc=idm,dc=example,dc=com
    changetype: add
    objectClass: top
    objectClass: inetorgperson
    uid: user_login
    sn: surname
    givenName: first_name
    cn: full_name
  • A template for adding a user with UID and GID assigned statically:

    dn: uid=user_login,cn=staged users,cn=accounts,cn=provisioning,dc=idm,dc=example,dc=com
    changetype: add
    objectClass: top
    objectClass: person
    objectClass: inetorgperson
    objectClass: organizationalperson
    objectClass: posixaccount
    uid: user_login
    uidNumber: UID_number
    gidNumber: GID_number
    sn: surname
    givenName: first_name
    cn: full_name
    homeDirectory: /home/user_login

    You are not required to specify any IdM object classes when adding stage users. IdM adds these classes automatically after the users are activated.

Templates for modifying existing users

  • Modifying a user’s attribute:

    dn: distinguished_name
    changetype: modify
    replace: attribute_to_modify
    attribute_to_modify: new_value
  • Disabling a user:

    dn: distinguished_name
    changetype: modify
    replace: nsAccountLock
    nsAccountLock: TRUE
  • Enabling a user:

    dn: distinguished_name
    changetype: modify
    replace: nsAccountLock
    nsAccountLock: FALSE

    Updating the nssAccountLock attribute has no effect on stage and preserved users. Even though the update operation completes successfully, the attribute value remains nssAccountLock: TRUE.

  • Preserving a user:

    dn: distinguished_name
    changetype: modrdn
    newrdn: uid=user_login
    deleteoldrdn: 0
    newsuperior: cn=deleted users,cn=accounts,cn=provisioning,dc=idm,dc=example,dc=com
Note

Before modifying a user, obtain the user’s distinguished name (DN) by searching using the user’s login. In the following example, the user_allowed_to_modify_user_entries user is a user allowed to modify user and group information, for example activator or IdM administrator. The password in the example is this user’s password:

[...]
# ldapsearch -LLL -x -D "uid=user_allowed_to_modify_user_entries,cn=users,cn=accounts,dc=idm,dc=example,dc=com" -w "Secret123" -H ldap://r8server.idm.example.com -b "cn=users,cn=accounts,dc=idm,dc=example,dc=com" uid=test_user
dn: uid=test_user,cn=users,cn=accounts,dc=idm,dc=example,dc=com
memberOf: cn=ipausers,cn=groups,cn=accounts,dc=idm,dc=example,dc=com

18.2. Templates for managing IdM group accounts externally

This section describes templates for various user group management operations in IdM. The templates show which attributes you must modify using ldapmodify to achieve the following aims:

  • Creating a new group
  • Deleting an existing group
  • Adding a member to a group
  • Removing a member from a group

The templates are formatted in the LDAP Data Interchange Format (LDIF). LDIF is a standard plain text data interchange format for representing LDAP directory content and update requests.

Using the templates, you can configure the LDAP provider of your provisioning system to manage IdM group accounts.

Creating a new group

dn: cn=group_name,cn=groups,cn=accounts,dc=idm,dc=example,dc=com
changetype: add
objectClass: top
objectClass: ipaobject
objectClass: ipausergroup
objectClass: groupofnames
objectClass: nestedgroup
objectClass: posixgroup
uid: group_name
cn: group_name
gidNumber: GID_number

Modifying groups

  • Deleting an existing group:

    dn: group_distinguished_name
    changetype: delete
  • Adding a member to a group:

    dn: group_distinguished_name
    changetype: modify
    add: member
    member: uid=user_login,cn=users,cn=accounts,dc=idm,dc=example,dc=com

    Do not add stage or preserved users to groups. Even though the update operation completes successfully, the users will not be updated as members of the group. Only active users can belong to groups.

  • Removing a member from a group:

    dn: distinguished_name
    changetype: modify
    delete: member
    member: uid=user_login,cn=users,cn=accounts,dc=idm,dc=example,dc=com
Note

Before modifying a group, obtain the group’s distinguished name (DN) by searching using the group’s name.

# ldapsearch -YGSSAPI -H ldap://server.idm.example.com -b "cn=groups,cn=accounts,dc=idm,dc=example,dc=com" "cn=group_name"
dn: cn=group_name,cn=groups,cn=accounts,dc=idm,dc=example,dc=com
ipaNTSecurityIdentifier: S-1-5-21-1650388524-2605035987-2578146103-11017
cn: testgroup
objectClass: top
objectClass: groupofnames
objectClass: nestedgroup
objectClass: ipausergroup
objectClass: ipaobject
objectClass: posixgroup
objectClass: ipantgroupattrs
ipaUniqueID: 569bf864-9d45-11ea-bea3-525400f6f085
gidNumber: 1997010017

18.3. Preserving an IdM user with ldapmodify

This section describes how to use ldapmodify to preserve an IdM user; that is, how to deactivate a user account after the employee has left the company.

Prerequisites

  • You can authenticate as an IdM user with a role to preserve users.

Procedure

  1. Log in as an IdM user with a role to preserve users:

    $ kinit admin
  2. Enter the ldapmodify command and specify the Generic Security Services API (GSSAPI) as the Simple Authentication and Security Layer (SASL) mechanism to be used for authentication:

    # ldapmodify -Y GSSAPI
    SASL/GSSAPI authentication started
    SASL username: admin@IDM.EXAMPLE.COM
    SASL SSF: 256
    SASL data security layer installed.
  3. Enter the dn of the user you want to preserve:

    dn: uid=user1,cn=users,cn=accounts,dc=idm,dc=example,dc=com
  4. Enter modrdn as the type of change you want to perform:

    changetype: modrdn
  5. Specify the newrdn for the user:

    newrdn: uid=user1
  6. Indicate that you want to preserve the user:

    deleteoldrdn: 0
  7. Specify the new superior DN:

    newsuperior: cn=deleted users,cn=accounts,cn=provisioning,dc=idm,dc=example,dc=com

    Preserving a user moves the entry to a new location in the directory information tree (DIT). For this reason, you must specify the DN of the new parent entry as the new superior DN.

  8. Press Enter again to confirm that this is the end of the entry:

    [Enter]
    
    modifying rdn of entry "uid=user1,cn=users,cn=accounts,dc=idm,dc=example,dc=com"
  9. Exit the connection using Ctrl + C.

Verification steps

  • Verify that the user has been preserved by listing all preserved users:

    $ ipa user-find --preserved=true
    --------------
    1 user matched
    --------------
      User login: user1
      First name: First 1
      Last name: Last 1
      Home directory: /home/user1
      Login shell: /bin/sh
      Principal name: user1@IDM.EXAMPLE.COM
      Principal alias: user1@IDM.EXAMPLE.COM
      Email address: user1@idm.example.com
      UID: 1997010003
      GID: 1997010003
      Account disabled: True
      Preserved user: True
    ----------------------------
    Number of entries returned 1
    ----------------------------

Chapter 19. Managing Hosts in IdM CLI

This chapter introduces hosts and host entries in Identity Management (IdM), and the following operations performed when managing hosts and host entries in IdM CLI:

The chapter also contains an overview table of the prerequisites, the context, and the consequences of these operations.

19.1. Hosts in IdM

Identity Management (IdM) manages these identities:

  • Users
  • Services
  • Hosts

A host represents a machine. As an IdM identity, a host has an entry in the IdM LDAP, that is the 389 Directory Server instance of the IdM server.

The host entry in IdM LDAP 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. Any host can be used in host-based access control (HBAC) rules.

IdM domain establishes a commonality between machines, with common identity information, common policies, and shared services. Any machine that belongs to a domain functions as a client of the domain, which means it uses the services that the domain provides. IdM domain provides three main services specifically for machines:

  • DNS
  • Kerberos
  • Certificate management

Hosts in IdM are closely connected with the services running on them:

  • Service entries are associated with a host.
  • A host stores both the host and the service Kerberos principals.

19.2. Host enrollment

This section describes enrolling hosts as IdM clients and what happens during and after the enrollment. The section compares the enrollment of IdM hosts and IdM users. The section also outlines alternative types of authentication available to hosts.

Enrolling a host consists of:

  • Creating a host entry in IdM LDAP: possibly using the ipa host-add command in IdM CLI, or the equivalent IdM Web UI operation.
  • Configuring IdM services on the host, for example the System Security Services Daemon (SSSD), Kerberos, and certmonger, and joining the host to the IdM domain.

The two actions can be performed separately or together.

If performed separately, they allow for dividing the two tasks between two users with different levels of privilege. This is useful for bulk deployments.

The ipa-client-install command can perform the two actions together. The command creates a host entry in IdM LDAP if that entry does not exist yet, and configures both the Kerberos and SSSD services for the host. The command brings the host within the IdM domain and allows it to identify the IdM server it will connect with. If the host belongs to a DNS zone managed by IdM, ipa-client-install adds DNS records for the host too. The command must be run on the client.

19.2.1. User privileges required for host enrollment

The host enrollment operation requires authentication to prevent an unprivileged user from adding unwanted machines to the IdM domain. The privileges required depend on several factors, for example:

  • If a host entry is created separately from running ipa-client-install
  • If a one-time password (OTP) is used for enrollment
User privileges for optionally manually creating a host entry in IdM LDAP

The user privilege required for creating a host entry in IdM LDAP using the ipa host-add CLI command or the IdM Web UI is Host Administrators. The Host Administrators privilege can be obtained through the IT Specialist role.

User privileges for joining the client to the IdM domain

Hosts are configured as IdM clients during the execution of the ipa-client-install command. The level of credentials required for executing the ipa-client-install command depends on which of the following enrolling scenarios you find yourself in:

  • The host entry in IdM LDAP does not exist. For this scenario, you need a full administrator’s credentials or the Host Administrators role. A full administrator is a member of the admins group. The Host Administrators role provides privileges to add hosts and enroll hosts. For details about this scenario, see Installing a client using user credentials: interactive installation.
  • The host entry in IdM LDAP exists. For this scenario, you need a limited administrator’s credentials to execute ipa-client-install successfully. The limited administrator in this case has the Enrollment Administrator role, which provides the Host Enrollment privilege. For details, see Installing a client using user credentials: interactive installation.
  • The host entry in IdM LDAP exists, and an OTP has been generated for the host by a full or limited administrator. For this scenario, you can install an IdM client as an ordinary user if you run the ipa-client-install command with the --password option, supplying the correct OTP. For details, see Installing a client by using a one-time password: Interactive installation.

After enrollment, IdM hosts authenticate every new session to be able to access IdM resources. 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.

19.2.2. Enrollment and authentication of IdM hosts and users: comparison

There are many similarities between users and hosts in IdM. This section describes some of the similarities that can be observed during the enrollment stage as well as those that concern authentication during the deployment stage.

  • The enrollment stage (Table 19.1, “User and host enrollment”):

    • An administrator can create an LDAP entry for both a user and a host before the user or host actually join IdM: for the stage user, the command is ipa stageuser-add; for the host, the command is ipa host-add.
    • A file containing a key table or, abbreviated, keytab, a symmetric key resembling to some extent a user password, is created during the execution of the ipa-client-install command on the host, resulting in the host joining the IdM realm. Analogically, a user is asked to create a password when they activate their account, thus joining the IdM realm.
    • While the user password is the default authentication method for a user, the keytab is the default authentication method for a host. The keytab is stored in a file on the host.

    Table 19.1. User and host enrollment

    ActionUserHost

    Pre-enrollment

    $ ipa stageuser-add user_name [--password]

    $ ipa host-add host_name [--random]

    Activating the account

    $ ipa stageuser-activate user_name

    $ ipa-client install [--password] (must be run on the host itself)

  • The deployment stage (Table 19.2, “User and host session authentication”):

    • When a user starts a new session, the user authenticates using a password; similarly, every time it is switched on, the host authenticates by presenting its keytab file. The System Security Services Daemon (SSSD) manages this process in the background.
    • If the authentication is successful, the user or host obtains a Kerberos ticket granting ticket (TGT).
    • The TGT is then used to obtain specific tickets for specific services.

    Table 19.2. User and host session authentication

     UserHost

    Default means of authentication

    Password

    Keytabs

    Starting a session (ordinary user)

    $ kinit user_name

    [switch on the host]

    The result of successful authentication

    TGT to be used to obtain access to specific services

    TGT to be used to obtain access to specific services

TGTs and other Kerberos tickets are generated as part of the Kerberos services and policies defined by the server. The initial granting of a Kerberos ticket, the renewing of the Kerberos credentials, and even the destroying of the Kerberos session are all handled automatically by the IdM services.

19.2.3. Alternative authentication options for IdM hosts

Apart from keytabs, IdM supports two other types of 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 IdM.
  • 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.

19.3. Host Operations

This section lists the most common operations related to host enrollment and enablement, and explains the prerequisites, the context, and the consequences of performing them.

Table 19.3. Host operations part 1

ActionWhat are the prerequisites of the action?When does it make sense to run the command?How is the action performed by a system administrator? What command(s) does he run?

Enrolling a client

see Preparing the system for Identity Management client installation in Installing_Identity_Management

When you want the host to join the IdM realm.

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) when the ipa host-add command is run, 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 IdM in advance of actually configuring the clients. This allows more flexible setup scenarios, including bulk deployments.

Disabling a client

The host must have an entry in IdM. The host needs to have an active keytab.

When you want to remove the host from the IdM realm temporarily, perhaps for maintenance purposes.

ipa host-disable host_name

Enabling a client

The host must have an entry in IdM.

When you want the temporarily disabled host to become active again.

ipa-getkeytab

Re-enrolling a client

The host must have en entry in IdM.

When the original host has been lost but you have installed a host with the same host name.

ipa-client-install --keytab or ipa-client-install --force-join

Un-enrolling a client

The host must have an entry in IdM.

When you want to remove the host from the IdM realm permanently.

ipa-client-install --uninstall

Table 19.4. Host operations part 2

ActionOn which machine can the administrator run the command(s)?What happens when the action is performed? What are the consequences for the host’s functioning in IdM? What limitations are introduced/removed?

Enrolling a client

In the case of a two-step enrollment: ipa host-add can be run on any IdM client; the second step of ipa-client-install must be run on the client itself

By default this configures SSSD to connect to an IdM server for authentication and authorization. Optionally one can instead configure the Pluggable Authentication Module (PAM) and the Name Switching Service (NSS) to work with an IdM server over Kerberos and LDAP.

Disabling a client

Any machine in IdM, even the host itself

The host’s Kerberos key and SSL certificate are invalidated, and all services running on the host are disabled.

Enabling a client

Any machine in IdM. If run on the disabled host, LDAP credentials need to be supplied.

The host’s Kerberos key and the SSL certificate are made valid again, and all IdM services running on the host are re-enabled.

Re-enrolling a client

The host to be re-enrolled. LDAP credentials need to be supplied.

A new Kerberos key is generated for the host, replacing the previous one.

Un-enrolling a client

The host to be un-enrolled.

The command unconfigures IdM and attempts to return the machine to its previous state. Part of this process is to unenroll the host from the IdM server. Unenrollment consists of disabling the principal key on the IdM server. The machine principal in /etc/krb5.keytab (host/<fqdn>@REALM) is used to authenticate to the IdM server to unenroll itself. If this principal does not exist then unenrollment will fail and an administrator will need to disable the host principal (ipa host-disable <fqdn>).

19.4. Host entry in IdM LDAP

This section describes what a host entry in Identity Management (IdM) looks like and what attributes it can contain.

An LDAP host entry contains all relevant 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
Note

Note that the IdM Web UI IdentityHosts tab does not show all the information about a particular host stored in the IdM LDAP.

19.4.1. Host entry configuration properties

A host entry can contain information about the host that is outside its system configuration, such as its physical location, MAC address, keys, and certificates.

This information can be set when the host entry is created if it is created manually. Alternatively, most of this information can be added to the host entry after the host is enrolled in the domain.

Table 19.5. Host Configuration Properties

UI FieldCommand-Line OptionDescription

Description

--desc=description

A description of the host.

Locality

--locality=locality

The geographic location of the host.

Location

--location=location

The physical location of the host, such as its data center rack.

Platform

--platform=string

The host hardware or architecture.

Operating system

--os=string

The operating system and version for the host.

MAC address

--macaddress=address

The MAC address for the host. This is a multi-valued attribute. The MAC address is used by the NIS plug-in to create a NIS ethers map for the host.

SSH public keys

--sshpubkey=string

The full SSH public key for the host. This is a multi-valued attribute, so multiple keys can be set.

Principal name (not editable)

--principalname=principal

The Kerberos principal name for the host. This defaults to the host name during the client installation, unless a different principal is explicitly set in the -p. This can be changed using the command-line tools, but cannot be changed in the UI.

Set One-Time Password

--password=string

This option sets a password for the host which can be used in bulk enrollment.

-

--random

This option generates a random password to be used in bulk enrollment.

-

--certificate=string

A certificate blob for the host.

-

--updatedns

This sets whether the host can dynamically update its DNS entries if its IP address changes.

19.5. Adding IdM host entries from IdM CLI

This section describes how to add host entries in Identity Management (IdM) using the command-line interface (CLI).

Host entries are created using the host-add command. This commands adds the host entry to the IdM Directory Server. Consult the ipa host manpage by typing ipa help host in your CLI to get the full list of options available with host-add.

There are a few different scenarios when adding a host to IdM:

  • At its most basic, specify only the client host name to add the client to the Kerberos realm and to create an entry in the IdM LDAP server:

    $ ipa host-add client1.example.com
  • If the IdM server is configured to manage DNS, add the host to the DNS resource records using the --ip-address option.

    Example 19.1. Creating Host Entries with Static IP Addresses

    $ ipa host-add --ip-address=192.168.166.31 client1.example.com
  • If the host to be added does not have a static IP address or if the IP address is not known at the time the client is configured, use the --force option with the ipa host-add command.

    Example 19.2. Creating Host Entries with DHCP

    $ ipa host-add --force client1.example.com

    For example, laptops may be preconfigured as IdM clients, but they do not have IP addresses at the time they are configured. Using --force 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.

19.6. Deleting host entries from IdM CLI

  • Use the host-del command to delete host records. If your IdM domain has integrated DNS, use the --updatedns option to remove the associated records of any kind for the host from the DNS:

    $ ipa host-del --updatedns client1.example.com

19.7. Re-enrolling an Identity Management client

19.7.1. Client re-enrollment in IdM

This section describes how to re-enroll an Identity Management (IdM) client.

If a client machine has been destroyed and lost connection with the IdM servers, for example due to the client’s hardware failure, and you still have its keytab, you can re-enroll the client. In this scenario, you want to get the client back in the IdM environment with the same hostname.

During the re-enrollment, the client generates a new Kerberos key and SSH keys, but the identity of the client in the LDAP database remains unchanged. After the re-enrollment, the host has its keys and other information in the same LDAP object with the same FQDN as previously, before the machine’s loss of connection with the IdM servers.

Important

You can only re-enroll clients whose domain entry is still active. If you uninstalled a client (using ipa-client-install --uninstall) or disabled its host entry (using ipa host-disable), you cannot re-enroll it.

You cannot re-enroll a client after you have renamed it. This is because in Identity Management, the key attribute of the client’s entry in LDAP is the client’s hostname, its FQDN. As opposed to re-enrolling a client, during which the client’s LDAP object remains unchanged, the outcome of renaming a client is that the client has its keys and other information in a different LDAP object with a new FQDN. Thus the only way to rename a client is to uninstall the host from IdM, change the host’s hostname, and install it as an IdM client with a new name. For details on how to rename a client, see Section 19.8, “Renaming Identity Management client systems”.

19.7.1.1. What happens during client re-enrollment

During re-enrollment, Identity Management:

  • Revokes the original host certificate
  • Creates new SSH keys
  • Generates a new keytab

19.7.2. Re-enrolling a client by using user credentials: Interactive re-enrollment

This procedure describes re-enrolling an Identity Management client interactively by using the credentials of an authorized user.

  1. Re-create the client machine with the same host name.
  2. Run the ipa-client-install --force-join command on the client machine:

    # ipa-client-install --force-join
  3. The script prompts for a user whose identity will be used to re-enroll the client. This could be, for example, a hostadmin user with the Enrollment Administrator role:

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

Additional resources

19.7.3. Re-enrolling a client by using the client keytab: Non-interactive re-enrollment

Prerequisites

  • Back up the original client keytab file, for example in the /tmp or /root directory.

Procedure

This procedure describes re-enrolling an Identity Management (IdM) client non-interactively by using the keytab of the client system. For example, re-enrollment using the client keytab is appropriate for an automated installation.

  1. Re-create the client machine with the same host name.
  2. Copy the keytab file from the backup location to the /etc/ directory on the re-created client machine.
  3. Use the ipa-client-install utility to re-enroll the client, and specify the keytab location with the --keytab option:

    # ipa-client-install --keytab /etc/krb5.keytab
    Note

    The keytab specified in the --keytab option is only used when authenticating to initiate the enrollment. During the re-enrollment, IdM generates a new keytab for the client.

19.7.4. Testing an Identity Management client after installation

The Command-Line Interface informs you that the ipa-client-install was successful, but you can also do your own test.

To test that the Identity Management client can obtain information about users defined on the server, check that you are able to resolve a user defined on the server. For example, to check the default admin user:

[user@client1 ~]$ id admin
uid=1254400000(admin) gid=1254400000(admins) groups=1254400000(admins)

To test that authentication works correctly, su - as another IdM user:

[user@client1 ~]$ su - idm_user
Last login: Thu Oct 18 18:39:11 CEST 2018 from 192.168.122.1 on pts/0
[idm_user@client1 ~]$

19.8. Renaming Identity Management client systems

The following sections describe how to change the host name of an Identity Management client system.

Warning

Renaming a client is a manual procedure. Do not perform it unless changing the host name is absolutely required.

Renaming an Identity Management client involves:

  1. Preparing the host. For details, see Section 19.8.1, “Prerequisites”
  2. Uninstalling the IdM client from the host. For details, see Section 19.8.2, “Uninstalling an Identity Management client”
  3. Renaming the host. For details, see Section 19.8.3, “Renaming the host system”
  4. Installing the IdM client on the host with the new name. For details, see Section 19.8.4, “Re-installing an Identity Management client”
  5. Configuring the host after the IdM client installation. For details, see Section 19.8.5, “Re-adding services, re-generating certificates, and re-adding host groups”

19.8.1. Prerequisites

Before uninstalling the current client, make note of certain settings for the client. You will apply this configuration after re-enrolling the machine with a new host name.

  • Identify which services are running on the machine:

    • Use the ipa service-find command, and identify services with certificates in the output:

      $ ipa service-find old-client-name.example.com
    • In addition, each host has a default host service which does not appear in the ipa service-find output. The service principal for the host service, also called a host principal, is host/old-client-name.example.com.
  • For all service principals displayed by ipa service-find old-client-name.example.com, determine the location of the corresponding keytabs on the old-client-name.example.com system:

    # find / -name "*.keytab"

    Each service on the client system has a Kerberos principal in the form service_name/host_name@REALM, such as ldap/old-client-name.example.com@EXAMPLE.COM.

  • Identify all host groups to which the machine belongs.

    # ipa hostgroup-find old-client-name.example.com

19.8.2. Uninstalling an Identity Management client

Uninstalling a client removes the client from the Identity Management domain, along with all of the specific Identity Management configuration of system services, such as System Security Services Daemon (SSSD). This restores the previous configuration of the client system.

Procedure

  1. Run the ipa-client-install --uninstall command:

    [root@client]# ipa-client-install --uninstall
  2. Remove the DNS entries for the client host manually from the server:

    [root@server]# ipa dnsrecord-del
    Record name: old-client-client
    Zone name: idm.example.com
    No option to delete specific record provided.
    Delete all? Yes/No (default No): yes
    ------------------------
    Deleted record "old-client-name"
  3. For each identified keytab other than /etc/krb5.keytab, remove the old principals:

    [root@client ~]# ipa-rmkeytab -k /path/to/keytab -r EXAMPLE.COM
  4. On an IdM server, remove the host entry. This removes all services and revokes all certificates issued for that host:

    [root@server ~]# ipa host-del client.example.com

19.8.3. Renaming the host system

Rename the machine as required. For example:

[root@client]# hostnamectl set-hostname new-client-name.example.com

You can now re-install the Identity Management client to the Identity Management domain with the new host name.

19.8.4. Re-installing an Identity Management client

Install an client on your renamed host following the procedure described in Installing an Identity Management client: Basic scenario in Installing Identity Management.

19.8.5. Re-adding services, re-generating certificates, and re-adding host groups

  1. On the Identity Management (IdM) server, add a new keytab for every service identified in Section 19.8.1, “Prerequisites”.

    [root@server ~]# ipa service-add service_name/new-client-name
  2. Generate certificates for services that had a certificate assigned in Section 19.8.1, “Prerequisites”. You can do this:

    • Using the IdM administration tools
    • Using the certmonger utility
  3. Re-add the client to the host groups identified in Section 19.8.1, “Prerequisites”.

19.9. Disabling and Re-enabling Host Entries

This section describes how to disable and re-enable hosts in Identity Management (IdM).

19.9.1. Disabling Hosts

Complete this procedure to disable a host entry in IdM.

Domain services, hosts, and users can access an active host. There can be situations when it is necessary to remove an active host temporarily, for maintenance reasons, for example. Deleting the host in such situations is not desired as it removes the host entry and all the associated configuration permanently. Instead, choose the option of disabling the host.

Disabling a host prevents domain users from accessing it without permanently removing it from the domain. This can be done by using the host-disable command. Disabling a host kills the host’s current, active keytabs.

For example:

$ kinit admin
$ ipa host-disable client.example.com

As a result of disabling a host, the host becomes unavailable to all IdM users, hosts and services.

Important

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

19.9.2. Re-enabling Hosts

This section describes how to re-enable a disabled IdM host.

Disabling a host killed its active keytabs, which removed the host from the IdM domain without otherwise touching its configuration entry.

To re-enable a host, use the ipa-getkeytab command, adding:

  • the -s option to specify which IdM server to request the keytab from
  • the -p option to specify the principal name
  • the -k option to specify the file to which to save the keytab.

For example, to request a new host keytab from server.example.com for client.example.com, and store the keytab in the /etc/krb5.keytab file:

$  ipa-getkeytab -s server.example.com -p host/client.example.com -k /etc/krb5.keytab -D "cn=directory manager" -w password
Note

You can also use the administrator’s credentials, specifying -D "uid=admin,cn=users,cn=accounts,dc=example,dc=com". It is important that the credentials correspond to a user allowed to create the keytab for the host.

If 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) if the user has a TGT obtained using, for example, kinit admin. To run the command directly on the disabled host, supply LDAP credentials to authenticate to the IdM server.

Chapter 20. Adding host entries from IdM Web UI

This chapter introduces hosts in Identity Management (IdM) and the operation of adding a host entry in the IdM Web UI.

20.1. Hosts in IdM

Identity Management (IdM) manages these identities:

  • Users
  • Services
  • Hosts

A host represents a machine. As an IdM identity, a host has an entry in the IdM LDAP, that is the 389 Directory Server instance of the IdM server.

The host entry in IdM LDAP 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. Any host can be used in host-based access control (HBAC) rules.

IdM domain establishes a commonality between machines, with common identity information, common policies, and shared services. Any machine that belongs to a domain functions as a client of the domain, which means it uses the services that the domain provides. IdM domain provides three main services specifically for machines:

  • DNS
  • Kerberos
  • Certificate management

Hosts in IdM are closely connected with the services running on them:

  • Service entries are associated with a host.
  • A host stores both the host and the service Kerberos principals.

20.2. Host enrollment

This section describes enrolling hosts as IdM clients and what happens during and after the enrollment. The section compares the enrollment of IdM hosts and IdM users. The section also outlines alternative types of authentication available to hosts.

Enrolling a host consists of:

  • Creating a host entry in IdM LDAP: possibly using the ipa host-add command in IdM CLI, or the equivalent IdM Web UI operation.
  • Configuring IdM services on the host, for example the System Security Services Daemon (SSSD), Kerberos, and certmonger, and joining the host to the IdM domain.

The two actions can be performed separately or together.

If performed separately, they allow for dividing the two tasks between two users with different levels of privilege. This is useful for bulk deployments.

The ipa-client-install command can perform the two actions together. The command creates a host entry in IdM LDAP if that entry does not exist yet, and configures both the Kerberos and SSSD services for the host. The command brings the host within the IdM domain and allows it to identify the IdM server it will connect with. If the host belongs to a DNS zone managed by IdM, ipa-client-install adds DNS records for the host too. The command must be run on the client.

20.2.1. User privileges required for host enrollment

The host enrollment operation requires authentication to prevent an unprivileged user from adding unwanted machines to the IdM domain. The privileges required depend on several factors, for example:

  • If a host entry is created separately from running ipa-client-install
  • If a one-time password (OTP) is used for enrollment
User privileges for optionally manually creating a host entry in IdM LDAP

The user privilege required for creating a host entry in IdM LDAP using the ipa host-add CLI command or the IdM Web UI is Host Administrators. The Host Administrators privilege can be obtained through the IT Specialist role.

User privileges for joining the client to the IdM domain

Hosts are configured as IdM clients during the execution of the ipa-client-install command. The level of credentials required for executing the ipa-client-install command depends on which of the following enrolling scenarios you find yourself in:

  • The host entry in IdM LDAP does not exist. For this scenario, you need a full administrator’s credentials or the Host Administrators role. A full administrator is a member of the admins group. The Host Administrators role provides privileges to add hosts and enroll hosts. For details about this scenario, see Installing a client using user credentials: interactive installation.
  • The host entry in IdM LDAP exists. For this scenario, you need a limited administrator’s credentials to execute ipa-client-install successfully. The limited administrator in this case has the Enrollment Administrator role, which provides the Host Enrollment privilege. For details, see Installing a client using user credentials: interactive installation.
  • The host entry in IdM LDAP exists, and an OTP has been generated for the host by a full or limited administrator. For this scenario, you can install an IdM client as an ordinary user if you run the ipa-client-install command with the --password option, supplying the correct OTP. For details, see Installing a client by using a one-time password: Interactive installation.

After enrollment, IdM hosts authenticate every new session to be able to access IdM resources. 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.

20.2.2. Enrollment and authentication of IdM hosts and users: comparison

There are many similarities between users and hosts in IdM. This section describes some of the similarities that can be observed during the enrollment stage as well as those that concern authentication during the deployment stage.

  • The enrollment stage (Table 20.1, “User and host enrollment”):

    • An administrator can create an LDAP entry for both a user and a host before the user or host actually join IdM: for the stage user, the command is ipa stageuser-add; for the host, the command is ipa host-add.
    • A file containing a key table or, abbreviated, keytab, a symmetric key resembling to some extent a user password, is created during the execution of the ipa-client-install command on the host, resulting in the host joining the IdM realm. Analogically, a user is asked to create a password when they activate their account, thus joining the IdM realm.
    • While the user password is the default authentication method for a user, the keytab is the default authentication method for a host. The keytab is stored in a file on the host.

    Table 20.1. User and host enrollment

    ActionUserHost

    Pre-enrollment

    $ ipa stageuser-add user_name [--password]

    $ ipa host-add host_name [--random]

    Activating the account

    $ ipa stageuser-activate user_name

    $ ipa-client install [--password] (must be run on the host itself)

  • The deployment stage (Table 20.2, “User and host session authentication”):

    • When a user starts a new session, the user authenticates using a password; similarly, every time it is switched on, the host authenticates by presenting its keytab file. The System Security Services Daemon (SSSD) manages this process in the background.
    • If the authentication is successful, the user or host obtains a Kerberos ticket granting ticket (TGT).
    • The TGT is then used to obtain specific tickets for specific services.

    Table 20.2. User and host session authentication

     UserHost

    Default means of authentication

    Password

    Keytabs

    Starting a session (ordinary user)

    $ kinit user_name

    [switch on the host]

    The result of successful authentication

    TGT to be used to obtain access to specific services

    TGT to be used to obtain access to specific services

TGTs and other Kerberos tickets are generated as part of the Kerberos services and policies defined by the server. The initial granting of a Kerberos ticket, the renewing of the Kerberos credentials, and even the destroying of the Kerberos session are all handled automatically by the IdM services.

20.2.3. Alternative authentication options for IdM hosts

Apart from keytabs, IdM supports two other types of 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 IdM.
  • 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.

20.3. Host entry in IdM LDAP

This section describes what a host entry in Identity Management (IdM) looks like and what attributes it can contain.

An LDAP host entry contains all relevant 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
Note

Note that the IdM Web UI IdentityHosts tab does not show all the information about a particular host stored in the IdM LDAP.

20.3.1. Host entry configuration properties

A host entry can contain information about the host that is outside its system configuration, such as its physical location, MAC address, keys, and certificates.

This information can be set when the host entry is created if it is created manually. Alternatively, most of this information can be added to the host entry after the host is enrolled in the domain.

Table 20.3. Host Configuration Properties

UI FieldCommand-Line OptionDescription

Description

--desc=description

A description of the host.

Locality

--locality=locality

The geographic location of the host.

Location

--location=location

The physical location of the host, such as its data center rack.

Platform

--platform=string

The host hardware or architecture.

Operating system

--os=string

The operating system and version for the host.

MAC address

--macaddress=address

The MAC address for the host. This is a multi-valued attribute. The MAC address is used by the NIS plug-in to create a NIS ethers map for the host.

SSH public keys

--sshpubkey=string

The full SSH public key for the host. This is a multi-valued attribute, so multiple keys can be set.

Principal name (not editable)

--principalname=principal

The Kerberos principal name for the host. This defaults to the host name during the client installation, unless a different principal is explicitly set in the -p. This can be changed using the command-line tools, but cannot be changed in the UI.

Set One-Time Password

--password=string

This option sets a password for the host which can be used in bulk enrollment.

-

--random

This option generates a random password to be used in bulk enrollment.

-

--certificate=string

A certificate blob for the host.

-

--updatedns

This sets whether the host can dynamically update its DNS entries if its IP address changes.

20.4. Adding Host Entries from the Web UI

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

    Figure 20.1. Adding Host Entries

    hosts list
  3. Enter 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.

    The Class field has no specific purpose at the moment.

    Figure 20.2. Add Host Wizard

    host add

    DNS zones can be created in IdM. If the IdM server does not manage the DNS server, the zone can be entered manually in the menu area, like a regular text field.

    Note

    Select the Force check box if you want to skip checking whether the host is resolvable via DNS.

  4. Click the Add and Edit button to go directly to the expanded entry page and enter more attribute information. Information about the host hardware and physical location can be included with the host entry.

    Figure 20.3. Expanded Entry Page

    host attr

Chapter 21. Managing hosts using Ansible playbooks

Ansible is an automation tool used to configure systems, deploy software, and perform rolling updates. Ansible includes support for Identity Management (IdM), and you can use Ansible modules to automate host management.

This chapter describes the following operations performed when managing hosts and host entries using Ansible playbooks:

21.1. Ensuring the presence of an IdM host entry with FQDN using Ansible playbooks

This section describes ensuring the presence of host entries in Identity Management (IdM) using Ansible playbooks. The host entries are only defined by their fully-qualified domain names (FQDNs).

Specifying the FQDN name of the host is enough if at least one of the following conditions applies:

  • The IdM server is not configured to manage DNS.
  • The host does not have a static IP address or the IP address is not known at the time the host is configured. Adding a host defined only by an FQDN essentially creates a placeholder entry in the IdM DNS service. For example, laptops may be preconfigured as IdM clients, but they do not have IP addresses at the time they are configured. When the DNS service dynamically updates its records, the host’s current IP address is detected and its DNS record is updated.
Note

Without Ansible, host entries are created in IdM using the ipa host-add command. The result of adding a host to IdM is the state of the host being present in IdM. Because of the Ansible reliance on idempotence, to add a host to IdM using Ansible, you must create a playbook in which you define the state of the host as present: state: present.

Prerequisites

  • You know the IdM administrator password.
  • The ansible-freeipa package is installed on the Ansible controller.

Procedure

  1. Create an inventory file, for example inventory.file, and define ipaserver in it:

    [ipaserver]
    server.idm.example.com
  2. Create an Ansible playbook file with the FQDN of the host whose presence in IdM you want to ensure. To simplify this step, you can copy and modify the example in the /usr/share/doc/ansible-freeipa/playbooks/host/add-host.yml file:

    ---
    - name: Host present
      hosts: ipaserver
      become: true
    
      tasks:
      - name: Host host01.idm.example.com present
        ipahost:
          ipaadmin_password: Secret123
          name: host01.idm.example.com
          state: present
          force: yes
  3. Run the playbook:

    $ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-host-is-present.yml
Note

The procedure results in a host entry in the IdM LDAP server being created but not in enrolling the host into the IdM Kerberos realm. For that, you must deploy the host as an IdM client. For details, see Installing an Identity Management client using an Ansible playbook.

Verification steps

  1. Log in to your IdM server as admin:

    $ ssh admin@server.idm.example.com
    Password:
  2. Enter the ipa host-show command and specify the name of the host:

    $ ipa host-show host01.idm.example.com
      Host name: host01.idm.example.com
      Principal name: host/host01.idm.example.com@IDM.EXAMPLE.COM
      Principal alias: host/host01.idm.example.com@IDM.EXAMPLE.COM
      Password: False
      Keytab: False
      Managed by: host01.idm.example.com

The output confirms that host01.idm.example.com exists in IdM.

21.2. Ensuring the presence of an IdM host entry with DNS information using Ansible playbooks

This section describes ensuring the presence of host entries in Identity Management (IdM) using Ansible playbooks. The host entries are defined by their fully-qualified domain names (FQDNs) and their IP addresses.

Note

Without Ansible, host entries are created in IdM using the ipa host-add command. The result of adding a host to IdM is the state of the host being present in IdM. Because of the Ansible reliance on idempotence, to add a host to IdM using Ansible, you must create a playbook in which you define the state of the host as present: state: present.

Prerequisites

  • You know the IdM administrator password.
  • The ansible-freeipa package is installed on the Ansible controller.

Procedure

  1. Create an inventory file, for example inventory.file, and define ipaserver in it:

    [ipaserver]
    server.idm.example.com
  2. Create an Ansible playbook file with the fully-qualified domain name (FQDN) of the host whose presence in IdM you want to ensure. In addition, if the IdM server is configured to manage DNS and you know the IP address of the host, specify a value for the ip_address parameter. The IP address is necessary for the host to exist in the DNS resource records. To simplify this step, you can copy and modify the example in the /usr/share/doc/ansible-freeipa/playbooks/host/host-present.yml file. You can also include other, additional information:

    ---
    - name: Host present
      hosts: ipaserver
      become: true
    
      tasks:
      - name: Ensure host01.idm.example.com is present
        ipahost:
          ipaadmin_password: ADMPassword123
          name: host01.idm.example.com
          description: Example host
          ip_address: 192.168.0.123
          locality: Lab
          ns_host_location: Lab
          ns_os_version: CentOS 7
          ns_hardware_platform: Lenovo T61
          mac_address:
          - "08:00:27:E3:B1:2D"
          - "52:54:00:BD:97:1E"
          state: present
  3. Run the playbook:

    $ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-host-is-present.yml
Note

The procedure results in a host entry in the IdM LDAP server being created but not in enrolling the host into the IdM Kerberos realm. For that, you must deploy the host as an IdM client. For details, see Installing an Identity Management client using an Ansible playbook.

Verification steps

  1. Log in to your IdM server as admin:

    $ ssh admin@server.idm.example.com
    Password:
  2. Enter the ipa host-show command and specify the name of the host:

    $ ipa host-show host01.idm.example.com
      Host name: host01.idm.example.com
      Description: Example host
      Locality: Lab
      Location: Lab
      Platform: Lenovo T61
      Operating system: CentOS 7
      Principal name: host/host01.idm.example.com@IDM.EXAMPLE.COM
      Principal alias: host/host01.idm.example.com@IDM.EXAMPLE.COM
      MAC address: 08:00:27:E3:B1:2D, 52:54:00:BD:97:1E
      Password: False
      Keytab: False
      Managed by: host01.idm.example.com

The output confirms host01.idm.example.com exists in IdM.

21.3. Ensuring the presence of multiple IdM host entries with random passwords using Ansible playbooks

The ipahost module allows the system administrator to ensure the presence or absence of multiple host entries in IdM using just one Ansible task. This section describes how to ensure the presence of multiple host entries that are only defined by their fully-qualified domain names (FQDNs). Running the Ansible playbook generates random passwords for the hosts.

Note

Without Ansible, host entries are created in IdM using the ipa host-add command. The result of adding a host to IdM is the state of the host being present in IdM. Because of the Ansible reliance on idempotence, to add a host to IdM using Ansible, you must create a playbook in which you define the state of the host as present: state: present.

Prerequisites

  • You know the IdM administrator password.
  • The ansible-freeipa package is installed on the Ansible controller.

Procedure

  1. Create an inventory file, for example inventory.file, and define ipaserver in it:

    [ipaserver]
    server.idm.example.com
  2. Create an Ansible playbook file with the fully-qualified domain name (FQDN) of the hosts whose presence in IdM you want to ensure. To make the Ansible playbook generate a random password for each host even when the host already exists in IdM and update_password is limited to on_create, add the random: yes and force: yes options. To simplify this step, you can copy and modify the example from the /usr/share/doc/ansible-freeipa/README-host.md Markdown file:

    ---
    - name: Ensure hosts with random password
      hosts: ipaserver
      become: true
    
      tasks:
      - name: Hosts host01.idm.example.com and host02.idm.example.com present with random passwords
        ipahost:
          ipaadmin_password: MyPassword123
          hosts:
          - name: host01.idm.example.com
            random: yes
            force: yes
          - name: host02.idm.example.com
            random: yes
            force: yes
        register: ipahost
  3. Run the playbook:

    $ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-hosts-are-present.yml
    [...]
    TASK [Hosts host01.idm.example.com and host02.idm.example.com present with random passwords]
    changed: [r8server.idm.example.com] => {"changed": true, "host": {"host01.idm.example.com": {"randompassword": "0HoIRvjUdH0Ycbf6uYdWTxH"}, "host02.idm.example.com": {"randompassword": "5VdLgrf3wvojmACdHC3uA3s"}}}

Verification steps

  1. Log in to your IdM server as admin:

    $ ssh admin@server.idm.example.com
    Password:
  2. Enter the ipa host-show command and specify the name of one of the hosts:

    $ ipa host-show host01.idm.example.com
      Host name: host01.idm.example.com
      Password: True
      Keytab: False
      Managed by: host01.idm.example.com

The output confirms host01.idm.example.com exists in IdM with a random password.

21.4. Ensuring the presence of an IdM host entry with multiple IP addresses using Ansible playbooks

This section describes how to ensure the presence of a host entry in Identity Management (IdM) using Ansible playbooks. The host entry is defined by its fully-qualified domain name (FQDN) and its multiple IP addresses.

Note

In contrast to the ipa host utility, the Ansible ipahost module can ensure the presence or absence of several IPv4 and IPv6 addresses for a host. The ipa host-mod command cannot handle IP addresses.

Prerequisites

  • You know the IdM administrator password.
  • The ansible-freeipa package is installed on the Ansible controller.

Procedure

  1. Create an inventory file, for example inventory.file, and define ipaserver in it:

    [ipaserver]
    server.idm.example.com
  2. Create an Ansible playbook file. Specify, as the name of the ipahost variable, the fully-qualified domain name (FQDN) of the host whose presence in IdM you want to ensure. Specify each of the multiple IPv4 and IPv6 ip_address values on a separate line by using the - ip_address syntax. To simplify this step, you can copy and modify the example in the /usr/share/doc/ansible-freeipa/playbooks/host/host-member-ipaddresses-present.yml file. You can also include additional information:

    ---
    - name: Host member IP addresses present
      hosts: ipaserver
      become: true
    
      tasks:
      - name: Ensure host101.example.com IP addresses present
        ipahost:
          ipaadmin_password: Secret123
          name: host01.idm.example.com
          ip_address:
          - 192.168.0.123
          - fe80::20c:29ff:fe02:a1b3
          - 192.168.0.124
          - fe80::20c:29ff:fe02:a1b4
          force: yes
  3. Run the playbook:

    $ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-host-with-multiple-IP-addreses-is-present.yml
Note

The procedure creates a host entry in the IdM LDAP server but does not enroll the host into the IdM Kerberos realm. For that, you must deploy the host as an IdM client. For details, see Installing an Identity Management client using an Ansible playbook.

Verification steps

  1. Log in to your IdM server as admin:

    $ ssh admin@server.idm.example.com
    Password:
  2. Enter the ipa host-show command and specify the name of the host:

    $ ipa host-show host01.idm.example.com
      Principal name: host/host01.idm.example.com@IDM.EXAMPLE.COM
      Principal alias: host/host01.idm.example.com@IDM.EXAMPLE.COM
      Password: False
      Keytab: False
      Managed by: host01.idm.example.com

    The output confirms that host01.idm.example.com exists in IdM.

  3. To verify that the multiple IP addresses of the host exist in the IdM DNS records, enter the ipa dnsrecord-show command and specify the following information:

    • The name of the IdM domain
    • The name of the host

      $ ipa dnsrecord-show idm.example.com host01
      [...]
        Record name: host01
        A record: 192.168.0.123, 192.168.0.124
        AAAA record: fe80::20c:29ff:fe02:a1b3, fe80::20c:29ff:fe02:a1b4

    The output confirms that all the IPv4 and IPv6 addresses specified in the playbook are correctly associated with the host01.idm.example.com host entry.

21.5. Ensuring the absence of an IdM host entry using Ansible playbooks

This section describes how to ensure the absence of host entries in Identity Management (IdM) using Ansible playbooks.

Prerequisites

  • IdM administrator credentials

Procedure

  1. Create an inventory file, for example inventory.file, and define ipaserver in it:

    [ipaserver]
    server.idm.example.com
  2. Create an Ansible playbook file with the fully-qualified domain name (FQDN) of the host whose absence from IdM you want to ensure. If your IdM domain has integrated DNS, use the updatedns: yes option to remove the associated records of any kind for the host from the DNS.

    To simplify this step, you can copy and modify the example in the /usr/share/doc/ansible-freeipa/playbooks/host/delete-host.yml file:

    ---
    - name: Host absent
      hosts: ipaserver
      become: true
    
      tasks:
      - name: Host host01.idm.example.com absent
        ipahost:
          ipaadmin_password: MyPassword123
          name: host01.idm.example.com
          updatedns: yes
          state: absent
  3. Run the playbook:

    $ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-host-absent.yml
Note

The procedure results in:

  • The host not being present in the IdM Kerberos realm.
  • The host entry not being present in the IdM LDAP server.

To remove the specific IdM configuration of system services, such as System Security Services Daemon (SSSD), from the client host itself, you must run the ipa-client-install --uninstall command on the client. For details, see Uninstalling an IdM client.

Verification steps

  1. Log into ipaserver as admin:

    $ ssh admin@server.idm.example.com
    Password:
    [admin@server /]$
  2. Display information about host01.idm.example.com:

    $ ipa host-show host01.idm.example.com
    ipa: ERROR: host01.idm.example.com: host not found

The output confirms that the host does not exist in IdM.

Additional resources

  • You can see the definitions of the ipahost variables as well as sample Ansible playbooks for ensuring the presence, absence, and disablement of hosts in the /usr/share/doc/ansible-freeipa/README-host.md Markdown file.
  • Additional playbooks are in the /usr/share/doc/ansible-freeipa/playbooks/host directory.

Chapter 22. Managing host groups using the IdM CLI

This chapter introduces host groups in Identity Management (IdM) and describes the following operations to manage host groups and their members in the command-line interface (CLI):

  • Viewing host groups and their members
  • Creating host groups
  • Deleting host groups
  • Adding host group members
  • Removing host group members

22.1. Host groups in IdM

IdM host groups can be used to centralize control over important management tasks, particularly access control.

Definition of host groups

A host group is an entity that contains a set of IdM hosts with common access control rules and other characteristics. For example, you can define host groups based on company departments, physical locations, or access control requirements.

A host group in IdM can include:

  • IdM servers and clients
  • Other IdM host groups

Host groups created by default

By default, the IdM server creates the host group ipaservers for all IdM server hosts.

Direct and indirect group members

Group attributes in IdM apply to both direct and indirect members: when host group B is a member of host group A, all members of host group B are considered indirect members of host group A.

22.2. Viewing IdM host groups using the CLI

This section describes how to view IdM host groups using the command-line interface (CLI).

Prerequisites

Procedure

  1. Find all host groups using the ipa hostgroup-find command.

    $ ipa hostgroup-find
    -------------------
    1 hostgroup matched
    -------------------
      Host-group: ipaservers
      Description: IPA server hosts
    ----------------------------
    Number of entries returned 1
    ----------------------------

    To display all attributes of a host group, add the --all option. For example:

    $ ipa hostgroup-find --all
    -------------------
    1 hostgroup matched
    -------------------
      dn: cn=ipaservers,cn=hostgroups,cn=accounts,dc=idm,dc=local
      Host-group: ipaservers
      Description: IPA server hosts
      Member hosts: xxx.xxx.xxx.xxx
      ipauniqueid: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
      objectclass: top, groupOfNames, nestedGroup, ipaobject, ipahostgroup
    ----------------------------
    Number of entries returned 1
    ----------------------------

22.3. Creating IdM host groups using the CLI

This section describes how to create IdM host groups using the command-line interface (CLI).

Prerequisites

Procedure

  1. Add a host group using the ipa hostgroup-add command.
    For example, to create an IdM host group named group_name and give it a description:

    $ ipa hostgroup-add --desc 'My new host group' group_name
    ---------------------
    Added hostgroup "group_name"
    ---------------------
      Host-group: group_name
      Description: My new host group
    ---------------------

22.4. Deleting IdM host groups using the CLI

This section describes how to delete IdM host groups using the command-line interface (CLI).

Prerequisites

Procedure

  1. Delete a host group using the ipa hostgroup-del command.
    For example, to delete the IdM host group named group_name:

    $ ipa hostgroup-del group_name
    --------------------------
    Deleted hostgroup "group_name"
    --------------------------
Note

Removing a group does not delete the group members from IdM.

22.5. Adding IdM host group members using the CLI

You can add hosts as well as host groups as members to an IdM host group using a single command.

Prerequisites

  • Administrator privileges for managing IdM or User Administrator role.
  • An active Kerberos ticket. For details, see Using kinit to log in to IdM manually.
  • Optional. Use the ipa hostgroup-find command to find hosts and host groups.

Procedure

  1. To add a member to a host group, use the ipa hostgroup-add-member and provide the relevant information. You can specify the type of member to add using these options:

    • Use the --hosts option to add one or more hosts to an IdM host group.
      For example, to add the host named example_member to the group named group_name:

      $ ipa hostgroup-add-member group_name --hosts example_member
      Host-group: group_name
      Description: My host group
      Member hosts: example_member
      -------------------------
      Number of members added 1
      -------------------------
    • Use the --hostgroups option to add one or more host groups to an IdM host group.
      For example, to add the host group named nested_group to the group named group_name:

      $ ipa hostgroup-add-member group_name --hostgroups nested_group
      Host-group: group_name
      Description: My host group
      Member host-groups: nested_group
      -------------------------
      Number of members added 1
      -------------------------
    • You can add multiple hosts and multiple host groups to an IdM host group in one single command using the following syntax:

      $ ipa hostgroup-add-member group_name --hosts={host1,host2} --hostgroups={group1,group2}
Important

When adding a host group as a member of another host group, do not create recursive groups. For example, if Group A is a member of Group B, do not add Group B as a member of Group A. Recursive groups can cause unpredictable behavior.

22.6. Removing IdM host group members using the CLI

You can remove hosts as well as host groups from an IdM host group using a single command.

Prerequisites

  • Administrator privileges for managing IdM or User Administrator role.
  • An active Kerberos ticket. For details, see Using kinit to log in to IdM manually.
  • Optional. Use the ipa hostgroup-find command to confirm that the group includes the member you want to remove.

Procedure

  1. To remove a host group member, use the ipa hostgroup-remove-member command and provide the relevant information. You can specify the type of member to remove using these options:

    • Use the --hosts option to remove one or more hosts from an IdM host group.
      For example, to remove the host named example_member from the group named group_name:

      $ ipa hostgroup-remove-member group_name --hosts example_member
      Host-group: group_name
      Description: My host group
      -------------------------
      Number of members removed 1
      -------------------------
    • Use the --hostgroups option to remove one or more host groups from an IdM host group.
      For example, to remove the host group named nested_group from the group named group_name:

      $ ipa hostgroup-remove-member group_name --hostgroups example_member
      Host-group: group_name
      Description: My host group
      -------------------------
      Number of members removed 1
      -------------------------
Note

Removing a group does not delete the group members from IdM.

  • You can remove multiple hosts and multiple host groups from an IdM host group in one single command using the following syntax:

    $ ipa hostgroup-remove-member group_name --hosts={host1,host2} --hostgroups={group1,group2}

Chapter 23. Managing host groups using the IdM Web UI

This chapter introduces host groups in Identity Management (IdM) and describes the following operations to manage host groups and their members in the Web interface (Web UI):

  • Viewing host groups and their members
  • Creating host groups
  • Deleting host groups
  • Adding host group members
  • Removing host group members

23.1. Host groups in IdM

IdM host groups can be used to centralize control over important management tasks, particularly access control.

Definition of host groups

A host group is an entity that contains a set of IdM hosts with common access control rules and other characteristics. For example, you can define host groups based on company departments, physical locations, or access control requirements.

A host group in IdM can include:

  • IdM servers and clients
  • Other IdM host groups

Host groups created by default

By default, the IdM server creates the host group ipaservers for all IdM server hosts.

Direct and indirect group members

Group attributes in IdM apply to both direct and indirect members: when host group B is a member of host group A, all members of host group B are considered indirect members of host group A.

23.2. Viewing host groups in the IdM Web UI

This section describes how to view IdM host groups using the Web interface (Web UI).

Prerequisites

Procedure

  1. Click Identity → Groups, and select the Host Groups tab.

    • The page lists the existing host groups and their descriptions.
    • You can search for a specific host group.

    idm viewing host groups

  2. Click on a group in the list to display the hosts that belong to this group. You can limit results to direct or indirect members.

    idm viewing host group members

  3. Select the Host Groups tab to display the host groups that belong to this group (nested host groups). You can limit results to direct or indirect members.

    idm viewing host group members nested group

23.3. Creating host groups in the IdM Web UI

This section describes how to create IdM host groups using the Web interface (Web UI).

Prerequisites

Procedure

  1. Click Identity → Groups, and select the Host Groups tab.
  2. Click Add. The Add host group dialog appears.
  3. Provide the information about the group: name (required) and description (optional).
  4. Click Add to confirm.

    idm creating host groups

23.4. Deleting host groups in the IdM Web UI

This section describes how to delete IdM host groups using the Web interface (Web UI).

Prerequisites

Procedure

  1. Click Identity → Groups and select the Host Groups tab.
  2. Select the IdM host group to remove, and click Delete. A confirmation dialog appears.
  3. Click Delete to confirm

    idm deleting host groups

Note

Removing a host group does not delete the group members from IdM.

23.5. Adding host group members in the IdM Web UI

This section describes how to add host group members in IdM using the web interface (Web UI).

Prerequisites

Procedure

  1. Click Identity → Groups and select the Host Groups tab.
  2. Click the name of the group to which you want to add members.
  3. Click the tab Hosts or Host groups depending on the type of members you want to add. The corresponding dialog appears.
  4. Select the hosts or host groups to add, and click the > arrow button to move them to the Prospective column.
  5. Click Add to confirm.

    idm adding host group members

23.6. Removing host group members in the IdM Web UI

This section describes how to remove host group members in IdM using the web interface (Web UI).

Prerequisites

Procedure

  1. Click Identity → Groups and select the Host Groups tab.
  2. Click the name of the group from which you want to remove members.
  3. Click the tab Hosts or Host groups depending on the type of members you want to remove.
  4. Select the check box next to the member you want to remove.
  5. Click Delete. A confirmation dialog appears.

    idm removing host group members

  6. Click Delete to confirm. The selected members are deleted.

Chapter 24. Managing host groups using Ansible playbooks

This chapter describes using Ansible to perform the following operations involving host groups in Identity Management (IdM):

24.1. Ensuring the presence of IdM host groups using Ansible playbooks

This section describes how to ensure the presence of host groups in Identity Management (IdM) using Ansible playbooks.

Note

Without Ansible, host group entries are created in IdM using the ipa hostgroup-add command. The result of adding a host group to IdM is the state of the host group being present in IdM. Because of the Ansible reliance on idempotence, to add a host group to IdM using Ansible, you must create a playbook in which you define the state of the host group as present: state: present.

Prerequisites

  • You know the IdM administrator password.
  • You have installed the ansible-freeipa package on the Ansible controller.

Procedure

  1. Create an inventory file, for example inventory.file, and define ipaserver in it with the list of IdM servers to target:

    [ipaserver]
    server.idm.example.com
  2. Create an Ansible playbook file with the necessary host group information. For example, to ensure the presence of a host group named databases, specify name: databases in the - ipahostgroup task. To simplify this step, you can copy and modify the example in the /usr/share/doc/ansible-freeipa/playbooks/user/ensure-hostgroup-is-present.yml file.

    ---
    - name: Playbook to handle hostgroups
      hosts: ipaserver
      become: true
    
      tasks:
      # Ensure host-group databases is present
      - ipahostgroup:
          ipaadmin_password: Secret123
          name: databases
          state: present

    In the playbook, state: present signifies a request to add the host group to IdM unless it already exists there.

  3. Run the playbook:

    $ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-hostgroup-is-present.yml

Verification steps

  1. Log into ipaserver as admin:

    $ ssh admin@server.idm.example.com
    Password:
    [admin@server /]$
  2. Request a Kerberos ticket for admin:

    $ kinit admin
    Password for admin@IDM.EXAMPLE.COM:
  3. Display information about the host group whose presence in IdM you wanted to ensure:

    $ ipa hostgroup-show databases
      Host-group: databases

The databases host group exists in IdM.

24.2. Ensuring the presence of hosts in IdM host groups using Ansible playbooks

This section describes how to ensure the presence of hosts in host groups in Identity Management (IdM) using Ansible playbooks.

Prerequisites

Procedure

  1. Create an inventory file, for example inventory.file, and define ipaserver in it with the list of IdM servers to target:

    [ipaserver]
    server.idm.example.com
  2. Create an Ansible playbook file with the necessary host information. Specify the name of the host group using the name parameter of the ipahostgroup variable. Specify the name of the host with the host parameter of the ipahostgroup variable. To simplify this step, you can copy and modify the examples in the /usr/share/doc/ansible-freeipa/playbooks/hostgroup/ensure-hosts-and-hostgroups-are-present-in-hostgroup.yml file:

    ---
    - name: Playbook to handle hostgroups
      hosts: ipaserver
      become: true
    
      tasks:
      # Ensure host-group databases is present
      - ipahostgroup:
          ipaadmin_password: Secret123
          name: databases
          host:
          - db.idm.example.com
          action: member

    This playbook adds the db.idm.example.com host to the databases host group. The action: member line indicates that when the playbook is run, no attempt is made to add the databases group itself. Instead, only an attempt is made to add db.idm.example.com to databases.

  3. Run the playbook:

    $ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-hosts-or-hostgroups-are-present-in-hostgroup.yml

Verification steps

  1. Log into ipaserver as admin:

    $ ssh admin@server.idm.example.com
    Password:
    [admin@server /]$
  2. Request a Kerberos ticket for admin:

    $ kinit admin
    Password for admin@IDM.EXAMPLE.COM:
  3. Display information about a host group to see which hosts are present in it:

    $ ipa hostgroup-show databases
      Host-group: databases
      Member hosts: db.idm.example.com

The db.idm.example.com host is present as a member of the databases host group.

24.3. Nesting IdM host groups using Ansible playbooks

This section describes ensuring the presence of nested host groups in Identity Management (IdM) host groups using Ansible playbooks.

Prerequisites

Procedure

  1. Create an inventory file, for example inventory.file, and define ipaserver in it with the list of IdM servers to target:

    [ipaserver]
    server.idm.example.com
  2. Create an Ansible playbook file with the necessary host group information. To ensure that a nested host group A exists in a host group B: in the Ansible playbook, specify, among the - ipahostgroup variables, the name of the host group B using the name variable. Specify the name of the nested hostgroup A with the hostgroup variable. To simplify this step, you can copy and modify the examples in the /usr/share/doc/ansible-freeipa/playbooks/hostgroup/ensure-hosts-and-hostgroups-are-present-in-hostgroup.yml file:

    ---
    - name: Playbook to handle hostgroups
      hosts: ipaserver
      become: true
    
      tasks:
      # Ensure hosts and hostgroups are present in existing databases hostgroup
      - ipahostgroup:
          ipaadmin_password: Secret123
          name: databases
          hostgroup:
          - mysql-server
          - oracle-server
          action: member

    This Ansible playbook ensures the presence of the myqsl-server and oracle-server host groups in the databases host group. The action: member line indicates that when the playbook is run, no attempt is made to add the databases group itself to IdM.

  3. Run the playbook:

    $ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-hosts-or-hostgroups-are-present-in-hostgroup.yml

Verification steps

  1. Log into ipaserver as admin:

    $ ssh admin@server.idm.example.com
    Password:
    [admin@server /]$
  2. Request a Kerberos ticket for admin:

    $ kinit admin
    Password for admin@IDM.EXAMPLE.COM:
  3. Display information about the host group in which nested host groups are present:

    $ ipa hostgroup-show databases
      Host-group: databases
      Member hosts: db.idm.example.com
      Member host-groups: mysql-server, oracle-server

The mysql-server and oracle-server host groups exist in the databases host group.

24.4. Ensuring the absence of hosts from IdM host groups using Ansible playbooks

This section describes how to ensure the absence of hosts from host groups in Identity Management (IdM) using Ansible playbooks.

Prerequisites

Procedure

  1. Create an inventory file, for example inventory.file, and define ipaserver in it with the list of IdM servers to target:

    [ipaserver]
    server.idm.example.com
  2. Create an Ansible playbook file with the necessary host and host group information. Specify the name of the host group using the name parameter of the ipahostgroup variable. Specify the name of the host whose absence from the host group you want to ensure using the host parameter of the ipahostgroup variable. To simplify this step, you can copy and modify the examples in the /usr/share/doc/ansible-freeipa/playbooks/hostgroup/ensure-hosts-and-hostgroups-are-absent-in-hostgroup.yml file:

    ---
    - name: Playbook to handle hostgroups
      hosts: ipaserver
      become: true
    
      tasks:
      # Ensure host-group databases is absent
      - ipahostgroup:
          ipaadmin_password: Secret123
          name: databases
          host:
          - db.idm.example.com
          action: member
          state: absent

    This playbook ensures the absence of the db.idm.example.com host from the databases host group. The action: member line indicates that when the playbook is run, no attempt is made to remove the databases group itself.

  3. Run the playbook:

    $ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-hosts-or-hostgroups-are-absent-in-hostgroup.yml

Verification steps

  1. Log into ipaserver as admin:

    $ ssh admin@server.idm.example.com
    Password:
    [admin@server /]$
  2. Request a Kerberos ticket for admin:

    $ kinit admin
    Password for admin@IDM.EXAMPLE.COM:
  3. Display information about the host group and the hosts it contains:

    $ ipa hostgroup-show databases
      Host-group: databases
      Member host-groups: mysql-server, oracle-server

The db.idm.example.com host does not exist in the databases host group.

24.5. Ensuring the absence of nested host groups from IdM host groups using Ansible playbooks

This section describes how to ensure the absence of nested host groups from outer host groups in Identity Management (IdM) using Ansible playbooks.

Prerequisites

Procedure

  1. Create an inventory file, for example inventory.file, and define ipaserver in it with the list of IdM servers to target:

    [ipaserver]
    server.idm.example.com
  2. Create an Ansible playbook file with the necessary host group information. Specify, among the - ipahostgroup variables, the name of the outer host group using the name variable. Specify the name of the nested hostgroup with the hostgroup variable. To simplify this step, you can copy and modify the examples in the /usr/share/doc/ansible-freeipa/playbooks/hostgroup/ensure-hosts-and-hostgroups-are-absent-in-hostgroup.yml file:

    ---
    - name: Playbook to handle hostgroups
      hosts: ipaserver
      become: true
    
      tasks:
      # Ensure hosts and hostgroups are absent in existing databases hostgroup
      - ipahostgroup:
          ipaadmin_password: Secret123
          name: databases
          hostgroup:
          - mysql-server
          - oracle-server
          action: member
          state: absent

    This playbook makes sure that the mysql-server and oracle-server host groups are absent from the databases host group. The action: member line indicates that when the playbook is run, no attempt is made to ensure the databases group itself is deleted from IdM.

  3. Run the playbook:

    $ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-hosts-or-hostgroups-are-absent-in-hostgroup.yml

Verification steps

  1. Log into ipaserver as admin:

    $ ssh admin@server.idm.example.com
    Password:
    [admin@server /]$
  2. Request a Kerberos ticket for admin:

    $ kinit admin
    Password for admin@IDM.EXAMPLE.COM:
  3. Display information about the host group from which nested host groups should be absent:

    $ ipa hostgroup-show databases
      Host-group: databases

The output confirms that the mysql-server and oracle-server nested host groups are absent from the outer databases host group.

24.6. Ensuring the ansence of IdM host groups using Ansible playbooks

This section describes how to ensure the absence of host groups in Identity Management (IdM) using Ansible playbooks.

Note

Without Ansible, host group entries are removed from IdM using the ipa hostgroup-del command. The result of removing a host group from IdM is the state of the host group being absent from IdM. Because of the Ansible reliance on idempotence, to remove a host group from IdM using Ansible, you must create a playbook in which you define the state of the host group as absent: state: absent.

Prerequisites

  • You know the IdM administrator password.
  • You have installed the ansible-freeipa package on the Ansible controller.

Procedure

  1. Create an inventory file, for example inventory.file, and define ipaserver in it with the list of IdM servers to target:

    [ipaserver]
    server.idm.example.com
  2. Create an Ansible playbook file with the necessary host group information. To simplify this step, you can copy and modify the example in the /usr/share/doc/ansible-freeipa/playbooks/user/ensure-hostgroup-is-absent.yml file.

    ---
    - name: Playbook to handle hostgroups
      hosts: ipaserver
      become: true
    
      tasks:
      # Ensure host-group databases is absent
      - ipahostgroup:
          ipaadmin_password: Secret123
          name: databases
          state: absent

    This playbook ensures the absence of the databases host group from IdM. The state: absent means a request to delete the host group from IdM unless it is already deleted.

  3. Run the playbook:

    $ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-hostgroup-is-absent.yml

Verification steps

  1. Log into ipaserver as admin:

    $ ssh admin@server.idm.example.com
    Password:
    [admin@server /]$
  2. Request a Kerberos ticket for admin:

    $ kinit admin
    Password for admin@IDM.EXAMPLE.COM:
  3. Display information about the host group whose absence you ensured:

    $ ipa hostgroup-show databases
    ipa: ERROR: databases: host group not found

The databases host group does not exist in IdM.

Chapter 25. Managing Kerberos ticket policies

Kerberos ticket policies in Identity Management (IdM) set restrictions on Kerberos ticket access, duration, and renewal. You can configure Kerberos ticket policies for the Key Distribution Center (KDC) running on your IdM server.

This chapter presents the following Kerberos ticket management topics and tasks:

25.1. The role of the IdM KDC

Identity Management’s authentication mechanisms use the Kerberos infrastructure established by the Key Distribution Center (KDC). The KDC is the trusted authority that stores credential information and ensures the authenticity of data originating from entities within the IdM network.

Each IdM user, service, and host acts as a Kerberos client and is identified by a unique Kerberos principal:

  • For users: identifier@REALM, such as admin@EXAMPLE.COM
  • For services: service/fully-qualified-hostname@REALM, such as http/master.example.com@EXAMPLE.COM
  • For hosts: host/fully-qualified-hostname@REALM, such as host/client.example.com@EXAMPLE.COM

The following image is a simplification of the communication between a Kerberos client, the KDC, and a Kerberized application that the client wants to communicate with.

Kerberos KDC flow of communication
  1. A Kerberos client identifies itself to the KDC by authenticating as a Kerberos principal. For example, an IdM user performs kinit username and provides their password.
  2. The KDC checks for the principal in its database, authenticates the client, and evaluates Kerberos ticket policies to determine whether to grant the request.
  3. The KDC issues the client a ticket-granting ticket (TGT) with a lifecycle and authentication indicators according to the appropriate ticket policy.
  4. With the TGT, the client requests a service ticket from the KDC to communicate with a Kerberized service on a target host.
  5. The KDC checks if the client’s TGT is still valid, and evaluates the service ticket request against ticket policies.
  6. The KDC issues the client a service ticket.
  7. With the service ticket, the client can initiate encrypted communication with the service on the target host.

25.2. IdM Kerberos ticket policy types

IdM Kerberos ticket policies implement the following ticket policy types:

Connection policy

To protect Kerberized services with different levels of security, you can define connection policies to enforce rules based on which pre-authentication mechanism a client used to retrieve a ticket-granting ticket (TGT).

For example, you can require smart card authentication to connect to client1.example.com, and require two-factor authentication to access the testservice application on client2.example.com.

To enforce connection policies, associate authentication indicators with services. Only clients that have the required authentication indicators in their service ticket requests are able to access those services. For more information, see Kerberos authentication indicators.

Ticket lifecycle policy

Each Kerberos ticket has a lifetime and a potential renewal age: you can renew a ticket before it reaches its maximum lifetime, but not after it exceeds its maximum renewal age.

The default global ticket lifetime is one day (86400 seconds) and the default global maximum renewal age is one week (604800 seconds). To adjust these global values, see Configuring the global ticket lifecycle policy.

You can also define your own ticket lifecycle policies:

25.3. Kerberos authentication indicators

The Kerberos Key Distribution Center (KDC) attaches authentication indicators to a ticket-granting ticket (TGT) based on which pre-authentication mechanism the client used prove its identity:

otp
two-factor authentication (password + One-Time Password)
radius
RADIUS authentication (commonly for 802.1x authentication)
pkinit
PKINIT, smart card, or certificate authentication
hardened
hardened passwords (SPAKE or FAST)[1]

The KDC then attaches the authentication indicators from the TGT to any service ticket requests that stem from it. The KDC enforces policies such as service access control, maximum ticket lifetime, and maximum renewable age based on the authentication indicators.

25.3.1. Authentication indicators and IdM services

If you associate a service or a host with an authentication indicator, only clients that used the corresponding authentication mechanism to obtain a TGT will be able to access it. The KDC, not the application or service, checks for authentication indicators in service ticket requests, and grants or denies requests based on Kerberos connection policies.

For example, to require two-factor authentication to connect to host secure.example.com, associate the otp authentication indicator with the host/secure.example.com@EXAMPLE.COM Kerberos principal. Only users who used a One-Time password to obtain their initial TGT from the KDC will be able to log in.

If a service or a host has no authentication indicators assigned to it, it will accept tickets authenticated by any mechanism.

Additional resources



[1] A hardened password is protected against brute-force password dictionary attacks by using Single-Party Public-Key Authenticated Key Exchange (SPAKE) pre-authentication and/or Flexible Authentication via Secure Tunneling (FAST) armoring.

25.4. Enforcing authentication indicators for an IdM service

This procedure describes creating an IdM service and configuring it to require particular Kerberos authentication indicators from incoming service ticket requests.

By associating authentication indicators with an IdM service, only clients who used those specific pre-authentication mechanisms to obtain their initial ticket-granting ticket (TGT) will be able to access the service.

25.4.1. Creating an IdM service entry and its Kerberos keytab

Adding an IdM service entry to IdM for a service running on an IdM host creates a corresponding Kerberos principal, and allows the service to request an SSL certificate, a Kerberos keytab, or both.

The following procedure describes creating an IdM service entry and generating an associated Kerberos keytab for encrypting communication with that service.

Prerequisites

  • Your service can store a Kerberos principal, an SSL certificate, or both.

Procedure

  1. Add an IdM service with the ipa service-add command to create a Kerberos principal associated with it. For example, to create the IdM service entry for the testservice application that runs on host client.example.com:

    [root@client ~]# ipa service-add testservice/client.example.com
    -------------------------------------------------------------
    Modified service "testservice/client.example.com@EXAMPLE.COM"
    -------------------------------------------------------------
      Principal name: testservice/client.example.com@EXAMPLE.COM
      Principal alias: testservice/client.example.com@EXAMPLE.COM
      Managed by: client.example.com
  2. Generate and store a Kerberos keytab for the service on the client.

    [root@client ~]# ipa-getkeytab -k /etc/testservice.keytab -p testservice/client.example.com
    Keytab successfully retrieved and stored in: /etc/testservice.keytab

Verification steps

  • Display information about an IdM service with the ipa service-show command.

    [root@server ~]# ipa service-show testservice/client.example.com
      Principal name: testservice/client.example.com@EXAMPLE.COM
      Principal alias: testservice/client.example.com@EXAMPLE.COM
      Keytab: True
      Managed by: client.example.com
  • Display the contents of the service’s Kerberos keytab with the klist command.

    [root@server etc]# klist -ekt /etc/testservice.keytab
    Keytab name: FILE:/etc/testservice.keytab
    KVNO Timestamp           Principal
    ---- ------------------- ------------------------------------------------------
       2 04/01/2020 17:52:55 testservice/client.example.com@EXAMPLE.COM (aes256-cts-hmac-sha1-96)
       2 04/01/2020 17:52:55 testservice/client.example.com@EXAMPLE.COM (aes128-cts-hmac-sha1-96)
       2 04/01/2020 17:52:55 testservice/client.example.com@EXAMPLE.COM (camellia128-cts-cmac)
       2 04/01/2020 17:52:55 testservice/client.example.com@EXAMPLE.COM (camellia256-cts-cmac)

25.4.2. Associating authentication indicators with an IdM service

This procedure describes configuring a service to require particular Kerberos authentication indicators from incoming service ticket requests.

Prerequisites

Warning

Do not assign authentication indicators to internal IdM services. The following IdM services cannot perform the interactive authentication steps required by PKINIT and multi-factor authentication methods:

host/server.example.com@EXAMPLE.COM
HTTP/server.example.com@EXAMPLE.COM
ldap/server.example.com@EXAMPLE.COM
DNS/server.example.com@EXAMPLE.COM
cifs/server.example.com@EXAMPLE.COM

Procedure

  • Use the ipa service-mod command to specify one or more required authentication indicators for a service, identified with the --auth-ind argument.

    Authentication method--auth-ind value

    Two-factor authentication

    otp

    RADIUS authentication

    radius

    PKINIT, smart card, or certificate authentication

    pkinit

    Hardened passwords (SPAKE or FAST)

    hardened

    For example, to require that a user was authenticated with smart card or OTP authentication to retrieve a service ticket for the testservice principal on host client.example.com:

    [root@server ~]# ipa service-mod testservice/client.example.com@EXAMPLE.COM --auth-ind otp --auth-ind pkinit
    -------------------------------------------------------------
    Modified service "testservice/client.example.com@EXAMPLE.COM"
    -------------------------------------------------------------
      Principal name: testservice/client.example.com@EXAMPLE.COM
      Principal alias: testservice/client.example.com@EXAMPLE.COM
      Authentication Indicators: otp, pkinit
      Managed by: client.example.com
Note

To remove all authentication indicators from a service, provide an empty list of indicators:

[root@server ~]# ipa service-mod testservice/client.example.com@EXAMPLE.COM --auth-ind ''
------------------------------------------------------
Modified service "testservice/client.example.com@EXAMPLE.COM"
------------------------------------------------------
  Principal name: testservice/client.example.com@EXAMPLE.COM
  Principal alias: testservice/client.example.com@EXAMPLE.COM
  Managed by: client.example.com

Verification steps

  • Display information about an IdM service, including the authentication indicators it requires, with the ipa service-show command.

    [root@server ~]# ipa service-show testservice/client.example.com
      Principal name: testservice/client.example.com@EXAMPLE.COM
      Principal alias: testservice/client.example.com@EXAMPLE.COM
      Authentication Indicators: otp, pkinit
      Keytab: True
      Managed by: client.example.com

Additional resources

25.4.3. Retrieving a Kerberos service ticket for an IdM service

The following procedure describes retrieving a Kerberos service ticket for an IdM service. You can use this procedure to test Kerberos ticket policies.

Prerequisites

Procedure

  • Use the kvno command with the -S option to retrieve a service ticket, and specify the name of the IdM service and the fully-qualified domain name of the host that manages it.

    [root@server ~]# kvno -S testservice client.example.com
    testservice/client.example.com@EXAMPLE.COM: kvno = 1
Note

If you need to access an IdM service and your current ticket-granting ticket (TGT) does not possess the required authentication indicators associated with it, clear your current Kerberos credentials cache with the kdestroy command and retrieve a new TGT:

[root@server ~]# kdestroy

For example, if you initially retrieved a TGT by authenticating with a password, and you need to access an IdM service that has the pkinit authentication indicator associated with it, destroy your current credentials cache and re-authenticate with a smart card. See Kerberos authentication indicators.

Verification steps

  • Use the klist command to verify that the service ticket is in the default Kerberos credentials cache.

    [root@server etc]# klist_
    Ticket cache: KCM:1000
    Default principal: admin@EXAMPLE.COM
    
    Valid starting       Expires              Service principal
    04/01/2020 12:52:42  04/02/2020 12:52:39  krbtgt/EXAMPLE.COM@EXAMPLE.COM
    04/01/2020 12:54:07 04/02/2020 12:52:39 testservice/client.example.com@EXAMPLE.COM

25.4.4. Additional resources

25.5. Configuring the global ticket lifecycle policy

The global ticket policy applies to all service tickets and to users that do not have any per-user ticket policies defined.

The following procedure describes adjusting the maximum ticket lifetime and maximum ticket renewal age for the global Kerberos ticket policy using the ipa krbtpolicy-mod command.

While using the ipa krbtpolicy-mod command, specify at least one of the following arguments:

  • --maxlife for the maximum ticket lifetime in seconds
  • --maxrenew for the maximum renewable age in seconds

Procedure

  • To modify the global ticket policy:

    [root@server ~]# ipa krbtpolicy-mod --maxlife=$((8*60*60)) --maxrenew=$((24*60*60))
      Max life: 28800
      Max renew: 86400

    In this example, the maximum lifetime is set to eight hours (8 * 60 minutes * 60 seconds) and the maximum renewal age is set to one day (24 * 60 minutes * 60 seconds).

  • Optional: To reset the global Kerberos ticket policy to the default installation values:

    [root@server ~]# ipa krbtpolicy-reset
      Max life: 86400
      Max renew: 604800

Verification steps

  • Display the global ticket policy:

    [root@server ~]# ipa krbtpolicy-show
      Max life: 28800
      Max renew: 86640

Additional resources

25.6. Configuring global ticket policies per authentication indicator

This procedure describes adjusting the global maximum ticket lifetime and maximum renewable age for each authentication indicator. These settings apply to users that do not have per-user ticket policies defined.

Use the ipa krbtpolicy-mod command to specify the global maximum lifetime or maximum renewable age for Kerberos tickets depending on the authentication indicators attached to them.

Procedure

  • For example, to set the global two-factor ticket lifetime and renewal age values to one week, and the global smart card ticket lifetime and renewal age values to two weeks:

    [root@server ~]# ipa krbtpolicy-mod --otp-maxlife=604800 --otp-maxrenew=604800 --pkinit-maxlife=172800 --pkinit-maxrenew=172800

Verification steps

  • Display the global ticket policy:

    [root@server ~]# ipa krbtpolicy-show
      Max life: 86400
      OTP max life: 604800
      PKINIT max life: 172800
      Max renew: 604800
      OTP max renew: 604800
      PKINIT max renew: 172800

    Notice that the OTP and PKINIT values are different from the global default Max life and Max renew values.

Additional resources

25.7. Configuring the default ticket policy for a user

You can define a unique Kerberos ticket policy that only applies to a single user. These per-user settings override the global ticket policy, for all authentication indicators.

Use the ipa krbtpolicy-mod username command, and specify at least one of the following arguments:

  • --maxlife for the maximum ticket lifetime in seconds
  • --maxrenew for the maximum renewable age in seconds

Procedure

  • For example, to set the IdM admin user’s maximum ticket lifetime to two days and maximum renewal age to two weeks:

    [root@server ~]# ipa krbtpolicy-mod admin --maxlife=172800 --maxrenew=1209600
      Max life: 172800
      Max renew: 1209600
  • Optional: To reset the ticket policy for a user:

    [root@server ~]# ipa krbtpolicy-reset admin

Verification steps

  • Display the effective Kerberos ticket policy that applies to a user:

    [root@server ~]# ipa krbtpolicy-show admin
      Max life: 172800
      Max renew: 1209600

Additional resources

25.8. Configuring individual authentication indicator ticket policies for a user

As an administrator, you can define Kerberos ticket policies for a user that differ per authentication indicator. For example, you can configure a policy to allow the IdM admin user to renew a ticket for two days if it was obtained with OTP authentication, and a week if it was obtained with smart card authentication.

These per-authentication indicator settings will override the user’s default ticket policy, the global default ticket policy, and any global authentication indicator ticket policy.

Use the ipa krbtpolicy-mod username command to set custom maximum lifetime and maximum renewable age values for a user’s Kerberos tickets depending on the authentication indicators attached to them.

Procedure

  • For example, to allow the IdM admin user to renew a Kerberos ticket for two days if it was obtained with One-Time Password authentication, set the --otp-maxrenew option:

    [root@server ~]# ipa krbtpolicy-mod admin --otp-maxrenew=$((2*24*60*60))
      OTP max renew: 172800
  • Optional: To reset the ticket policy for a user:

    [root@server ~]# ipa krbtpolicy-reset username

Verification steps

  • Display the effective Kerberos ticket policy that applies to a user:

    [root@server ~]# ipa krbtpolicy-show admin
      Max life: 28800
      Max renew: 86640

Additional resources

25.9. Authentication indicator options for the krbtpolicy-mod command

Specify values for authentication indicators with the following arguments.

Table 25.1. Authentication indicator options for the krbtpolicy-mod command

Authentication indicatorArgument for maximum lifetimeArgument for maximum renewal age

otp

--otp-maxlife

--otp-maxrenew

radius

--radius-maxlife

--radius-maxrenew

pkinit

--pkinit-maxlife

--pkinit-maxrenew

hardened

--hardened-maxlife

--hardened-maxrenew

Chapter 26. Defining IdM Password Policies

This chapter describes Identity Management (IdM) password policies and how to add a new password policy in IdM using an Ansible playbook.

26.1. What is a password policy

A password policy is a set of rules that passwords must meet. For example, a password policy can define the minimum password length and the maximum password lifetime. All users affected by this policy are required to set a sufficiently long password and change it frequently enough to meet the specified conditions. In this way, password policies help reduce the risk of someone discovering and misusing a user’s password.

26.2. Password policies in IdM

Passwords are the most common way for Identity Management (IdM) users to authenticate to the IdM Kerberos domain. Password policies define the requirements that these IdM user passwords must meet.

Note

The IdM password policy is set in the underlying LDAP directory, but the Kerberos Key Distribution Center (KDC) enforces the password policy.

Password policy attributes lists the attributes you can use to define a password policy in IdM.

Table 26.1. Password Policy Attributes

AttributeExplanationExample

Max lifetime

The maximum amount of time in days that a password is valid before a user must reset it.

Max lifetime = 90

User passwords are valid only for 90 days. After that, IdM prompts users to change them.

Min lifetime

The minimum amount of time in hours that must pass between two password change operations.

Min lifetime = 1

After users change their passwords, they must wait at least 1 hour before changing them again.

History size

The number of previous passwords that are stored. A user cannot reuse a password from their password history but can reuse old passwords that are not stored.

History size = 0

In this case, the password history is empty and users can reuse any of their previous passwords.

Character classes

The number of different character classes the user must use in the password. The character classes are:

* Uppercase characters

* Lowercase characters

* Digits

* Special characters, such as comma (,), period (.), asterisk (*)

* Other UTF-8 characters

Using a character three or more times in a row decreases the character class by one. For example:

* Secret1 has 3 character classes: uppercase, lowercase, digits

* Secret111 has 2 character classes: uppercase, lowercase, digits, and a -1 penalty for using 1 repeatedly

Character classes = 0

The default number of classes required is 0. To configure the number, run the ipa pwpolicy-mod command with the --minclasses option.

See also the Important note below this table.

Min length

The minimum number of characters in a password.

Min length = 8

Users cannot use passwords shorter than 8 characters.

Max failures

The maximum number of failed login attempts before IdM locks the user account.

Max failures = 6

IdM locks the user account when the user enters a wrong password 7 times in a row.

Failure reset interval

The amount of time in seconds after which IdM resets the current number of failed login attempts.

Failure reset interval = 60

If the user waits for more than 1 minute after the number of failed login attempts defined in Max failures, the user can attempt to log in again without risking a user account lock.

Lockout duration

The amount of time in seconds that the user account is locked after the number of failed login attempts defined in Max failures.

Lockout duration = 600

Users with locked accounts are unable to log in for 10 minutes.

Important

Use the English alphabet and common symbols for the character classes requirement if you have a diverse set of hardware that may not have access to international characters and symbols. For more information about character class policies in passwords, see What characters are valid in a password? in Red Hat Knowledgebase.

26.3. Ensuring the presence of a password policy in IdM using an Ansible playbook

This section describes how to ensure the presence of a password policy in Identity Management (IdM) using an Ansible playbook.

In the default global_policy password policy in IdM, the number of different character classes in the password is set to 0. The history size is also set to 0.

Complete this procedure to enforce a stronger password policy for an IdM group using an Ansible playbook.

Note

You can only define a password policy for an IdM group. You cannot define a password policy for an individual user.

Prerequisites

  • You have installed the ansible-freeipa package on the Ansible controller.
  • You know the IdM administrator password.
  • The group for which you are ensuring the presence of a password policy exists in IdM.

Procedure

  1. Create an inventory file, for example inventory.file, and define the FQDN of your IdM server in the [ipaserver] section:

    [ipaserver]
    server.idm.example.com
  2. Create your Ansible playbook file that defines the password policy whose presence you want to ensure. To simplify this step, copy and modify the example in the /usr/share/doc/ansible-freeipa/playbooks/pwpolicy/pwpolicy_present.yml file:

    ---
    - name: Tests
      hosts: ipaserver
      become: true
      gather_facts: false
    
      tasks:
      - name: Ensure presence of pwpolicy for group ops
        ipapwpolicy:
          ipaadmin_password: Secret123
          name: ops
          minlife: 7
          maxlife: 49
          history: 5
          priority: 1
          lockouttime: 300
          minlength: 8
          minclasses: 4
          maxfail: 3
          failinterval: 5

    For details on what the individual variables mean, see Password policy attributes.

  3. Run the playbook:

    $ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory_/new_pwpolicy_present.yml

You have successfully used an Ansible playbook to ensure that a password policy for the ops group is present in IdM.

Important

The priority of the ops password policy is set to 1, whereas the global_policy password policy has no priority set. For this reason, the ops policy automatically supersedes global_policy for the ops group and is enforced immediately.

global_policy serves as a fallback policy when no group policy is set for a user, and it can never take precedence over a group policy.

Additional resources

  • For more details about using Ansible to define password policies in IdM and about playbook variables, see the README-pwpolicy.md Markdown file available in the /usr/share/doc/ansible-freeipa/ directory.
  • For more details about how password policy priorities work in IdM, see Password policy priorities in RHEL 7 documentation.

Chapter 27. Granting sudo access to an IdM user on an IdM client

27.1. Sudo access on an IdM client

System administrators can grant sudo access to allow non-root users to execute administrative commands that are normally reserved for the root user. Consequently, when users need to perform an administrative command normally reserved for the root user, they precede that command with sudo. After entering their password, the command is executed as if they were the root user.

If a Red Hat Enterprise Linux (RHEL) 8 host is enrolled as an Identity Management (IdM) client, you can specify sudo rules defining which IdM users can perform which commands on the host in the following ways:

  • Locally in the /etc/sudoers file
  • Centrally in IdM

This chapter describes creating a central sudo rule for an IdM client using IdM Web UI. For details on creating local sudo rules on a RHEL 8 host, see Managing sudo access.

Note that you can also define central IdM sudo rules using the IdM command-line interface.

27.2. Granting sudo access to an IdM user on an IdM client using IdM Web UI

In Identity Management (IdM), you can grant sudo access for a specific command to an IdM user account on a specific IdM host. First, add a sudo command and then create a sudo rule for one or more commands.

Complete this procedure to create the idm_user_reboot sudo rule to grant idm_user the permission to run the /usr/sbin/reboot command on the idmclient machine.

Prerequisites

  • You are logged in as IdM administrator.
  • You have created a user account for idm_user in IdM and unlocked the account by creating a password for the user. For details on adding a new IdM user using the command-line interface, see Adding users using the command line.
  • No local idm_user account has been created on idmclient. The idm_user user is not listed in the local /etc/passwd file.

Procedure

  1. Add the /usr/sbin/reboot command to the IdM database of sudo commands:

    1. Navigate to PolicySudoSudo Commands.
    2. Click Add in the upper right corner to open the Add sudo command dialog box.
    3. Enter the command you want the user to be able to perform using sudo: /usr/sbin/reboot.

      Figure 27.1. Adding IdM sudo command

      adding IdM sudo command
    4. Click Add.
  2. Use the new sudo command entry to create a sudo rule to allow idm_user to reboot the idmclient machine:

    1. Navigate to PolicySudoSudo rules.
    2. Click Add in the upper right corner to open the Add sudo rule dialog box.
    3. Enter the name of the sudo rule: idm_user_reboot.
    4. Click Add and Edit.
    5. Specify the user:

      1. In the Who section, check the Specified Users and Groups radio button.
      2. In the User category the rule applies to subsection, click Add to open the Add users into sudo rule "idm_user_reboot" dialog box.
      3. In the Add users into sudo rule "idm_user_reboot" dialog box in the Available column, check the idm_user checkbox, and move it to the Prospective column.
      4. Click Add.
    6. Specify the host:

      1. In the Access this host section, check the Specified Hosts and Groups radio button.
      2. In the Host category this rule applies to subsection, click Add to open the Add hosts into sudo rule "idm_user_reboot" dialog box.
      3. In the Add hosts into sudo rule "idm_user_reboot" dialog box in the Available column, check the idmclient.idm.example.com checkbox, and move it to the Prospective column.
      4. Click Add.
      1. Specify the commands:

        1. In the Command category the rule applies to subsection of the Run Commands section, check the Specified Commands and Groups radio button.
        2. In the Sudo Allow Commands subsection, click Add to open the Add allow sudo commands into sudo rule "idm_user_reboot" dialog box.
        3. In the Add allow sudo commands into sudo rule "idm_user_reboot" dialog box in the Available column, check the /usr/sbin/reboot checkbox, and move it to the Prospective column.
        4. Click Add to return to the idm_sudo_reboot page.

          Figure 27.2. Adding IdM sudo rule

          IdM sudo rule WebUI
    7. Click Save in the top left corner.

The new rule is enabled by default.

Verification steps

Test that the sudo rule that you have set up on the IdM server works on idmclient by verifying that idm_user can now reboot idmclient using sudo. Note that propagating the changes from the server to the client can take a few minutes.

  1. Log in to idmclient as idm_user.
  2. Reboot the machine using sudo. Enter the password for idm_user when prompted:

    $ sudo /usr/sbin/reboot
    [sudo] password for idm_user:

If sudo is configured correctly, the machine reboots.

27.3. Using an Ansible playbook to ensure sudo access for an IdM user on an IdM client

In Identity Management (IdM), you can ensure sudo access to a specific command is granted to an IdM user account on a specific IdM host.

Complete this procedure to ensure a sudo rule named idm_user_reboot exists. The rule grants idm_user the permission to run the /usr/sbin/reboot command on the idmclient machine.

Prerequisites

Procedure

  1. Create an inventory file, for example inventory.file, and define ipaservers in it:

    [ipaservers]
    server.idm.example.com
  2. Add one or more sudo commands:

    1. Create an ensure-reboot-sudocmd-is-present.yml Ansible playbook that ensures the presence of the /usr/sbin/reboot command in the IdM database of sudo commands. To simplify this step, you can copy and modify the example in the /usr/share/doc/ansible-freeipa/playbooks/sudocmd/ensure-sudocmd-is-present.yml file:

      ---
      - name: Playbook to manage sudo command
        hosts: ipaserver
        become: true
      
        tasks:
        # Ensure sudo command is present
        - ipasudocmd:
            ipaadmin_password: Secret123
            name: /usr/sbin/reboot
            state: present
    2. Run the playbook:

      $ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-reboot-sudocmd-is-present.yml
  3. Create a sudo rule that references the commands:

    1. Create an ensure-sudorule-for-idmuser-on-idmclient-is-present.yml Ansible playbook that uses the sudo command entry to ensure the presence of a sudo rule. The sudo rule allows idm_user to reboot the idmclient machine. To simplify this step, you can copy and modify the example in the /usr/share/doc/ansible-freeipa/playbooks/sudorule/ensure-sudorule-is-present.yml file:

      ---
      - name: Tests
        hosts: ipaserver
        become: true
      
        tasks:
        # Ensure a sudorule is present granting idm_user the permission to run /usr/sbin/reboot on idmclient
        - ipasudorule:
            ipaadmin_password: Secret123
            name: idm_user_reboot
            description: A test sudo rule.
            allow_sudocmd: /usr/sbin/reboot
            host: idmclient.idm.example.com
            user: idm_user
            state: present
    2. Run the playbook:

      $ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-sudorule-for-idmuser-on-idmclient-is-present.yml

Verification steps

Test that the sudo rule whose presence you have ensured on the IdM server works on idmclient by verifying that idm_user can reboot idmclient using sudo. Note that it can take a few minutes for the changes made on the server to take effect on the client.

  1. Log in to idmclient as idm_user.
  2. Reboot the machine using sudo. Enter the password for idm_user when prompted:

    $ sudo /usr/sbin/reboot
    [sudo] password for idm_user:

If sudo is configured correctly, the machine reboots.

Additional materials

  • For more details on how to apply sudo commands, command groups, and rules in IdM using an Ansible playbook including the descriptions of playbook variables, see the README-sudocmd.md, README-sudocmdgroup.md, and README-sudorule.md Markdown files available in the /usr/share/doc/ansible-freeipa/ directory.

Chapter 28. Ensuring the presence of host-based access control rules in IdM using Ansible playbooks

This chapter describes Identity Management (IdM) host-based access policies and how to define them using Ansible.

Ansible is an automation tool used to configure systems, deploy software, and perform rolling updates. It includes support for Identity Management (IdM).

28.1. Host-based access control rules in IdM

Host-based access control (HBAC) rules define which users or user groups can access which hosts or host groups by using which services or services in a service group. As a system administrator, you can use HBAC rules to achieve the following goals:

  • Limit access to a specified system in your domain to members of a specific user group.
  • Allow only a specific service to be used to access systems in your domain.

By default, IdM is configured with a default HBAC rule named allow_all, which means universal access to every host for every user via every relevant service in the entire IdM domain.

You can fine-tune access to different hosts by replacing the default allow_all rule with your own set of HBAC rules. For centralized and simplified access control management, you can apply HBAC rules to user groups, host groups, or service groups instead of individual users, hosts, or services.

28.2. Ensuring the presence of an HBAC rule in IdM using an Ansible playbook

This section describes how to ensure the presence of a host-based access control (HBAC) rule in Identity Management (IdM) using an Ansible playbook.

Prerequisites

Procedure

  1. Create an inventory file, for example inventory.file, and define ipaserver in it:

    [ipaserver]
    server.idm.example.com
  2. Create your Ansible playbook file that defines the HBAC policy whose presence you want to ensure. To simplify this step, you can copy and modify the example in the /usr/share/doc/ansible-freeipa/playbooks/hbacrule/ensure-hbacrule-allhosts-present.yml file:

    ---
    - name: Playbook to handle hbacrules
      hosts: ipaserver
      become: true
    
      tasks:
      # Ensure idm_user can access client.idm.example.com via the sshd service
      - ipahbacrule:
          ipaadmin_password: Secret123
          name: login
          user: idm_user
          host: client.idm.example.com
          hbacsvc:
          - sshd
          state: present
  3. Run the playbook:

    $ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-new-hbacrule-present.yml

Verification steps

  1. Log in to the IdM Web UI as administrator.
  2. Navigate to PolicyHost-Based-Access-ControlHBAC Test.
  3. In the Who tab, select idm_user.
  4. In the Accessing tab, select client.idm.example.com.
  5. In the Via service tab, select sshd.
  6. In the Rules tab, select login.
  7. In the Run test tab, click the Run test button. If you see ACCESS GRANTED, the HBAC rule is implemented successfully.

Additional resources

  • For more details about and examples of, configuring HBAC services, service groups, and rules using Ansible, see the README-hbacsvc.md, README-hbacsvcgroup.md, and README-hbacrule.md Markdown files. These files are available in the /usr/share/doc/ansible-freeipa directory. Also see the playbooks available in the relevant subdirectories of the /usr/share/doc/ansible-freeipa/playbooks directory.

Chapter 29. Public key certificates in Identity Management

This chapter introduces X.509 public key certificates, which are used to authenticate users, hosts and services in Identity Management (IdM). In addition to authentication, X.509 certificates also enable digital signing and encryption to provide privacy, integrity and non-repudiation.

A certificate contains information about

  • the subject that the certificate authenticates
  • who has signed (validated) the certificate, that is the issuer
  • the start and end of the validity of the certificate
  • the valid uses of the certificate
  • the public key of the subject

A message encrypted by the public key can only be decrypted by a corresponding private key. Although a certificate and the public key it includes can be made freely available, a user, host or machine must keep their private key secret.

29.1. Certificate authorities in IdM

Certificate authorities operate in a hierarchy of trust. In an IdM environment with an internal Certificate Authority (CA), all the IdM hosts, users and services trust certificates that have been signed by the CA. Apart from this root CA, IdM supports sub-CAs to which the root CA has granted the ability to sign certificates in their turn. Frequently, the certificates that such sub-CAs are able to sign are certificates of a specific kind, for example VPN certificates.

From the certificate point of view, there is no difference between being signed by a self-signed IdM CA and being signed externally.

The role of the CA is the following:

  • It issues and verifies digital certificates
  • It signs the certificate to prove that the certificate belongs to the user, host or service that presents it
  • In an IdM environment with an internal CA, the CA which is the Certificate Renewal Master and which maintains the Certificate Revocation List (CRL) is the highest authority

29.2. Comparison of certificates and Kerberos

Certificates perform a similar function to that performed by Kerberos tickets. Kerberos is a computer network authentication protocol that works on the basis of tickets to allow nodes communicating over a non-secure network to prove their identity to one another in a secure manner. The following table shows a comparison of Kerberos and X.509 certificates:

Table 29.1. Comparison of certificates and Kerberos

Characteristic

Kerberos

X.509

Authentication

Yes

Yes

Privacy

Optional

Yes

Integrity

Optional

Yes

Type of cryptography involved

Symmetrical

Asymmetrical

Default validity

Short (1 day)

Long(2 years)

By default, Kerberos in Identity Management only ensures the identity of the communicating parties.

29.3. The pros and cons of using certificates to authenticate users in IdM

The advantages of using certificates to authenticate users in IdM include:

  • A PIN that protects the private key on a smart card is typically less complex and easier to remember than a regular password.
  • Depending on the device, a private key stored on a smart card cannot be exported. This provides additional security.
  • Smart cards can make logout automatic: IdM can be configured to log out users when they remove the smart card from the reader.
  • Stealing the private key requires actual physical access to a smart card, making smart cards secure against hacking attacks.
  • Smart card authentication is two-factor authentication: it requires both something you have (the card) and something you know (the PIN).
  • Smart cards are more flexible than passwords because they provide the keys that can be used for other purposes, such as encrypting email.
  • Using smart cards use on shared machines that are IdM clients does not typically pose additional configuration problems for system administrators. In fact, smart card authentication is an ideal choice for shared machines.

The disadvantages of using certificates to authenticate users in IdM include:

  • Users might lose or forget to bring their smart card or certificate and be effectively locked out.
  • Mistyping a PIN multiple times might result in a card becoming locked.
  • There is generally an intermediate step between request and authorization by some sort of security officer or approver. In IdM, the security officer or administrator must run the ipa cert-request command.
  • Smart cards and readers tend to be vendor and driver specific: although a lot of readers can be used for different cards, a smart card of a specific vendor might not work in the reader of another vendor or in the type of a reader for which it was not designed.
  • The learning curve to certificates and smart cards might seem daunting to admininstrators with no experience in the area.

Chapter 30. Converting certificate formats to work with IdM

This user story describes how to make sure that you as an IdM system administrator are using the correct format of a certificate with specific IdM commands. This is useful, for example, in the following situations:

30.1. Certificate formats and encodings in IdM

Certificate authentication including smart card authentication in IdM proceeds by comparing the certificate that the user presents with the certificate, or certificate data, that are stored in the user’s IdM profile.

System configuration

What is stored in the IdM profile is only the certificate, not the corresponding private key. During authentication, the user must also show that he is in possession of the corresponding private key. The user does that by either presenting a PKCS #12 file that contains both the certificate and the private key or by presenting two files: one that contains the certificate and the other containing the private key.

Therefore, processes such as loading a certificate into a user profile only accept certificate files that do not contain the private key.

Similarly, when a system administrator provides you with an external CA certificate, he will provide only the public data: the certificate without the private key. The ipa-advise utility for configuring the IdM server or the IdM client for smart card authentication expects the input file to contain the certificate of the external CA but not the private key.

Certificate encodings

There are two common certificate encodings: Privacy-enhanced Electronic Mail (PEM) and Distinguished Encoding Rules (DER). The base64 format is almost identical to the PEM format but it does not contain the -----BEGIN CERTIFICATE-----/-----END CERTIFICATE----- header and footer.

A certificate that has been encoded using DER is a binary X509 digital certificate file. As a binary file, the certificate is not human-readable. DER files sometimes use the .der filename extension, but files with the .crt and .cer filename extensions also sometimes contain DER certificates. DER files containing keys can be named .key.

A certificate that has been encoded using PEM Base64 is a human-readable file. The file contains ASCII (Base64) armored data prefixed with a “-----BEGIN …” line. PEM files sometimes use the .pem filename extension, but files with the .crt and .cer filename extensions also sometimes contain PEM certificates. PEM files containing keys can be named .key.

Different ipa commands have different limitations regarding the types of certificates that they accept. For example, the ipa user-add-cert command only accepts certificates encoded in the base64 format but ipa-server-certinstall accepts PEM, DER, PKCS #7, PKCS #8 and PKCS #12 certificates.

Table 30.1. Certificate encodings

Encoding formatHuman-readableCommon filename extensionsSample IdM commands accepting the encoding format

PEM/base64

Yes

.pem, .crt, .cer

ipa user-add-cert, ipa-server-certinstall, …​

DER

No

.der, .crt, .cer

ipa-server-certinstall, …​

Section 30.4, “Certificate-related commands and formats in IdM” lists further ipa commands with the certificate formats that the commands accept.

User authentication

When using the web UI to access IdM, the user proves that he is in possession of the private key corresponding to the certificate by having both stored in the browser’s database.

When using the CLI to access IdM, the user proves that he is in possession of the private key corresponding to the certificate by one of the following methods:

  • The user adds, as the value of the X509_user_identity parameter of the kinit -X command, the path to the smart card module that is connected to the smart card that contains both the certificate and the key:

    $ kinit -X X509_user_identity='PKCS11:opensc-pkcs11.so' idm_user
  • The user adds two files as the values of the X509_user_identity parameter of the kinit -X command, one containing the certificate and the other the private key:

    $ kinit -X X509_user_identity='FILE:`/path/to/cert.pem,/path/to/cert.key`' idm_user

Useful certificate commands

To view the certificate data, such as the subject and the issuer:

$ openssl x509 -noout -text -in ca.pem

To compare in which lines two certificates differ:

$ diff cert1.crt cert2.crt

To compare in which lines two certificates differ with the output displayed in two columns:

$ diff cert1.crt cert2.crt -y

30.2. Converting an external certificate to load into an IdM user account

This section describes how to make sure that an external certificate is correctly encoded and formatted before adding it to a user entry.

Prerequisites

  • If your certificate was issued by an Active Directory certificate authority and uses the PEM encoding, make sure that the PEM file has been converted into the UNIX format. To convert a file, use the dos2unix utility provided by the eponymous package.

30.2.1. Converting an external certificate in the IdM CLI and loading it into an IdM user account

The IdM CLI only accepts a PEM certificate from which the first and last lines (-----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----) have been removed.

Procedure

  1. Convert the certificate to the PEM format:

    • If your certificate is in the DER format:

      $ openssl x509 -in cert.crt -inform der -outform pem -out cert.pem
    • If your file is in the PKCS #12 format, whose common filename extensions are .pfx and .p12, and contains a certificate, a private key, and possibly other data, extract the certificate using the openssl pkcs12 utility. When prompted, enter the password protecting the private key stored in the file:

      $ openssl pkcs12 -in cert_and_key.p12 -clcerts -nokeys -out cert.pem
      Enter Import Password:
  2. Obtain the administrator’s credentials:

    $ kinit admin
  3. Add the certificate to the user account using the IdM CLI following one of the following methods:

    • Remove the first and last lines (-----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----) of the PEM file using the sed utility before adding the string to the ipa user-add-cert command:

      $ ipa user-add-cert some_user --certificate="$(sed -e '/BEGIN CERTIFICATE/d;/END CERTIFICATE/d' cert.pem)"
    • Copy and paste the contents of the certificate file without the first and last lines (-----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----) into the ipa user-add-cert command:

      $ ipa user-add-cert some_user --certificate=MIIDlzCCAn+gAwIBAgIBATANBgkqhki...
      Note

      You cannot pass a PEM file containing the certificate as input to the ipa user-add-cert command directly, without first removing the first and last lines (-----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----):

      $ ipa user-add-cert some_user --cert=some_user_cert.pem

      This command results in the "ipa: ERROR: Base64 decoding failed: Incorrect padding" error message.

  4. Optionally, to check if the certificate was accepted by the system:

    [idm_user@r8server]$ ipa user-show some_user

30.2.2. Converting an external certificate in the IdM web UI for loading into an IdM user account:

Procedure

  1. Using the CLI, convert the certificate to the PEM format:

    • If your certificate is in the DER format:

      $ openssl x509 -in cert.crt -inform der -outform pem -out cert.pem
    • If your file is in the PKCS #12 format, whose common filename extensions are .pfx and .p12, and contains a certificate, a private key, and possibly other data, extract the certificate using the openssl pkcs12 utility. When prompted, enter the password protecting the private key stored in the file:

      $ openssl pkcs12 -in cert_and_key.p12 -clcerts -nokeys -out cert.pem
      Enter Import Password:
  2. Open the certificate in an editor and copy the contents. You can include the "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----" header and footer lines but you do not have to, as both the PEM and base64 formats are accepted by the IdM web UI.
  3. In the IdM web UI, log in as security officer.
  4. Go to IdentityUserssome_user.
  5. Click Add next to Certificates.
  6. Paste the PEM-formatted contents of the certificate into the window that opens.
  7. Click Add.

If the certificate was accepted by the system, you can see it listed among the Certificates in the user profile.

30.3. Preparing to load a certificate into the browser

Before importing a user certificate into the browser, make sure that the certificate and the corresponding private key are in a PKCS #12 format. There are two common situations requiring extra preparatory work:

Afterwards, to import both the CA certificate in the PEM format and the user certificate in the PKCS #12 format into the browser, follow the procedures in Section 35.4, “Configuring a browser to enable certificate authentication” and Section 35.5, “Authenticating to the Identity Management Web UI with a Certificate as an Identity Management User”.

30.3.1. Exporting a certificate and private key from an NSS database into a PKCS #12 file

Procedure

  1. Use the pk12util command to export the certificate from the NSS database to the PKCS12 format. For example, to export the certificate with the some_user nickname from the NSS database stored in the ~/certdb directory into the ~/some_user.p12 file:

    $ pk12util -d ~/certdb -o ~/some_user.p12 -n some_user
    Enter Password or Pin for "NSS Certificate DB":
    Enter password for PKCS12 file:
    Re-enter password:
    pk12util: PKCS12 EXPORT SUCCESSFUL
  2. Set appropriate permissions for the .p12 file:

    # chmod 600 ~/some_user.p12

    Because the PKCS #12 file also contains the private key, it must be protected to prevent other users from using the file. Otherwise, they would be able to impersonate the user.

30.3.2. Combining certificate and private key PEM files into a PKCS #12 file

This section describes how to combine a certificate and the corresponding key stored in separate PEM files into a PKCS #12 file.

Procedure

  • To combine a certificate stored in certfile.cer and a key stored in certfile.key into a certfile.p12 file that contains both the certificate and the key:

    $ openssl pkcs12 -export -in certfile.cer -inkey certfile.key -out certfile.p12

30.4. Certificate-related commands and formats in IdM

Table IdM certificate commands and formats displays certificate-related commands in IdM with acceptable formats.

Table 30.2. IdM certificate commands and formats

CommandAcceptable formatsNotes

ipa user-add-cert some_user --certificate

base64 PEM certificate

 

ipa-server-certinstall

PEM and DER certificate; PKCS#7 certificate chain; PKCS#8 and raw private key; PKCS#12 certificate and private key

 

ipa-cacert-manage install

DER; PEM; PKCS#7

 

ipa-cacert-manage renew --external-cert-file

PEM and DER certificate; PKCS#7 certificate chain

 

ipa-ca-install --external-cert-file

PEM and DER certificate; PKCS#7 certificate chain

 

ipa cert-show <cert serial> --certificate-out /path/to/file.pem

N/A

Creates the PEM-encoded file.pem file with the certificate having the <cert_serial> serial number.

ipa cert-show <cert serial> --certificate-out /path/to/file.pem

N/A

Creates the PEM-encoded file.pem file with the certificate having the <cert_serial> serial number. If the --chain option is used, the PEM file contains the certificate including the certificate chain.

ipa cert-request --certificate-out=FILE /path/to/req.csr

N/A

Creates the req.csr file in the PEM format with the new certificate.

ipa cert-request --certificate-out=FILE /path/to/req.csr

N/A

Creates the req.csr file in the PEM format with the new certificate. If the --chain option is used, the PEM file contains the certificate including the certificate chain.

Chapter 31. Managing the validity of certificates in IdM

In Identity Management (IdM), you can manage the validity of both already existing certificates and certificates you want to issue in the future, but the methods are different.

Managing the validity of an existing certificate that was issued by IdM CA

In IdM, the following methods of viewing the expiry date of a certificate are available:

You can manage the validity of an already existing certificate that was issued by IdM CA in the following ways:

Managing the validity of future certificates issued by IdM CA

To manage the validity of future certificates issued by IdM CA, modify, import, or create a certificate profile. For details, see Certificate profiles in RHEL 7 documentation.

31.1. Viewing the expiry date of a certificate

31.1.1. Viewing the expiry date of a certificate in IdM WebUI

You can use IdM WebUI to view the expiry date of all the certificates that have been issued by IdM CA.

Prerequisites

  • Ensure that you have obtained the administrator’s credentials.

Procedure

  1. In the Authentication menu, click Certificates > Certificates.
  2. Click the serial number of the certificate to open the certificate information page.

    Figure 31.1. List of Certificates

    host cert list
  3. In the certificate information page, locate the Expires On information.

31.1.2. Viewing the expiry date of a certificate in the CLI

You can use the command-line interface (CLI) to view the expiry date of a certificate.

Procedure

  • Use the openssl utility to open the file in a human-readable format:

    $ openssl x509 -noout -text -in ca.pem
    Certificate:
        Data:
            Version: 3 (0x2)
            Serial Number: 1 (0x1)
            Signature Algorithm: sha256WithRSAEncryption
            Issuer: O = IDM.EXAMPLE.COM, CN = Certificate Authority
            Validity
                Not Before: Oct 30 19:39:14 2017 GMT
                Not After : Oct 30 19:39:14 2037 GMT

31.2. Revoking certificates with the integrated IdM CAs

31.2.1. Certificate revocation reasons

A revoked certificate is invalid and cannot be used for authentication. All revocations are permanent, except for reason 6: Certificate Hold.

The default revocation reason is 0: unspecified.

Table 31.1. Revocation Reasons

IDReasonExplanation

0

Unspecified

 

1

Key Compromised

The key that issued the certificate is no longer trusted.

Possible causes: lost token, improperly accessed file.

2

CA Compromised

The CA that issued the certificate is no longer trusted.

3

Affiliation Changed

Possible causes:

* A person has left the company or moved to another department.

* A host or service is being retired.

4

Superseded

A newer certificate has replaced the current certificate.

5

Cessation of Operation

The host or service is being decommissioned.

6

Certificate Hold

The certificate is temporarily revoked. You can restore the certificate later.

8

Remove from CRL

The certificate is not included in the certificate revocation list (CRL).

9

Privilege Withdrawn

The user, host, or service is no longer permitted to use the certificate.

10

Attribute Authority (AA) Compromise

The AA certificate is no longer trusted.

31.2.2. Revoking certificates with the integrated IdM CAs using IdM WebUI

If you know you have lost the private key for your certificate, you must revoke the certificate to prevent its abuse. Complete this procedure to use the IdM WebUI to revoke a certificate issued by the IdM CA.

Procedure

  1. Click Authentication > Certificates > Certificates.
  2. Click the serial number of the certificate to open the certificate information page.

    Figure 31.2. List of Certificates

    host cert list
  3. In the certificate information page, click ActionsRevoke Certificate.
  4. Select the reason for revoking and click Revoke. See Section 31.2.1, “Certificate revocation reasons” for details.

31.2.3. Revoking certificates with the integrated IdM CAs using IdM CLI

If you know you have lost the private key for your certificate, you must revoke the certificate to prevent its abuse. Complete this procedure to use the IdM CLI to revoke a certificate issued by the IdM CA.

Procedure

For example, to revoke the certificate with serial number 1032 because of reason 1: Key Compromised, enter:

$ ipa cert-revoke 1032 --revocation-reason=1

For details on requesting a new certificate, see the following documentation:

31.3. Restoring certificates with the integrated IdM CAs

If you have revoked a certificate because of reason 6: Certificate Hold, you can restore it again if the private key for the certificate has not been compromised. To restore a certificate, use one of the following procedures:

31.3.1. Restoring certificates with the integrated IdM CAs using IdM WebUI

Complete this procedure to use the IdM WebUI to restore an IdM certificate that has been revoked because of Reason 6: Certificate Hold.

Procedure

  1. In the Authentication menu, click Certificates > Certificates.
  2. Click the serial number of the certificate to open the certificate information page.

    Figure 31.3. List of Certificates

    host cert list
  3. In the certificate information page, click ActionsRestore Certificate.

31.3.2. Restoring certificates with the integrated IdM CAs using IdM CLI

Complete this procedure to use the IdM CLI to restore an IdM certificate that has been revoked because of Reason 6: Certificate Hold.

Procedure

  • Use the ipa cert-remove-hold command and specify the certificate serial number. For example:

    $ ipa cert-remove-hold 1032

Chapter 32. Configuring Identity Management for smart card authentication

Authentication based on smart cards is an alternative to passwords. You can store user credentials on a smart card in the form of a private key and a certificate, and special software and hardware is used to access them. Place the smart card into a reader or a USB port and supply the PIN code for the smart card instead of providing your password.

Identity Management (IdM) supports smart card authentication with:

  • User certificates issued by the IdM certificate authority
  • User certificates issued by an external certificate authority

This user story shows how to set up smart card authentication in IdM for both types of certificates. In the user story, the smartcard_ca.pem CA certificate is the file containing the certificate of a trusted external certificate authority.

The user story contains the following modules:

32.1. Configuring the IdM server for smart card authentication

If you want to enable smart card authentication for users whose certificates have been issued by the certificate authority of the EXAMPLE.ORG domain, whose LDAP distinguished name (DN) is CN=Certificate Authority,DC=EXAMPLE,DC=ORG, then you need to obtain the certificate of the authority so that you can run it with the script configuring the IdM server. You can, for example, download the certificate from a web page whose certificate has been issued by the authority. For details, see Steps 1 - 4a in Section 35.4, “Configuring a browser to enable certificate authentication”.

To enable smart card authentication for IdM users who have been issued a certificate by the IdM Certificate Authority, obtain the CA certificate from the /etc/ipa/ca.crt file on the IdM server on which the IdM CA is running.

This section describes how to configure an IdM server for smart card authentication. First, obtain files with the CA certificates in the PEM format, then run the in-built ipa-advise script. Finally, reload the system configuration.

Prerequisites

  • You have root access to the IdM server.

Procedure

  1. Create a directory in which you will do the configuration:

    [root@server]# mkdir ~/SmartCard/
  2. Navigate to the directory:

    [root@server]# cd ~/SmartCard/
  3. Obtain the relevant CA certificates stored in files in PEM format. If your CA certificate is stored in a file of a different format, such as DER, convert it to PEM format. The IdM Certificate Authority certificate is located in the /etc/ipa/ca.crt file.

    Convert a DER file to a PEM file:

    # openssl x509 -in <filename>.der -inform DER -out <filename>.pem -outform PEM
  4. For convenience, copy the certificates to the directory in which you want to do the configuration:

    [root@server SmartCard]# cp /etc/ipa/ca.crt ~/SmartCard/
    [root@server SmartCard]# cp /tmp/smartcard_ca.pem ~/SmartCard/
  5. Optionally, if you use certificates of external certificate authorities, use the openssl x509 utility to view the contents of the files in the PEM format to check that the Issuer and Subject values are correct:

    [root@server SmartCard]# openssl x509 -noout -text -in smartcard_ca.pem | more
  6. Generate a configuration script with the in-built ipa-advise utility, using the administrator’s privileges:

    [root@server SmartCard]# kinit admin
    [root@server SmartCard]# sudo ipa-advise config-server-for-smart-card-auth > config-server-for-smart-card-auth.sh

    The config-server-for-smart-card-auth.sh script performs the following actions:

    • It configures the IdM Apache HTTP Server.
    • It enables Public Key Cryptography for Initial Authentication in Kerberos (PKINIT) on the Key Distribution Center (KDC).
    • It configures the IdM Web UI to accept smart card authorization requests.
  7. Execute the script, adding the PEM files containing the CA certificates as arguments:

    [root@server SmartCard]# chmod +x config-server-for-smart-card-auth.sh
    [root@server SmartCard]# ./config-server-for-smart-card-auth.sh smartcard_ca.pem ca.crt
    Ticket cache:KEYRING:persistent:0:0
    Default principal: admin@IDM.EXAMPLE.COM
    [...]
    Systemwide CA database updated.
    The ipa-certupdate command was successful
  8. Optionally, if the certificate authority that issued the user certificate does not provide any Online Certificate Status Protocol (OCSP) responder, you may need to disable OCSP check for authentication to the IdM Web UI:

    1. Set the SSLOCSPEnable parameter to off in the /etc/httpd/conf.d/ssl.conf file:

      SSLOCSPEnable off
    2. Restart the Apache daemon (httpd) for the changes to take effect immediately:

      [root@server SmartCard]# sudo systemctl restart httpd
    Warning

    Do not disable the OCSP check if you only use user certificates issued by the IdM CA. OCSP responders are part of IdM.

    For instructions on how to keep the OCSP check enabled, and yet prevent a user certificate from being rejected by the IdM server if it does not contain the information about the location at which the CA that issued the user certificate listens for OCSP service requests, see the SSLOCSPDefaultResponder directive in Apache mod_ssl configuration options.

The server is now configured for smart card authentication.

Note

To enable smart card authentication in the whole topology, run the procedure on each IdM server.

32.2. Configuring the IdM client for smart card authentication

This section describes how to configure IdM clients for smart card authentication. The procedure needs to be run on each IdM system, a client or a server, to which you want to connect while using a smart card for authentication. For example, to enable an ssh connection from host A to host B, the script needs to be run on host B.

As an administrator, run this procedure to enable smart card authentication using

This procedure is not required for authenticating to the IdM Web UI. Authenticating to the IdM Web UI involves two hosts, neither of which needs to be an IdM client:

  • the machine - possibly outside of the IdM domain - on which the browser is running
  • the IdM server on which httpd is running

The following procedure assumes that you are configuring smart card authentication on an IdM client that is not also an IdM master. For this reason you need two computers: an IdM master to generate the configuration script, and the IdM client on which to run the script.

Prerequisites

Procedure

  1. On an IdM master, generate a configuration script with ipa-advise using the administrator’s privileges:

    [root@server SmartCard]# kinit admin
    [root@server SmartCard]# ipa-advise config-client-for-smart-card-auth > config-client-for-smart-card-auth.sh

    The config-client-for-smart-card-auth.sh script performs the following actions:

    • It configures the smart card daemon.
    • It sets the system-wide trust store.
    • It configures the System Security Services Daemon (SSSD) to allow smart card logins to the desktop.
  2. From the IdM master, copy the script to a directory of your choice on the IdM client machine:

    [root@server SmartCard]# scp config-client-for-smart-card-auth.sh root@client.idm.example.com:/root/SmartCard/
    Password:
    config-client-for-smart-card-auth.sh        100%   2419       3.5MB/s   00:00
  3. From the IdM master, copy the CA certificate files in the PEM format for convenience to the same directory on the IdM client machine as used in the previous step:

    [root@server SmartCard]# scp {smartcard_ca.pem,ca.crt} root@client.idm.example.com:/root/SmartCard/
    Password:
    smartcard_ca.pem                    100%   1237     9.6KB/s   00:00
    ca.crt                              100%   2514    19.6KB/s   00:00
  4. On the client machine, execute the script, adding the PEM files containing the CA certificates as arguments:

    [root@client SmartCard]# kinit admin
    [root@client SmartCard]# chmod +x config-client-for-smart-card-auth.sh
    [root@client SmartCard]# ./config-client-for-smart-card-auth.sh smartcard_ca.pem ca.crt
    Ticket cache:KEYRING:persistent:0:0
    Default principal: admin@IDM.EXAMPLE.COM
    [...]
    Systemwide CA database updated.
    The ipa-certupdate command was successful

The client is now configured for smart card authentication.

32.3. Adding a certificate to a user entry in IdM

This procedure describes how to add an external certificate to a user entry in IdM.

Instead of uploading the whole certificate, it is also possible to upload certificate mapping data to a user entry in IdM. User entries containing either full certificates or certificate mapping data can be used in conjunction with corresponding certificate mapping rules to facilitate the configuration of smart card authentication for system administrators. For details, see Chapter 34, Configuring certificate mapping rules in Identity Management.

Note

If the user’s certificate has been issued by the IdM Certificate Authority, the certificate is already stored in the user entry, and you can skip this section.

32.3.1. Adding a certificate to a user entry in the IdM Web UI

Prerequisites

  • You have the certificate that you want to add to the user entry at your disposal.

Procedure

  1. Log into the IdM Web UI as an administrator if you want to add a certificate to another user. For adding a certificate to your own profile, you do not need the administrator’s credentials.
  2. Navigate to UsersActive userssc_user.
  3. Find the Certificate option and click Add.
  4. In the Command-Line Interface, display the certificate in the PEM format using the cat utility or a text editor:

    [user@client SmartCard]$ cat testuser.crt
  5. Copy and paste the certificate from the CLI into the window that has opened in the Web UI.
  6. Click Add.

    Figure 32.1. Adding a new certificate in the IdM Web UI

    idm add cert

The sc_user entry now contains an external certificate.

32.3.2. Adding a certificate to a user entry in the IdM CLI

Prerequisites

  • You have the certificate that you want to add to the user entry at your disposal.

Procedure

  1. Log into the IdM CLI as an administrator if you want to add a certificate to another user:

    [user@client SmartCard]$ kinit admin

    For adding a certificate to your own profile, you do not need the administrator’s credentials:

    [user@client SmartCard]$ kinit sc_user
  2. Create an environment variable containing the certificate with the header and footer removed and concatenated into a single line, which is the format expected by the ipa user-add-cert command:

    [user@client SmartCard]$ export CERT=`openssl x509 -outform der -in testuser.crt | base64 -w0 -`

    Note that certificate in the testuser.crt file must be in the PEM format.

  3. Add the certificate to the profile of sc_user using the ipa user-add-cert command:

    [user@client SmartCard]$ ipa user-add-cert sc_user --certificate=$CERT

The sc_user entry now contains an external certificate.

32.4. Installing tools for managing and using smart cards

To configure your smart card, you need tools which can generate certificates and store them on a smart card.

You must:

  • Install the gnutls-utils package which helps you to manage certificates.
  • Install the opensc package which provides a set of libraries and utilities to work with smart cards.
  • Start the pcscd service which communicates with the smart card reader.

Procedure

  1. Install the opensc and gnutls-utils packages:

    # dnf -y install opensc gnutls-utils
  2. Start the pcscd service.

    # systemctl start pcscd

Verify that the pcscd service is up and running.

32.5. Storing a certificate on a smart card

This section describes smart card configuration with the pkcs15-init tool, which helps you to configure:

  • Erasing your smart card
  • Setting new PINs and optional PIN Unblocking Keys (PUKs)
  • Creating a new slot on the smart card
  • Storing the certificate, private key, and public key in the slot
  • Locking the smart card settings (some smart cards require this type of finalization)

Prerequisites

  • The opensc package, which includes the pkcs15-init tool is installed.

    For details, see Installing tools for managing and using smart cards.

  • The card is inserted in the reader and connected to the computer.
  • You have the private key, public key, and certificate to store on the smart card. In this procedure, testuser.key, testuserpublic.key, and testuser.crt are the names used for the private key, public key, and the certificate.
  • Your current smart card user PIN and Security Officer PIN (SO-PIN)

Procedure

  1. Erase your smart card and authenticate yourself with your PIN:

    $ pkcs15-init --erase-card --use-default-transport-keys
    Using reader with a card: Reader name
    PIN [Security Officer PIN] required.
    Please enter PIN [Security Officer PIN]:

    The card has been erased.

  2. Initialize your smart card, set your user PIN and PUK, and your Security Officer PIN and PUK:

    $ pkcs15-init --create-pkcs15 --use-default-transport-keys \
        --pin 963214 --puk 321478 --so-pin 65498714 --so-puk 784123
    Using reader with a card: Reader name

    The pcks15-init tool creates a new slot on the smart card.

  3. Set the label and the authentication ID for the slot:

    $ pkcs15-init --store-pin --label testuser \
        --auth-id 01 --so-pin 65498714 --pin 963214 --puk 321478
    Using reader with a card: Reader name

    The label is set to a human-readable value, in this case, testuser. The auth-id must be two hexadecimal values, in this case it is set to 01.

  4. Store and label the private key in the new slot on the smart card:

    $ pkcs15-init --store-private-key testuser.key --label testuser_key \
        --auth-id 01 --id 01 --pin 963214
    Using reader with a card: Reader name
    Note

    The value you specify for --id must be the same when storing your private key, and certificate. If you do not specify a value for --id, a more complicated value is calculated by the tool and it is therefore easier to define your own value.

  5. Store and label the certificate in the new slot on the smart card:

    $ pkcs15-init --store-certificate testuser.crt --label testuser_crt \
        --auth-id 01 --id 01 --format pem --pin 963214
    Using reader with a card: Reader name
  6. (Optional) Store and label the public key in the new slot on the smart card:

    $ pkcs15-init --store-public-key testuserpublic.key
        --label testuserpublic_key --auth-id 01 --id 01 --pin 963214
    Using reader with a card: Reader name
    Note

    If the public key corresponds to a private key and/or certificate, you should specify the same ID as that private key and/or certificate.

  7. (Optional) Some smart cards require you to finalize the card by locking the settings:

    $ pkcs15-init -F

    At this stage, your smart card includes the certificate, private key, and public key in the newly created slot. You have also created your user PIN and PUK and the Security Officer PIN and PUK.

32.6. Logging in to IdM with smart cards

This section provides information about using smart cards for logging in to IdM Web UI.

Prerequisites

  • The web browser is configured for using smart card authentication.
  • The IdM server has been configured for smart card authentication.
  • The certificate installed on your smart card is known to the IdM server.
  • You need the PIN to unlock the smart card.
  • The smart card has been plugged to the reader.

Procedure

  1. Open the IdM Web UI in the browser.
  2. Click on Log In Using Certificate.

    ipa login smart card

  3. If the Password Required dialog box opens, add the PIN to unlock the smart card and click the OK button.

    The User Identification Request dialog box opens.

    If the smart card contains more than one certificate, select the certificate you want to use for authentication in the drop down list below Choose a certificate to present as identification.

  4. Click the OK button.

Now you are successfully logged in to the IdM Web UI.

web ui users

32.7. Configuring GDM access using smart card authentication

The Gnome Desktop Manager (GDM) requires authentication. You can use your password, however, you can also use a smart card for authentication.

This section describes smart card authentication to access GDM.

The advantage of using smart card authentication is that if the user account is part of the Identity Management domain, you also get a ticket-granting ticket (TGT).

Prerequisites

Procedure

  1. Insert the smart card in the reader.
  2. Enter the smart card PIN.
  3. Click Sign In.

You are successfully logged in to the RHEL system and you have a TGT provided by the IdM server.

Verification steps

  • In the Terminal window, enter klist and check the result:

    $ klist
    Ticket cache: KEYRING:persistent:1358900015:krb_cache_TObtNMd
    Default principal: example.user@REDHAT.COM
    
    Valid starting       Expires              Service principal
    04/20/2020 13:58:24  04/20/2020 23:58:24  krbtgt/EXAMPLE.COM@EXAMPLE.COM
    	renew until 04/27/2020 08:58:15

32.8. Configuring su access using smart card authentication

Changing to a different user requires authentication. You can use a password or a certificate. This section describes using your smart card with the su command. It means that after entering the su command, you are prompted for the smart card PIN.

Prerequisites

  • The smart card contains your certificate and private key.
  • The card is inserted in the reader and connected to the computer.

Procedure

  • In a terminal window, change to a different user with the su command:

    $ su - example.user
    PIN for smart_card

    If the configuration is successful, you are prompted to enter the smart card PIN.

Chapter 33. Configuring certificates issued by ADCS for smart card authentication in IdM

This scenario describes the following situation:

  • Your deployment is based on cross-forest trust between Identity Management (IdM) and Active Directory (AD).
  • You want to allow smart card authentication for users whose accounts are stored in AD.
  • Certificates are created and stored in Active Directory Certificate Services (ADCS).

Configuration will be accomplished in the following steps:

Prerequisites

  • Identity Management (IdM) and Active Directory (AD) trust is installed

    For details, see Installing trust between IdM and AD.

  • Active Directory Certificate Services (ADCS) is installed and certificates for users are generated

assembly_configuring-smart-card-authentication-with-the-web-console.adoc

33.1. Smart card authentication

A smart card is a physical device which can provide personal authentication using certificates stored on the card. Personal authentication means that you can use smart cards in the same way as user passwords.

You can store user credentials on the smart card in the form of a private key and a certificate, and special software and hardware is used to access them. You place the smart card into a reader or a USB socket and supply the PIN code for the smart card instead of providing your password.

You can configure how you want smart card authentication to work in a particular IdM client:

  • Users can authenticate with the user name and password or with their smart cards
  • Users can authenticate with their smart cards, and passwords are not allowed
  • Users can use the smart card for logout with a function lock on removal, and passwords are not allowed

Identity Management (IdM) supports smart card authentication with:

Note

If you want to start to use smart card authentication, see the hardware requirements: Smart Card support in RHEL8.

33.2. Windows Server settings required for trust configuration and certificate usage

This section summarizes what must be configured on Windows Server:

  • Active Directory Certificate Services (ADCS) is installed
  • Certificate Authority is created
  • [Optional] If you are using Certificate Authority Web Enrollment, the Internet Information Services (IIS) must be configured

Export the certificate:

  • Key must have 2048 bits or more
  • Include a private key
  • You will need a certificate in the following format: Personal Information Exchange — PKCS #12(.PFX)

    • Enable certificate privacy

33.3. Copying certificates from Active Directory using sftp

To be able to use smart card authetication, you need to copy the following certificate files:

  • A root CA certificate in the CER format: adcs-winserver-ca.cer on your IdM server.
  • A user certificate with a private key in the PFX format: aduser1.pfx on an IdM client.
Note

This procedure expects SSH access is allowed. If SSH is unavailable the user must copy the file from the AD Server to the IdM server and client.

Procedure

  1. Connect from the IdM server and copy the adcs-winserver-ca.cer root certificate to the IdM server:

    root@idmserver ~]# sftp Administrator@winserver.ad.example.com
    Administrator@winserver.ad.example.com's password:
    Connected to Administrator@winserver.ad.example.com.
    sftp> cd <Path to certificates>
    sftp> ls
    adcs-winserver-ca.cer    aduser1.pfx
    sftp>
    sftp> get adcs-winserver-ca.cer
    Fetching <Path to certificates>/adcs-winserver-ca.cer to adcs-winserver-ca.cer
    <Path to certificates>/adcs-winserver-ca.cer                 100%  1254    15KB/s 00:00
    sftp quit
  2. Connect from the IdM client and copy the aduser1.pfx user certificate to the client:

    [root@client1 ~]# sftp Administrator@winserver.ad.example.com
    Administrator@winserver.ad.example.com's password:
    Connected to Administrator@winserver.ad.example.com.
    sftp> cd /<Path to certificates>
    sftp> get aduser1.pfx
    Fetching <Path to certificates>/aduser1.pfx to aduser1.pfx
    <Path to certificates>/aduser1.pfx                 100%  1254    15KB/s 00:00
    sftp quit

Now the CA certificate is stored in the IdM server and the user certificates is stored on the client machine.

33.4. Configuring the IdM server and clients for smart card authentication using ADCS certificates

You must configure the IdM (Identity Management) server and clients to be able to use smart card authentication in the IdM environment. IdM includes the ipa-advise scripts which makes all necessary changes:

  • install necessary packages
  • it configures IdM server and clients
  • copy the CA certificates into expected locations

You can run ipa-advise on your IdM server.

This procedure describes:

  • On an IdM server: Preparing the ipa-advise script to configure your IdM server for smart card authentication.
  • On an IdM server: Preparing the ipa-advise script to configure your IdM client for smart card authentication.
  • On an IdM server: Applying the the ipa-advise server script on the IdM server using the AD certificate.
  • Moving the client script to the IdM client machine.
  • On an IdM client: Applying the the ipa-advise client script on the IdM client using the AD certificate.

Prerequisites

  • The certificate has been copied to the IdM server.
  • Obtain the Kerberos ticket.
  • Log in as a user with administration rights.

Procedure

  1. On the IdM server, use the ipa-advise script for configuring a client:

    [root@idmserver ~]# ipa-advise config-client-for-smart-card-auth > sc_client.sh
  2. On the IdM server, use the ipa-advise script for configuring a server:

    [root@idmserver ~]# ipa-advise config-server-for-smart-card-auth > sc_server.sh
  3. On the IdM server, execute the script:

    [root@idmserver ~]# sh -x sc_server.sh adcs-winserver-ca.cer
    • It configures the IdM Apache HTTP Server.
    • It enables Public Key Cryptography for Initial Authentication in Kerberos (PKINIT) on the Key Distribution Center (KDC).
    • It configures the IdM Web UI to accept smart card authorization requests.
  4. Copy the sc_client.sh script to the client system:

    [root@idmserver ~]# scp sc_client.sh root@client1.idm.example.com:/root
    Password:
    sc_client.sh                  100%  2857   1.6MB/s   00:00
  5. Copy the Windows certificate to the client system:

    [root@idmserver ~]# scp adcs-winserver-ca.cer root@client1.idm.example.com:/root
    Password:
    adcs-winserver-ca.cer                 100%  1254   952.0KB/s   00:00
  6. On the client system, run the client script:

    [root@idmclient1 ~]# sh -x sc_client.sh adcs-winserver-ca.cer

The CA certificate is installed in the correct format on the IdM server and client systems and next step is to copy the user certificates onto the smart card itself.

33.5. Converting the PFX file

Before you store the PFX (PKCS#12) file into the smart card, you must:

  • convert the file to the PEM format
  • extract the private key and the certificate to two different files

Prerequisites

  • The PFX file is copied into the IdM client machine.

Procedure

  1. On the IdM client, into the PEM format:

    [root@idmclient1 ~]# openssl pkcs12 -in aduser1.pfx -out aduser1_cert_only.pem -clcerts -nodes
    Enter Import Password:
  2. Extract the key into the separate file:

    [root@idmclient1 ~]# openssl pkcs12 -in adduser1.pfx -nocerts -out adduser1.pem > aduser1.key
  3. Extract the public certificate into the separate file:

    [root@idmclient1 ~]# openssl pkcs12 -in adduser1.pfx -clcerts -nokeys -out aduser1_cert_only.pem > aduser1.crt

At this point, you can store the aduser1.key and aduser1.crt into the smart card.

33.6. Installing tools for managing and using smart cards

To configure your smart card, you need tools which can generate certificates and store them on a smart card.

You must:

  • Install the gnutls-utils package which helps you to manage certificates.
  • Install the opensc package which provides a set of libraries and utilities to work with smart cards.
  • Start the pcscd service which communicates with the smart card reader.

Procedure

  1. Install the opensc and gnutls-utils packages:

    # dnf -y install opensc gnutls-utils
  2. Start the pcscd service.

    # systemctl start pcscd

Verify that the pcscd service is up and running.

33.7. Storing a certificate on a smart card

This section describes smart card configuration with the pkcs15-init tool, which helps you to configure:

  • Erasing your smart card
  • Setting new PINs and optional PIN Unblocking Keys (PUKs)
  • Creating a new slot on the smart card
  • Storing the certificate, private key, and public key in the slot
  • Locking the smart card settings (some smart cards require this type of finalization)

Prerequisites

  • The opensc package, which includes the pkcs15-init tool is installed.

    For details, see Installing tools for managing and using smart cards.

  • The card is inserted in the reader and connected to the computer.
  • You have the private key, public key, and certificate to store on the smart card. In this procedure, testuser.key, testuserpublic.key, and testuser.crt are the names used for the private key, public key, and the certificate.
  • Your current smart card user PIN and Security Officer PIN (SO-PIN)

Procedure

  1. Erase your smart card and authenticate yourself with your PIN:

    $ pkcs15-init --erase-card --use-default-transport-keys
    Using reader with a card: Reader name
    PIN [Security Officer PIN] required.
    Please enter PIN [Security Officer PIN]:

    The card has been erased.

  2. Initialize your smart card, set your user PIN and PUK, and your Security Officer PIN and PUK:

    $ pkcs15-init --create-pkcs15 --use-default-transport-keys \
        --pin 963214 --puk 321478 --so-pin 65498714 --so-puk 784123
    Using reader with a card: Reader name

    The pcks15-init tool creates a new slot on the smart card.

  3. Set the label and the authentication ID for the slot:

    $ pkcs15-init --store-pin --label testuser \
        --auth-id 01 --so-pin 65498714 --pin 963214 --puk 321478
    Using reader with a card: Reader name

    The label is set to a human-readable value, in this case, testuser. The auth-id must be two hexadecimal values, in this case it is set to 01.

  4. Store and label the private key in the new slot on the smart card:

    $ pkcs15-init --store-private-key testuser.key --label testuser_key \
        --auth-id 01 --id 01 --pin 963214
    Using reader with a card: Reader name
    Note

    The value you specify for --id must be the same when storing your private key, and certificate. If you do not specify a value for --id, a more complicated value is calculated by the tool and it is therefore easier to define your own value.

  5. Store and label the certificate in the new slot on the smart card:

    $ pkcs15-init --store-certificate testuser.crt --label testuser_crt \
        --auth-id 01 --id 01 --format pem --pin 963214
    Using reader with a card: Reader name
  6. (Optional) Store and label the public key in the new slot on the smart card:

    $ pkcs15-init --store-public-key testuserpublic.key
        --label testuserpublic_key --auth-id 01 --id 01 --pin 963214
    Using reader with a card: Reader name
    Note

    If the public key corresponds to a private key and/or certificate, you should specify the same ID as that private key and/or certificate.

  7. (Optional) Some smart cards require you to finalize the card by locking the settings:

    $ pkcs15-init -F

    At this stage, your smart card includes the certificate, private key, and public key in the newly created slot. You have also created your user PIN and PUK and the Security Officer PIN and PUK.

33.8. Configuring timeouts in sssd.conf

Authentication with a smart card certificate might take longer than the default timeouts used by SSSD. Time out expiration can be caused by:

  • slow reader
  • a forwarding form a physical device into a virtual environment
  • too many certificates stored on the smart card
  • slow response from the OCSP (Online Certificate Status Protocol) responder if OCSP is used to verify the certificates

In this case you can prolong the following timeouts in the sssd.conf file, for example, to 60 seconds:

  • p11_child_timeout
  • krb5_auth_timeout

Prerequisites

  • You must be logged in as root.

Procedure

  1. Open the sssd.conf file:

    [root@idmclient1 ~]# vim /etc/sssd/sssd.conf
  2. Change the value of p11_child_timeout:

    [pam]
    p11_child_timeout = 60
  3. Change the value of krb5_auth_timeout:

    [domain/IDM.EXAMPLE.COM]
    krb5_auth_timeout = 60
  4. Save the settings.

Now, the interaction with the smart card is allowed to run for 1 minute (60 seconds) before authentication will fail with a timeout.

33.9. Creating certificate mapping rules for smart card authentication

If you want to use one certificate for the same user who has accounts in AD (Active Directory) and in IdM (Identity Management) too, you can create a certificate mapping rule on the IdM server. After creating such a rule, the user is able to authenticate with their smart card in both domains.

For details about certificate mapping rules, see Certificate mapping rules for configuring authentication on smart cards.

Chapter 34. Configuring certificate mapping rules in Identity Management

34.1. Certificate mapping rules for configuring authentication on smart cards

Certificate mapping rules are a convenient way of allowing users to authenticate using certificates in scenarios when the Identity Management (IdM) administrator does not have access to certain users' certificates. This lack of access is typically caused by the fact that the certificates have been issued by an external certificate authority. A special use case is represented by certificates issued by the Certificate System of an Active Directory (AD) with which the IdM domain is in a trust relationship.

Certificate mapping rules are also convenient if the IdM environment is large with a lot of users using smart cards. In this situation, adding full certificates can be complicated. The subject and issuer are predictable in most scenarios and thus easier to add ahead of time than the full certificate. As a system administrator, you can create a certificate mapping rule and add certificate mapping data to a user entry even before a certificate is issued to a particular user. Once the certificate is issued, the user can log in using the certificate even though the full certificate has not yet been uploaded to the user entry.

In addition, as certificates have to be renewed at regular intervals, certificate mapping rules reduce administrative overhead. When a user’s certificate gets renewed, the administrator does not have to update the user entry. For example, if the mapping is based on the Subject and Issuer values, and if the new certificate has the same subject and issuer as the old one, the mapping still applies. If, in contrast, the full certificate was used, then the administrator would have to upload the new certificate to the user entry to replace the old one.

To set up certificate mapping:

  1. An administrator has to load the certificate mapping data (typically the issuer and subject) or the full certificate into a user account.
  2. An administrator has to create a certificate mapping rule to allow successful logging into IdM for a user

    1. whose account contains a certificate mapping data entry
    2. whose certificate mapping data entry matches the information on the certificate

    For details on the individual components that make up a mapping rule and how to obtain and use them, see Components of an identity mapping rule in IdM and Obtaining the issuer from a certificate for use in a matching rule.

Afterwards, when the end-user presents the certificate, stored either in the filesystem or on a smart card, authentication is successful.

34.1.1. Certificate mapping rules for trusts with Active Directory domains

This section outlines the different certificate mapping use cases that are possible if an IdM deployment is in a trust relationship with an Active Directory (AD) domain.

Certificate mapping rules are a convenient way to enable access to IdM resources for users who have smart card certificates that were issued by the trusted AD Certificate System. Depending on the AD configuration, the following scenarios are possible:

34.1.2. Components of an identity mapping rule in IdM

This section describes the components of an identity mapping rule in IdM and how to configure them. Each component has a default value that you can override. You can define the components in either the web UI or the CLI. In the CLI, the identity mapping rule is created using the ipa certmaprule-add command.

Mapping rule

The mapping rule component associates (or maps) a certificate with one or more user accounts. The rule defines an LDAP search filter that associates a certificate with the intended user account.

Certificates issued by different certificate authorities (CAs) might have different properties and might be used in different domains. Therefore, IdM does not apply mapping rules unconditionally, but only to the appropriate certificates. The appropriate certificates are defined using matching rules.

Note that if you leave the mapping rule option empty, the certificates are searched in the userCertificate attribute as a DER encoded binary file.

Define the mapping rule in the CLI using the --maprule option.

Matching rule

The matching rule component selects a certificate to which you want to apply the mapping rule. The default matching rule matches certificates with the digitalSignature key usage and clientAuth extended key usage.

Define the matching rule in the CLI using the --matchrule option.

Domain list

The domain list specifies the identity domains in which you want IdM to search the users when processing identity mapping rules. If you leave the option unspecified, IdM searches the users only in the local domain to which the IdM client belongs.

Define the domain in the CLI using the --domain option.

Priority

When multiple rules are applicable to a certificate, the rule with the highest priority takes precedence. All other rules are ignored.

  • The lower the numerical value, the higher the priority of the identity mapping rule. For example, a rule with a priority 1 has higher priority than a rule with a priority 2.
  • If a rule has no priority value defined, it has the lowest priority.

Define the mapping rule priority in the CLI using the --priority option.

Certificate mapping rule example

To define, using the CLI, a certificate mapping rule called simple_rule that allows authentication for a certificate issued by the Smart Card CA of the EXAMPLE.ORG organisation as long as the Subject on that certificate matches a certmapdata entry in a user account in IdM:

# ipa certmaprule-add simple_rule --matchrule '<ISSUER>CN=Smart Card CA,O=EXAMPLE.ORG' --maprule '(ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500})'

34.1.3. Obtaining the issuer from a certificate for use in a matching rule

This procedure describes how to obtain the issuer information from a certificate so that you can copy and paste it into the matching rule of a certificate mapping rule. To get the issuer format required by a matching rule, use the openssl x509 utility.

Prerequisites

  • You have the user certificate in a .pem or .crt format

Procedure

  1. Obtain the user information from the certificate. Use the openssl x509 certificate display and signing utility with:

    • the -noout option to prevent the output of an encoded version of the request
    • the -issuer option to output the issuer name
    • the -in option to specify the input file name to read the certificate from
    • the -nameopt option with the RFC2253 value to display the output with the most specific relative distinguished name (RDN) first

      If the input file contains an Identity Management certificate, the output of the command shows that the Issuer is defined using the Organisation information:

      # openssl x509 -noout -issuer -in idm_user.crt -nameopt RFC2253
      issuer=CN=Certificate Authority,O=REALM.EXAMPLE.COM

      If the input file contains an Active Directory certificate, the output of the command shows that the Issuer is defined using the Domain Component information:

      # openssl x509 -noout -issuer -in ad_user.crt -nameopt RFC2253
      issuer=CN=AD-WIN2012R2-CA,DC=AD,DC=EXAMPLE,DC=COM
  2. Optionally, to create a new mapping rule in the CLI based on a matching rule which specifies that the certificate issuer must be the extracted AD-WIN2012R2-CA of the ad.example.com domain and the subject on the certificate must match the certmapdata entry in a user account in IdM:

    # ipa certmaprule-add simple_rule --matchrule '<ISSUER>CN=AD-WIN2012R2-CA,DC=AD,DC=EXAMPLE,DC=COM' --maprule '(ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500})'

Additional information

For details about the supported formats for the matching rule and the mapping rule, and an explanation of the priority and domain fields, see the sss-certmap(5) man page.

34.2. Configuring certificate mapping for users stored in IdM

This user story describes the steps a system administrator must take to enable certificate mapping in IdM if the user for whom certificate authentication is being configured is stored in IdM.

Prerequisites

  • The user has an account in IdM.
  • The administrator has either the whole certificate or the certificate mapping data to add to the user entry.

34.2.1. Adding a certificate mapping rule in IdM

This section describes how to set up a certificate mapping rule so that IdM users with certificates that match the conditions specified in the mapping rule and in their certificate mapping data entries can authenticate to IdM.

34.2.1.1. Adding a certificate mapping rule in the IdM web UI

  1. Log in to the IdM web UI as an administrator.
  2. Navigate to AuthenticationCertificate Identity Mapping RulesCertificate Identity Mapping Rules.
  3. Click Add.

    Figure 34.1. Adding a new certificate mapping rule in the IdM web UI

    new certmaprule add
  4. Enter the rule name.
  5. Enter the mapping rule. For example, to make IdM search for the Issuer and Subject entries in any certificate presented to them, and base its decision to authenticate or not on the information found in these two entries of the presented certificate:

    (ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500})
  6. Enter the matching rule. For example, to only allow certificates issued by the Smart Card CA of the EXAMPLE.ORG organization to authenticate users to IdM:

    <ISSUER>CN=Smart Card CA,O=EXAMPLE.ORG

    Figure 34.2. Entering the details for a certificate mapping rule in the IdM web UI

    certmaprule add details1
  7. Click Add at the bottom of the dialog box to add the rule and close the box.
  8. The System Security Services Daemon (SSSD) periodically re-reads the certificate mapping rules. To force the newly-created rule to be loaded immediately, restart SSSD:

    # systemctl restart sssd

Now you have a certificate mapping rule set up that compares the type of data specified in the mapping rule that it finds on a smart card certificate with the certificate mapping data in your IdM user entries. Once it finds a match, it authenticates the matching user.

34.2.1.2. Adding a certificate mapping rule in the IdM CLI

  1. Obtain the administrator’s credentials:

    # kinit admin
  2. Enter the mapping rule and the matching rule the mapping rule is based on. For example, to make IdM search for the Issuer and Subject entries in any certificate presented, and base its decision to authenticate or not on the information found in these two entries of the presented certificate, recognizing only certificates issued by the Smart Card CA of the EXAMPLE.ORG organization:

    # ipa certmaprule-add rule_name --matchrule '<ISSUER>CN=Smart Card CA,O=EXAMPLE.ORG' --maprule '(ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500})'
    -------------------------------------------------------
    Added Certificate Identity Mapping Rule "rule_name"
    -------------------------------------------------------
      Rule name: rule_name
      Mapping rule: (ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500})
      Matching rule: <ISSUER>CN=Smart Card CA,O=EXAMPLE.ORG
      Enabled: TRUE
  3. The System Security Services Daemon (SSSD) periodically re-reads the certificate mapping rules. To force the newly-created rule to be loaded immediately, restart SSSD:

    # systemctl restart sssd

Now you have a certificate mapping rule set up that compares the type of data specified in the mapping rule that it finds on a smart card certificate with the certificate mapping data in your IdM user entries. Once it finds a match, it authenticates the matching user.

34.2.2. Adding certificate mapping data to a user entry in IdM

This section describes how to enter certificate mapping data to an IdM user entry so that the user can authenticate using multiple certificates as long as they all contain the values specified in the certificate mapping data entry.

34.2.2.1. Adding certificate mapping data to a user entry in the IdM web UI

  1. Log into the IdM web UI as an administrator.
  2. Navigate to UsersActive usersidm_user.
  3. Find the Certificate mapping data option and click Add.
  4. If you have the certificate of idm_user at your disposal:

    1. In the Command-Line Interface, display the certificate using the cat utility or a text editor:

      [root@server ~]# cat idm_user_certificate.pem
      -----BEGIN CERTIFICATE-----
      MIIFFTCCA/2gAwIBAgIBEjANBgkqhkiG9w0BAQsFADA6MRgwFgYDVQQKDA9JRE0u
      RVhBTVBMRS5DT00xHjAcBgNVBAMMFUNlcnRpZmljYXRlIEF1dGhvcml0eTAeFw0x
      ODA5MDIxODE1MzlaFw0yMDA5MDIxODE1MzlaMCwxGDAWBgNVBAoMD0lETS5FWEFN
      [...output truncated...]
    2. Copy the certificate.
    3. In the IdM web UI, click Add next to Certificate and paste the certificate into the window that opens up.

      Figure 34.3. Adding a user’s certificate mapping data: certificate

      user add cert

      Alternatively, if you do not have the certificate of idm_user at your disposal but know the Issuer and the Subject of the certificate, check the radio button of Issuer and subject and enter the values in the two respective boxes.

      Figure 34.4. Adding a user’s certificate mapping data: issuer and subject

      user add certdata
  5. Click Add.
  6. Optionally, if you have access to the whole certificate in the .pem format, verify that the user and certificate are linked:

    1. Use the sss_cache utility to invalidate the record of idm_user in the SSSD cache and force a reload of the idm_user information:

      # sss_cache -u idm_user
    2. Run the ipa certmap-match command with the name of the file containing the certificate of the IdM user:

      # ipa certmap-match idm_user_cert.pem
      --------------
      1 user matched
      --------------
       Domain: IDM.EXAMPLE.COM
       User logins: idm_user
      ----------------------------
      Number of entries returned 1
      ----------------------------

      The output confirms that now you have certificate mapping data added to idm_user and that a corresponding mapping rule defined in Adding a certificate mapping rule in IdM exists. This means that you can use any certificate that matches the defined certificate mapping data to authenticate as idm_user.

34.2.2.2. Adding certificate mapping data to a user entry in the IdM CLI

  1. Obtain the administrator’s credentials:

    # kinit admin
  2. If you have the certificate of idm_user at your disposal, add the certificate to the user account using the ipa user-add-cert command:

    # CERT=`cat idm_user_cert.pem | tail -n +2| head -n -1 | tr -d '\r\n'\`
    # ipa user-add-certmapdata idm_user --certificate $CERT

    Alternatively, if you do not have the certificate of idm_user at your disposal but know the Issuer and the Subject of idm_user’s certificate:

    # ipa user-add-certmapdata idm_user --subject "O=EXAMPLE.ORG,CN=test" --issuer "CN=Smart Card CA,O=EXAMPLE.ORG"
    --------------------------------------------
    Added certificate mappings to user "idm_user"
    --------------------------------------------
      User login: idm_user
      Certificate mapping data: X509:<I>O=EXAMPLE.ORG,CN=Smart Card CA<S>CN=test,O=EXAMPLE.ORG
  3. Optionally, if you have access to the whole certificate in the .pem format, verify that the user and certificate are linked:

    1. Use the sss_cache utility to invalidate the record of idm_user in the SSSD cache and force a reload of the idm_user information:

      # sss_cache -u idm_user
    2. Run the ipa certmap-match command with the name of the file containing the certificate of the IdM user:

      # ipa certmap-match idm_user_cert.pem
      --------------
      1 user matched
      --------------
       Domain: IDM.EXAMPLE.COM
       User logins: idm_user
      ----------------------------
      Number of entries returned 1
      ----------------------------

      The output confirms that now you have certificate mapping data added to idm_user and that a corresponding mapping rule defined in Adding a certificate mapping rule in IdM exists. This means that you can use any certificate that matches the defined certificate mapping data to authenticate as idm_user.

34.3. Configuring certificate mapping for users whose AD user entry contains the whole certificate

This user story describes the steps necessary for enabling certificate mapping in IdM if the IdM deployment is in trust with Active Directory (AD), the user is stored in AD and the user entry in AD contains the whole certificate.

Prerequisites

  • The user does not have an account in IdM.
  • The user has an account in AD which contains a certificate.
  • The IdM administrator has access to data on which the IdM certificate mapping rule can be based.

34.3.1. Adding a certificate mapping rule for users whose AD entry contains whole certificates

34.3.1.1. Adding a certificate mapping rule in the IdM web UI

  1. Log into the IdM web UI as an administrator.
  2. Navigate to AuthenticationCertificate Identity Mapping RulesCertificate Identity Mapping Rules.
  3. Click Add.

    Figure 34.5. Adding a new certificate mapping rule in the IdM web UI

    new certmaprule add
  4. Enter the rule name.
  5. Enter the mapping rule. To have the whole certificate that is presented to IdM for authentication compared to what is available in AD:

    (userCertificate;binary={cert!bin})
  6. Enter the matching rule. For example, to only allow certificates issued by the AD-ROOT-CA of the AD.EXAMPLE.COM domain to authenticate:

    <ISSUER>CN=AD-ROOT-CA,DC=ad,DC=example,DC=com

    Figure 34.6. Certificate mapping rule for a user with a certificate stored in AD

    certmaprule add details ad cert
  7. Click Add.
  8. The System Security Services Daemon (SSSD) periodically re-reads the certificate mapping rules. To force the newly-created rule to be loaded immediately, restart SSSD in the CLI::

    # systemctl restart sssd

34.3.1.2. Adding a certificate mapping rule in the IdM CLI

  1. Obtain the administrator’s credentials:

    # kinit admin
  2. Enter the mapping rule and the matching rule the mapping rule is based on. To have the whole certificate that is presented for authentication compared to what is available in AD, only allowing certificates issued by the AD-ROOT-CA of the AD.EXAMPLE.COM domain to authenticate:

    # ipa certmaprule-add simpleADrule --matchrule '<ISSUER>CN=AD-ROOT-CA,DC=ad,DC=example,DC=com' --maprule '(userCertificate;binary={cert!bin})' --domain ad.example.com
    -------------------------------------------------------
    Added Certificate Identity Mapping Rule "simpleADrule"
    -------------------------------------------------------
      Rule name: simpleADrule
      Mapping rule: (userCertificate;binary={cert!bin})
      Matching rule: <ISSUER>CN=AD-ROOT-CA,DC=ad,DC=example,DC=com
      Domain name: ad.example.com
      Enabled: TRUE
  3. The System Security Services Daemon (SSSD) periodically re-reads the certificate mapping rules. To force the newly-created rule to be loaded immediately, restart SSSD:

    # systemctl restart sssd

34.4. Configuring certificate mapping if AD is configured to map user certificates to user accounts

This user story describes the steps necessary for enabling certificate mapping in IdM if the IdM deployment is in trust with Active Directory (AD), the user is stored in AD and the user entry in AD contains certificate mapping data.

Prerequisites

  • The user does not have an account in IdM.
  • The user has an account in AD which contains the altSecurityIdentities attribute, the AD equivalent of the IdM certmapdata attribute.
  • The IdM administrator has access to data on which the IdM certificate mapping rule can be based.

34.4.1. Adding a certificate mapping rule if the trusted AD domain is configured to map user certificates

34.4.1.1. Adding a certificate mapping rule in the IdM web UI

  1. Log into the IdM web UI as an administrator.
  2. Navigate to AuthenticationCertificate Identity Mapping RulesCertificate Identity Mapping Rules.
  3. Click Add.

    Figure 34.7. Adding a new certificate mapping rule in the IdM web UI

    new certmaprule add
  4. Enter the rule name.
  5. Enter the mapping rule. For example, to make AD DC search for the Issuer and Subject entries in any certificate presented, and base its decision to authenticate or not on the information found in these two entries of the presented certificate:

    (altSecurityIdentities=X509:<I>{issuer_dn!ad_x500}<S>{subject_dn!ad_x500})
  6. Enter the matching rule. For example, to only allow certificates issued by the AD-ROOT-CA of the AD.EXAMPLE.COM domain to authenticate users to IdM:

    <ISSUER>CN=AD-ROOT-CA,DC=ad,DC=example,DC=com
  7. Enter the domain:

    ad.example.com

    Figure 34.8. Certificate mapping rule if AD is configured for mapping

    certmaprule add details ad map
  8. Click Add.
  9. The System Security Services Daemon (SSSD) periodically re-reads the certificate mapping rules. To force the newly-created rule to be loaded immediately, restart SSSD in the CLI::

    # systemctl restart sssd

34.4.1.2. Adding a certificate mapping rule in the IdM CLI

  1. Obtain the administrator’s credentials:

    # kinit admin
  2. Enter the mapping rule and the matching rule the mapping rule is based on. For example, to make AD search for the Issuer and Subject entries in any certificate presented, and only allow certificates issued by the AD-ROOT-CA of the AD.EXAMPLE.COM domain:

    # ipa certmaprule-add ad_configured_for_mapping_rule --matchrule '<ISSUER>CN=AD-ROOT-CA,DC=ad,DC=example,DC=com' --maprule '(altSecurityIdentities=X509:<I>{issuer_dn!ad_x500}<S>{subject_dn!ad_x500})' --domain=ad.example.com
    -------------------------------------------------------
    Added Certificate Identity Mapping Rule "ad_configured_for_mapping_rule"
    -------------------------------------------------------
      Rule name: ad_configured_for_mapping_rule
      Mapping rule: (altSecurityIdentities=X509:<I>{issuer_dn!ad_x500}<S>{subject_dn!ad_x500})
      Matching rule: <ISSUER>CN=AD-ROOT-CA,DC=ad,DC=example,DC=com
      Domain name: ad.example.com
      Enabled: TRUE
  3. The System Security Services Daemon (SSSD) periodically re-reads the certificate mapping rules. To force the newly-created rule to be loaded immediately, restart SSSD:

    # systemctl restart sssd

34.4.2. Checking certificate mapping data on the AD side

The altSecurityIdentities attribute is the Active Directory (AD) equivalent of certmapdata user attribute in IdM. When configuring certificate mapping in IdM in the scenario when a trusted AD domain is configured to map user certificates to user accounts, the IdM system administrator needs to check that the altSecurityIdentities attribute is set correctly in the user entries in AD.

To check that AD contains the right information for the user stored in AD, use the ldapsearch command.

  • For example, enter the command below to check with the adserver.ad.example.com server that the following conditions apply:

    • The altSecurityIdentities attribute is set in the user entry of ad_user.
    • The matchrule stipulates that the following conditions apply:

      • The certificate that ad_user uses to authenticate to AD was issued by AD-ROOT-CA of the ad.example.com domain.
      • The subject is <S>DC=com,DC=example,DC=ad,CN=Users,CN=ad_user:
    $ ldapsearch -o ldif-wrap=no -LLL -h adserver.ad.example.com \
    -p 389 -D cn=Administrator,cn=users,dc=ad,dc=example,dc=com \
    -W -b cn=users,dc=ad,dc=example,dc=com "(cn=ad_user)" \
    altSecurityIdentities
    Enter LDAP Password:
    dn: CN=ad_user,CN=Users,DC=ad,DC=example,DC=com
    altSecurityIdentities: X509:<I>DC=com,DC=example,DC=ad,CN=AD-ROOT-CA<S>DC=com,DC=example,DC=ad,CN=Users,CN=ad_user

34.5. Configuring certificate mapping if AD user entry contains no certificate or mapping data

This user story describes the steps necessary for enabling certificate mapping in IdM if the IdM deployment is in trust with Active Directory (AD), the user is stored in AD and the user entry in AD contains neither the whole certificate nor certificate mapping data.

Prerequisites

  • The user does not have an account in IdM.
  • The user has an account in AD which contains neither the whole certificate nor the altSecurityIdentities attribute, the AD equivalent of the IdM certmapdata attribute.
  • The IdM administrator has the whole AD user certificate to add to the AD user’s user ID override in IdM.

34.5.1. Adding a certificate mapping rule if the AD user entry contains no certificate or mapping data

34.5.1.1. Adding a certificate mapping rule in the IdM web UI

  1. Log into the IdM web UI as an administrator.
  2. Navigate to AuthenticationCertificate Identity Mapping RulesCertificate Identity Mapping Rules.
  3. Click Add.

    Figure 34.9. Adding a new certificate mapping rule in the IdM web UI

    new certmaprule add
  4. Enter the rule name.
  5. Enter the mapping rule. To have the whole certificate that is presented to IdM for authentication compared to the certificate stored in the user ID override entry of the AD user entry in IdM:

    (userCertificate;binary={cert!bin})
  6. Enter the matching rule. For example, to only allow certificates issued by the AD-ROOT-CA of the AD.EXAMPLE.COM domain to authenticate:

    <ISSUER>CN=AD-ROOT-CA,DC=ad,DC=example,DC=com
  7. Enter the domain name. For example, to search for users in the ad.example.com domain:

    Figure 34.10. Certificate mapping rule for a user with no certificate or mapping data stored in AD

    certmaprule add details ad cert
  8. Click Add.
  9. The System Security Services Daemon (SSSD) periodically re-reads the certificate mapping rules. To force the newly-created rule to be loaded immediately, restart SSSD in the CLI:

    # systemctl restart sssd

34.5.1.2. Adding a certificate mapping rule in the IdM CLI

  1. Obtain the administrator’s credentials:

    # kinit admin
  2. Enter the mapping rule and the matching rule the mapping rule is based on. To have the whole certificate that is presented for authentication compared to the certificate stored in the user ID override entry of the AD user entry in IdM, only allowing certificates issued by the AD-ROOT-CA of the AD.EXAMPLE.COM domain to authenticate:

    # ipa certmaprule-add simpleADrule --matchrule '<ISSUER>CN=AD-ROOT-CA,DC=ad,DC=example,DC=com' --maprule '(userCertificate;binary={cert!bin})' --domain ad.example.com
    -------------------------------------------------------
    Added Certificate Identity Mapping Rule "simpleADrule"
    -------------------------------------------------------
      Rule name: simpleADrule
      Mapping rule: (userCertificate;binary={cert!bin})
      Matching rule: <ISSUER>CN=AD-ROOT-CA,DC=ad,DC=example,DC=com
      Domain name: ad.example.com
      Enabled: TRUE
  3. The System Security Services Daemon (SSSD) periodically re-reads the certificate mapping rules. To force the newly-created rule to be loaded immediately, restart SSSD:

    # systemctl restart sssd

34.5.2. Adding a certificate to an AD user’s ID override if the user entry in AD contains no certificate or mapping data

34.5.2.1. Adding a certificate to an AD user’s ID override in the IdM web UI

  1. Navigate to IdentityID ViewsDefault Trust View.
  2. Click Add.

    Figure 34.11. Adding a new user ID override in the IdM web UI

    new useridoverride add
  3. In the User to override field, enter ad_user@ad.example.com.
  4. Copy and paste the certificate of ad_user into the Certificate field.

    Figure 34.12. Configuring the User ID override for an AD user

    useridoverride add details
  5. Click Add.
  6. Optionally, verify that the user and certificate are linked:

    1. Use the sss_cache utility to invalidate the record of ad_user@ad.example.com in the SSSD cache and force a reload of the ad_user@ad.example.com information:

      # sss_cache -u ad_user@ad.example.com
    2. Run the ipa certmap-match command with the name of the file containing the certificate of the AD user:

      # ipa certmap-match ad_user_cert.pem
      --------------
      1 user matched
      --------------
       Domain: AD.EXAMPLE.COM
       User logins: ad_user@ad.example.com
      ----------------------------
      Number of entries returned 1
      ----------------------------

      The output confirms that you have certificate mapping data added to ad_user@ad.example.com and that a corresponding mapping rule defined in Adding a certificate mapping rule if the AD user entry contains no certificate or mapping data exists. This means that you can use any certificate that matches the defined certificate mapping data to authenticate as ad_user@ad.example.com.

34.5.2.2. Adding a certificate to an AD user’s ID override in the IdM CLI

  1. Obtain the administrator’s credentials:

    # kinit admin
  2. Add the certificate of ad_user@ad.example.com to the user account using the ipa idoverrideuser-add-cert command:

    # CERT=`cat ad_user_cert.pem | tail -n +2| head -n -1 | tr -d '\r\n'\`
    # ipa idoverrideuser-add-cert ad_user@ad.example.com --certificate $CERT
  3. Optionally, verify that the user and certificate are linked:

    1. Use the sss_cache utility to invalidate the record of ad_user@ad.example.com in the SSSD cache and force a reload of the ad_user@ad.example.com information:

      # sss_cache -u ad_user@ad.example.com
    2. Run the ipa certmap-match command with the name of the file containing the certificate of the AD user:

      # ipa certmap-match ad_user_cert.pem
      --------------
      1 user matched
      --------------
       Domain: AD.EXAMPLE.COM
       User logins: ad_user@ad.example.com
      ----------------------------
      Number of entries returned 1
      ----------------------------

      The output confirms that you have certificate mapping data added to ad_user@ad.example.com and that a corresponding mapping rule defined in Adding a certificate mapping rule if the AD user entry contains no certificate or mapping data exists. This means that you can use any certificate that matches the defined certificate mapping data to authenticate as ad_user@ad.example.com.

34.6. Combining several identity mapping rules into one

To combine several identity mapping rules into one combined rule, use the | (or) character to precede the individual mapping rules, and separate them using () brackets, for example:

Certificate mapping filter example 1

$ ipa certmaprule-add ad_cert_for_ipa_and_ad_users \ --maprule='(|(ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500})(altSecurityIdentities=X509:<I>{issuer_dn!ad_x500}<S>{subject_dn!ad_x500}))' \ --matchrule='<ISSUER>CN=AD-ROOT-CA,DC=ad,DC=example,DC=com' \ --domain=ad.example.com

In the above example, the filter definition in the --maprule option includes these criteria:

  • ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500} is a filter that links the subject and issuer from a smart card certificate to the value of the ipacertmapdata attribute in an IdM user account, as described in Adding a certificate mapping rule in IdM
  • altSecurityIdentities=X509:<I>{issuer_dn!ad_x500}<S>{subject_dn!ad_x500} is a filter that links the subject and issuer from a smart card certificate to the value of the altSecurityIdentities attribute in an AD user account, as described in Adding a certificate mapping rule if the trusted AD domain is configured to map user certificates
  • The addition of the --domain=ad.example.com option means that users mapped to a given certificate are not only searched in the local idm.example.com domain but also in the ad.example.com domain

The filter definition in the --maprule option accepts the logical operator | (or), so that you can specify multiple criteria. In this case, the rule maps all user accounts that meet at least one of the criteria.

Certificate mapping filter example 2

$ ipa certmaprule-add ipa_cert_for_ad_users \
  --maprule='(|(userCertificate;binary={cert!bin})(ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500})(altSecurityIdentities=X509:<I>{issuer_dn!ad_x500}<S>{subject_dn!ad_x500}))' \
  --matchrule='<ISSUER>CN=Certificate Authority,O=REALM.EXAMPLE.COM' \
  --domain=idm.example.com --domain=ad.example.com

In the above example, the filter definition in the --maprule option includes these criteria:

The filter definition in the --maprule option accepts the logical operator | (or), so that you can specify multiple criteria. In this case, the rule maps all user accounts that meet at least one of the criteria.

Chapter 35. Configuring authentication with a certificate stored on the desktop of an IdM client

By configuring Identity Management (IdM), IdM system administrators can enable users to authenticate to the IdM web UI and command-line interface (CLI) using a certificate that a Certificate Authority (CA) has issued to the users.

The web browser can run on a system that is not part of the IdM domain.

This user story provides instructions on how to effectively configure and test logging into Identity Management web UI and CLI with a certificate stored on the desktop of an IdM client. In following this user story,

Note

Only Identity Management users can log into the web UI using a certificate. Active Directory users can log in with their user name and password.

35.1. Configuring the Identity Management Server for Certificate Authentication in the Web UI

As an Identity Management (IdM) administrator, you can allow users to use certificates to authenticate to your IdM environment.

Procedure

As the Identity Management administrator:

  1. On an Identity Management server, obtain administrator privileges and create a shell script to configure the server.

    1. Run the ipa-advise config-server-for-smart-card-auth command, and save its output to a file, for example server_certificate_script.sh:

      # kinit admin
      # ipa-advise config-server-for-smart-card-auth > server_certificate_script.sh
    2. Add execute permissions to the file using the chmod utility:

      # chmod +x server_certificate_script.sh
  2. On all the servers in the Identity Management domain, run the server_certificate_script.sh script

    1. with the path of the IdM Certificate Authority certificate, /etc/ipa/ca.crt, as input if the IdM CA is the only certificate authority that has issued the certificates of the users you want to enable certificate authentication for:

      # ./server_certificate_script.sh /etc/ipa/ca.crt
    2. with the paths leading to the relevant CA certificates as input if different external CAs signed the certificates of the users who you want to enable certificate authentication for:

      # ./server_certificate_script.sh /tmp/ca1.pem /tmp/ca2.pem
Note

Do not forget to run the script on each new replica that you add to the system in the future if you want to have certificate authentication for users enabled in the whole topology.

35.2. Requesting a new user certificate and exporting it to the client

As an Identity Management (IdM) administrator, you can create certificates for users in your IdM environment and export them to the IdM clients on which you want to enable certificate authentication for users.

Note

You can skip this section if the user you want to authenticate using a certificate already has a certificate.

Procedure

  1. Optionally, create a new directory, for example ~/certdb/, and make it a temporary certificate database. When asked, create an NSS Certificate DB password to encrypt the keys to the certificate to be generated in a subsequent step:

    # mkdir ~/certdb/
    # certutil -N -d ~/certdb/
    Enter a password which will be used to encrypt your keys.
    The password should be at least 8 characters long,
    and should contain at least one non-alphabetic character.
    
    Enter new password:
    Re-enter password:
  2. Create the certificate signing request (CSR) and redirect the output to a file. For example, to create a CSR with the name certificate_request.csr for a 4096 bit certificate for the idm_user user in the IDM.EXAMPLE.COM realm, setting the nickname of the certificate private keys to idm_user for easy findability, and setting the subject to CN=idm_user,O=IDM.EXAMPLE.COM:

    # certutil -R -d ~/certdb/ -a -g 4096 -n idm_user -s "CN=idm_user,O=IDM.EXAMPLE.COM" > certificate_request.csr
  3. When prompted, enter the same password that you entered when using certutil to create the temporary database. Then continue typing randlomly until told to stop:

    Enter Password or Pin for "NSS Certificate DB":
    
    A random seed must be generated that will be used in the
    creation of your key.  One of the easiest ways to create a
    random seed is to use the timing of keystrokes on a keyboard.
    
    To begin, type keys on the keyboard until this progress meter
    is full.  DO NOT USE THE AUTOREPEAT FUNCTION ON YOUR KEYBOARD!
    
    
    Continue typing until the progress meter is full:
  4. Submit the certificate request file to the server. Specify the Kerberos principal to associate with the newly-issued certificate, the output file to store the certificate, and optionally the certificate profile. For example, to obtain a certificate of the IECUserRoles profile, a profile with added user roles extension, for the idm_user@IDM.EXAMPLE.COM principal, and save it in the ~/idm_user.pem file:

    # ipa cert-request certificate_request.csr --principal=idm_user@IDM.EXAMPLE.COM --profile-id=IECUserRoles --certificate-out=~/idm_user.pem
  5. Add the certificate to the NSS database. Use the -n option to set the same nickname that you used when creating the CSR previously so that the certificate matches the private key in the NSS database. The -t option sets the trust level. For details, see the certutil(1) man page. The -i option specifies the input certificate file. For example, to add to the NSS database a certificate with the idm_user nickname that is stored in the ~/idm_user.pem file in the ~/certdb/ database:

    # certutil -A -d ~/certdb/ -n idm_user -t "P,," -i ~/idm_user.pem
  6. Verify that the key in the NSS database does not show (orphan) as its nickname. For example, to verify that the certificate stored in the ~/certdb/ database is not orphaned:

    # certutil -K -d ~/certdb/
    < 0> rsa      5ad14d41463b87a095b1896cf0068ccc467df395   NSS Certificate DB:idm_user
  7. Use the pk12util command to export the certificate from the NSS database to the PKCS12 format. For example, to export the certificate with the idm_user nickname from the /root/certdb NSS database into the ~/idm_user.p12 file:

    # pk12util -d ~/certdb -o ~/idm_user.p12 -n idm_user
    Enter Password or Pin for "NSS Certificate DB":
    Enter password for PKCS12 file:
    Re-enter password:
    pk12util: PKCS12 EXPORT SUCCESSFUL
  8. Transfer the certificate to the host on which you want the certificate authentication for idm_user to be enabled:

    # scp ~/idm_user.p12 idm_user@client.idm.example.com:/home/idm_user/
  9. On the host to which the certificate has been transferred, make the directory in which the .pkcs12 file is stored inaccessible to the 'other' group for security reasons:

    # chmod o-rwx /home/idm_user/
  10. For security reasons, remove the temporary NSS database and the .pkcs12 file from the server:

    # rm ~/certdb/
    # rm ~/idm_user.p12

35.3. Making sure the certificate and user are linked together

Note

You can skip this section if the user’s certificate has been issued by the IdM CA.

For certificate authentication to work, you need to make sure that the certificate is linked to the user that will use it to authenticate to Identity Management (IdM).

35.4. Configuring a browser to enable certificate authentication

To be able to authenticate with a certificate when using the WebUI to log into Identity Management (IdM), you need to import the user and the relevant certificate authority (CA) certificates into the Mozilla Firefox or Google Chrome browser. The host itself on which the browser is running does not have to be part of the IdM domain.

IdM supports the following browsers for connecting to the WebUI:

  • Mozilla Firefox 38 and later
  • Google Chrome 46 and later

The following procedure shows how to configure the Mozilla Firefox 57.0.1 browser.

Prerequisites

  • You have the user certificate that you want to import to the browser at your disposal in the PKCS#12 format.

Procedure

  1. Open Firefox, then navigate to PreferencesPrivacy & Security.

    Figure 35.1. Privacy and Security section in Preferences

    privacy and security
  2. Click View Certificates.

    Figure 35.2. View Certificates in Privacy and Security

    view certificates
  3. In the Your Certificates tab, click Import. Locate and open the certificate of the user in the PKCS12 format, then click OK and OK.
  4. Make sure that the Identity Management Certificate Authority is recognized by Firefox as a trusted authority:

    1. Save the IdM CA certificate locally:

      • Navigate to the IdM web UI by writing the name of your IdM server in the Firefox address bar. Click Advanced on the Insecure Connection warning page.

        Figure 35.3. Insecure Connection

        connection not secure idm
      • Add Exception. Click View.

        Figure 35.4. View the Details of a Certificate

        view ca certificate idm
      • In the Details tab, highlight the Certificate Authority fields.

        Figure 35.5. Exporting the CA Certificate

        exporting ca cert idm
      • Click Export. Save the CA certificate, for example as the CertificateAuthority.crt file, then click Close, and Cancel.
    2. Import the IdM CA certificate to Firefox as a trusted certificate authority certificate:

      • Open Firefox, navigate to Preferences and click Privacy & Security.

        Figure 35.6. Privacy and Security section in Preferences

        privacy and security
      • Click View Certificates.

        Figure 35.7. View Certificates in Privacy and Security

        view certificates
      • In the Authorities tab, click Import. Locate and open the CA certificate that you saved in the previous step in the CertificateAuthority.crt file. Trust the certificate to identify websites, then click OK and OK.
  5. Continue to Authenticating to the Identity Management Web UI with a Certificate as an Identity Management User.

35.5. Authenticating to the Identity Management Web UI with a Certificate as an Identity Management User

This procedure describes authenticating as a user to the Identity Management (IdM) web UI using a certificate stored on the desktop of an Identity Management client.

Procedure

  1. In the browser, navigate to the Identity Management web UI at, for example, https://server.idm.example.com/ipa/ui.
  2. Click Login Using Certificate.

    .Login Using Certificate in the Identity Management web UI

    smart card login
  3. The user’s certificate should already be selected. Uncheck Remember this decision, then click OK.

You are now authenticated as the user who corresponds to the certificate.

Additional resources

  • For information about authenticating to the IdM web UI using a certificate stored on a smart card, see

35.6. Configuring an IdM client to enable authenticating to the CLI using a certificate

To make certificate authentication work for an IdM user in the Command Line Interface (CLI) of your IdM client, import the IdM user’s certificate and the private key to the IdM client. For details on creating and transferring the user certificate, see Section 35.2, “Requesting a new user certificate and exporting it to the client”.

Procedure

  • Log into the IdM client and have the .p12 file containing the user’s certificate and the private key ready. To obtain and cache the Kerberos ticket granting ticket (TGT), run the kinit command with the user’s principal, using the -X option with the X509_username:/path/to/file.p12 attribute to specify where to find the user’s X509 identity information. For example, to obtain the TGT for idm_user using the user’s identity information stored in the ~/idm_user.p12 file:

    $ kinit -X X509_idm_user='PKCS12:~/idm_user.p12' idm_user
    Note

    The command also supports the .pem file format: kinit -X X509_username='FILE:/path/to/cert.pem,/path/to/key' user_principal

Chapter 36. Using IdM CA renewal master

36.1. Explanation of IdM CA renewal master

In an Identity Management (IdM) deployment that uses an embedded certificate authority (CA), the CA renewal master server maintains and renews IdM system certificates. It ensures nondisruptive IdM deployments.

IdM system certificates include:

  • IdM CA certificate
  • OCSP signing certificate
  • IdM CA subsystem certificates
  • IdM CA audit signing certificate
  • IdM renewal agent (RA) certificate
  • KRA transport and storage certificates

What characterizes system certificates is that their keys are shared by all CA replicas. In contrast, the IdM service certificates (for example, LDAP, HTTP and PKINIT certificates), have different keypairs and subject names on different IdM CA servers.

In IdM topology, by default, the first master IdM CA server is the CA renewal master.

Note

In upstream documentation, the IdM CA is called Dogtag.

The role of the CA renewal master server

The IdM CA, IdM CA subsystem, and IdM RA certificates are crucial for IdM deployment. Each certificate is stored in an NSS database in the /etc/pki/pki-tomcat/ directory and also as an LDAP database entry. The certificate stored in LDAP must match the certificate stored in the NSS database. If they do not match, authentication failures occur between the IdM framework and IdM CA, and between IdM CA and LDAP.

All IdM CA replicas have tracking requests for every system certificate. If an IdM deployment with integrated CA does not contain a CA renewal master, each IdM CA server requests the renewal of system certificates independently. This results in different CA replicas having various system certificates and authentication failures occurring.

Appointing one CA replica as the renewal master allows the system certificates to be renewed exactly once, when required, and thus prevents authentication failures.

The role of certmonger on CA replicas

The certmonger service running on all IdM CA replicas uses the dogtag-ipa-ca-renew-agent renewal helper to keep track of IdM system certificates. The renewal helper program reads the CA renewal master configuration. On each CA replica that is not the CA renewal master, the renewal helper programme retrieves the latest system certificates from the ca_renewal LDAP entries. Due to non-determinism in when exactly certmonger renewal attempts occur, the dogtag-ipa-ca-renew-agent helper sometimes attempts to update a system certificate before the CA renewal master has actually renewed the certificate. If this happens, the old, soon-to-expire certificate is returned to the certmonger on the CA replica. The certmonger, realizing it is the same certificate that is already stored in its database, keeps attempting to renew the certificate with some delay between individual attempts until it can retrieve the updated certificate from the CA renewal master.

The correct functioning of IdM CA renewal master

An IdM deployment with an embedded CA is an IdM deployment that was installed with an IdM CA - or whose IdM CA master server was installed later. An IdM deployment with an embedded CA must at all times have exactly one CA replica configured as the renewal master. The renewal master server must be online and fully functional, and must replicate properly with the other servers.

If the current CA renewal master server is being deleted using the ipa server-del, ipa-replica-manage del, ipa-csreplica-manage del or ipa-server-install --uninstall commands, a CA replica is automatically assigned as the CA renewal master server. This policy ensures that the renewal master configuration remains valid.

This policy does not cover the following situations:

  • Offline renewal master

    • If the renewal master is offline for an extended duration, it may miss a renewal window. In this situation, all nonrenewal master servers keep reinstalling the current system certificates until the certificates expire. When this occurs, the IdM deployment is disrupted because even one expired certificate can cause renewal failures for other certificates. To prevent this situation: if your current renewal master is offline and unavailable for an extended period of time, consider assigning a new CA renewal master manually.
  • Replication problems

    • If replication problems exist between the renewal master and other CA replicas, renewal might succeed, but the other CA replicas might not be able to retrieve the updated certificates before they expire. To prevent this situation, make sure that your replication agreements are working correctly. For details, see general or specific replication troubleshooting guidelines in the RHEL 7 Linux Domain Identity, Authentication, and Policy Guide.

36.2. Changing and resetting IdM CA renewal master

When a certificate authority (CA) renewal master is being decommissioned, Identity Management (IdM) automatically selects a new CA renewal master from the list of IdM CA servers. The system administrator cannot influence the selection.

To be able to select the new IdM CA renewal master server, the system administrator must perform the replacement manually. Select the master before starting the process of decommissioning the current renewal master.

If the current CA renewal master configuration is invalid, reset the IdM CA renewal master.

Complete this procedure to change or reset the CA renewal master.

Prerequisites

  • You have the IdM administrator credentials.

Procedure

  1. Obtain the IdM administrator credentials:

    ~]$ kinit admin
    Password for admin@IDM.EXAMPLE.COM:
  2. Optionally, to find out which IdM servers in the deployment have the CA role necessary to be eligible to become the new CA renewal master:

    ~]$ ipa server-role-find --role 'CA server'
    ----------------------
    2 server roles matched
    ----------------------
      Server name: server.idm.example.com
      Role name: CA server
      Role status: enabled
    
      Server name: replica.idm.example.com
      Role name: CA server
      Role status: enabled
    ----------------------------
    Number of entries returned 2
    ----------------------------

    There are two CA servers in the deployment.

  3. Optionally, to find out which CA server is the current CA renewal master, enter:

    ~]$ ipa config-show | grep 'CA renewal master'
      IPA CA renewal master: server.idm.example.com

    The current renewal master is server.idm.example.com.

  4. To change the renewal master configuration, use the ipa config-mod utility with the --ca-renewal-master-server option:

    ~]$ ipa config-mod --ca-renewal-master-server replica.idm.example.com | grep 'CA renewal master'
      IPA CA renewal master: replica.idm.example.com
    Important

    You can also switch to a new CA renewal master using:

    • the ipa-cacert-manage --renew command. This command both renews the CA certificate and makes the CA server on which you execute the command the new CA renewal master.
    • the ipa-cert-fix command. This command recovers the deployment when expired certificates are causing failures. It also makes the CA server on which you execute the command the new CA renewal master.

      For details, see Renewing expired system certificates when IdM is offline.

36.3. Switching from an externally to self-signed CA in IdM

Complete this procedure to switch from an externally-signed to a self-signed certificate of the Identity Management (IdM) certificate authority (CA). With a self-signed CA, the renewal of the CA certificate is managed automatically: a system administrator does not need to submit a certificate signing request (CSR) to an external authority.

Switching from an externally-signed to a self-signed CA replaces only the CA certificate. The certificates signed by the previous CA are still valid and still in use. For example, the certificate chain for the LDAP certificate remains unchanged even after you have moved to a self-signed CA:

external_CA certificate > IdM CA certificate > LDAP certificate

Prerequisites

  • You have root access to the IdM CA renewal master.
  • You have the IdM administrator credentials.

Procedure

  1. On the IdM CA renewal master, renew the CA certificate as self-signed:

    ~]# ipa-cacert-manage renew --self-signed
    Renewing CA certificate, please wait
    CA certificate successfully renewed
    The ipa-cacert-manage command was successful
  2. On all the IdM servers and clients, update the local IdM certificate databases with the certificates from the server:

    [client ~]$ kinit admin
    [client ~]$ ipa-certupdate
    Systemwide CA database updated.
    Systemwide CA database updated.
    The ipa-certupdate command was successful
  3. Optionally, to check if your update has been successful and the new CA certificate has been added to the /etc/ipa/ca.crt file:

    [client ~]$ openssl crl2pkcs7 -nocrl -certfile /etc/ipa/ca.crt | openssl pkcs7 -print_certs -text -noout
    [...]
    Certificate:
        Data:
            Version: 3 (0x2)
            Serial Number: 39 (0x27)
            Signature Algorithm: sha256WithRSAEncryption
            Issuer: O=IDM.EXAMPLE.COM, CN=Certificate Authority
            Validity
                Not Before: Jul  1 16:32:45 2019 GMT
                Not After : Jul  1 16:32:45 2039 GMT
            Subject: O=IDM.EXAMPLE.COM, CN=Certificate Authority
    [...]

    The output shows that the update has been successful as the new CA certificate is listed with the older CA certificates.

36.4. Renewing the IdM CA renewal master with an externally-signed certificate

This section describes how to renew the Identity Management (IdM) certificate authority (CA) certificate using an external CA to sign the certificate signing request (CSR). In this configuration, your IdM CA server is a subCA of the external CA. The external CA can, but does not have to, be an Active Directory Certificate Server (AD CS).

If the external certificate authority is AD CS, you can specify the template you want for the IdM CA certificate in the CSR. A certificate template defines the policies and rules that a CA uses when a certificate request is received. Certificate templates in AD correspond to certificate profiles in IdM.

You can define a specific AD CS template by its Object Identifier (OID). OIDs are unique numeric values issued by various issuing authorities to uniquely identify data elements, syntaxes, and other parts of distributed applications.

Alternatively, you can define a specific AD CS template by its name. For example, the name of the default profile used in a CSR submitted by an IdM CA to an AD CS is subCA.

To define a profile by specifying its OID or name in the CSR, use the external-ca-profile option. For details, see the ipa-cacert-manage man page.

Apart from using a ready-made certificate template, you can also create a custom certificate template in the AD CS, and use it in the CSR.

Prerequisites

  • You have root access to the IdM CA renewal master.
  • You have the IdM administrator credentials.

Procedure

Complete this procedure to renew the certificate of the IdM CA with external signing, regardless of whether current CA certificate is self-signed or externally-signed.

  1. Create a CSR to be submitted to the external CA:

    • If the external CA is an AD CS, use the --external-ca-type=ms-cs option. If you want a different template than the default subCA template, specify it using the --external-ca-profile option:

      ~]# ipa-cacert-manage renew --external-ca --external-ca-type=ms-cs [--external-ca-profile=PROFILE]
      Exporting CA certificate signing request, please wait
      The next step is to get /var/lib/ipa/ca.csr signed by your CA and re-run ipa-cacert-manage as:
      ipa-cacert-manage renew --external-cert-file=/path/to/signed_certificate --external-cert-file=/path/to/external_ca_certificate
      The ipa-cacert-manage command was successful
    • If the external CA is not an AD CS:

      ~]# ipa-cacert-manage renew --external-ca
      Exporting CA certificate signing request, please wait
      The next step is to get /var/lib/ipa/ca.csr signed by your CA and re-run ipa-cacert-manage as:
      ipa-cacert-manage renew --external-cert-file=/path/to/signed_certificate --external-cert-file=/path/to/external_ca_certificate
      The ipa-cacert-manage command was successful

      The output shows that a CSR has been created and is stored in the /var/lib/ipa/ca.csr file.

  2. Submit the CSR located in /var/lib/ipa/ca.csr to the external CA. The process differs depending on the service to be used as the external CA.
  3. Retrieve the issued certificate and the CA certificate chain for the issuing CA in a base 64-encoded blob, which is:

    • a PEM file if the external CA is not an AD CS.
    • a Base_64 certificate if the external CA is an AD CS.

      The process differs for every certificate service. Usually, a download link on a web page or in the notification email allows the administrator to download all the required certificates.

      If the external CA is an AD CS and you have submitted the CSR with a known template through the Microsoft Windows Certification Authority management window, the AD CS issues the certificate immediately and the Save Certificate dialog appears in the AD CS web interface, asking where to save the issued certificate.

  4. Run the ipa-cacert-manage renew command again, adding all the CA certificate files required to supply a full certificate chain. Specify as many files as you need, using the --external-cert-file option multiple times:

    ~]# ipa-cacert-manage renew --external-cert-file=/path/to/signed_certificate --external-cert-file=/path/to/external_ca_certificate_1 --external-cert-file=/path/to/external_ca_certificate_2
  5. On all the IdM servers and clients, update the local IdM certificate databases with the certificates from the server:

    [client ~]$ kinit admin
    [client ~]$ ipa-certupdate
    Systemwide CA database updated.
    Systemwide CA database updated.
    The ipa-certupdate command was successful
  6. Optionally, to check if your update has been successful and the new CA certificate has been added to the /etc/ipa/ca.crt file:

    [client ~]$ openssl crl2pkcs7 -nocrl -certfile /etc/ipa/ca.crt | openssl pkcs7 -print_certs -text -noout
    [...]
    Certificate:
        Data:
            Version: 3 (0x2)
            Serial Number: 39 (0x27)
            Signature Algorithm: sha256WithRSAEncryption
            Issuer: O=IDM.EXAMPLE.COM, CN=Certificate Authority
            Validity
                Not Before: Jul  1 16:32:45 2019 GMT
                Not After : Jul  1 16:32:45 2039 GMT
            Subject: O=IDM.EXAMPLE.COM, CN=Certificate Authority
    [...]

    The output shows that the update has been successful as the new CA certificate is listed with the older CA certificates.

Chapter 37. Renewing expired system certificates when IdM is offline

When a system certificate has expired, Identity Management (IdM) fails to start. IdM supports renewing system certificates when IdM is offline using the ipa-cert-fix tool.

Prerequisites

  • IdM is installed only on Red Hat Enterprise Linux 8.1 or later

37.1. Renewing expired system certificates on a CA Renewal Master

This section describes how to apply the ipa-cert-fix tool on expired IdM certificates.

Important

If you run the ipa-cert-fix tool on a CA (Certificate Authority) host that is not the CA Renewal Master, and the utility renews shared certificates, that host automatically becomes the new CA Renewal Master in the domain. There must be always only one CA Renewal Master in the domain to avoid inconsistencies.

Prerequisites

  • Log in to the server with administration rights

Procedure

  1. Start the ipa-cert-fix tool to analyze the system and list expired certificates that require renewal:

    # ipa-cert-fix
    ...
    The following certificates will be renewed:
    
    Dogtag sslserver certificate:
      Subject: CN=ca1.example.com,O=EXAMPLE.COM 201905222205
      Serial:  13
      Expires: 2019-05-12 05:55:47
    ...
    Enter "yes" to proceed:
  2. Enter yes to start the renewal process:

    Enter "yes" to proceed: yes
    Proceeding.
    Renewed Dogtag sslserver certificate:
      Subject: CN=ca1.example.com,O=EXAMPLE.COM 201905222205
      Serial:  268369925
      Expires: 2021-08-14 02:19:33
    ...
    
    Becoming renewal master.
    The ipa-cert-fix command was successful

    It can take up to one minute before ipa-cert-fix renews all expired certificates.

  3. Optionally, verify that all services are now running:

    # ipactl status
    Directory Service: RUNNING
    krb5kdc Service: RUNNING
    kadmin Service: RUNNING
    httpd Service: RUNNING
    ipa-custodia Service: RUNNING
    pki-tomcatd Service: RUNNING
    ipa-otpd Service: RUNNING
    ipa: INFO: The ipactl command was successful

At this point, certificates have been renewed and services are running. The next step is to check other servers in the IdM domain.

37.2. Verifying other IdM servers in the IdM domain after renewal

After the renewing the CA Renewal Master’s certificates with the ipa-cert-fix tool, you must:

  • Restart all other Identity Management (IdM) servers in the domain.
  • Check if certmonger renewed certificates.
  • If there are other Certificate Authority (CA) replicas with expired system certificates, renew those certificates with the ipa-cert-fix tool as well.

Prerequisites

  • Log in to the server with administration rights.

Procedure

  1. Restart IdM with the --force parameter:

    # ipactl restart --force

    With the --force parameter, the ipactl utility ignores individual service startup failures. For example, if the server is also a CA with expired certificates, the pki-tomcat service fails to start. This is expected and ignored because of using the --force parameter.

  2. After the restart, verify that the certmonger service renewed the certificates (certificate status says MONITORING):

    # getcert list | egrep '^Request|status:|subject:'
    Request ID '20190522120745':
            status: MONITORING
            subject: CN=IPA RA,O=EXAMPLE.COM 201905222205
    Request ID '20190522120834':
            status: MONITORING
            subject: CN=Certificate Authority,O=EXAMPLE.COM 201905222205
    ...

    It can take some time before certmonger renews the shared certificates on the replica.

  3. If the server is also a CA, the previous command reports CA_UNREACHABLE for the certificate the pki-tomcat service uses:

    Request ID '20190522120835':
            status: CA_UNREACHABLE
            subject: CN=ca2.example.com,O=EXAMPLE.COM 201905222205
    ...
  4. To renew this certificate, use the ipa-cert-fix utility:

    # ipa-cert-fix
    Dogtag sslserver certificate:
      Subject: CN=ca2.example.com,O=EXAMPLE.COM
      Serial:  3
      Expires: 2019-05-11 12:07:11
    
    Enter "yes" to proceed: yes
    Proceeding.
    Renewed Dogtag sslserver certificate:
      Subject: CN=ca2.example.com,O=EXAMPLE.COM 201905222205
      Serial:  15
      Expires: 2019-08-14 04:25:05
    
    The ipa-cert-fix command was successful

Now, all IdM certificates have been renewed and work correctly.

Chapter 38. Generating CRL on the IdM CA server

If your IdM deployment uses an embedded certificate authority (CA), you may need to move generating the Certificate Revocation List (CRL) from one Identity Management (IdM) server to another. It can be necessary, for example, when you want to migrate the server to another system.

Only one server must generate CRL. The CRL generation role is usually co-located with the IdM CA Renewal Master, but this is not mandatory. Before the CRL Generation Master is decommissioned, a new CRL Generation Master must be selected by the administrator and configured.

This chapter describes:

  • Stopping CRL generation on the IdM master.
  • Starting to generate CRL on the IdM replica.

38.1. Stopping CRL generation on IdM master server

To stop the Certificate Revocation List (CRL) generation on the IdM master server, use the ipa-crlgen-manage command. Before you disable the generation, verify that the server really generates CRL. You can then disable it.

Prerequisites

  • Identity Management (IdM) server is installed on the RHEL 8.1 system or newer.
  • You must be logged in as root.

Procedure

  1. Check if your master server is generating the CRL:

    [root@master ~]# ipa-crlgen-manage status
    CRL generation: enabled
    Last CRL update: 2019-10-31 12:00:00
    Last CRL Number: 6
    The ipa-crlgen-manage command was successful
  2. Stop generating CRL on the master server:

    [root@master ~]# ipa-crlgen-manage disable
    Stopping pki-tomcatd
    Editing /var/lib/pki/pki-tomcat/conf/ca/CS.cfg
    Starting pki-tomcatd
    Editing /etc/httpd/conf.d/ipa-pki-proxy.conf
    Restarting httpd
    CRL generation disabled on the local host. Please make sure to configure CRL generation on another master with ipa-crlgen-manage enable.
    The ipa-crlgen-manage command was successful
  3. Check if the master server stopped generating CRL:

    [root@master ~]# ipa-crlgen-manage status

The master server stopped generating CRL. The next step is to enable CRL generation on the new master server.

38.2. Starting CRL generation on IdM replica server

You can start the Certificate Revocation List (CRL) generation with the following command: ipa-crlgen-manage

Prerequisites

  • Identity Management (IdM) server is installed on the RHEL 8.1 system or newer.
  • The RHEL system must be an IdM Certificate Authority server.
  • You must be logged in as root.

Procedure

  1. To start with generating CRL:

    [root@replica1 ~]# ipa-crlgen-manage enable
    Stopping pki-tomcatd
    Editing /var/lib/pki/pki-tomcat/conf/ca/CS.cfg
    Starting pki-tomcatd
    Editing /etc/httpd/conf.d/ipa-pki-proxy.conf
    Restarting httpd
    Forcing CRL update
    CRL generation enabled on the local host. Please make sure to have only a single CRL generation master.
    The ipa-crlgen-manage command was successful
  2. To check if CRL is generated:

    [root@replica1 ~]# ipa-crlgen-manage status
    CRL generation: enabled
    Last CRL update: 2019-10-31 12:10:00
    Last CRL Number: 7
    The ipa-crlgen-manage command was successful

Chapter 39. Obtaining an IdM certificate for a service using certmonger

39.1. Certmonger overview

What certmonger does

When Identity Management (IdM) is installed with an integrated IdM Certificate Authority (CA), it uses the certmonger service to track and renew system and service certificates. When the certificate is reaching its expiration date, certmonger manages the renewal process by:

  • regenerating a certificate-signing request (CSR) using the options provided in the original request.
  • submitting the CSR to the IdM CA using the IdM API cert-request command.
  • receiving the certificate from the IdM CA.
  • executing a pre-save command if specified by the original request.
  • installing the new certificate in the location specified in the renewal request: either in an NSS database or in a file.
  • executing a post-save command if specified by the original request. For example, the post-save command can instruct certmonger to restart a relevant service, so that the service picks up the new certificate.

Types of certificates certmonger tracks

Certificates can be divided into system and service certificates.

Unlike service certificates (for example, for HTTP, LDAP and PKINIT), which have different keypairs and subject names on different servers, IdM system certificates and their keys are shared by all CA replicas. The IdM system certificates include:

  • IdM CA certificate
  • OCSP signing certificate
  • IdM CA subsystem certificates
  • IdM CA audit signing certificate
  • IdM renewal agent (RA) certificate
  • KRA transport and storage certificates

The certmonger service tracks the IdM system and service certificates that were requested during the installation of IdM environment with an integrated CA. Certmonger also tracks certificates that have been requested manually by the system administrator for other services running on the IdM host. Certmonger does not track external CA certificates or user certificates.

Certmonger components

The certmonger service consists of two main components:

  • The certmonger daemon, which is the engine tracking the list of certificates and launching renewal commands
  • The getcert utility for the command-line interface (CLI), which allows the system administrator to actively send commands to the certmonger daemon.

More specifically, the system administrator can use the getcert utility to:

39.2. Obtaining an IdM certificate for a service using certmonger

To ensure that communication between browsers and the web service running on your Identity Management (IdM) client is secure and encrypted, use a TLS certificate. Obtain the TLS certificate for your web service from the IdM Certificate Authority (CA).

This section describes how to use certmonger to obtain an IdM certificate for a service (HTTP/my_company.idm.example.com@IDM.EXAMPLE.COM) running on an IdM client.

Using certmonger to request the certificate automatically means that certmonger manages and renews the certificate when it is due for a renewal.

For a visual representation of what happens when certmonger requests a service certificate, see Section 39.3, “Communication flow for certmonger requesting a service certificate”.

Prerequisites

  • The web server is enrolled as an IdM client.
  • You have root access to the IdM client on which you are running the procedure.
  • The service for which you are requesting a certificate does not have to pre-exist in IdM.

Procedure

  1. On the my_company.idm.example.com IdM client on which the HTTP service is running, request a certificate for the service corresponding to the HTTP/my_company.idm.example.com@IDM.EXAMPLE.COM principal, and specify that

    • The certificate is to be stored in the local /etc/pki/tls/certs/httpd.pem file
    • The private key is to be stored in the local /etc/pki/tls/private/httpd.key file
    • That an extensionRequest for a SubjectAltName be added to the signing request with the DNS name of my_company.idm.example.com:

      # ipa-getcert request -K HTTP/my_company.idm.example.com -k /etc/pki/tls/private/httpd.key -f /etc/pki/tls/certs/httpd.pem -D my_company.idm.example.com -C "systemctl restart httpd"
      New signing request "20190604065735" added.

      In the command above:

      • The ipa-getcert request command specifies that the certificate is to be obtained from the IdM CA. The ipa-getcert request command is a shortcut for getcert request -c IPA.
      • The -C option instructs certmonger to restart the httpd service after obtaining the certificate.
      • The -D option specifies the SubjectAltName DNS value to be added to the request.
      • To specify that the certificate be issued with a particular profile, use the -T option.
      • To request a certificate using the named issuer from the specified CA, use the -X ISSUER option.
      Note

      RHEL 8 uses a different SSL module in Apache than the one used in RHEL 7. The SSL module relies on OpenSSL rather than NSS. For this reason, in RHEL 8 you cannot use an NSS database to store the HTTPS certificate and the private key.

  2. Optionally, to check the status of your request:

    # ipa-getcert list -f /etc/pki/tls/certs/httpd.pem
    Number of certificates and requests being tracked: 3.
    Request ID '20190604065735':
        status: MONITORING
        stuck: no
        key pair storage: type=FILE,location='/etc/pki/tls/private/httpd.key'
        certificate: type=FILE,location='/etc/pki/tls/certs/httpd.crt'
        CA: IPA
    [...]

    The output shows that the request is in the MONITORING status, which means that a certificate has been obtained. The locations of the key pair and the certificate are those requested.

39.3. Communication flow for certmonger requesting a service certificate

The diagrams in this section show the stages of what happens when certmonger requests a service certificate from Identity Management (IdM) certificate authority (CA) server. The sequence consists of these diagrams:

Figure 39.1, “Unencrypted communication” shows the initial situation: without an HTTPS certificate, the communication between the web server and the browser is unencrypted.

Figure 39.1. Unencrypted communication

84 RHEL IdM 0420 1


Figure 39.2, “Certmonger requesting a service certificate” shows the system administrator using certmonger to manually request an HTTPS certificate for the Apache web server. Note that when requesting a web server certificate, certmonger does not communicate directly with the CA. It proxies through IdM.

Figure 39.2. Certmonger requesting a service certificate

84 RHEL IdM 0420 2


Figure 39.3, “IdM CA issuing the service certificate” shows an IdM CA issuing an HTTPS certificate for the web server.

Figure 39.3. IdM CA issuing the service certificate

84 RHEL IdM 0420 3


Figure 39.4, “Certmonger applying the service certificate” shows certmonger placing the HTTPS certificate in appropriate locations on the IdM client and, if instructed to do so, restarting the httpd service. The Apache server subsequently uses the HTTPS certificate to encrypt the traffic between itself and the browser.

Figure 39.4. Certmonger applying the service certificate

84 RHEL IdM 0420 4


Figure 39.5, “Certmonger requesting a new certificate when the old one is nearing expiration” shows certmonger automatically requesting a renewal of the service certificate from the IdM CA before the expiration of the certificate. The IdM CA issues a new certificate.

Figure 39.5. Certmonger requesting a new certificate when the old one is nearing expiration

84 RHEL IdM 0420 5


39.4. Viewing the details of a certificate request tracked by certmonger

The certmonger service monitors certificate requests. When a request for a certificate is successfully signed, it results in a certificate. Certmonger manages certificate requests including the resulting certificates. This section describes how to view the details of a particular certificate request managed by certmonger.

Procedure

  • If you know how to specify the certificate request, list the details of only that particular certificate request. You can, for example, specify:

    • The request ID
    • The location of the certificate
    • The certificate nickname

      For example, to view the details of the certificate whose request ID is 20190408143846, using the -v option to view all the details of errors in case your request for a certificate was unsuccessful:

      # getcert list -i 20190408143846 -v
      Number of certificates and requests being tracked: 16.
      Request ID '20190408143846':
      	status: MONITORING
      	stuck: no
      	key pair storage: type=NSSDB,location='/etc/dirsrv/slapd-IDM-EXAMPLE-COM',nickname='Server-Cert',token='NSS Certificate DB',pinfile='/etc/dirsrv/slapd-IDM-EXAMPLE-COM/pwdfile.txt'
      	certificate: type=NSSDB,location='/etc/dirsrv/slapd-IDM-EXAMPLE-COM',nickname='Server-Cert',token='NSS Certificate DB'
      	CA: IPA
      	issuer: CN=Certificate Authority,O=IDM.EXAMPLE.COM
      	subject: CN=r8server.idm.example.com,O=IDM.EXAMPLE.COM
      	expires: 2021-04-08 16:38:47 CEST
      	dns: r8server.idm.example.com
      	principal name: ldap/server.idm.example.com@IDM.EXAMPLE.COM
      	key usage: digitalSignature,nonRepudiation,keyEncipherment,dataEncipherment
      	eku: id-kp-serverAuth,id-kp-clientAuth
      	pre-save command:
      	post-save command: /usr/libexec/ipa/certmonger/restart_dirsrv IDM-EXAMPLE-COM
      	track: yes
      	auto-renew: yes

    The output displays several pieces of information about the certificate, for example:

    • the certificate location; in the example above, it is the NSS database in the /etc/dirsrv/slapd-IDM-EXAMPLE-COM directory
    • the certificate nickname; in the example above, it is Server-Cert
    • the file storing the pin; in the example above, it is /etc/dirsrv/slapd-IDM-EXAMPLE-COM/pwdfile.txt
    • the Certificate Authority (CA) that will be used to renew the certificate; in the example above, it is the IPA CA
    • the expiration date; in the example above, it is 2021-04-08 16:38:47 CEST
    • the status of the certificate; in the example above, the MONITORING status means that the certificate is valid and it is being tracked
    • the post-save command; in the example above, it is the restart of the LDAP service
  • If you do not know how to specify the certificate request, list the details of all the certificates that certmonger is monitoring or attempting to obtain:

    # getcert list

Additional information

  • To view the different options how to specify the certificate request displayed, see the getcert list man page.

39.5. Starting and stopping certificate tracking

This section describes how you can use the getcert stop-tracking and getcert start-tracking commands to monitor certificates. The two commands are provided by the certmonger service. Enabling certificate tracking is especially useful if you have imported a certificate issued by the Identity Management (IdM) certificate authority (CA) onto the machine from a different IdM client. Enabling certificate tracking can also be the final step of the following provisioning scenario:

  1. On the IdM server, you create a certificate for a system that does not exist yet.
  2. You create the new system.
  3. You enroll the new system as an IdM client.
  4. You import the certificate and the key from the IdM server on to the IdM client.
  5. You start tracking the certificate using certmonger to ensure that it gets renewed when it is due to expire.

Procedure

  • To disable the monitoring of a certificate with the Request ID of 20190408143846:

    # getcert stop-tracking -i 20190408143846

    For more options, see the getcert stop-tracking man page.

  • To enable the monitoring of a certificate stored in the /tmp/some_cert.crt file, whose private key is stored in the /tmp/some_key.key file:

    # getcert start-tracking -c IPA -f /tmp/some_cert.crt -k /tmp/some_key.key

    Certmonger cannot automatically identify the CA type that issued the certificate. For this reason, add the -c option with the IPA value to the getcert start-tracking command if the certificate was issued by the IdM CA. Omitting to add the -c option results in certmonger entering the NEED_CA state.

    For more options, see the getcert start-tracking man page.

Note

The two commands do not manipulate the certificate. For example, getcert stop-tracking does not delete the certificate or remove it from the NSS database or from the filesystem but simply removes the certificate from the list of monitored certificates. Similarly, getcert start-tracking only adds a certificate to the list of monitored certificates.

39.6. Renewing a certificate manually

When a certificate is near its expiration date, the certmonger daemon automatically issues a renewal command using the certificate authority (CA) helper, obtains a renewed certificate and replaces the previous certificate with the new one.

It is also possible to manually renew a certificate in advance by using the getcert resubmit command. This way, you can update the information the certificate contains, e.g. by adding a Subject Alternative Name (SAN).

This section describes how to renew a certificate manually.

Procedure

  • To renew a certificate with the Request ID of 20190408143846:

    #