Red Hat Training

A Red Hat training course is available for RHEL 8

Configuring and managing Identity Management

Red Hat Enterprise Linux 8

Logging in to IdM and managing services, users, hosts, groups, access control rules, and certificates.

Red Hat Customer Content Services

Abstract

The main feature of Red Hat Identity Management (IdM) is the management of users, groups, hosts, access control rules, and certificates. However, before you can perform administration tasks in IdM, you must log in to the service. You can use Kerberos and one time passwords as authentication methods in IdM when you log in by using the command line or the IdM Web UI.
You can manage certificates in IdM by using the integrated or an external Certificate Authority (CA). You can request, renew, and replace certificates using many tools, for example, Ansible Playbooks. To replace the web server and LDAP server certificates of IdM servers, you must perform manual actions.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

In Identity Management, planned terminology replacements include:

  • block list replaces blacklist
  • allow list replaces whitelist
  • secondary replaces slave
  • The word master is being replaced with more precise language, depending on the context:

    • IdM server replaces IdM master
    • CA renewal server replaces CA renewal master
    • CRL publisher server replaces CRL master
    • multi-supplier replaces multi-master

Providing feedback on Red Hat documentation

We appreciate your feedback on our documentation. Let us know how we can improve it.

Submitting feedback through Jira (account required)

  1. Log in to the Jira website.
  2. Click Create in the top navigation bar.
  3. Enter a descriptive title in the Summary field.
  4. Enter your suggestion for improvement in the Description field. Include links to the relevant parts of the documentation.
  5. Click Create at the bottom of the dialogue.

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

Follow this procedure to use 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

Follow this procedure 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

Follow this procedure 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.

1.4. Additional resources

  • The krb5.conf(5) man page.
  • The kinit(1) man page.
  • The klist(1) man page.
  • The kdestroy(1) man page.

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. The IdM services

There are many different services that can be installed and run on the IdM servers and clients.

List of services hosted by IdM servers

Most of the following services are not strictly required to be installed on the IdM server. For example, you can install services such as a certificate authority (CA) or DNS server on an external server outside the IdM domain.

Kerberos
the krb5kdc and kadmin services

IdM uses the Kerberos protocol to support single sign-on. With Kerberos, users only need to present the correct username and password once and can access IdM services without the system prompting for credentials again.

Kerberos is divided into two parts:

  • The krb5kdc service is the Kerberos Authentication service and Key Distribution Center (KDC) daemon.
  • The kadmin service is the Kerberos database administration program.

For information about how to authenticate using Kerberos in IdM, see Logging in to Identity Management from the command line and Logging in to IdM in the Web UI: Using a Kerberos ticket.

LDAP directory server
the dirsrv service

The IdM LDAP directory server instance stores all IdM information, such as information related to Kerberos, user accounts, host entries, services, policies, DNS, and others. The LDAP directory server instance is based on the same technology as Red Hat Directory Server. However, it is tuned to IdM-specific tasks.

Certificate Authority
the pki-tomcatd service

The integrated certificate authority (CA) is based on the same technology as Red Hat Certificate System. pki is the command-line interface for accessing Certificate System services.

You can also install the server without the integrated CA if you create and provide all required certificates independently.

For more information, see Planning your CA services.

Domain Name System (DNS)
the named service

IdM uses DNS for dynamic service discovery. The IdM client installation utility can use information from DNS to automatically configure the client machine. After the client is enrolled in the IdM domain, it uses DNS to locate IdM servers and services within the domain. The BIND (Berkeley Internet Name Domain) implementation of the DNS (Domain Name System) protocols in Red Hat Enterprise Linux includes the named DNS server. named-pkcs11 is a version of the BIND DNS server built with native support for the PKCS#11 cryptographic standard.

For information, see Planning your DNS services and host names.

Apache HTTP Server
the httpd service

The Apache HTTP web server provides the IdM Web UI, and also manages communication between the Certificate Authority and other IdM services.

Samba / Winbind
smb and winbind services

Samba implements the Server Message Block (SMB) protocol, also known as the Common Internet File System (CIFS) protocol, in Red Hat Enterprise Linux. Via the smb service, the SMB protocol enables you to access resources on a server, such as file shares and shared printers. If you have configured a Trust with an Active Directory (AD) environment, the`Winbind` service manages communication between IdM servers and AD servers.

One-time password (OTP) authentication
the ipa-otpd services

One-time passwords (OTP) are passwords that are generated by an authentication token for only one session, as part of two-factor authentication. OTP authentication is implemented in Red Hat Enterprise Linux via the ipa-otpd service.

For more information, see Logging in to the Identity Management Web UI using one time passwords.

OpenDNSSEC
the ipa-dnskeysyncd service

OpenDNSSEC is a DNS manager that automates the process of keeping track of DNS security extensions (DNSSEC) keys and the signing of zones. The ipa-dnskeysyncd service manages synchronization between the IdM Directory Server and OpenDNSSEC.

The Identity Management Server: Unifying Services

List of services hosted by IdM clients

  • System Security Services Daemon: the sssd service

The System Security Services Daemon (SSSD) is the client-side application that manages user authentication and caching credentials. Caching enables the local system to continue normal authentication operations if the IdM server becomes unavailable or if the client goes offline.

For more information, see Understanding SSSD and its benefits.

  • Certmonger: the certmonger service

The certmonger service monitors and renews the certificates on the client. It can request new certificates for the services on the system.

For more information, see Obtaining an IdM certificate for a service using certmonger.

Interactions Between IdM Services

2.2. Viewing the status of IdM services

To view the status of the IdM services that are configured on your IdM server, run the ipactl status command:

[root@server ~]# ipactl status
Directory Service: RUNNING
krb5kdc Service: RUNNING
kadmin Service: RUNNING
named Service: RUNNING
httpd 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

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.3. Starting and stopping the entire Identity Management server

Use the ipa systemd service to stop, start, or restart the entire IdM server along with all the installed services. Using the systemctl utility to control the ipa systemd service ensures all services are stopped, started, or restarted in the appropriate order. The ipa systemd service also upgrades the RHEL IdM configuration before starting the IdM services, and it uses the proper SELinux contexts when administrating with IdM services. You do not need to have a valid Kerberos ticket to run the systemctl ipa commands.

ipa systemd service commands

To start the entire IdM server:

# systemctl start ipa

To stop the entire IdM server:

# systemctl stop ipa

To restart the entire IdM server:

# systemctl restart ipa

To show the status of all the services that make up IdM, use the ipactl utility:

# ipactl status
Important
  • Do not directly use the ipactl utility to start, stop, or restart IdM services. Use the systemctl ipa commands instead, which call the ipactl utility in a predictable environment.
  • You cannot use the IdM web UI to perform the ipactl commands.

2.4. Starting and stopping an individual Identity Management service

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 systemctl restart ipa. Because of dependencies between the services installed with the IdM server, the order in which they are started and stopped is critical. The ipa systemd service 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.5. 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 upper-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

Learn more about 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 for managing 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.

The IPA command-line interface (CLI) generates available help topics from loaded IdM plugin modules. To use the IPA help utility, you must:

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

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

You can use the following options for different ipa help use cases:

$ 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 specify a TOPIC, a COMMAND, or topics, or commands, with the basic ipa help command:

    • topics — You can run the command ipa help topics to display a list of topics that are covered by the IPA help, such as user, cert, server and many others.
    • TOPIC — The TOPIC with capital letters is a variable. Therefore, you can specify a particular topic, for example, ipa help user.
    • commands — You can enter the command ipa help commands to display 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 is a variable. Therefore, you can specify a particular command, for example, ipa help user-add.

3.3. Using IPA help topics

The following procedure describes how to use the IPA help in the command-line interface.

Procedure

  1. Open a 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 output 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 describes how to create IPA help commands in the command-line interface.

Procedure

  1. Open a 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

  • The ipa man 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

The 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 also includes an object: ipa user-mod USER_NAME [options].

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

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

Prerequisites

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

Procedure

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

    $ ipa user-add

    The command runs a script that prompts you to provide 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 to accept the suggested user name.

    The user name must be unique for the whole IdM database. If an error occurs because that user name already exists, repeat the process with the ipa user-add command and use a different, unique user name.

After you add the user name, the user account is added to the IdM database and the IPA command line interface (CLI) prints the following output:

----------------------
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
Note

By default, a user password is not set for the user account. To add a password while creating a user account, use the ipa user-add command with the following syntax:

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

The IPA CLI then prompts you to add or confirm a user name and password.

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

Additional resources

  • Run the ipa help user-add command for more information about parameters.

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.

Procedure

  1. Open a terminal and connect to the IdM server.
  2. Enter the ipa user-mod command, specify the user to modify, and any options, such as --password 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.

The IPA CLI prints the following output:

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

  • Run the ipa help user-mod command for more information about parameters.

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

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

For example, 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

You can use the ipa *-find commands to help you to search for particular types 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 procedure 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 temporarily 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 procedure describes adjusting global search size and time limits in the IdM Web UI.

Procedure

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

    Screenshot of the IdM Web UI highlighting the "IPA Server" tab from the top menu

  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.

    Screenshot of the IdM Web UI highlighting the Save button which is below the "Configuration" title at the top of the Configuration page

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

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

5.1. What is the IdM Web UI

The IdM (Identity Management) Web UI is a web application for IdM administration. 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 set of operations depending on permissions granted to the user. Active Directory users can now be administrators for Identity Management. For details, see Enabling AD users to administer IdM.

5.2. Web browsers supported for accessing the Web UI

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

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

You might experience problems accessing the IdM Web UI with a smart card if your browser attempts to use TLS v1.3:

[ssl:error] [pid 125757:tid 140436077168384] [client 999.999.999.999:99999] AH: verify client post handshake
[ssl:error] [pid 125757:tid 140436077168384] [client 999.999.999.999:99999] AH10158: cannot perform post-handshake authentication
[ssl:error] [pid 125757:tid 140436077168384] SSL Library Error: error:14268117:SSL routines:SSL_verify_client_post_handshake:extension not received

This is because the most recent versions of browsers do not have TLS Post-Handshake Authentication (PHA) enabled by default, or they do not support PHA. PHA is necessary to require a TLS client certificate for only a part of a web site, such as when accessing the IdM Web UI with smart card authentication.

To resolve this issue for Mozilla Firefox 68 and later, enable TLS PHA:

  1. Enter about:config in the address bar to access the Mozilla Firefox preferences menu.
  2. Enter security.tls.enable_post_handshake_auth in the search bar.
  3. Click the toggle button to set the parameter to true.

To resolve this issue for Chrome, which currently does not support PHA, disable TLS v1.3:

  1. Open the /etc/httpd/conf.d/ssl.conf configuration file.
  2. Add -TLSv1.3 to the SSLProtocol option:

    SSLProtocol all -TLSv1 -TLSv1.1 -TLSv1.3
  3. Restart the httpd service:

    service httpd restart

Note that IdM manages the ssl.conf file and might overwrite its contents during package updates. Verify custom settings after updating IdM packages.

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.

    Screenshot of the IdM Web UI accessed within a web browser displaying a "Username" field and a "Password" field. There is a blue "Log in" button below and to the right of those two fields.

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

    A Screenshot of the IdM Web UI with the "Username" field filled in with "admin" and the "Password" field displays several black circles obfuscating the password by replacing the characters tat were typed in.

  3. Click Log in.

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

A screenshot of the first screen visible after logging in to the IdM Web UI. There are 5 tabs listed along the top of the screen: Identity - Policy - Authentication - Network Services - IPA Server. The Identity tab has been selected and it is displaying the Users page which is the first menu item among 6 choices just below the tabs: Users - Hosts - Services - Groups - ID Views - Automember. The Active users page displays a table of user logins and their information: First name - Last name - Status - UID - Email address - Telephone number - Job Title.

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

Learn more about how to configure 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

Follow this procedure to use 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.

    A screenshot of the IdM Web UI log in page with empty entry fields for the Username and Password and a blue "Log in" button below those fields. Text to the right of the "Log in" button explains "to log in with Kerberos please make sure you have valid tickets (obtainable via kinit) and configured the browser correctly then click Log in." The URL for the word "configured" has been highlighted.

  3. Follow the steps on the configuration page.

    A screenshot of a web browser with instructions for "Browser Kerberos Setup."

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

Follow this procedure to log 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 Configuring the browser for Kerberos authentication.

    A screenshot of the IdM Web UI log in screen displaying an error above the empty Username and Password fields. The error message says "Authentication with Kerberos failed."

6.5. Configuring an external system for Kerberos authentication

Follow this procedure 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 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.
  • Configure a RADIUS server for OTP validation in IdM.
  • 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

Identity Management (IdM) administrators can enable two-factor authentication (2FA) for IdM users either globally or individually. The user enters the one-time password (OTP) after their regular password on the command line or in the dedicated field in the Web UI login dialog, with no space between these passwords.

Enabling 2FA is not the same as enforcing it. If you use logins based on LDAP-binds, IdM users can still authenticate by entering a password only. However, if you use krb5-based logins, the 2FA is enforced. In a future release, Red Hat plans to provide a configuration option for administrators to select one of the following:

  • Allow users to set their own tokens. In this case, LDAP-binds are still not going to enforce 2FA though krb5-based logins are.
  • Not allow users to set their own tokens. In this case, 2FA is going to be enforced in both LDAP-binds and krb5-based logins.

Complete this procedure to use the IdM Web UI to enable 2FA for the individual example.user IdM user.

Prerequisites

  • Administration privileges

Procedure

  1. Log in to the IdM Web UI with IdM admin privileges.
  2. Open the Identity → Users → Active users tab.

    A screenshot of the IdM Web UI displaying the "Active Users" page which is a sub-page of the Users submenu from the Identity tab.

  3. Select example.user 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 for the IdM user.

Now you or example.user must assign a new token ID to the example.user account.

7.4. Configuring a RADIUS server for OTP validation in IdM

To enable the migration of a large deployment from a proprietary one-time password (OTP) solution to the Identity Management (IdM)-native OTP solution, IdM offers a way to offload OTP validation to a third-party RADIUS server for a subset of users. The administrator creates a set of RADIUS proxies where each proxy can only reference a single RADIUS server. If more than one server needs to be addressed, it is recommended to create a virtual IP solution that points to multiple RADIUS servers.

Such a solution must be built outside of RHEL IdM with the help of the keepalived daemon, for example. The administrator then assigns one of these proxy sets to a user. As long as the user has a RADIUS proxy set assigned, IdM bypasses all other authentication mechanisms.

Note

IdM does not provide any token management or synchronization support for tokens in the third-party system.

Complete the procedure to configure a RADIUS server for OTP validation and to add a user to the proxy server:

Prerequisites

Procedure

  1. Add a RADIUS proxy:

    $ ipa radiusproxy-add proxy_name --secret secret

    The command prompts you for inserting the required information.

    The configuration of the RADIUS proxy requires the use of a common secret between the client and the server to wrap credentials. Specify this secret in the --secret parameter.

  2. Assign a user to the added proxy:

    ipa user-mod radiususer --radius=proxy_name
  3. If required, configure the user name to be sent to RADIUS:

    ipa user-mod radiususer --radius-username=radius_user

As a result, the RADIUS proxy server starts to process the user OTP authentication.

When the user is ready to be migrated to the IdM native OTP system, you can simply remove the RADIUS proxy assignment for the user.

7.4.1. Changing the timeout value of a KDC when running a RADIUS server in a slow network

In certain situations, such as running a RADIUS proxy in a slow network, the Identity Management (IdM) Kerberos Distribution Center (KDC) closes the connection before the RADIUS server responds because the connection timed out while waiting for the user to enter the token.

To change the timeout settings of the KDC:

  1. Change the value of the timeout parameter in the [otp] section in the /var/kerberos/krb5kdc/kdc.conf file. For example, to set the timeout to 120 seconds:

    [otp]
    DEFAULT = {
      timeout = 120
      ...
    }
  2. Restart the krb5kdc service:

    # systemctl restart krb5kdc

Additional resources

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

    Screenshot of the IdM Web UI highlighting the Add button near the upper-right of the OTP Tokens page which is a sub-page of the Authentication section

  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.

Screenshot of the FreeOTP application from a mobile telephone displaying two entries for OTP tokens. The first OTP token is for the example.user@IDM.EXAMPLE.COM domain and its entry displays a 6-digit OTP while its timer is running out.

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

Follow this procedure to login for the first time 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 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 IdM Web UI does not open, verify the DNS configuration of your Identity Management server.

After successful login, the IdM Web UI appears.

A screenshot of the first screen visible after logging in to the IdM Web UI. There are 5 tabs listed along the top of the screen: Identity - Policy - Authentication - Network Services - IPA Server. The Identity tab has been selected and it is displaying the Users page which is the first menu item among 6 choices just below the tabs: Users - Hosts - Services - Groups - ID Views - Automember. The Active users page displays a table of user logins and their information: First name - Last name - Status - UID - Email address - Telephone number - Job Title.

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

    A screenshot of the IdM Web UI log in page. The "Username" and "Password" fields are empty. A link to "Sync OTP Token" at the bottom right next to the "Log In" button is highlighted.

  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.

    A screenshot of the screen to change the OTP token. The "Username" field has been filled in with "admin". The password in the "Password" field has been obfuscated with solid circles. The "First OTP" and "Second OTP" fields also have their 6-character entries obfuscated. The last field is labeled "Token ID" and has 16 hexadecimal characters such as "18c5d06cfcbd4927". There are "Cancel" and "Sync OTP Token" buttons at the bottom right.

  6. Click Sync OTP Token.

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

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

    A screenshot of the IdM Web UI with a banner across the top that states "Your password has expired. Please enter a new password." The "Username" field displays "example.user" and cannot be edited. The following fields have been filled in but their contents have been replaced with dots to obfuscate the passwords: "Current Password" - "OTP" - "New Password" - "Verify Password."

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

Chapter 8. Troubleshooting authentication with SSSD in IdM

Authentication in an Identity Management (IdM) environment involves many components:

On the IdM client:

  • The SSSD service.
  • The Name Services Switch (NSS).
  • Pluggable Authentication Modules (PAM).

On the IdM server:

  • The SSSD service.
  • The IdM Directory Server.
  • The IdM Kerberos Key Distribution Center (KDC).

If you are authenticating as an Active Directory (AD) user:

  • The Directory Server on an AD Domain Controller.
  • The Kerberos server on an AD Domain Controller.

To authenticate users, you must be able to perform the following functions with the SSSD service:

  • Retrieve user information from the authentication server.
  • Prompt the user for their credentials, pass those credentials to the authentication server, and process the outcome.

To learn more about how information flows between the SSSD service and servers that store user information, so you can troubleshoot failing authentication attempts in your environment, see the following:

8.1. Data flow when retrieving IdM user information with SSSD

The following diagram is a simplification of the information flow between an IdM client and an IdM server during a request for IdM user information with the command getent passwd <idm_user_name>.

A diagram with numbered arrows representing the flow of information between an IdM client and an IdM server. The following numbered list describes each step in the process.

  1. The getent command triggers the getpwnam call from the libc library.
  2. The libc library references the /etc/nsswitch.conf configuration file to check which service is responsible for providing user information, and discovers the entry sss for the SSSD service.
  3. The libc library opens the nss_sss module.
  4. The nss_sss module checks the memory-mapped cache for the user information. If the data is present in the cache, the nss_sss module returns it.
  5. If the user information is not in the memory-mapped cache, the request is passed to the SSSD sssd_nss responder process.
  6. The SSSD service checks its cache. If the data is present in the cache and valid, the sssd_nss responder reads the data from the cache and returns it to the application.
  7. If the data is not present in the cache or it is expired, the sssd_nss responder queries the appropriate back-end process and waits for a reply. The SSSD service uses the IPA backend in an IdM environment, enabled by the setting id_provider=ipa in the sssd.conf configuration file.
  8. The sssd_be back-end process connects to the IdM server and requests the information from the IdM LDAP Directory Server.
  9. The SSSD back-end on the IdM server responds to the SSSD back-end process on the IdM client.
  10. The SSSD back-end on the client stores the resulting data in the SSSD cache and alerts the responder process that the cache has been updated.
  11. The sssd_nss front-end responder process retrieves the information from the SSSD cache.
  12. The sssd_nss responder sends the user information to the nss_sss responder, completing the request.
  13. The libc library returns the user information to the application that requested it.

8.2. Data flow when retrieving AD user information with SSSD

If you have established a cross-forest trust between your IdM environment and an Active Directory (AD) domain, the information flow when retrieving AD user information about an IdM client is very similar to the information flow when retrieving IdM user information, with the additional step of contacting the AD user database.

The following diagram is a simplification of the information flow when a user requests information about an AD user with the command getent passwd <ad_user_name@ad.example.com>. This diagram does not include the internal details discussed in the Data flow when retrieving IdM user information with SSSD section. It focuses on the communication between the SSSD service on an IdM client, the SSSD service on an IdM server, and the LDAP database on an AD Domain Controller.

A diagram with numbered arrows representing the flow of information between an IdM client, an IdM server, and an AD Domain Controller. The following numbered list describes each step in the process.

  1. The IdM client looks to its local SSSD cache for AD user information.
  2. If the IdM client does not have the user information, or the information is stale, the SSSD service on the client contacts the extdom_extop plugin on the IdM server to perform an LDAP extended operation and requests the information.
  3. The SSSD service on the IdM server looks for the AD user information in its local cache.
  4. If the IdM server does not have the user information in its SSSD cache, or its information is stale, it performs an LDAP search to request the user information from an AD Domain Controller.
  5. The SSSD service on the IdM server receives the AD user information from the AD domain controller and stores it in its cache.
  6. The extdom_extop plugin receives the information from the SSSD service on the IdM server, which completes the LDAP extended operation.
  7. The SSSD service on the IdM client receives the AD user information from the LDAP extended operation.
  8. The IdM client stores the AD user information in its SSSD cache and returns the information to the application that requested it.

8.3. Data flow when authenticating as a user with SSSD in IdM

Authenticating as a user on an IdM server or client involves the following components:

  • The service that initiates the authentication request, such as the sshd service.
  • The Pluggable Authentication Module (PAM) library and its modules.
  • The SSSD service, its responders, and back-ends.
  • A smart card reader, if smart card authentication is configured.
  • The authentication server:

    • IdM users are authenticated against an IdM Kerberos Key Distribution Center (KDC).
    • Active Directory (AD) users are authenticated against an AD Domain Controller (DC).

The following diagram is a simplification of the information flow when a user needs to authenticate during an attempt to log in locally to a host via the SSH service on the command line.

A diagram with numbered arrows representing the flow of information between an IdM client and an IdM server or AD Domain Controller during an authentication attempt. The following numbered list describes each step in the process.

  1. The authentication attempt with the ssh command triggers the libpam library.
  2. The libpam library references the PAM file in the /etc/pam.d/ directory that corresponds to the service requesting the authentication attempt. In this example involving authenticating via the SSH service on the local host, the libpam library checks the /etc/pam.d/system-auth configuration file and discovers the pam_sss.so entry for the SSSD PAM:

    auth    sufficient    pam_sss.so
  3. To determine which authentication methods are available, the libpam library opens the pam_sss module and sends an SSS_PAM_PREAUTH request to the sssd_pam PAM responder of the SSSD service.
  4. If smart card authentication is configured, the SSSD service spawns a temporary p11_child process to check for a smart card and retrieve certificates from it.
  5. If smart card authentication is configured for the user, the sssd_pam responder attempts to match the certificate from the smart card with the user. The sssd_pam responder also performs a search for the groups that the user belongs to, since group membership might affect access control.
  6. The sssd_pam responder sends an SSS_PAM_PREAUTH request to the sssd_be back-end responder to see which authentication methods the server supports, such as passwords or 2-factor authentication. In an IdM environment, where the SSSD service uses the IPA responder, the default authentication method is Kerberos. For this example, the user authenticates with a simple Kerberos password.
  7. The sssd_be responder spawns a temporary krb5_child process.
  8. The krb5_child process contacts the KDC on the IdM server and checks for available authentication methods.
  9. The KDC responds to the request:

    1. The krb5_child process evaluates the reply and sends the results back to the sssd_be backend process.
    2. The sssd_be backend process receives the result.
    3. The sssd_pam responder receives the result.
    4. The pam_sss module receives the result.
  10. If password authentication is configured for the user, the pam_sss module prompts the user for their password. If smart card authentication is configured, the pam_sss module prompts the user for their smart card PIN.
  11. The module sends an SSS_PAM_AUTHENTICATE request with the user name and password, which travels to:

    1. The sssd_pam responder.
    2. The sssd_be back-end process.
  12. The sssd_be process spawns a temporary krb5_child process to contact the KDC.
  13. The krb5_child process attempts to retrieve a Kerberos Ticket Granting Ticket (TGT) from the KDC with the user name and password the user provided.
  14. The krb5_child process receives the result of the authentication attempt.
  15. The krb5_child process:

    1. Stores the TGT in a credential cache.
    2. Returns the authentication result to the sssd_be back-end process.
  16. The authentication result travels from the sssd_be process to:

    1. The sssd_pam responder.
    2. The pam_sss module.
  17. The pam_sss module sets an environment variable with the location of the user’s TGT so other applications can reference it.

8.4. Narrowing the scope of authentication issues

To successfully authenticate a user, you must be able to retrieve user information with the SSSD service from the database that stores user information. The following procedure describes steps to test different components of the authentication process so you can narrow the scope of authentication issues when a user is unable to log in.

Procedure

  1. Verify that the SSSD service and its processes are running.

    [root@client ~]# pstree -a | grep sssd
      |-sssd -i --logger=files
      |   |-sssd_be --domain implicit_files --uid 0 --gid 0 --logger=files
      |   |-sssd_be --domain example.com --uid 0 --gid 0 --logger=files
      |   |-sssd_ifp --uid 0 --gid 0 --logger=files
      |   |-sssd_nss --uid 0 --gid 0 --logger=files
      |   |-sssd_pac --uid 0 --gid 0 --logger=files
      |   |-sssd_pam --uid 0 --gid 0 --logger=files
      |   |-sssd_ssh --uid 0 --gid 0 --logger=files
      |   `-sssd_sudo --uid 0 --gid 0 --logger=files
      |-sssd_kcm --uid 0 --gid 0 --logger=files
  2. Verify that the client can contact the user database server via the IP address.

    [user@client ~]$ ping <IP_address_of_the_database_server>

    If this step fails, check that your network and firewall settings allow direct communication between IdM clients and servers. See Using and configuring firewalld.

  3. Verify that the client can discover and contact the IdM LDAP server (for IdM users) or AD domain controller (for AD users) via the fully qualified host name.

    [user@client ~]$ dig -t SRV _ldap._tcp.example.com @<name_server>
    [user@client ~]$ ping <fully_qualified_host_name_of_the_server>

    If this step fails, check your Dynamic Name Service (DNS) settings, including the /etc/resolv.conf file. See Configuring the order of DNS servers.

    Note

    By default, the SSSD service attempts to automatically discover LDAP servers and AD DCs through DNS service (SRV) records. Alternatively, you can restrict the SSSD service to use specific servers by setting the following options in the sssd.conf configuration file:

    • ipa_server = <fully_qualified_host_name_of_the_server>
    • ad_server = <fully_qualified_host_name_of_the_server>
    • ldap_uri = <fully_qualified_host_name_of_the_server>

    If you use these options, verify you can contact the servers listed in them.

  4. Verify that the client can authenticate to the LDAP server and retrieve user information with ldapsearch commands.

    1. If your LDAP server is an IdM server, like server.example.com, retrieve a Kerberos ticket for the host and perform the database search authenticating with the host Kerberos principal:

      [user@client ~]$ kinit -k 'host/client.example.com@EXAMPLE.COM'
      [user@client ~]$ ldapsearch -LLL -Y GSSAPI -h server.example.com -b “dc=example,dc=com” uid=<user_name>
    2. If your LDAP server is an Active Directory (AD) Domain Controller (DC), like server.ad.example.com, retrieve a Kerberos ticket for the host and perform the database search authenticating with the host Kerberos principal:

      [user@client ~]$ kinit -k 'CLIENT$@AD.EXAMPLE.COM'
      [user@client ~]$ ldapsearch -LLL -Y GSSAPI -h server.ad.example.com -b “dc=example,dc=com” sAMAccountname=<user_name>
    3. If your LDAP server is a plain LDAP server, and you have set the ldap_default_bind_dn and ldap_default_authtok options in the sssd.conf file, authenticate as the same ldap_default_bind_dn account:

      [user@client ~]$ ldapsearch -xLLL -D "cn=ldap_default_bind_dn_value" -W -h ldapserver.example.com -b “dc=example,dc=com” uid=<user_name>

    If this step fails, verify that your database settings allow your host to search the LDAP server.

  5. Since the SSSD service uses Kerberos encryption, verify you can obtain a Kerberos ticket as the user that is unable to log in.

    1. If your LDAP server is an IdM server:

      [user@client ~]$ kinit <user_name>
    2. If LDAP server database is an AD server:

      [user@client ~]$ kinit <user_name@AD.EXAMPLE.COM>

    If this step fails, verify that your Kerberos server is operating properly, all servers have their times synchronized, and that the user account is not locked.

  6. Verify you can retrieve user information about the command line.

    [user@client ~]$ getent passwd <user_name>
    [user@client ~]$ id <user_name>

    If this step fails, verify that the SSSD service on the client can receive information from the user database:

    1. Review errors in the /var/log/messages log file.
    2. Enable detailed logging in the SSSD service, collect debugging logs, and review the logs for indications to the source of the issue.
    3. (Optional) Open a Red Hat Technical Support case and provide the troubleshooting information you have gathered.
  7. If you are allowed to run sudo on the host, use the sssctl utility to verify the user is allowed to log in.

    [user@client ~]$ sudo sssctl user-checks -a auth -s ssh <user_name>

    If this step fails, verify your authorization settings, such as your PAM configuration, IdM HBAC rules, and IdM RBAC rules:

    1. Ensure that the user’s UID is equal to or higher than UID_MIN, which is defined in the /etc/login.defs file.
    2. Review authorization errors in the /var/log/secure and /var/log/messages log files.
    3. Enable detailed logging in the SSSD service, collect debugging logs, and review the logs for indications to the source of the issue.
    4. (Optional) Open a Red Hat Technical Support case and provide the troubleshooting information you have gathered.

8.5. SSSD log files and logging levels

Each SSSD service logs into its own log file in the /var/log/sssd/ directory. For an IdM server in the example.com IdM domain, its log files might look like this:

[root@server ~]# ls -l /var/log/sssd/
total 620
-rw-------.  1 root root      0 Mar 29 09:21 krb5_child.log
-rw-------.  1 root root  14324 Mar 29 09:50 ldap_child.log
-rw-------.  1 root root 212870 Mar 29 09:50 sssd_example.com.log
-rw-------.  1 root root      0 Mar 29 09:21 sssd_ifp.log
-rw-------.  1 root root      0 Mar 29 09:21 sssd_implicit_files.log
-rw-------.  1 root root      0 Mar 29 09:21 sssd.log
-rw-------.  1 root root 219873 Mar 29 10:03 sssd_nss.log
-rw-------.  1 root root      0 Mar 29 09:21 sssd_pac.log
-rw-------.  1 root root  13105 Mar 29 09:21 sssd_pam.log
-rw-------.  1 root root   9390 Mar 29 09:21 sssd_ssh.log
-rw-------.  1 root root      0 Mar 29 09:21 sssd_sudo.log

8.5.1. SSSD log file purposes

krb5_child.log
Log file for the short-lived helper process involved in Kerberos authentication.
ldap_child.log
Log file for the short-lived helper process involved in getting a Kerberos ticket for the communication with the LDAP server.
sssd_<example.com>.log

For each domain section in the sssd.conf file, the SSSD service logs information about communication with the LDAP server to a separate log file. For example, in an environment with an IdM domain named example.com, the SSSD service logs its information in a file named sssd_example.com.log. If a host is directly integrated with an AD domain named ad.example.com, information is logged to a file named sssd_ad.example.com.log.

Note

If you have an IdM environment and a cross-forest trust with an AD domain, information about the AD domain is still logged to the log file for the IdM domain.

Similarly, if a host is directly integrated to an AD domain, information about any child domains is written in the log file for the primary domain.

selinux_child.log
Log file for the short-lived helper process that retrieves and sets SELinux information.
sssd.log
Log file for SSSD monitoring and communicating with its responder and backend processes.
sssd_ifp.log
Log file for the InfoPipe responder, which provides a public D-Bus interface accessible over the system bus.
sssd_nss.log
Log file for the Name Services Switch (NSS) responder that retrieves user and group information.
sssd_pac.log
Log file for the Microsoft Privilege Attribute Certificate (PAC) responder, which collects the PAC from AD Kerberos tickets and derives information about AD users from the PAC, which avoids requesting it directly from AD.
sssd_pam.log
Log file for the Pluggable Authentication Module (PAM) responder.
sssd_ssh.log
Log file for the SSH responder process.

8.5.2. SSSD logging levels

Setting a debug level also enables all debug levels below it. For example, setting the debug level at 6 also enables debug levels 0 through 5.

Table 8.1. SSSD logging levels

LevelDescription

0

Fatal failures. Errors that prevent the SSSD service from starting up or cause it to terminate. This is the default debug log level for RHEL 8.3 and earlier.

1

Critical failures. Errors that do not terminate the SSSD service, but at least one major feature is not working properly.

2

Serious failures. Errors announcing that a particular request or operation has failed. This is the default debug log level for RHEL 8.4 and later.

3

Minor failures. Errors that cause the operation failures captured at level 2.

4

Configuration settings.

5

Function data.

6

Trace messages for operation functions.

7

Trace messages for internal control functions.

8

Contents of function-internal variables.

9

Extremely low-level tracing information.

8.6. Enabling detailed logging for SSSD in the sssd.conf file

By default, the SSSD service in RHEL 8.4 and later only logs serious failures (debug level 2), but it does not log at the level of detail necessary to troubleshoot authentication issues.

To enable detailed logging persistently across SSSD service restarts, add the option debug_level=<integer> in each section of the /etc/sssd/sssd.conf configuration file, where the <integer> value is a number between 0 and 9. Debug levels up to 3 log larger failures, and levels 8 and higher provide a large number of detailed log messages. Level 6 is a good starting point for debugging authentication issues.

Prerequisites

  • You need the root password to edit the sssd.conf configuration file and restart the SSSD service.

Procedure

  1. Open the /etc/sssd/sssd.conf file in a text editor.
  2. Add the debug_level option to every section of the file, and set the debug level to the verbosity of your choice.

    [domain/example.com]
    debug_level = 6
    id_provider = ipa
    ...
    
    [sssd]
    debug_level = 6
    services = nss, pam, ifp, ssh, sudo
    domains = example.com
    
    [nss]
    debug_level = 6
    
    [pam]
    debug_level = 6
    
    [sudo]
    debug_level = 6
    
    [ssh]
    debug_level = 6
    
    [pac]
    debug_level = 6
    
    [ifp]
    debug_level = 6
  3. Save and close the sssd.conf file.
  4. Restart the SSSD service to load the new configuration settings.

    [root@server ~]# systemctl restart sssd

Additional resources

8.7. Enabling detailed logging for SSSD with the sssctl command

By default, the SSSD service in RHEL 8.4 and later only logs serious failures (debug level 2), but it does not log at the level of detail necessary to troubleshoot authentication issues.

You can change the debug level of the SSSD service on the command line with the sssctl debug-level <integer> command, where the <integer> value is a number between 0 and 9. Debug levels up to 3 log larger failures, and levels 8 and higher provide a large number of detailed log messages. Level 6 is a good starting point for debugging authentication issues.

Prerequisites

  • You need the root password to run the sssctl command.

Procedure

  • Use the sssctl debug-level command to set the debug level of your choiceto your desired verbosity.

    [root@server ~]# sssctl debug-level 6

Additional resources

8.8. Gathering debugging logs from the SSSD service to troubleshoot authentication issues with an IdM server

If you experience issues when attempting to authenticate as an IdM user to an IdM server, enable detailed debug logging in the SSSD service on the server and gather logs of an attempt to retrieve information about the user.

Prerequisites

  • You need the root password to run the sssctl command and restart the SSSD service.

Procedure

  1. Enable detailed SSSD debug logging on the IdM server.

    [root@server ~]# sssctl debug-level 6
  2. Invalidate objects in the SSSD cache for the user that is experiencing authentication issues, so you do not bypass the LDAP server and retrieve information SSSD has already cached.

    [root@server ~]# sssctl cache-expire -u idmuser
  3. Minimize the troubleshooting dataset by removing older SSSD logs.

    [root@server ~]# sssctl logs-remove
  4. Attempt to switch to the user experiencing authentication problems, while gathering timestamps before and after the attempt. These timestamps further narrow the scope of the dataset.

    [root@server sssd]# date; su idmuser; date
    Mon Mar 29 15:33:48 EDT 2021
    su: user idmuser does not exist
    Mon Mar 29 15:33:49 EDT 2021
  5. (Optional) Lower the debug level if you do not wish to continue gathering detailed SSSD logs.

    [root@server ~]# sssctl debug-level 2
  6. Review SSSD logs for information about the failed request. For example, reviewing the /var/log/sssd/sssd_example.com.log file shows that the SSSD service did not find the user in the cn=accounts,dc=example,dc=com LDAP subtree. This might indicate that the user does not exist, or exists in another location.

    (Mon Mar 29 15:33:48 2021) [sssd[be[example.com]]] [dp_get_account_info_send] (0x0200): Got request for [0x1][BE_REQ_USER][name=idmuser@example.com]
    ...
    (Mon Mar 29 15:33:48 2021) [sssd[be[example.com]]] [sdap_get_generic_ext_step] (0x0400): calling ldap_search_ext with [(&(uid=idmuser)(objectclass=posixAccount)(uid=)(&(uidNumber=)(!(uidNumber=0))))][cn=accounts,dc=example,dc=com].
    (Mon Mar 29 15:33:48 2021) [sssd[be[example.com]]] [sdap_get_generic_op_finished] (0x0400): Search result: Success(0), no errmsg set
    (Mon Mar 29 15:33:48 2021) [sssd[be[example.com]]] [sdap_search_user_process] (0x0400): Search for users, returned 0 results.
    (Mon Mar 29 15:33:48 2021) [sssd[be[example.com]]] [sysdb_search_by_name] (0x0400): No such entry
    (Mon Mar 29 15:33:48 2021) [sssd[be[example.com]]] [sysdb_delete_user] (0x0400): Error: 2 (No such file or directory)
    (Mon Mar 29 15:33:48 2021) [sssd[be[example.com]]] [sysdb_search_by_name] (0x0400): No such entry
    (Mon Mar 29 15:33:49 2021) [sssd[be[example.com]]] [ipa_id_get_account_info_orig_done] (0x0080): Object not found, ending request
  7. If you are unable to determine the cause of the authentication issue:

    1. Collect the SSSD logs you recently generated.

      [root@server ~]# sssctl logs-fetch sssd-logs-Mar29.tar
    2. Open a Red Hat Technical Support case and provide:

      1. The SSSD logs: sssd-logs-Mar29.tar
      2. The console output, including the time stamps and user name, of the request that corresponds to the logs:

        [root@server sssd]# date; id idmuser; date
        Mon Mar 29 15:33:48 EDT 2021
        id: ‘idmuser’: no such user
        Mon Mar 29 15:33:49 EDT 2021

8.9. Gathering debugging logs from the SSSD service to troubleshoot authentication issues with an IdM client

If you experience issues when attempting to authenticate as an IdM user to an IdM client, verify that you can retrieve user information about the IdM server. If you cannot retrieve the user information about an IdM server, you will not be able to retrieve it on an IdM client (which retrieves information from the IdM server).

After you have confirmed that authentication issues do not originate from the IdM server, gather SSSD debugging logs from both the IdM server and IdM client.

Prerequisites

  • The user only has authentication issues on IdM clients, not IdM servers.
  • You need the root password to run the sssctl command and restart the SSSD service.

Procedure

  1. On the client: Open the /etc/sssd/sssd.conf file in a text editor.
  2. On the client: Add the ipa_server option to the [domain] section of the file and set it to an IdM server. This avoids the IdM client autodiscovering other IdM servers, thus limiting this test to just one client and one server.

    [domain/example.com]
    ipa_server = server.example.com
    ...
  3. On the client: Save and close the sssd.conf file.
  4. On the client: Restart the SSSD service to load the configuration changes.

    [root@client ~]# systemctl restart sssd
  5. On the server and client: Enable detailed SSSD debug logging.

    [root@server ~]# sssctl debug-level 6
    [root@client ~]# sssctl debug-level 6
  6. On the server and client: Invalidate objects in the SSSD cache for the user experiencing authentication issues, so you do not bypass the LDAP database and retrieve information SSSD has already cached.

    [root@server ~]# sssctl cache-expire -u idmuser
    [root@client ~]# sssctl cache-expire -u idmuser
  7. On the server and client: Minimize the troubleshooting dataset by removing older SSSD logs.

    [root@server ~]# sssctl logs-remove
    [root@server ~]# sssctl logs-remove
  8. On the client: Attempt to switch to the user experiencing authentication problems while gathering timestamps before and after the attempt. These timestamps further narrow the scope of the dataset.

    [root@client sssd]# date; su idmuser; date
    Mon Mar 29 16:20:13 EDT 2021
    su: user idmuser does not exist
    Mon Mar 29 16:20:14 EDT 2021
  9. (Optional) On the server and client: Lower the debug level if you do not wish to continue gathering detailed SSSD logs.

    [root@server ~]# sssctl debug-level 0
    [root@client ~]# sssctl debug-level 0
  10. On the server and client: Review SSSD logs for information about the failed request.

    1. Review the request from the client in the client logs.
    2. Review the request from the client in the server logs.
    3. Review the result of the request in the server logs.
    4. Review the outcome of the client receiving the results of the request from the server.
  11. If you are unable to determine the cause of the authentication issue:

    1. Collect the SSSD logs you recently generated on the IdM server and IdM client. Label them according to their hostname or role.

      [root@server ~]# sssctl logs-fetch sssd-logs-server-Mar29.tar
      [root@client ~]# sssctl logs-fetch sssd-logs-client-Mar29.tar
    2. Open a Red Hat Technical Support case and provide:

      1. The SSSD debug logs:

        1. sssd-logs-server-Mar29.tar from the server
        2. sssd-logs-client-Mar29.tar from the client
      2. The console output, including the time stamps and user name, of the request that corresponds to the logs:

        [root@client sssd]# date; su idmuser; date
        Mon Mar 29 16:20:13 EDT 2021
        su: user idmuser does not exist
        Mon Mar 29 16:20:14 EDT 2021

8.10. Tracking client requests in the SSSD backend

SSSD processes requests asynchronously and as messages from different requests are added to the same log file, you can use the unique request identifier and client ID to track client requests in the back-end logs. The unique request identifier is added to the debug logs in the form of RID#<integer> and the client ID in the form [CID #<integer]. This allows you to isolate logs pertaining to an individual request, and you can track requests from start to finish across log files from multiple SSSD components.

Prerequisites

  • You have enabled debug logging and a request has been submitted from an IdM client.
  • You must have root privileges to display the contents of the SSSD log files.

Procedure

  1. To review your SSSD log file, open the log file using the less utility. For example, to view the /var/log/sssd/sssd_example.com.log:

    [root@server ~]# less /var/log/sssd/sssd_example.com.log
  2. Review the SSSD logs for information about the client request.

    (2021-07-26 18:26:37): [be[testidm.com]] [dp_req_destructor] (0x0400): [RID#3] Number of active DP request: 0
    (2021-07-26 18:26:37): [be[testidm.com]] [dp_req_reply_std] (0x1000): [RID#3] DP Request AccountDomain #3: Returning [Internal Error]: 3,1432158301,GetAccountDomain() not supported
    (2021-07-26 18:26:37): [be[testidm.com]] [dp_attach_req] (0x0400): [RID#4] DP Request Account #4: REQ_TRACE: New request. [sssd.nss CID #1] Flags [0x0001].
    (2021-07-26 18:26:37): [be[testidm.com]] [dp_attach_req] (0x0400): [RID#4] Number of active DP request: 1

    This sample output from an SSSD log file shows the unique identifiers RID#3 and RID#4 for two different requests.

However, a single client request to the SSSD client interface often triggers multiple requests in the backend and as a result it is not a 1-to-1 correlation between client request and requests in the backend. Though the multiple requests in the backend have different RID numbers, each initial backend request includes the unique client ID so an administrator can track the multiple RID numbers to the single client request.

The following example shows one client request [sssd.nss CID #1] and the multiple requests generated in the backend, [RID#5] to [RID#13]:

(2021-10-29 13:24:16): [be[ad.vm]] [dp_attach_req] (0x0400): [RID#5] DP Request [Account #5]: REQ_TRACE: New request. [sssd.nss CID #1] Flags [0x0001].
(2021-10-29 13:24:16): [be[ad.vm]] [dp_attach_req] (0x0400): [RID#6] DP Request [AccountDomain #6]: REQ_TRACE: New request. [sssd.nss CID #1] Flags [0x0001].
(2021-10-29 13:24:16): [be[ad.vm]] [dp_attach_req] (0x0400): [RID#7] DP Request [Account #7]: REQ_TRACE: New request. [sssd.nss CID #1] Flags [0x0001].
(2021-10-29 13:24:17): [be[ad.vm]] [dp_attach_req] (0x0400): [RID#8] DP Request [Initgroups #8]: REQ_TRACE: New request. [sssd.nss CID #1] Flags [0x0001].
(2021-10-29 13:24:17): [be[ad.vm]] [dp_attach_req] (0x0400): [RID#9] DP Request [Account #9]: REQ_TRACE: New request. [sssd.nss CID #1] Flags [0x0001].
(2021-10-29 13:24:17): [be[ad.vm]] [dp_attach_req] (0x0400): [RID#10] DP Request [Account #10]: REQ_TRACE: New request. [sssd.nss CID #1] Flags [0x0001].
(2021-10-29 13:24:17): [be[ad.vm]] [dp_attach_req] (0x0400): [RID#11] DP Request [Account #11]: REQ_TRACE: New request. [sssd.nss CID #1] Flags [0x0001].
(2021-10-29 13:24:17): [be[ad.vm]] [dp_attach_req] (0x0400): [RID#12] DP Request [Account #12]: REQ_TRACE: New request. [sssd.nss CID #1] Flags [0x0001].
(2021-10-29 13:24:17): [be[ad.vm]] [dp_attach_req] (0x0400): [RID#13] DP Request [Account #13]: REQ_TRACE: New request. [sssd.nss CID #1] Flags [0x0001].

8.11. Tracking client requests using the log analyzer tool

The System Security Services Daemon (SSSD) includes a log parsing tool that can be used to track requests from start to finish across log files from multiple SSSD components.

8.11.1. How the log analyzer tool works

Using the log parsing tool, you can track SSSD requests from start to finish across log files from multiple SSSD components. You run the analyzer tool using the sssctl analyze command.

The log analyzer tool helps you to troubleshoot NSS and PAM issues in SSSD and more easily review SSSD debug logs. You can extract and print SSSD logs related only to certain client requests across SSSD processes.

SSSD tracks user and group identity information (id, getent) separately from user authentication (su, ssh) information. The client ID (CID) in the NSS responder is independent of the CID in the PAM responder and you see overlapping numbers when analyzing NSS and PAM requests. Use the --pam option with the sssctl analyze command to review PAM requests.

Note

Requests returned from the SSSD memory cache are not logged and cannot be tracked by the log analyzer tool.

Additional resources

  • sudo sssctl analyze request --help
  • sudo sssctl analyze --help
  • sssd.conf man page
  • sssctl man page

8.11.2. Running the log analyzer tool

Follow this procedure to use the log analyzer tool to track client requests in SSSD.

Prerequisites

  • You must set debug_level to at least 7 in the [$responder] section, and [domain/$domain] section of the /etc/sssd/sssd.conf file to enable log parsing functionality.
  • Logs to analyze must be from a compatible version of SSSD built with libtevent chain ID support, that is SSSD in RHEL 8.5 and later.

Procedure

  1. Run the log analyzer tool in list mode to determine the client ID of the request you are tracking, adding the -v option to display verbose output:

    # sssctl analyze request list -v

    A verbose list of recent client requests made to SSSD is displayed.

    Note

    If analyzing PAM requests, run the sssctl analyze request list command with the --pam option.

  2. Run the log analyzer tool with the show [unique client ID] option to display logs pertaining to the specified client ID number:

    # sssctl analyze request show 20
  3. If required, you can run the log analyzer tool against log files, for example:

    # sssctl analyze request --logdir=/tmp/var/log/sssd

Additional resources

  • sssctl analyze request list --help
  • sssctl analyze request show --help
  • sssctl man page.

8.12. Additional resources

Chapter 9. Preparing your environment for managing IdM using Ansible playbooks

As a system administrator managing Identity Management (IdM), when working with Red Hat Ansible Engine, it is good practice to do the following:

  • Keep a subdirectory dedicated to Ansible playbooks in your home directory, for example ~/MyPlaybooks.
  • Copy and adapt sample Ansible playbooks from the /usr/share/doc/ansible-freeipa/* and /usr/share/doc/rhel-system-roles/* directories and subdirectories into your ~/MyPlaybooks directory.
  • Include your inventory file in your ~/MyPlaybooks directory.

Using this practice, you can find all your playbooks in one place.

Note

You can run your ansible-freeipa playbooks without invoking root privileges on the managed nodes. Exceptions include playbooks that use the ipaserver, ipareplica, ipaclient, ipasmartcard_server, ipasmartcard_client and ipabackup ansible-freeipa roles. These roles require privileged access to directories and the dnf software package manager.

The playbooks in the Red Hat Enterprise Linux IdM documentation assume the following security configuration:

  • The IdM admin is your remote Ansible user on the managed nodes.
  • You store the IdM admin password encrypted in an Ansible vault.
  • You have placed the password that protects the Ansible vault in a password file.
  • You block access to the vault password file to everyone except your local ansible user.
  • You regularly remove and re-create the vault password file.

Consider also alternative security configurations.

9.1. Preparing a control node and managed nodes for managing IdM using Ansible playbooks

Follow this procedure to create the ~/MyPlaybooks directory and configure it so that you can use it to store and run Ansible playbooks.

Prerequisites

  • You have installed an IdM server on your managed nodes, server.idm.example.com and replica.idm.example.com.
  • You have configured DNS and networking so you can log in to the managed nodes, server.idm.example.com and replica.idm.example.com, directly from the control node.
  • You know the IdM admin password.

Procedure

  1. Change into the ~/MyPlaybooks/ directory:

    $ cd ~/MyPlaybooks
  2. Create the ~/MyPlaybooks/ansible.cfg file with the following content:

    [defaults]
    inventory = /home/your_username/MyPlaybooks/inventory
    remote_user = admin
  3. Create the ~/MyPlaybooks/inventory file with the following content:

    [eu]
    server.idm.example.com
    
    [us]
    replica.idm.example.com
    
    [ipaserver:children]
    eu
    us

    This configuration defines two host groups, eu and us, for hosts in these locations. Additionally, this configuration defines the ipaserver host group, which contains all hosts from the eu and us groups.

  4. [Optional] Create an SSH public and private key. To simplify access in your test environment, do not set a password on the private key:

    $ ssh-keygen
  5. Copy the SSH public key to the IdM admin account on each managed node:

    $ ssh-copy-id admin@server.idm.example.com
    $ ssh-copy-id admin@replica.idm.example.com

    These commands require that you enter the IdM admin password.

  6. Create a password_file file that contains the vault password:

    redhat
  7. Change the permissions to modify the file:

    $ chmod 0600 password_file
  8. Create a secret.yml Ansible vault to store the IdM admin password:

    1. Configure password_file to store the vault password:

      $ ansible-vault create --vault-password-file=password_file secret.yml
    2. When prompted, enter the content of the secret.yml file:

      ipaadmin_password: Secret123
Note

To use the encrypted ipaadmin_password in a playbook, you must use the vars_file directive. For example, a simple playbook to delete an IdM user can look as follows:

---
- name: Playbook to handle users
  hosts: ipaserver

  vars_files:
  - /home/user_name/MyPlaybooks/secret.yml

  tasks:
  - name: Delete user robot
    ipauser:
      ipaadmin_password: "{{ ipaadmin_password }}"
      name: robot
      state: absent

When executing a playbook, instruct Ansible use the vault password to decrypt ipaadmin_password by adding the --vault-password-file=password_file option. For example:

ansible-playbook -i inventory --vault-password-file=password_file del-user.yml
Warning

For security reasons, remove the vault password file at the end of each session, and repeat steps 7-9 at the start of each new session.

9.2. Different methods to provide the credentials required for ansible-freeipa playbooks

There are advantages and disadvantages in the different methods for providing the credentials required for running playbooks that use ansible-freeipa roles and modules.

Storing passwords in plain text in a playbook

Benefits:

  • Not being prompted all the time you run the playbook.
  • Easy to implement.

Drawbacks:

  • Everyone with access to the file can read the password. Setting wrong permissions and sharing the file, for example in an internal or external repository, can compromise security.
  • High maintenance work: if the password is changed, it needs to be changed in all playbooks.

Entering passwords interactively when you execute a playbook

Benefits:

  • No-one can steal the password as it is not stored anywhere.
  • You can update the password easily.
  • Easy to implement.

Drawbacks:

  • If you are using Ansible playbooks in scripts, the requirement to enter the password interactively can be inconvenient.

Storing passwords in an Ansible vault and the vault password in a file:

Benefits:

  • The user password is stored encrypted.
  • You can update the user password easily, by creating a new Ansible vault.
  • You can update the password file that protects the ansible vault easily, by using the ansible-vault rekey --new-vault-password-file=NEW_VAULT_PASSWORD_FILE secret.yml command.
  • If you are using Ansible playbooks in scripts, it is convenient not to have to enter the password protecting the Ansible vault interactively.

Drawbacks:

  • It is vital that the file that contains the sensitive plain text password be protected through file permissions and other security measures.

Storing passwords in an Ansible vault and entering the vault password interactively

Benefits:

  • The user password is stored encrypted.
  • No-one can steal the vault password as it is not stored anywhere.
  • You can update the user password easily, by creating a new Ansible vault.
  • You can update the vault password easily too, by using the ansible-vault rekey file_name command.

Drawbacks:

  • If you are using Ansible playbooks in scripts, the need to enter the vault password interactively can be inconvenient.

Chapter 10. Configuring global IdM settings using Ansible playbooks

Using the Ansible config module, you can retrieve and set global configuration parameters for Identity Management (IdM).

10.1. Retrieving IdM configuration using an Ansible playbook

The following procedure describes how you can use an Ansible playbook to retrieve information about the current global IdM configuration.

Prerequisites

  • You know the IdM administrator password.
  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password.

Procedure

  1. Open the /usr/share/doc/ansible-freeipa/playbooks/config/retrieve-config.yml Ansible playbook file for editing:

    ---
    - name: Playbook to handle global IdM configuration
      hosts: ipaserver
      become: no
      gather_facts: no
    
      vars_files:
      - /home/user_name/MyPlaybooks/secret.yml
      tasks:
      - name: Query IPA global configuration
        ipaconfig:
          ipaadmin_password: "{{ ipaadmin_password }}"
        register: serverconfig
    
      - debug:
          msg: "{{ serverconfig }}"
  2. Adapt the file by changing the following:

    • The password of IdM administrator.
    • Other values, if necessary.
  3. Save the file.
  4. Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:

    $ ansible-playbook --vault-password-file=password_file -v -i path_to_inventory_directory/inventory.file /usr/share/doc/ansible-freeipa/playbooks/config/retrieve-config.yml
    [...]
    TASK [debug]
    ok: [server.idm.example.com] => {
        "msg": {
            "ansible_facts": {
                "discovered_interpreter_
            },
            "changed": false,
            "config": {
                "ca_renewal_master_server": "server.idm.example.com",
                "configstring": [
                    "AllowNThash",
                    "KDC:Disable Last Success"
                ],
                "defaultgroup": "ipausers",
                "defaultshell": "/bin/bash",
                "emaildomain": "idm.example.com",
                "enable_migration": false,
                "groupsearch": [
                    "cn",
                    "description"
                ],
                "homedirectory": "/home",
                "maxhostname": "64",
                "maxusername": "64",
                "pac_type": [
                    "MS-PAC",
                    "nfs:NONE"
                ],
                "pwdexpnotify": "4",
                "searchrecordslimit": "100",
                "searchtimelimit": "2",
                "selinuxusermapdefault": "unconfined_u:s0-s0:c0.c1023",
                "selinuxusermaporder": [
                    "guest_u:s0$xguest_u:s0$user_
                ],
                "usersearch": [
                    "uid",
                    "givenname",
                    "sn",
                    "telephonenumber",
                    "ou",
                    "title"
                ]
            },
            "failed": false
        }
    }

10.2. Configuring the IdM CA renewal server using an Ansible playbook

In an Identity Management (IdM) deployment that uses an embedded certificate authority (CA), the CA renewal server maintains and renews IdM system certificates. It ensures robust IdM deployments.

For more details on the role of the IdM CA renewal server, see Using IdM CA renewal server.

The following procedure describes how you can use an Ansible playbook to configure the IdM CA renewal server.

Prerequisites

  • You know the IdM administrator password.
  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password.

Procedure

  1. Optional: Identify the current IdM CA renewal server:

    $ ipa config-show | grep 'CA renewal'
      IPA CA renewal master: server.idm.example.com
  2. Create an inventory file, for example inventory.file, and define ipaserver in it:

    [ipaserver]
    server.idm.example.com
  3. Open the /usr/share/doc/ansible-freeipa/playbooks/config/set-ca-renewal-master-server.yml Ansible playbook file for editing:

    ---
    - name: Playbook to handle global DNS configuration
      hosts: ipaserver
      become: no
      gather_facts: no
      vars_files:
      - /home/user_name/MyPlaybooks/secret.yml
    
      tasks:
      - name: set ca_renewal_master_server
        ipaconfig:
          ipaadmin_password: "{{ ipaadmin_password }}"
          ca_renewal_master_server: carenewal.idm.example.com
  4. Adapt the file by changing:

    • The password of IdM administrator set by the ipaadmin_password variable.
    • The name of the CA renewal server set by the ca_renewal_master_server variable.
  5. Save the file.
  6. Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:

    $ ansible-playbook --vault-password-file=password_file -v -i path_to_inventory_directory/inventory.file /usr/share/doc/ansible-freeipa/playbooks/config/set-ca-renewal-master-server.yml

Verification steps

You can verify that the CA renewal server has been changed:

  1. Log into ipaserver as IdM administrator:

    $ ssh admin@server.idm.example.com
    Password:
    [admin@server /]$
  2. Request the identity of the IdM CA renewal server:

    $ ipa config-show | grep ‘CA renewal’
    IPA CA renewal master:  carenewal.idm.example.com

    The output shows the carenewal.idm.example.com server is the new CA renewal server.

10.3. Configuring the default shell for IdM users using an Ansible playbook

The shell is a program that accepts and interprets commands. Several shells are available in Red Hat Enterprise Linux (RHEL), such as bash, sh, ksh, zsh, fish, and others. Bash, or /bin/bash, is a popular shell on most Linux systems, and it is normally the default shell for user accounts on RHEL.

The following procedure describes how you can use an Ansible playbook to configure sh, an alternative shell, as the default shell for IdM users.

Prerequisites

  • You know the IdM administrator password.
  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password.

Procedure

  1. Optional: Use the retrieve-config.yml Ansible playbook to identify the current shell for IdM users. See Retrieving IdM configuration using an Ansible playbook for details.
  2. Create an inventory file, for example inventory.file, and define ipaserver in it:

    [ipaserver]
    server.idm.example.com
  3. Open the /usr/share/doc/ansible-freeipa/playbooks/config/ensure-config-options-are-set.yml Ansible playbook file for editing:

    ---
    - name: Playbook to ensure some config options are set
      hosts: ipaserver
      vars_files:
      - /home/user_name/MyPlaybooks/secret.yml
    
      tasks:
      # Set defaultlogin and maxusername
      - ipaconfig:
          ipaadmin_password: "{{ ipaadmin_password }}"
          defaultshell: /bin/bash
          maxusername: 64
  4. Adapt the file by changing the following:

    • The password of IdM administrator set by the ipaadmin_password variable.
    • The default shell of the IdM users set by the defaultshell variable into /bin/sh.
  5. Save the file.
  6. Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:

    $ ansible-playbook --vault-password-file=password_file -v -i path_to_inventory_directory/inventory.file /usr/share/doc/ansible-freeipa/playbooks/config/ensure-config-options-are-set.yml

Verification steps

You can verify that the default user shell has been changed by starting a new session in IdM:

  1. Log into ipaserver as IdM administrator:

    $ ssh admin@server.idm.example.com
    Password:
    [admin@server /]$
  2. Display the current shell:

    [admin@server /]$ echo "$SHELL"
    /bin/sh

    The logged-in user is using the sh shell.

10.4. Configuring a NetBIOS name for an IdM domain by using Ansible

The NetBIOS name is used for Microsoft Windows' (SMB) type of sharing and messaging. You can use NetBIOS names to map a drive or connect to a printer.

Follow this procedure to use an Ansible playbook to configure a NetBIOS name for your Identity Management (IdM) domain.

Prerequisites

  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.14 or later.
    • The ansible-freeipa package is installed.

Assumptions

  • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
  • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password and that you know the vault file password.

Procedure

  1. Navigate to your ~/MyPlaybooks/ directory:

    $ cd ~/MyPlaybooks/
  2. Create a netbios-domain-name-present.yml Ansible playbook file.
  3. Add the following content to the file:

    ---
    - name: Playbook to change IdM domain netbios name
      hosts: ipaserver
      become: no
      gather_facts: no
    
    
      vars_files:
      - /home/user_name/MyPlaybooks/secret.yml
    
      tasks:
        - name: Set IdM domain netbios name
          ipaconfig:
            ipaadmin_password: "{{ ipaadmin_password }}"
            netbios_name: IPADOM
  4. Save the file.
  5. Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:

    $ ansible-playbook --vault-password-file=password_file -v -i inventory netbios-domain-name-present.yml

    When prompted, provide the vault file password.

10.5. Ensuring that IdM users and groups have SIDs by using Ansible

The Identity Management (IdM) server can assign unique security identifiers (SIDs) to IdM users and groups internally, based on the data from the ID ranges of the local domain. The SIDs are stored in the user and group objects.

The goal of ensuring that IdM users and groups have SIDs is to allow the generation of the Privileged Attribute Certificate (PAC), which is the first step towards IdM-IdM trusts. If IdM users and groups have SIDs, IdM is able to issue Kerberos tickets with PAC data.

Follow this procedure to achieve the following goals:

  • Generate SIDs for already existing IdM users and user groups.
  • Enable the generation of SIDs for IdM new users and groups.

Prerequisites

  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.14 or later.
    • The ansible-freeipa package is installed.

Assumptions

  • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
  • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password and that you know the vault file password.

Procedure

  1. Navigate to your ~/MyPlaybooks/ directory:

    $ cd ~/MyPlaybooks/
  2. Create a sids-for-users-and-groups-present.yml Ansible playbook file.
  3. Add the following content to the file:

    ---
    - name: Playbook to ensure SIDs are enabled and users and groups have SIDs
      hosts: ipaserver
      become: no
      gather_facts: no
    
      vars_files:
      - /home/user_name/MyPlaybooks/secret.yml
    
      tasks:
        - name: Enable SID and generate users and groups SIDS
          ipaconfig:
            ipaadmin_password: "{{ ipaadmin_password }}"
            enable_sid: true
            add_sids: true

    The enable_sid variable enables SID generation for future IdM users and groups. The add_sids variable generates SIDs for existing IdM users and groups.

    Note

    When using add_sids: true, you must also set the enable_sid variable to true.

  4. Save the file.
  5. Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:

    $ ansible-playbook --vault-password-file=password_file -v -i inventory sids-for-users-and-groups-present.yml

    When prompted, provide the vault file password.

10.6. Additional resources

  • See README-config.md in the /usr/share/doc/ansible-freeipa/ directory.
  • See sample playbooks in the /usr/share/doc/ansible-freeipa/playbooks/config directory.

Chapter 11. Managing user accounts using the command line

There are several stages in the user life cycle in IdM (Identity Management), including the following:

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

11.1. User life cycle

Identity Management (IdM) 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.

A flow chart displaying 4 items: Active users - Stage users - Preserved users - Deleted users. Arrows communicate the relationships between each kind of user: Active users can be "preserved" as Preserved users. Preserved users can be "restored" as Active users. Preserved users can be "staged" as Stage users and Stage users can be "activated" into Active users. All users can be deleted to become "Deleted users".

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.

Warning

Do not add local users to IdM. The Name Service Switch (NSS) always resolves IdM users and groups before resolving local users and groups. This means that, for example, IdM group membership does not work for local users.

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

This command lists all user accounts with details.

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

This command lists all user accounts with details.

11.4. Preserving users using the command line

You can preserve a user account if you want to remove it, but keep the option to restore it later. To preserve a user account, use the --preserve option with 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"
    --------------------
    Note

    Despite the output saying the user account was deleted, it has been preserved.

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

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

Verification steps

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

    $ ipa user-find

    This command lists all user accounts with details.

Chapter 12. Managing user accounts using the IdM Web UI

Identity Management (IdM) provides several stages that can help you to manage various user life cycle 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 is dismissed, delete the account without a backup.

12.1. User life cycle

Identity Management (IdM) 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.

A flow chart displaying 4 items: Active users - Stage users - Preserved users - Deleted users. Arrows communicate the relationships between each kind of user: Active users can be "preserved" as Preserved users. Preserved users can be "restored" as Active users. Preserved users can be "staged" as Stage users and Stage users can be "activated" into Active users. All users can be deleted to become "Deleted users".

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.

Warning

Do not add local users to IdM. The Name Service Switch (NSS) always resolves IdM users and groups before resolving local users and groups. This means that, for example, IdM group membership does not work for local users.

12.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, enter your password and confirm it, ensuring they both match.
  8. Click on the Add button.

    Screenshot of the "Add stage user" pop-up window with the "New Password" the "Verify Password" fields filled in. The "Add" button is at the bottom left.

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

Screenshot of the IdM Web UI showing user entries in the Stage Users table. This is selected from the Identity tab - the Users sub-tab - and the Stage users category listed on the left.

Note

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

12.3. Activating stage users in the IdM Web UI

You must follow this procedure to activate a stage user account, before the user can log in to IdM and before the user can be added to an IdM group.

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.

    Screenshot of the IdM Web UI showing user entries in the "Stage Users" table. This is selected from the Identity tab - the Users sub-tab - and the Stage users category listed on the left.

  5. On the Confirmation dialog box, click OK.

If the activation is successful, 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.

Screenshot of the IdM Web UI showing the "staged.user" user entry in the "Active Users" table. Its status is "enabled."

Note

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

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

    Screenshot of the "Active Users" page with a table displaying attributes for several users such as User login - First name - Last name - Status - UID - Email address - Telephone Number - Job Title. The entry for the "euser" account has been highlighted and so have the "Enable" and "Disable" buttons at the top right.

  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.

Screenshot of the same "Active Users" page with the table displaying attributes for several users. The "euser" account is now greyed-out and shows "Disabled" in its "Status" column.

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

    Screenshot of the "Active Users" page with a table displaying attributes for several users such as User login - First name - Last name - Status - UID - Email address - Telephone Number - Job Title. The entry for the "euser" account has been highlighted and so have the "Enable" and "Disable" buttons at the top right.

  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.

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

    A screenshot of the "Active Users" page displaying a table of users. The checkbox for the entry for the "preserved.user" account has been checked and the "Delete" button at the top is highlighted.

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

    A screenshot of a pop-up window titled "Remove users." The contents say "Are you sure you want to delete selected entries?" and specifies "preserved.user" below. There is a label "Delete mode" with two radial options: "delete" and "preserve" (which is selected). There are "Delete" and "Cancel" buttons at the bottom right corner of the window.

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.

12.7. Restoring users in the IdM Web UI

IdM (Identity Management) enables you to restore preserved user accounts back to the active state. You can restore a preserved user to an active user or a stage user.

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.

    A screenshot of the "Preserved users" page displaying a table of users and their attributes. The checkbox next to one user entry is checked and the "Restore" button at the top right is highlighted.

  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.

12.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 13. Managing user accounts using Ansible playbooks

You can manage users in IdM using Ansible playbooks. After presenting the user life cycle, this chapter describes how to use Ansible playbooks for the following operations:

13.1. User life cycle

Identity Management (IdM) 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.

A flow chart displaying 4 items: Active users - Stage users - Preserved users - Deleted users. Arrows communicate the relationships between each kind of user: Active users can be "preserved" as Preserved users. Preserved users can be "restored" as Active users. Preserved users can be "staged" as Stage users and Stage users can be "activated" into Active users. All users can be deleted to become "Deleted users".

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.

Warning

Do not add local users to IdM. The Name Service Switch (NSS) always resolves IdM users and groups before resolving local users and groups. This means that, for example, IdM group membership does not work for local users.

13.2. 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 admin password.
  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password.

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
    
      vars_files:
      - /home/user_name/MyPlaybooks/secret.yml
      tasks:
      - name: Create user idm_user
        ipauser:
          ipaadmin_password: "{{ ipaadmin_password }}"
          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 --vault-password-file=password_file -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.

13.3. 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 admin password.
  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password.

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
    
      vars_files:
      - /home/user_name/MyPlaybooks/secret.yml
      tasks:
      - name: Create user idm_users
        ipauser:
          ipaadmin_password: "{{ ipaadmin_password }}"
          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 --vault-password-file=password_file -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.

13.4. 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 admin password.
  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password.

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
    
      vars_files:
      - /home/user_name/MyPlaybooks/secret.yml
      tasks:
      - name: Include users.json
        include_vars:
          file: users.json
    
      - name: Users present
        ipauser:
          ipaadmin_password: "{{ ipaadmin_password }}"
          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. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:

    $ ansible-playbook --vault-password-file=password_file -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.

13.5. 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 admin password.
  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password.

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
    
      vars_files:
      - /home/user_name/MyPlaybooks/secret.yml
      tasks:
      - name: Delete users idm_user_1, idm_user_2, idm_user_3
        ipauser:
          ipaadmin_password: "{{ ipaadmin_password }}"
          users:
          - name: idm_user_1
          - name: idm_user_2
          - name: idm_user_3
          state: absent
  3. Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:

    $ ansible-playbook --vault-password-file=password_file -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.

13.6. Additional resources

  • See the README-user.md Markdown file in the /usr/share/doc/ansible-freeipa/ directory.
  • See sample Ansible playbooks in the /usr/share/doc/ansible-freeipa/playbooks/user directory.

Chapter 14. 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

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

14.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 14.1. Direct and Indirect Group Membership

A chart with Group A (with 2 users) and Group B (with 3 users). Group B is nested inside Group A so Group A contains a total of 5 users.

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

14.3. Adding a user group using IdM CLI

Follow this procedure to add a user group using the 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.

14.4. Searching for user groups using IdM CLI

Follow this procedure to search for existing user groups using the 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 about different group types, see The different group types in IdM.

14.5. Deleting a user group using IdM CLI

Follow this procedure 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"
    --------------------------

14.6. Adding 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. Follow this procedure to add a member to a user group by using the IdM CLI.

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.

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

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

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

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

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

14.8. Adding users or groups as member managers to an IdM user group using the IdM CLI

Follow this procedure to add users or groups as member managers to an IdM user group using the IdM CLI. Member managers can add users or groups to IdM user groups but cannot change the attributes of a group.

Prerequisites

  • You must be logged in as the administrator. For details, see Using kinit to log in to IdM manually.
  • You must have the name of the user or group you are adding as member managers and the name of the group you want them to manage.

Procedure

  • Add a user as a member manager to an IdM user group by using the ipa group-add-member-manager command.

    For example, to add the user test as a member manager of group_a:

    $ ipa group-add-member-manager group_a --users=test
    Group name: group_a
    GID: 1133400009
    Membership managed by users: test
    -------------------------
    Number of members added 1
    -------------------------

    User test can now manage members of group_a.

  • Add a group as a member manager to an IdM user group by using the ipa group-add-member-manager command.

    For example, to add the group group_admins as a member manager of group_a:

    $ ipa group-add-member-manager group_a --groups=group_admins
    Group name: group_a
    GID: 1133400009
    Membership managed by groups: group_admins
    Membership managed by users: test
    -------------------------
    Number of members added 1
    -------------------------

    Group group_admins can now manage members of group_a.

Note

After you add a member manager to a user group, the update may take some time to spread to all clients in your Identity Management environment.

Verification steps

  • Using the ipa group-show command to verify the user and group were added as member managers.

    $ ipa group-show group_a
    Group name: group_a
    GID: 1133400009
    Membership managed by groups: group_admins
    Membership managed by users: test

Additional resources

  • See ipa group-add-member-manager --help for more details.

14.9. Viewing group members using IdM CLI

Follow this procedure 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.

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

Follow this procedure 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

14.11. Removing users or groups as member managers from an IdM user group using the IdM CLI

Follow this procedure to remove users or groups as member managers from an IdM user group using the IdM CLI. Member managers can remove users or groups from IdM user groups but cannot change the attributes of a group.

Prerequisites

  • You must be logged in as the administrator. For details, see Using kinit to log in to IdM manually.
  • You must have the name of the existing member manager user or group you are removing and the name of the group they are managing.

Procedure

  • Remove a user as a member manager of an IdM user group by using the ipa group-remove-member-manager command.

    For example, to remove the user test as a member manager of group_a:

    $ ipa group-remove-member-manager group_a --users=test
    Group name: group_a
    GID: 1133400009
    Membership managed by groups: group_admins
    ---------------------------
    Number of members removed 1
    ---------------------------

    User test can no longer manage members of group_a.

  • Remove a group as a member manager of an IdM user group by using the ipa group-remove-member-manager command.

    For example, to remove the group group_admins as a member manager of group_a:

    $ ipa group-remove-member-manager group_a --groups=group_admins
    Group name: group_a
    GID: 1133400009
    ---------------------------
    Number of members removed 1
    ---------------------------

    Group group_admins can no longer manage members of group_a.

Note

After you remove a member manager from a user group, the update may take some time to spread to all clients in your Identity Management environment.

Verification steps

  • Using the ipa group-show command to verify the user and group were removed as member managers.

    $ ipa group-show group_a
    Group name: group_a
    GID: 1133400009

Additional resources

  • See ipa group-remove-member-manager --help for more details.

14.12. Enabling group merging for local and remote groups in IdM

Groups are either centrally managed, provided by a domain such as Identity Management (IdM) or Active Directory (AD), or they are managed on a local system in the etc/group file. In most cases, users rely on a centrally managed store. However, in some cases software still relies on membership in known groups for managing access control.

If you want to manage groups from a domain controller and from the local etc/group file, you can enable group merging. You can configure your nsswitch.conf file to check both the local files and the remote service. If a group appears in both, the list of member users is combined and returned in a single response.

The steps below describe how to enable group merging for a user, idmuser.

Procedure

  1. Add [SUCCESS=merge] to the /etc/nsswitch.conf file:

    # Allow initgroups to default to the setting for group.
    initgroups: sss [SUCCESS=merge] files
  2. Add the idmuser to IdM:

    # ipa user-add idmuser
    First name: idm
    Last name: user
    ---------------------
    Added user "idmuser"
    ---------------------
    User login: idmuser
    First name: idm
    Last name: user
    Full name: idm user
    Display name: idm user
    Initials: tu
    Home directory: /home/idmuser
    GECOS: idm user
    Login shell: /bin/sh
    Principal name: idmuser@IPA.TEST
    Principal alias: idmuser@IPA.TEST
    Email address: idmuser@ipa.test
    UID: 19000024
    GID: 19000024
    Password: False
    Member of groups: ipausers
    Kerberos keys available: False
  3. Verify the GID of the local audio group.

    $ getent group audio
    ---------------------
    audio:x:63
  4. Add the group audio to IdM:

    $ ipa group-add audio --gid 63
    -------------------
    Added group "audio"
    -------------------
    Group name: audio
    GID: 63
    Note

    The GID you define when adding the audio group to IdM must be the same as the GID of the local audio group.

  5. Add idmuser user to the IdM audio group:

    $ ipa group-add-member audio --users=idmuser
    Group name: audio
    GID: 63
    Member users: idmuser
    -------------------------
    Number of members added 1
    -------------------------

Verification

  1. Log in as the idmuser.
  2. Verify the idmuser has the local group in their session:

    $ id idmuser
    uid=1867800003(idmuser) gid=1867800003(idmuser) groups=1867800003(idmuser),63(audio),10(wheel)

Chapter 15. 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

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

15.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 15.1. Direct and Indirect Group Membership

A chart with Group A (with 2 users) and Group B (with 3 users). Group B is nested inside Group A so Group A contains a total of 5 users.

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

15.3. Adding a user group using IdM Web UI

Follow this procedure 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.

    Screenshot of the "Add user group" pop-up window with the following fields: Group name (which is a required field) - Description - Group Type - GID. The "Add" button is at the bottom.
  4. Click Add to confirm.

15.4. Deleting a user group using IdM Web UI

Follow this procedure 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.

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

    A screenshot of the "User Group" page highlighting the three buttons for the three categories of group members you can add: "Users" - "User Groups" - "External users".
  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.

    A screenshot of the "Add users into user group group_a" pop-up window with a column to the left with "Available users" logins that can be checked. There is a right-arrow you can click to add users to the "Prospective" list on the right.
  7. Click Add to confirm.

15.6. Adding users or groups as member managers to an IdM user group using the Web UI

Follow this procedure to add users or groups as member managers to an IdM user group using the Web UI. Member managers can add users or groups to IdM user groups but cannot change the attributes of a group.

Prerequisites

  • You are logged in to the IdM Web UI.
  • You must have the name of the user or group you are adding as member managers and the name of the group you want them to manage.

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 manager you want to add: Users or User Groups.

    groups add member manager
  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 managers users
  7. Click Add to confirm.
Note

After you add a member manager to a user group, the update may take some time to spread to all clients in your Identity Management environment.

Verification steps

  • Verify the newly added user or user group has been added to the member manager list of users or user groups:

    groups member manager added

Additional resources

  • See ipa group-add-member-manager --help for more information.

15.7. Viewing group members using IdM Web UI

Follow this procedure 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.

    A screenshot showing radial buttons next to the "Direct Membership" and "Indirect Membership" options next to "Show Results."

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

Follow this procedure 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.

    A screenshot of the "User Group" page highlighting the three buttons for the three categories of group members you can add: "Users" - "User Groups" - "External users".
  4. Select the check box next to the member you want to remove.
  5. Click Delete.
  6. Click Delete to confirm.

15.9. Removing users or groups as member managers from an IdM user group using the Web UI

Follow this procedure to remove users or groups as member managers from an IdM user group using the Web UI. Member managers can remove users or groups from IdM user groups but cannot change the attributes of a group.

Prerequisites

  • You are logged in to the IdM Web UI.
  • You must have the name of the existing member manager user or group you are removing and the name of the group they are managing.

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 member manager you want to remove: Users or User Groups.

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

After you remove a member manager from a user group, the update may take some time to spread to all clients in your Identity Management environment.

Verification steps

  • Verify the user or user group has been removed from the member manager list of users or user groups:

    groups member manager removed

Additional resources

  • See ipa group-add-member-manager --help for more details.

Chapter 16. Managing user groups using Ansible playbooks

This section introduces user group management using Ansible playbooks.

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

The section includes the following topics:

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

16.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 16.1. Direct and Indirect Group Membership

A chart with Group A (with 2 users) and Group B (with 3 users). Group B is nested inside Group A so Group A contains a total of 5 users.

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

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

  • You know the IdM administrator password.
  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password.
  • The users you want to reference in your Ansible playbook exist in IdM. For details on ensuring the presence of users using Ansible, see Managing user accounts using Ansible playbooks.

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:

    ---
    - name: Playbook to handle groups
      hosts: ipaserver
    
      vars_files:
      - /home/user_name/MyPlaybooks/secret.yml
      tasks:
      - name: Create group ops with gid 1234
        ipagroup:
          ipaadmin_password: "{{ ipaadmin_password }}"
          name: ops
          gidnumber: 1234
    
      - name: Create group sysops
        ipagroup:
          ipaadmin_password: "{{ ipaadmin_password }}"
          name: sysops
          user:
          - idm_user
    
      - name: Create group appops
        ipagroup:
          ipaadmin_password: "{{ ipaadmin_password }}"
          name: appops
    
      - name: Add group members sysops and appops to group ops
        ipagroup:
          ipaadmin_password: "{{ ipaadmin_password }}"
          name: ops
          group:
          - sysops
          - appops
  3. Run the playbook:

    $ ansible-playbook --vault-password-file=password_file -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

  • See the /usr/share/doc/ansible-freeipa/README-group.md Markdown file.

16.4. Using Ansible to add multiple IdM groups in a single task

You can use the ansible-freeipa ipagroup module to add, modify, and delete multiple Identity Management (IdM) user groups with a single Ansible task. For that, use the groups option of the ipagroup module.

Using the groups option, you can also specify multiple group variables that only apply to a particular group. Define this group by the name variable, which is the only mandatory variable for the groups option.

Complete this procedure to ensure the presence of the sysops and the appops groups in IdM in a single task. Define the sysops group as a nonposix group and the appops group as an external group.

Prerequisites

  • On the control node:

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package.
    • You have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server in the ~/MyPlaybooks/ directory.
    • You are using RHEL 8.9 and later.
    • You have stored your ipaadmin_password in the secret.yml Ansible vault.

Procedure

  1. Create your Ansible playbook file add-nonposix-and-external-groups.yml with the following content:

    ---
    - name: Playbook to add nonposix and external groups
      hosts: ipaserver
      vars_files:
      - /home/user_name/MyPlaybooks/secret.yml
    
      tasks:
      - name: Add nonposix group sysops and external group appops
        ipagroup:
          ipaadmin_password: "{{ ipaadmin_password }}"
          groups:
          - name: sysops
            nonposix: true
          - name: appops
            external: true
  2. Run the playbook:

    $ ansible-playbook --vault-password-file=password_file -v -i <path_to_inventory_directory>/hosts <path_to_playbooks_directory>/add-nonposix-and-external-groups.yml

16.5. Using Ansible to enable AD users to administer IdM

Follow this procedure to use an Ansible playbook to ensure that a user ID override is present in an Identity Management (IdM) group. The user ID override is the override of an Active Directory (AD) user that you created in the Default Trust View after you established a trust with AD. As a result of running the playbook, an AD user, for example an AD administrator, is able to fully administer IdM without having two different accounts and passwords.

Prerequisites

  • You know the IdM admin password.
  • You have installed a trust with AD.
  • The user ID override of the AD user already exists in IdM. If it does not, create it with the ipa idoverrideuser-add 'default trust view' ad_user@ad.example.com command.
  • The group to which you are adding the user ID override already exists in IdM.
  • You are using the 4.8.7 version of IdM or later. To view the version of IdM you have installed on your server, enter ipa --version.
  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password.

Procedure

  1. Navigate to your ~/MyPlaybooks/ directory:

    $ cd ~/MyPlaybooks/
  2. Create an add-useridoverride-to-group.yml playbook with the following content:

    ---
    - name: Playbook to ensure presence of users in a group
      hosts: ipaserver
    
    
      - name: Ensure the ad_user@ad.example.com user ID override is a member of the admins group:
        ipagroup:
          ipaadmin_password: "{{ ipaadmin_password }}"
          name: admins
          idoverrideuser:
          - ad_user@ad.example.com

    In the example:

    • Secret123 is the IdM admin password.
    • admins is the name of the IdM POSIX group to which you are adding the ad_user@ad.example.com ID override. Members of this group have full administrator privileges.
    • ad_user@ad.example.com is the user ID override of an AD administrator. The user is stored in the AD domain with which a trust has been established.
  3. Save the file.
  4. Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:

    $ ansible-playbook --vault-password-file=password_file -v -i inventory add-useridoverride-to-group.yml

Additional resources

16.6. Ensuring the presence of member managers in IdM user groups using Ansible playbooks

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

Prerequisites

  • You know the IdM administrator password.
  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password.
  • You must have the name of the user or group you are adding as member managers and the name of the group you want them to manage.

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 member management information:

    ---
    - name: Playbook to handle membership management
      hosts: ipaserver
    
      vars_files:
      - /home/user_name/MyPlaybooks/secret.yml
      tasks:
      - name: Ensure user test is present for group_a
        ipagroup:
          ipaadmin_password: "{{ ipaadmin_password }}"
          name: group_a
          membermanager_user: test
    
      - name: Ensure group_admins is present for group_a
        ipagroup:
          ipaadmin_password: "{{ ipaadmin_password }}"
          name: group_a
          membermanager_group: group_admins
  3. Run the playbook:

    $ ansible-playbook --vault-password-file=password_file -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/add-member-managers-user-groups.yml

Verification steps

You can verify if the group_a group contains test as a member manager and group_admins is a member manager of group_a 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 managergroup1:

    ipaserver]$ ipa group-show group_a
      Group name: group_a
      GID: 1133400009
      Membership managed by groups: group_admins
      Membership managed by users: test

Additional resources

  • See ipa host-add-member-manager --help.
  • See the ipa man page.

16.7. Ensuring the absence of member managers in IdM user groups using Ansible playbooks

The following procedure describes ensuring the absence of IdM member managers - both users and user groups - using an Ansible playbook.

Prerequisites

  • You know the IdM administrator password.
  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password.
  • You must have the name of the existing member manager user or group you are removing and the name of the group they are managing.

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 member management information:

    ---
    - name: Playbook to handle membership management
      hosts: ipaserver
    
      vars_files:
      - /home/user_name/MyPlaybooks/secret.yml
      tasks:
      - name: Ensure member manager user and group members are absent for group_a
        ipagroup:
          ipaadmin_password: "{{ ipaadmin_password }}"
          name: group_a
          membermanager_user: test
          membermanager_group: group_admins
          action: member
          state: absent
  3. Run the playbook:

    $ ansible-playbook --vault-password-file=password_file -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-member-managers-are-absent.yml

Verification steps

You can verify if the group_a group does not contain test as a member manager and group_admins as a member manager of group_a 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 group_a:

    ipaserver]$ ipa group-show group_a
      Group name: group_a
      GID: 1133400009

Additional resources

  • See ipa host-remove-member-manager --help.
  • See the ipa man page.

Chapter 17. 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:

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

17.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 about 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.

17.3. Adding an automember rule using IdM CLI

Follow this procedure to add 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

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

After configuring automember rules, you can then add a condition to that 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

17.5. Viewing existing automember rules using IdM CLI

Follow this procedure 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
    ----------------------------

17.6. Deleting an automember rule using IdM CLI

Follow this procedure 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.

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

Follow this procedure 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
    ------------------------------

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

17.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 18. 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:

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

18.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 about 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.

18.3. Adding an automember rule using IdM Web UI

Follow this procedure to add 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.

    Screenshot of the "Add Rule" window displaying the drop-down field for the Automember Rule where you can choose between rules you have previously defined.
  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.

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

After configuring automember rules, you can then add a condition to that 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.

    A screenshot of the User group rule page displaying attributes for the user_group rule. The "Inclusive" section has a table with an "Attribute" column and an "Expression" column with an entry for the Attribute "uid" and its Expression is ".*". At the bottom is the Exclusive section which also has a table with an Attribute column and an Expression column but it has no entries.
  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.

    Screenshot of the "Add Condition into automember" pop-up window displaying a drop-down menu for an Attribute (uid is selected) and a field for the corresponding "Expression" (which is required and .* has been entered). The "Add" button is at the bottom of the window.

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

Follow this procedure 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.

    A screenshot of the details of the user group rule "user_group." There is a "General" section displaying the name of the Automember rule and a "Description." There is an "Inclusive" section at the bottom with a table displaying entries with columns labeled "Attribute" and "Expression." This table has one entry with uid as the Attribute and .* as the Expression. At the very bottom there is an "Exclusive" section with a table that matches the structure of the "Inclusive" table but it has no entries.

18.6. Deleting an automember rule using IdM Web UI

Follow this procedure 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.

    A screenshot of the "User group rules" page displaying a table of automember rules. The checkbox for the "user_group" entry has been selected and the "Delete" button has been highlighted.
  4. Click Delete to confirm.

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

Follow this procedure 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.

    A screenshot of the "User group rule" page displaying information for "user_group". An entry in the "Inclusive" section has its checkbox checked and the "Delete" button that pertains to the "Inclusive" section is highlighted.
  5. Click Delete to confirm.

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

18.8.1. Rebuilding automatic membership for all users or hosts

Follow this procedure 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.

    A screenshot highlighting that "Rebuild auto membership" is an option from the "Actions" drop-down menu.

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

Follow this procedure 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.

    A screenshot highlighting the "Rebuild auto membership" option among many others in the contents of the "Actions" drop-down menu.

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

18.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 19. Using Ansible to automate group membership in IdM

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

  • Divide employees' user entries into groups based on the employees' manager, location, position or any other attribute. You can list all attributes by entering ipa user-add --help on the command-line.
  • Divide hosts into groups based on their class, location, or any other attribute. You can list all attributes by entering ipa host-add --help on the command-line.
  • Add all users or all hosts to a single global group.

You can use Red Hat Ansible Engine to automate the management of automatic group membership in Identity Management (IdM).

This section covers the following topics:

19.1. Preparing your Ansible control node for managing IdM

As a system administrator managing Identity Management (IdM), when working with Red Hat Ansible Engine, it is good practice to do the following:

  • Create a subdirectory dedicated to Ansible playbooks in your home directory, for example ~/MyPlaybooks.
  • Copy and adapt sample Ansible playbooks from the /usr/share/doc/ansible-freeipa/* and /usr/share/doc/rhel-system-roles/* directories and subdirectories into your ~/MyPlaybooks directory.
  • Include your inventory file in your ~/MyPlaybooks directory.

By following this practice, you can find all your playbooks in one place and you can run your playbooks without invoking root privileges.

Note

You only need root privileges on the managed nodes to execute the ipaserver, ipareplica, ipaclient, ipabackup, ipasmartcard_server and ipasmartcard_client ansible-freeipa roles. These roles require privileged access to directories and the dnf software package manager.

Follow this procedure to create the ~/MyPlaybooks directory and configure it so that you can use it to store and run Ansible playbooks.

Prerequisites

  • You have installed an IdM server on your managed nodes, server.idm.example.com and replica.idm.example.com.
  • You have configured DNS and networking so you can log in to the managed nodes, server.idm.example.com and replica.idm.example.com, directly from the control node.
  • You know the IdM admin password.

Procedure

  1. Create a directory for your Ansible configuration and playbooks in your home directory:

    $ mkdir ~/MyPlaybooks/
  2. Change into the ~/MyPlaybooks/ directory:

    $ cd ~/MyPlaybooks
  3. Create the ~/MyPlaybooks/ansible.cfg file with the following content:

    [defaults]
    inventory = /home/your_username/MyPlaybooks/inventory
    
    [privilege_escalation]
    become=True
  4. Create the ~/MyPlaybooks/inventory file with the following content:

    [ipaserver]
    server.idm.example.com
    
    [ipareplicas]
    replica1.idm.example.com
    replica2.idm.example.com
    
    [ipacluster:children]
    ipaserver
    ipareplicas
    
    [ipacluster:vars]
    ipaadmin_password=SomeADMINpassword
    
    [ipaclients]
    ipaclient1.example.com
    ipaclient2.example.com
    
    [ipaclients:vars]
    ipaadmin_password=SomeADMINpassword

    This configuration defines two host groups, eu and us, for hosts in these locations. Additionally, this configuration defines the ipaserver host group, which contains all hosts from the eu and us groups.

  5. [Optional] Create an SSH public and private key. To simplify access in your test environment, do not set a password on the private key:

    $ ssh-keygen
  6. Copy the SSH public key to the IdM admin account on each managed node:

    $ ssh-copy-id admin@server.idm.example.com
    $ ssh-copy-id admin@replica.idm.example.com

    You must enter the IdM admin password when you enter these commands.

19.2. Using Ansible to ensure that an automember rule for an IdM user group is present

The following procedure describes how to use an Ansible playbook to ensure an automember rule for an Identity Management (IdM) group exists. In the example, the presence of an automember rule is ensured for the testing_group user group.

Prerequisites

  • You know the IdM admin password.
  • The testing_group user group exists in IdM.
  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password.

Procedure

  1. Navigate to your ~/MyPlaybooks/ directory:

    $ cd ~/MyPlaybooks/
  2. Copy the automember-group-present.yml Ansible playbook file located in the /usr/share/doc/ansible-freeipa/playbooks/automember/ directory:

    $ cp /usr/share/doc/ansible-freeipa/playbooks/automember/automember-group-present.yml automember-group-present-copy.yml
  3. Open the automember-group-present-copy.yml file for editing.
  4. Adapt the file by setting the following variables in the ipaautomember task section:

    • Set the ipaadmin_password variable to the password of the IdM admin.
    • Set the name variable to testing_group.
    • Set the automember_type variable to group.
    • Ensure that the state variable is set to present.

    This is the modified Ansible playbook file for the current example:

    ---
    - name: Automember group present example
      hosts: ipaserver
      vars_files:
      - /home/user_name/MyPlaybooks/secret.yml
      tasks:
      - name: Ensure group automember rule admins is present
        ipaautomember:
          ipaadmin_password: "{{ ipaadmin_password }}"
          name: testing_group
          automember_type: group
          state: present
  5. Save the file.
  6. Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:

    $ ansible-playbook --vault-password-file=password_file -v -i inventory automember-group-present-copy.yml

Additional resources

19.3. Using Ansible to ensure that a specified condition is present in an IdM user group automember rule

The following procedure describes how to use an Ansible playbook to ensure that a specified condition exists in an automember rule for an Identity Management (IdM) group. In the example, the presence of a UID-related condition in the automember rule is ensured for the testing_group group. By specifying the .* condition, you ensure that all future IdM users automatically become members of the testing_group.

Prerequisites

  • You know the IdM admin password.
  • The testing_group user group and automember user group rule exist in IdM.
  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password.

Procedure

  1. Navigate to your ~/MyPlaybooks/ directory:

    $ cd ~/MyPlaybooks/
  2. Copy the automember-hostgroup-rule-present.yml Ansible playbook file located in the /usr/share/doc/ansible-freeipa/playbooks/automember/ directory and name it, for example, automember-usergroup-rule-present.yml:

    $ cp /usr/share/doc/ansible-freeipa/playbooks/automember/automember-hostgroup-rule-present.yml automember-usergroup-rule-present.yml
  3. Open the automember-usergroup-rule-present.yml file for editing.
  4. Adapt the file by modifying the following parameters:

    • Rename the playbook to correspond to your use case, for example: Automember user group rule member present.
    • Rename the task to correspond to your use case, for example: Ensure an automember condition for a user group is present.
    • Set the following variables in the ipaautomember task section:

      • Set the ipaadmin_password variable to the password of the IdM admin.
      • Set the name variable to testing_group.
      • Set the automember_type variable to group.
      • Ensure that the state variable is set to present.
      • Ensure that the action variable is set to member.
      • Set the inclusive key variable to UID.
      • Set the inclusive expression variable to .*

    This is the modified Ansible playbook file for the current example:

    ---
    - name: Automember user group rule member present
      hosts: ipaserver
      vars_files:
      - /home/user_name/MyPlaybooks/secret.yml
      tasks:
      - name: Ensure an automember condition for a user group is present
        ipaautomember:
          ipaadmin_password: "{{ ipaadmin_password }}"
          name: testing_group
          automember_type: group
          state: present
          action: member
          inclusive:
            - key: UID
              expression: .*
  5. Save the file.
  6. Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:

    $ ansible-playbook --vault-password-file=password_file -v -i inventory automember-usergroup-rule-present.yml

Verification steps

  1. Log in as an IdM administrator.

    $ kinit admin
  2. Add a user, for example:

    $ ipa user-add user101 --first user --last 101
    -----------------------
    Added user "user101"
    -----------------------
      User login: user101
      First name: user
      Last name: 101
      ...
      Member of groups: ipausers, testing_group
      ...

Additional resources

19.4. Using Ansible to ensure that a condition is absent from an IdM user group automember rule

The following procedure describes how to use an Ansible playbook to ensure a condition is absent from an automember rule for an Identity Management (IdM) group. In the example, the absence of a condition in the automember rule is ensured that specifies that users whose initials are dp should be included. The automember rule is applied to the testing_group group. By applying the condition, you ensure that no future IdM user whose initials are dp becomes a member of the testing_group.

Prerequisites

  • You know the IdM admin password.
  • The testing_group user group and automember user group rule exist in IdM.
  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password.

Procedure

  1. Navigate to your ~/MyPlaybooks/ directory:

    $ cd ~/MyPlaybooks/
  2. Copy the automember-hostgroup-rule-absent.yml Ansible playbook file located in the /usr/share/doc/ansible-freeipa/playbooks/automember/ directory and name it, for example, automember-usergroup-rule-absent.yml:

    $ cp /usr/share/doc/ansible-freeipa/playbooks/automember/automember-hostgroup-rule-absent.yml automember-usergroup-rule-absent.yml
  3. Open the automember-usergroup-rule-absent.yml file for editing.
  4. Adapt the file by modifying the following parameters:

    • Rename the playbook to correspond to your use case, for example: Automember user group rule member absent.
    • Rename the task to correspond to your use case, for example: Ensure an automember condition for a user group is absent.
    • Set the following variables in the ipaautomember task section:

      • Set the ipaadmin_password variable to the password of the IdM admin.
      • Set the name variable to testing_group.
      • Set the automember_type variable to group.
      • Ensure that the state variable is set to absent.
      • Ensure that the action variable is set to member.
      • Set the inclusive key variable to initials.
      • Set the inclusive expression variable to dp.

    This is the modified Ansible playbook file for the current example:

    ---
    - name: Automember user group rule member absent
      hosts: ipaserver
      vars_files:
      - /home/user_name/MyPlaybooks/secret.yml
      tasks:
      - name: Ensure an automember condition for a user group is absent
        ipaautomember:
          ipaadmin_password: "{{ ipaadmin_password }}"
          name: testing_group
          automember_type: group
          state: absent
          action: member
          inclusive:
            - key: initials
              expression: dp
  5. Save the file.
  6. Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:

    $ ansible-playbook --vault-password-file=password_file -v -i inventory automember-usergroup-rule-absent.yml

Verification steps

  1. Log in as an IdM administrator.

    $ kinit admin
  2. View the automember group:

    $ ipa automember-show --type=group testing_group
     Automember Rule: testing_group

The absence of an Inclusive Regex: initials=dp entry in the output confirms that the testing_group automember rule does not contain the condition specified.

Additional resources

19.5. Using Ansible to ensure that an automember rule for an IdM user group is absent

The following procedure describes how to use an Ansible playbook to ensure an automember rule is absent for an Identity Management (IdM) group. In the example, the absence of an automember rule is ensured for the testing_group group.

Note

Deleting an automember rule also deletes all conditions associated with the rule. To remove only specific conditions from a rule, see Using Ansible to ensure that a condition is absent in an IdM user group automember rule.

Prerequisites

  • You know the IdM admin password.
  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password.

Procedure

  1. Navigate to your ~/MyPlaybooks/ directory:

    $ cd ~/MyPlaybooks/
  2. Copy the automember-group-absent.yml Ansible playbook file located in the /usr/share/doc/ansible-freeipa/playbooks/automember/ directory:

    $ cp /usr/share/doc/ansible-freeipa/playbooks/automember/automember-group-absent.yml automember-group-absent-copy.yml
  3. Open the automember-group-absent-copy.yml file for editing.
  4. Adapt the file by setting the following variables in the ipaautomember task section:

    • Set the ipaadmin_password variable to the password of the IdM admin.
    • Set the name variable to testing_group.
    • Set the automember_type variable to group.
    • Ensure that the state variable is set to absent.

    This is the modified Ansible playbook file for the current example:

    ---
    - name: Automember group absent example
      hosts: ipaserver
      vars_files:
      - /home/user_name/MyPlaybooks/secret.yml
      tasks:
      - name: Ensure group automember rule admins is absent
        ipaautomember:
          ipaadmin_password: "{{ ipaadmin_password }}"
          name: testing_group
          automember_type: group
          state: absent
  5. Save the file.
  6. Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:

    $ ansible-playbook --vault-password-file=password_file -v -i inventory automember-group-absent.yml

Additional resources

19.6. Using Ansible to ensure that a condition is present in an IdM host group automember rule

Follow this procedure to use Ansible to ensure that a condition is present in an IdM host group automember rule. The example describes how to ensure that hosts with the FQDN of .*.idm.example.com are members of the primary_dns_domain_hosts host group and hosts whose FQDN is .*.example.org are not members of the primary_dns_domain_hosts host group.

Prerequisites

  • You know the IdM admin password.
  • The primary_dns_domain_hosts host group and automember host group rule exist in IdM.
  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password.

Procedure

  1. Navigate to your ~/MyPlaybooks/ directory:

    $ cd ~/MyPlaybooks/
  2. Copy the automember-hostgroup-rule-present.yml Ansible playbook file located in the /usr/share/doc/ansible-freeipa/playbooks/automember/ directory:

    $ cp /usr/share/doc/ansible-freeipa/playbooks/automember/automember-hostgroup-rule-present.yml automember-hostgroup-rule-present-copy.yml
  3. Open the automember-hostgroup-rule-present-copy.yml file for editing.
  4. Adapt the file by setting the following variables in the ipaautomember task section:

    • Set the ipaadmin_password variable to the password of the IdM admin.
    • Set the name variable to primary_dns_domain_hosts.
    • Set the automember_type variable to hostgroup.
    • Ensure that the state variable is set to present.
    • Ensure that the action variable is set to member.
    • Ensure that the inclusive key variable is set to fqdn.
    • Set the corresponding inclusive expression variable to .*.idm.example.com.
    • Set the exclusive key variable to fqdn.
    • Set the corresponding exclusive expression variable to .*.example.org.

    This is the modified Ansible playbook file for the current example:

    ---
    - name: Automember user group rule member present
      hosts: ipaserver
      vars_files:
      - /home/user_name/MyPlaybooks/secret.yml
      tasks:
      - name: Ensure an automember condition for a user group is present
        ipaautomember:
          ipaadmin_password: "{{ ipaadmin_password }}"
          name: primary_dns_domain_hosts
          automember_type: hostgroup
          state: present
          action: member
          inclusive:
            - key: fqdn
              expression: .*.idm.example.com
          exclusive:
            - key: fqdn
              expression: .*.example.org
  5. Save the file.
  6. Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:

    $ ansible-playbook --vault-password-file=password_file -v -i inventory automember-hostgroup-rule-present-copy.yml

Additional resources

19.7. Additional resources

Chapter 20. Access control in IdM

Access control defines the rights or permissions users have been granted to perform operations on other users or objects, such as hosts or services. Identity Management (IdM) provides several access control areas to make it clear what kind of access is being granted and to whom it is granted. As part of this, IdM draws a distinction between access control to resources within the domain and access control to the IdM configuration itself.

This chapter outlines the different internal access control mechanisms that are available for IdM users both to the resources within the domain and to the IdM configuration itself.

20.1. Access control instructions in IdM

The Identity Management (IdM) access control structure is based on the 389 Directory Server access control. By using access control instructions (ACIs), you can grant or deny specific IdM users access over other entries. All entries, including IdM users, are stored in LDAP.

An ACI has three parts:

Actor
The entity that is being granted permission to do something. In LDAP access control models, you can, for example, specify that the ACI rule is applied only when a user binds to the directory using their distinguished name (DN). Such a specification is called the bind rule: it defines who the user is and can optionally require other limits on the bind attempt, such as restricting attempts to a certain time of day or a certain machine.
Target
The entry that the actor is allowed to perform operations on.
Operation type
Determines what kinds of actions the actor is allowed to perform. The most common operations are add, delete, write, read, and search. In IdM, the read and search rights of a non-administrative user are limited, and even more so in the IdM Web UI than the IdM CLI.

When an LDAP operation is attempted, the following occurs:

  1. The IdM client sends user credentials to an IdM server as part of the bind operation.
  2. The IdM server DS checks the user credentials.
  3. The IdM server DS checks the user account to see if the user has a permission to perform the requested operation.

20.2. Access control methods in IdM

Identity Management (IdM) divides access control methods into the following categories:

Self-service rules
Define what operations a user can perform on the user’s own personal entry. This access control type only allows write permissions to specific attributes within the user entry. Users can update the values of specific attributes but cannot add or delete the attributes as such.
Delegation rules
By using a delegation rule, you can allow a specific user group to perform write, that is edit, operations on specific attributes of users in another user group. Similarly to self-service rules, this form of access control rule is limited to editing the values of specific attributes. It does not grant the ability to add or remove whole entries or control over unspecified attributes.
Role-based access control

Creates special access control groups that are then granted much broader authority over all types of entities in the IdM domain. Roles can be granted edit, add, and delete rights, meaning they can be granted complete control over entire entries, not just selected attributes.

Certain roles are already available in IdM by default, for example Enrollment Administrator, IT Security Specialist, and IT Specialist. You can create additional roles to manage any types of entries, such as hosts, automount configuration, netgroups, DNS settings, and IdM configuration.

Chapter 21. Managing self-service rules in IdM using the CLI

Learn about self-service rules in Identity Management (IdM) and how to create and edit self-service access rules in the command-line interface (CLI).

21.1. Self-service access control in IdM

Self-service access control rules define which operations an Identity Management (IdM) entity can perform on its IdM Directory Server entry: for example, IdM users have the ability to update their own passwords.

This method of control allows an authenticated IdM entity to edit specific attributes within its LDAP entry, but does not allow add or delete operations on the entire entry.

Warning

Be careful when working with self-service access control rules: configuring access control rules improperly can inadvertently elevate an entity’s privileges.

21.2. Creating self-service rules using the CLI

Follow this procedure to create self-service access rules in IdM using the command-line interface (CLI).