Menu Close

Red Hat Training

A Red Hat training course is available for RHEL 8

Configuring and managing Identity Management

Red Hat Enterprise Linux 8

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

Red Hat Customer Content Services

Abstract

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

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 input on our documentation. Please let us know how we could make it better.

  • For simple comments on specific passages:

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

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

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

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

Important

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

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

1.1. Using kinit to log in to IdM manually

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

Note

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

Procedure

  1. To log in to IdM

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

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

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

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

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

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

1.2. Destroying a user’s active Kerberos ticket

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

Procedure

  1. To destroy your Kerberos ticket:

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

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

1.3. Configuring an external system for Kerberos authentication

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

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

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

Prerequisites

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

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

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

Procedure

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

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

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

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

    $ export KRB5_CONFIG=/etc/krb5_ipa.conf

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

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

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

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

This section describes the 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 on 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: the ipactl utility

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

ipactl commands

To start the entire IdM server:

# ipactl start

To stop the entire IdM server:

# ipactl stop

To restart the entire IdM server:

# ipactl restart

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

# ipactl status
Important

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

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

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

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

# systemctl restart dirsrv@REALM-NAME.service

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

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

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

# systemctl restart sssd.service

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

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

Important

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

Useful systemctl commands

To start a particular IdM service:

# systemctl start name.service

To stop a particular IdM service:

# systemctl stop name.service

To restart a particular IdM service:

# systemctl restart name.service

To view the status of a particular IdM service:

# systemctl status name.service
Important

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

2.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 top-right.

Checking IdM Software Version
Displaying version with ipa commands

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

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

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

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

Chapter 3. Introduction to the IdM command-line utilities

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

Prerequisites

3.1. What is the IPA command line interface

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

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

IPA CLI allows you to:

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

3.2. What is the IPA help

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

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

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

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

Executing help with options has the following syntax:

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

3.3. Using IPA help topics

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

Procedure

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

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

    In the example, we use the following topic: user

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

    $ ipa help user | less

    You can then scroll down and read the whole help.

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

3.4. Using IPA help commands

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

Procedure

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

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

    $ ipa help user-add

Additional resources

  • 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

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

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

and many others.

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

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

Commands have the following structure:

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

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

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

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

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

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

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

Prerequisites

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

Procedure

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

    $ ipa user-add

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

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

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

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

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

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

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

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

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

Additional resources

  • 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 in the IdM server.

Procedure

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

    $ ipa user-mod euser --password

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

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

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

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

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

Additional resources

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

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

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

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

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

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

or

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

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

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

or

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

3.9. How to use special characters with the IdM utilities

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

For example, to escape an asterisk (*):

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

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

Chapter 4. Searching Identity Management entries from the command line

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

4.1. Overview of listing IdM entries

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

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

$ ipa help commands | grep find

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

$ ipa user-find

To list user groups whose specified attributes contain a keyword:

$ ipa group-find keyword

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

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

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

   Group name: trust admins
   Description: Trusts administrators group

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

$ ipa group-find --user=user_name

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

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

4.2. Showing details for a particular entry

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

Procedure

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

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

4.3. Adjusting the search size and time limit

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

Search size limit

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

Default: 100 entries.

Search time limit

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

Default: 2 seconds.

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

Important

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

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

The following 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 following sections provide an overview of the IdM (Identity Management) Web UI and describe how to access it.

5.1. What is the IdM Web UI

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

You can access the IdM Web UI as:

  • IdM users: A limited set of operations depending on permissions granted to the user in the IdM server. Basically, active IdM users can log in to the IdM server and configure their own account. They cannot change settings of other users or the IdM server settings.
  • Administrators: Full access rights to the IdM server.
  • Active Directory users: A 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 portion of a web site, such as when accessing the IdM Web UI with smart card authentication.

To resolve this issue, disable TLS v1.3 by adding -TLSv1.3 to the SSLProtocol option in the /etc/httpd/conf.d/ssl.conf configuration file:

SSLProtocol all -TLSv1 -TLSv1.1 -TLSv1.3

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

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

Prerequisites

6.1. Kerberos authentication in Identity Management

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

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

To use Kerberos authentication on hosts, install:

6.2. Using kinit to log in to IdM manually

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

Note

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

Procedure

  1. To log in to IdM

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

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

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

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

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

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

6.3. Configuring the browser for Kerberos authentication

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

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

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

  • Firefox
  • Chrome

Procedure

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

    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

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

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

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

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

Procedure

  • Open the IdM Web UI.

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

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

    If you see an error message Authentication with Kerberos failed, verify that your browser is configured for Kerberos authentication. See 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

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

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

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

Prerequisites

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

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

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

Procedure

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

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

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

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

    $ export KRB5_CONFIG=/etc/krb5_ipa.conf

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

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

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

6.6. Web UI login for Active Directory users

To enable Web UI login for Active Directory users, define an ID override for each Active Directory user in the Default Trust View. For example:

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

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

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

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

The following sections help you to:

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

7.1. Prerequisites

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

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

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

Identity Management supports the following two standard OTP mechanisms:

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

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

7.3. Enabling the one time password in the Web UI

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

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

Only administrators can enable OTP authentication in the user settings.

Prerequisites

  • Administration privileges

Procedure

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

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

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

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

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

7.4. Adding OTP tokens in the Web UI

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

Prerequisites

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

Procedure

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

    Screenshot of the IdM Web UI highlighting the Add button near the top-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.5. Logging into the Web UI with a one time password

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

Prerequisites

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

    To enable the OTP configuration, see Enabling the one time password in the Web UI.

  • A hardware or software device generating OTP tokens configured.

Procedure

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

    If the authentication fails, synchronize OTP tokens.

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

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

After successful login, the IdM Web UI appears.

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.6. Synchronizing OTP tokens using the Web UI

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

The following text describes token re-synchronization.

Prerequisites

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

Procedure

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

    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.7. Changing expired passwords

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

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

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

Prerequisites

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

Procedure

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

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

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

    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.

The following sections discuss how information flows between the SSSD service and servers that store user information, so you can troubleshoot failing authentication attempts in your environment:

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 on 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 -t '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 -t '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 on 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 on the IdM server. If you cannot retrieve the user information on 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

This procedure describes how 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.

Chapter 9. Configuring global IdM settings using Ansible playbooks

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

This chapter includes the following sections:

9.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 installed the ansible-freeipa package on the Ansible controller.

Procedure

  1. Create an inventory file, for example inventory.file, and define the IdM server from which you want to retrieve the IdM configuration in the [ipaserver] section. For example, to instruct Ansible to retrieve the data from server.idm.example.com, enter:

    [ipaserver]
    server.idm.example.com
  2. 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
    
      tasks:
      - name: Query IPA global configuration
        ipaconfig:
          ipaadmin_password: Secret123
        register: serverconfig
    
      - debug:
          msg: "{{ serverconfig }}"
  3. Adapt the file by changing the following:

    • The password of IdM administrator.
    • Other values, if necessary.
  4. Save the file.
  5. Run the Ansible playbook specifying the playbook file and the inventory file:

    $ ansible-playbook -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
        }
    }

9.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 installed the ansible-freeipa package on the Ansible controller.

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
    
      tasks:
      - name: set ca_renewal_master_server
        ipaconfig:
          ipaadmin_password: SomeADMINpassword
          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 and the inventory file:

    $ ansible-playbook -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.

9.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 installed the ansible-freeipa package on the Ansible controller.

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
      become: true
    
      tasks:
      # Set defaultlogin and maxusername
      - ipaconfig:
          ipaadmin_password: Secret123
          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 and the inventory file:

    $ ansible-playbook -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.

9.4. 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 10. Managing user accounts using the command line

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

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

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

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

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

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

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

10.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 11. Managing user accounts using the IdM Web UI

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

Creating a user account

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

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

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

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

11.3. Activating stage users in the IdM Web UI

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

Prerequisites

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

Procedure

  1. Log in to the IdM Web UI.

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

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

    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. In the Confirmation dialog box, click on the OK button.

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.

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

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

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

11.7. Restoring users in the IdM Web UI

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

Prerequisites

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

Procedure

  1. Log in to the IdM Web UI.

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

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

    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.

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

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. Ensuring the presence of an IdM user using an Ansible playbook

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

Prerequisites

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

Procedure

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

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

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

    You must use the following options to add a user:

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

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

    Note

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

  3. Run the playbook:

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

Verification steps

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

    1. Log into ipaserver as admin:

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

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

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

    The user named idm_user is present in IdM.

12.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 administator password.
  • You have installed the ansible-freeipa package on the Ansible controller.

Procedure

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

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

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

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

  3. Run the playbook:

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

Verification steps

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

    1. Log into ipaserver as administrator:

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

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

    The user named idm_user_1 is present in IdM.

12.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 administator password.
  • You have installed the ansible-freeipa package on the Ansible controller.

Procedure

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

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

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

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

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

Verification steps

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

    1. Log into ipaserver as administrator:

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

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

    The user named idm_user_1 is present in IdM.

12.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 administator password.
  • You have installed the ansible-freeipa package on the Ansible controller.

Procedure

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

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

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

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

Verification steps

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

  1. Log into ipaserver as administrator:

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

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

    The user named idm_user_1 does not exist in IdM.

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

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

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

13.3. Adding a user group using IdM CLI

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

Prerequisites

Procedure

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

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

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

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

Warning

Do not add local groups 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.4. Searching for user groups using IdM CLI

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

Procedure

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

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

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

13.5. Deleting a user group using IdM CLI

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

Prerequisites

Procedure

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

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

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

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

Prerequisites

Procedure

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

    Specify the type of member using these options:

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

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

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

    Members of group_b are now indirect members of group_a.

Important

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

Note

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

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

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

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

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

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

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

This section describes how 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.

13.9. Viewing group members using IdM CLI

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

Procedure:

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

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

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

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

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

Prerequisites

Procedure

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

    Specify members to remove using these options:

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

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

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

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

This section describes how 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.

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

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

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

Prerequisites

  • You are logged in to the IdM Web UI.

Procedure

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

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

    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.

14.4. Deleting a user group using IdM Web UI

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

Prerequisites

  • You are logged in to the IdM Web UI.

Procedure

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

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

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

This section describes how 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.

14.7. Viewing group members using IdM Web UI

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

Prerequisites

  • You are logged in to the IdM Web UI.

Procedure

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

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

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

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

Prerequisites

  • You are logged in to the IdM Web UI.

Procedure

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

    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.

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

This section describes how 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 15. 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:

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. Ensuring the presence of IdM groups and group members using Ansible playbooks

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

Prerequisites

Procedure

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

    [ipaserver]
    server.idm.example.com
  2. Create an Ansible playbook file with the necessary user and group information:

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

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

Verification steps

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

  1. Log into ipaserver as administrator:

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

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

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

Additional resources

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

15.4. 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 installed the ansible-freeipa package on the Ansible controller.
  • 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
      become: true
    
      tasks:
      - name: Ensure user test is present for group_a
        ipagroup:
          ipaadmin_password: MySecret123
          name: group_a
          membermanager_user: test
    
      - name: Ensure group_admins is present for group_a
        ipagroup:
          ipaadmin_password: MySecret123
          name: group_a
          membermanager_group: group_admins
  3. Run the playbook:

    $ ansible-playbook -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.

15.5. 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 installed the ansible-freeipa package on the Ansible controller.
  • 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
      become: true
    
      tasks:
      - name: Ensure member manager user and group members are absent for group_a
        ipagroup:
          ipaadmin_password: MySecret123
          name: group_a
          membermanager_user: test
          membermanager_group: group_admins
          action: member
          state: absent
  3. Run the playbook:

    $ ansible-playbook -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 16. 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:

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

16.2. Automember rules

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

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

  • Inclusive conditions

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

  • Exclusive conditions

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

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

Note

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

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

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

16.3. Adding an automember rule using IdM CLI

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

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

Note

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

Prerequisites

Procedure

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

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

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

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

Verification steps

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

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

Prerequisites

Procedure

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

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

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

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

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

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

Verification steps

16.5. Viewing existing automember rules using IdM CLI

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

Prerequisites

Procedure

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

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

      For example:

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

16.6. Deleting an automember rule using IdM CLI

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

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

Prerequisites

Procedure

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

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

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

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

Prerequisites

Procedure

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

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

      For example:

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

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

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

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 on PCRE, see the pcresyntax(3) man page.

Note

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

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

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

17.3. Adding an automember rule using IdM Web UI

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

Note

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

Prerequisites

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

Procedure

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

    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.

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

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

Prerequisites

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

Procedure

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

    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.

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

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

Prerequisites

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

Procedure

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

    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.

17.6. Deleting an automember rule using IdM Web UI

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

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

Prerequisites

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

Procedure

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

    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.

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

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

Prerequisites

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

Procedure

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

    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.

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

17.8.1. Rebuilding automatic membership for all users or hosts

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

Prerequisites

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

Procedure

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

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

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

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

Prerequisites

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

Procedure

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

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

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

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

18.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 and ipabackup ansible-freeipa roles. These roles require privileged access to directories and the dnf software package manager.

This section describes how 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:

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

  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.

18.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 an Ansible control node that meets the following requirements:

    • You are using Ansible version 2.8 or later.
    • You have installed the ansible-freeipa package.
    • In the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server where you are configuring these options.

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
      become: true
      tasks:
      - name: Ensure group automember rule admins is present
        ipaautomember:
          ipaadmin_password: Secret123
          name: testing_group
          automember_type: group
          state: present
  5. Save the file.
  6. Run the Ansible playbook specifying the playbook file and the inventory file:

    $ ansible-playbook -v -i inventory automember-group-present-copy.yml

Additional resources

18.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 an Ansible control node that meets the following requirements:

    • You are using Ansible version 2.8 or later.
    • You have installed the ansible-freeipa package.
    • In the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server where you are configuring these options.

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
      become: true
      tasks:
      - name: Ensure an automember condition for a user group is present
        ipaautomember:
          ipaadmin_password: Secret123
          name: testing_group
          automember_type: group
          state: present
          action: member
          inclusive:
            - key: UID
              expression: .*
  5. Save the file.
  6. Run the Ansible playbook specifying the playbook file and the inventory file:

    $ ansible-playbook -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

18.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 an Ansible control node that meets the following requirements:

    • You are using Ansible version 2.8 or later.
    • You have installed the ansible-freeipa package.
    • In the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server where you are configuring these options.

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
      become: true
      tasks:
      - name: Ensure an automember condition for a user group is absent
        ipaautomember:
          ipaadmin_password: Secret123
          name: testing_group
          automember_type: group
          state: absent
          action: member
          inclusive:
            - key: initials
              expression: dp
  5. Save the file.
  6. Run the Ansible playbook specifying the playbook file and the inventory file:

    $ ansible-playbook -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

18.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 an Ansible control node that meets the following requirements:

    • You are using Ansible version 2.8 or later.
    • You have installed the ansible-freeipa package.
    • In the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server where you are configuring these options.

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
      become: true
      tasks:
      - name: Ensure group automember rule admins is absent
        ipaautomember:
          ipaadmin_password: Secret123
          name: testing_group
          automember_type: group
          state: absent
  5. Save the file.
  6. Run the Ansible playbook specifying the playbook file and the inventory file:

    $ ansible-playbook -v -i inventory automember-group-absent.yml

Additional resources

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

This section describes how 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 an Ansible control node that meets the following requirements:

    • You are using Ansible version 2.8 or later.
    • You have installed the ansible-freeipa package.
    • In the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server where you are configuring these options.

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
      become: true
      tasks:
      - name: Ensure an automember condition for a user group is present
        ipaautomember:
          ipaadmin_password: Secret123
          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 specifying the playbook file and the inventory file:

    $ ansible-playbook -v -i inventory automember-hostgroup-rule-present-copy.yml

Additional resources

18.7. Additional resources

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

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

19.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 20. Managing self-service rules in IdM using the CLI

This chapter introduces self-service rules in Identity Management (IdM) and describes how to create and edit self-service access rules in the command-line interface (CLI).

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

20.2. Creating self-service rules using the CLI

This procedure describes creating self-service access rules in IdM using the command-line interface (CLI).

Prerequisites

Procedure

  • To add a self-service rule, use the ipa selfservice-add command and specify the following two options:

    --permissions
    sets the read and write permissions the Access Control Instruction (ACI) grants.
    --attrs
    sets the complete list of attributes to which this ACI grants permission.

For example, to create a self-service rule allowing users to modify their own name details:

$ ipa selfservice-add "Users can manage their own name details" --permissions=write --attrs=givenname --attrs=displayname --attrs=title --attrs=initials
-----------------------------------------------------------
Added selfservice "Users can manage their own name details"
-----------------------------------------------------------
    Self-service name: Users can manage their own name details
    Permissions: write
    Attributes: givenname, displayname, title, initials

20.3. Editing self-service rules using the CLI

This procedure describes editing self-service access rules in IdM using the command-line interface (CLI).

Prerequisites

Procedure

  1. Optional: Display existing self-service rules with the ipa selfservice-find command.
  2. Optional: Display details for the self-service rule you want to modify with the ipa selfservice-show command.
  3. Use the ipa selfservice-mod command to edit a self-service rule.

For example:

$ ipa selfservice-mod "Users can manage their own name details" --attrs=givenname --attrs=displayname --attrs=title --attrs=initials --attrs=surname
--------------------------------------------------------------
Modified selfservice "Users can manage their own name details"
--------------------------------------------------------------
Self-service name: Users can manage their own name details
Permissions: write
Attributes: givenname, displayname, title, initials
Important

Using the ipa selfservice-mod command overwrites the previously defined permissions and attributes, so always include the complete list of existing permissions and attributes along with any new ones you want to define.

Verification steps

  • Use the ipa selfservice-show command to display the self-service rule you edited.
$ ipa selfservice-show "Users can manage their own name details"
--------------------------------------------------------------
Self-service name: Users can manage their own name details
Permissions: write
Attributes: givenname, displayname, title, initials

20.4. Deleting self-service rules using the CLI

This procedure describes deleting self-service access rules in IdM using the command-line interface (CLI).

Prerequisites

Procedure

  • Use the ipa selfservice-del command to delete a self-service rule.

For example:

$ ipa selfservice-del "Users can manage their own name details"
-----------------------------------------------------------
Deleted selfservice "Users can manage their own name details"
-----------------------------------------------------------

Verification steps

  • Use the ipa selfservice-find command to display all self-service rules. The rule you just deleted should be missing.

Chapter 21. Managing self-service rules using the IdM Web UI

This chapter introduces self-service rules in Identity Management (IdM) and describes how to create and edit self-service access rules in the web interface (IdM Web UI).

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 IdM Web UI

This procedure describes how to create self-service access rules in IdM using the web interface (IdM Web UI).

Prerequisites

Procedure

  1. Open the Role-Based Access Control sub-menu in the IPA Server tab and select Self Service Permissions.
  2. Click Add at the top-right of the list of the self-service access rules:

    Adding a self-service rule

  3. The Add Self Service Permission window opens. Enter the name of the new self-service rule in the Self-service name field. Spaces are allowed:

    Form for adding a self-service rule

  4. Select the check boxes next to the attributes you want users to be able to edit.
  5. Optional: If an attribute you would like to provide access to is not listed, you can add a listing for it:

    1. Click the Add button.
    2. Enter the attribute name in the Attribute text field of the following Add Custom Attribute window.
    3. Click the OK button to add the attribute
    4. Verify that the new attribute is selected
  6. Click the Add button at the bottom of the form to save the new self-service rule.
    Alternatively, you can save and continue editing the self-service rule by clicking the Add and Edit button, or save and add further rules by clicking the Add and Add another button.

21.3. Editing self-service rules using the IdM Web UI

This procedure describes how to edit self-service access rules in IdM using the web interface (IdM Web UI).

Prerequisites

Procedure

  1. Open the Role-Based Access Control sub-menu in the IPA Server tab and select Self Service Permissions.
  2. Click on the name of the self-service rule you want to modify.

    Editing an existing self-service rule

  3. The edit page only allows you to edit the list of attributes to you want to add or remove to the self-service rule. Select or deselect the appropriate check boxes.
  4. Click the Save button to save your changes to the self-service rule.

21.4. Deleting self-service rules using the IdM Web UI

This procedure describes how to delete self-service access rules in IdM using the web interface (IdM Web UI).

Prerequisites

Procedure

  1. Open the Role-Based Access Control sub-menu in the IPA Server tab and select Self Service Permissions.
  2. Select the check box next to the rule you want to delete, then click on the Delete button on the right of the list.

    Deleting a self-service rule

  3. A dialog opens, click on Delete to confirm.

Chapter 22. Using Ansible playbooks to manage self-service rules in IdM

This section introduces self-service rules in Identity Management (IdM) and describes how to create and edit self-service access rules using Ansible playbooks. Self-service access control rules allow an IdM entity to perform specified operations on its IdM Directory Server entry.

This section covers the following topics:

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

22.2. Using Ansible to ensure that a self-service rule is present

The following procedure describes how to use an Ansible playbook to define self-service rules and ensure their presence on an Identity Management (IdM) server. In this example, the new Users can manage their own name details rule grants users the ability to change their own givenname, displayname, title and initials attributes. This allows them to, for example, change their display name or initials if they want to.

Prerequisites

  • You know the IdM administrator password.
  • You have configured an Ansible control node that meets the following requirements:

    • You are using Ansible version 2.8 or later.
    • You have installed the ansible-freeipa package.
    • In the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server where you are configuring these options.

Procedure

  1. Navigate to the ~/MyPlaybooks/ directory:

    $ cd ~/MyPlaybooks/
  2. Make a copy of the selfservice-present.yml file located in the /usr/share/doc/ansible-freeipa/playbooks/selfservice/ directory:

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

    • Set the ipaadmin_password variable to the password of the IdM administrator.
    • Set the name variable to the name of the new self-service rule.
    • Set the permission variable to a comma-separated list of permissions to grant: read and write.
    • Set the attribute variable to a list of attributes that users can manage themselves: givenname, displayname, title, and initials.

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

    ---
    - name: Self-service present
      hosts: ipaserver
      become: true
    
      tasks:
      - name: Ensure self-service rule "Users can manage their own name details" is present
        ipaselfservice:
          ipaadmin_password: Secret123
          name: "Users can manage their own name details"
          permission: read, write
          attribute:
          - givenname
          - displayname
          - title
          - initials
  5. Save the file.
  6. Run the Ansible playbook specifying the playbook file and the inventory file:

    $ ansible-playbook -v -i inventory selfservice-present-copy.yml

Additional resources

  • See Self-service access control in IdM.
  • See the README-selfservice.md file in the /usr/share/doc/ansible-freeipa/ directory.
  • See the /usr/share/doc/ansible-freeipa/playbooks/selfservice directory.

22.3. Using Ansible to ensure that a self-service rule is absent

The following procedure describes how to use an Ansible playbook to ensure a specified self-service rule is absent from your IdM configuration. The example below describes how to make sure the Users can manage their own name details self-service rule does not exist in IdM. This will ensure that users cannot, for example, change their own display name or initials.

Prerequisites

  • You know the IdM administrator password.
  • You have configured an Ansible control node that meets the following requirements:

    • You are using Ansible version 2.8 or later.
    • You have installed the ansible-freeipa package.
    • In the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server where you are configuring these options.

Procedure

  1. Navigate to the ~/MyPlaybooks/ directory:

    $ cd ~/MyPlaybooks/
  2. Make a copy of the selfservice-absent.yml file located in the /usr/share/doc/ansible-freeipa/playbooks/selfservice/ directory:

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

    • Set the ipaadmin_password variable to the password of the IdM administrator.
    • Set the name variable to the name of the self-service rule.
    • Set the state variable to absent.

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

    ---
    - name: Self-service absent
      hosts: ipaserver
      become: true
    
      tasks:
      - name: Ensure self-service rule "Users can manage their own name details" is absent
        ipaselfservice:
          ipaadmin_password: Secret123
          name: "Users can manage their own name details"
          state: absent
  5. Save the file.
  6. Run the Ansible playbook specifying the playbook file and the inventory file:

    $ ansible-playbook -v -i inventory selfservice-absent-copy.yml

Additional resources

  • See Self-service access control in IdM.
  • See the README-selfservice.md file in the /usr/share/doc/ansible-freeipa/ directory.
  • See the sample playbooks in the /usr/share/doc/ansible-freeipa/playbooks/selfservice directory.

22.4. Using Ansible to ensure that a self-service rule has specific attributes

The following procedure describes how to use an Ansible playbook to ensure that an already existing self-service rule has specific settings. In the example, you ensure the Users can manage their own name details self-service rule also has the surname member attribute.

Prerequisites

  • You know the IdM administrator password.
  • You have configured an Ansible control node that meets the following requirements:

    • You are using Ansible version 2.8 or later.
    • You have installed the ansible-freeipa package.
    • In the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server where you are configuring these options.
  • The Users can manage their own name details self-service rule exists in IdM.

Procedure

  1. Navigate to the ~/MyPlaybooks/ directory:

    $ cd ~/MyPlaybooks/
  2. Make a copy of the selfservice-member-present.yml file located in the /usr/share/doc/ansible-freeipa/playbooks/selfservice/ directory:

    $ cp /usr/share/doc/ansible-freeipa/playbooks/selfservice/selfservice-member-present.yml selfservice-member-present-copy.yml
  3. Open the selfservice-member-present-copy.yml Ansible playbook file for editing.
  4. Adapt the file by setting the following variables in the ipaselfservice task section:

    • Set the ipaadmin_password variable to the password of the IdM administrator.
    • Set the name variable to the name of the self-service rule to modify.
    • Set the attribute variable to surname.
    • Set the action variable to member.

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

    ---
    - name: Self-service member present
      hosts: ipaserver
      become: true
    
      tasks:
      - name: Ensure selfservice "Users can manage their own name details" member attribute surname is present
        ipaselfservice:
          ipaadmin_password: Secret123
          name: "Users can manage their own name details"
          attribute:
          - surname
          action: member
  5. Save the file.
  6. Run the Ansible playbook specifying the playbook file and the inventory file:

    $ ansible-playbook -v -i inventory selfservice-member-present-copy.yml

Additional resources

  • See Self-service access control in IdM.
  • See the README-selfservice.md file available in the /usr/share/doc/ansible-freeipa/ directory.
  • See the sample playbooks in the /usr/share/doc/ansible-freeipa/playbooks/selfservice directory.

22.5. Using Ansible to ensure that a self-service rule does not have specific attributes

The following procedure describes how to use an Ansible playbook to ensure that a self-service rule does not have specific settings. You can use this playbook to make sure a self-service rule does not grant undesired access. In the example, you ensure the Users can manage their own name details self-service rule does not have the givenname and surname member attributes.

Prerequisites

  • You know the IdM administrator password.
  • You have configured an Ansible control node that meets the following requirements:

    • You are using Ansible version 2.8 or later.
    • You have installed the ansible-freeipa package.
    • In the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server where you are configuring these options.
  • The Users can manage their own name details self-service rule exists in IdM.

Procedure

  1. Navigate to the ~/MyPlaybooks/ directory:

    $ cd ~/MyPlaybooks/
  2. Make a copy of the selfservice-member-absent.yml file located in the /usr/share/doc/ansible-freeipa/playbooks/selfservice/ directory:

    $ cp /usr/share/doc/ansible-freeipa/playbooks/selfservice/selfservice-member-absent.yml selfservice-member-absent-copy.yml
  3. Open the selfservice-member-absent-copy.yml Ansible playbook file for editing.
  4. Adapt the file by setting the following variables in the ipaselfservice task section:

    • Set the ipaadmin_password variable to the password of the IdM administrator.
    • Set the name variable to the name of the self-service rule you want to modify.
    • Set the attribute variable to givenname and surname.
    • Set the action variable to member.
    • Set the state variable to absent.

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

    ---
    - name: Self-service member absent
      hosts: ipaserver
      become: true
    
      tasks:
      - name: Ensure selfservice "Users can manage their own name details" member attributes givenname and surname are absent
        ipaselfservice:
          ipaadmin_password: Secret123
          name: "Users can manage their own name details"
          attribute:
          - givenname
          - surname
          action: member
          state: absent
  5. Save the file.
  6. Run the Ansible playbook specifying the playbook file and the inventory file:

    $ ansible-playbook -v -i inventory selfservice-member-absent-copy.yml

Additional resources

  • See Self-service access control in IdM.
  • See the README-selfservice.md file in the /usr/share/doc/ansible-freeipa/ directory.
  • See the sample playbooks in the /usr/share/doc/ansible-freeipa/playbooks/selfservice directory.

Chapter 23. Delegating permissions to user groups to manage users using IdM CLI

Delegation is one of the access control methods in IdM, along with self-service rules and role-based access control (RBAC). You can use delegation to assign permissions to one group of users to manage entries for another group of users.

This section covers the following topics:

23.1. Delegation rules

You can delegate permissions to user groups to manage users by creating delegation rules.

Delegation rules allow a specific user group to perform write (edit) operations on specific attributes for users in another user group. This form of access control rule is limited to editing the values of a subset of attributes you specify in a delegation rule; it does not grant the ability to add or remove whole entries or control over unspecified attributes.

Delegation rules grant permissions to existing user groups in IdM. You can use delegation to, for example, allow the managers user group to manage selected attributes of users in the employees user group.

23.2. Creating a delegation rule using IdM CLI

This section describes how to create a delegation rule using the IdM CLI.

Prerequisites

  • You are logged in as a member of the admins group.

Procedure

  • Enter the ipa delegation-add command. Specify the following options:

    • --group: the group who is being granted permissions to the entries of users in the user group.
    • --membergroup: the group whose entries can be edited by members of the delegation group.
    • --permissions: whether users will have the right to view the given attributes (read) and add or change the given attributes (write). If you do not specify permissions, only the write permission will be added.
    • --attrs: the attributes which users in the member group are allowed to view or edit.

    For example:

$ ipa delegation-add "basic manager attributes" --permissions=read --permissions=write --attrs=businesscategory --attrs=departmentnumber --attrs=employeetype --attrs=employeenumber --group=managers --membergroup=employees
-------------------------------------------
Added delegation "basic manager attributes"
-------------------------------------------
  Delegation name: basic manager attributes
  Permissions: read, write
  Attributes: businesscategory, departmentnumber, employeetype, employeenumber
  Member user group: employees
  User group: managers

23.3. Viewing existing delegation rules using IdM CLI

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

Prerequisites

  • You are logged in as a member of the admins group.

Procedure

  • Enter the ipa delegation-find command:
$ ipa delegation-find
--------------------
1 delegation matched
--------------------
  Delegation name: basic manager attributes
  Permissions: read, write
  Attributes: businesscategory, departmentnumber, employeenumber, employeetype
  Member user group: employees
  User group: managers
----------------------------
Number of entries returned 1
----------------------------

23.4. Modifying a delegation rule using IdM CLI

This section describes how to modify an existing delegation rule using the IdM CLI.

Important

The --attrs option overwrites whatever the previous list of supported attributes was, so always include the complete list of attributes along with any new attributes. This also applies to the --permissions option.

Prerequisites

  • You are logged in as a member of the admins group.

Procedure

  • Enter the ipa delegation-mod command with the desired changes. For example, to add the displayname attribute to the basic manager attributes example rule:

    $ ipa delegation-mod "basic manager attributes" --attrs=businesscategory --attrs=departmentnumber --attrs=employeetype --attrs=employeenumber --attrs=displayname
    ----------------------------------------------
    Modified delegation "basic manager attributes"
    ----------------------------------------------
      Delegation name: basic manager attributes
      Permissions: read, write
      Attributes: businesscategory, departmentnumber, employeetype, employeenumber, displayname
      Member user group: employees
      User group: managers

23.5. Deleting a delegation rule using IdM CLI

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

Prerequisites

  • You are logged in as a member of the admins group.

Procedure

  • Enter the ipa delegation-del command.
  • When prompted, enter the name of the delegation rule you want to delete:

    $ ipa delegation-del
    Delegation name: basic manager attributes
    ---------------------------------------------
    Deleted delegation "basic manager attributes"
    ---------------------------------------------

Chapter 24. Delegating permissions to user groups to manage users using IdM WebUI

Delegation is one of the access control methods in IdM, along with self-service rules and role-based access control (RBAC). You can use delegation to assign permissions to one group of users to manage entries for another group of users.

This section covers the following topics:

24.1. Delegation rules

You can delegate permissions to user groups to manage users by creating delegation rules.

Delegation rules allow a specific user group to perform write (edit) operations on specific attributes for users in another user group. This form of access control rule is limited to editing the values of a subset of attributes you specify in a delegation rule; it does not grant the ability to add or remove whole entries or control over unspecified attributes.

Delegation rules grant permissions to existing user groups in IdM. You can use delegation to, for example, allow the managers user group to manage selected attributes of users in the employees user group.

24.2. Creating a delegation rule using IdM WebUI

This section describes how to create a delegation rule using the IdM WebUI.

Prerequisites

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

Procedure

  1. From the IPA Server menu, click Role-Based Access ControlDelegations.
  2. Click Add.

    A screenshot of the IdM Web UI displaying contents of the "Role-Based Access Control" drop-down sub-menu from the "IPA Server" tab. There are five options in the "Role-Based Access Control" drop-down menu: Roles - Privileges - Permissions - Self Service Permissions - Delegations.
  3. In the Add delegation window, do the following:

    1. Name the new delegation rule.
    2. Set the permissions by selecting the check boxes that indicate whether users will have the right to view the given attributes (read) and add or change the given attributes (write).
    3. In the User group drop-down menu, select the group who is being granted permissions to view or edit the entries of users in the member group.
    4. In the Member user group drop-down menu, select the group whose entries can be edited by members of the delegation group.
    5. In the attributes box, select the check boxes by the attributes to which you want to grant permissions.

      A screenshot of the "Add delegation" pop-up window where you can enter details for a delegation. The entry options include a text field for the Delegation name and checkboxes for "read" and "write" permissions. There is also a drop-down menu for the User group - a drop-down menu for the Member user group - and many checkboxes for Attributes (such as departmentnumber - employeenumber - businesscategory - employeetype).
    6. Click the Add button to save the new delegation rule.

24.3. Viewing existing delegation rules using IdM WebUI

This section describes how to view existing delegation rules using the IdM WebUI.

Prerequisites

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

Procedure

  • From the IPA Server menu, click Role-Based Access ControlDelegations.

    A screenshot of the IdM Web UI displaying the "Delegations" page from the "Role-Based Access Control" submenu of the "IPA Server" tab. There is a table displaying Delegations organized by their "Delegation name."

24.4. Modifying a delegation rule using IdM WebUI

This section describes how to modify an existing delegation rule using the IdM WebUI.

Prerequisites

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

Procedure

  1. From the IPA Server menu, click Role-Based Access ControlDelegations.

    A screenshot of the IdM Web UI displaying the Role-Based Access Control sub page from the IPA Server tab. The Delegations page displays a table with an entry for the "basic manager attributes" Delegation name.
  2. Click on the rule you want to modify.
  3. Make the desired changes:

    • Change the name of the rule.
    • Change granted permissions by selecting the check boxes that indicate whether users will have the right to view the given attributes (read) and add or change the given attributes (write).
    • In the User group drop-down menu, select the group who is being granted permissions to view or edit the entries of users in the member group.
    • In the Member user group drop-down menu, select the group whose entries can be edited by members of the delegation group.
    • In the attributes box, select the check boxes by the attributes to which you want to grant permissions. To remove permissions to an attribute, uncheck the relevant check box.

      The Delegation page displays details of the "basic manager attributes" Delegation such as the Delegation name - Permissions (which is required - such as "read" and "write") - User group (required such as "managers") - Member user group (required such as "employees") and Attributes (required such as employeetype - businesscategory - departmentnumber - displayname - employeenumber - homedirectory). The "save" button at the top left is highlighted.
    • Click the Save button to save the changes.

24.5. Deleting a delegation rule using IdM WebUI

This section describes how to delete an existing delegation rule using the IdM WebUI.

Prerequisites

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

Procedure

  1. From the IPA Server menu, click Role-Based Access ControlDelegations.
  2. Select the check box next to the rule you want to remove.
  3. Click Delete.

    Screenshot of the "Role-Based Access Control" sub-menu of the "IPA Server" tab. The "Delegations" page displays a table with Delegation names and the checkbox for the "basic manager attributes" entry has been checked. The "Delete" button has been highlighted.
  4. Click Delete to confirm.

Chapter 25. Delegating permissions to user groups to manage users using Ansible playbooks

Delegation is one of the access control methods in IdM, along with self-service rules and role-based access control (RBAC). You can use delegation to assign permissions to one group of users to manage entries for another group of users.

This section covers the following topics:

25.1. Delegation rules

You can delegate permissions to user groups to manage users by creating delegation rules.

Delegation rules allow a specific user group to perform write (edit) operations on specific attributes for users in another user group. This form of access control rule is limited to editing the values of a subset of attributes you specify in a delegation rule; it does not grant the ability to add or remove whole entries or control over unspecified attributes.

Delegation rules grant permissions to existing user groups in IdM. You can use delegation to, for example, allow the managers user group to manage selected attributes of users in the employees user group.

25.2. Creating an Ansible inventory file for IdM

When working with Ansible, it is good practice to create, in your home directory, a subdirectory dedicated to Ansible playbooks that you copy and adapt from the /usr/share/doc/ansible-freeipa/* and /usr/share/doc/rhel-system-roles/* subdirectories. This practice has the following advantages:

  • You can find all your playbooks in one place.
  • You can run your playbooks without invoking root privileges.

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/<username>/MyPlaybooks/inventory
    
    [privilege_escalation]
    become=True
  4. 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.

25.3. Using Ansible to ensure that a delegation rule is present

The following procedure describes how to use an Ansible playbook to define privileges for a new IdM delegation rule and ensure its presence. In the example, the new basic manager attributes delegation rule grants the managers group the ability to read and write the following attributes for members of the employees group:

  • businesscategory
  • departmentnumber
  • employeenumber
  • employeetype

Prerequisites

  • You know the IdM administrator password.
  • You have configured an Ansible control node that meets the following requirements:

    • You are using Ansible version 2.8 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 where you are configuring these options.
    • Your Ansible inventory file is located in the ~/MyPlaybooks/ directory.

Procedure

  1. Navigate to the ~/MyPlaybooks/ directory:

    $ cd ~/MyPlaybooks/
  2. Make a copy of the delegation-present.yml file located in the /usr/share/doc/ansible-freeipa/playbooks/delegation/ directory:

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

    • Set the ipaadmin_password variable to the password of the IdM administrator.
    • Set the name variable to the name of the new delegation rule.
    • Set the permission variable to a comma-separated list of permissions to grant: read and write.
    • Set the attribute variable to a list of attributes the delegated user group can manage: businesscategory, departmentnumber, employeenumber, and employeetype.
    • Set the group variable to the name of the group that is being given access to view or modify attributes.
    • Set the membergroup variable to the name of the group whose attributes can be viewed or modified.

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

    ---
    - name: Playbook to manage a delegation rule
      hosts: ipaserver
      become: true
    
      tasks:
      - name: Ensure delegation "basic manager attributes" is present
        ipadelegation:
          ipaadmin_password: Secret123
          name: "basic manager attributes"
          permission: read, write
          attribute:
          - businesscategory
          - departmentnumber
          - employeenumber
          - employeetype
          group: managers
          membergroup: employees
  5. Save the file.
  6. Run the Ansible playbook specifying the playbook file and the inventory file:

    $ ansible-playbook -v -i ~/MyPlaybooks/inventory delegation-present-copy.yml

Additional resources

  • See Delegation rules.
  • See the README-delegation.md file in the /usr/share/doc/ansible-freeipa/ directory.
  • See the sample playbooks in the /usr/share/doc/ansible-freeipa/playbooks/ipadelegation directory.

25.4. Using Ansible to ensure that a delegation rule is absent

The following procedure describes how to use an Ansible playbook to ensure a specified delegation rule is absent from your IdM configuration. The example below describes how to make sure the custom basic manager attributes delegation rule does not exist in IdM.

Prerequisites

  • You know the IdM administrator password.
  • You have configured an Ansible control node that meets the following requirements:

    • You are using Ansible version 2.8 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 where you are configuring these options.
    • Your Ansible inventory file is located in the ~/MyPlaybooks/ directory.

Procedure

  1. Navigate to the ~/MyPlaybooks/ directory:

    $ cd ~/MyPlaybooks>/
  2. Make a copy of the delegation-absent.yml file located in the /usr/share/doc/ansible-freeipa/playbooks/delegation/ directory:

    $ cp /usr/share/doc/ansible-freeipa/playbooks/delegation/delegation-present.yml delegation-absent-copy.yml
  3. Open the delegation-absent-copy.yml Ansible playbook file for editing.
  4. Adapt the file by setting the following variables in the ipadelegation task section:

    • Set the ipaadmin_password variable to the password of the IdM administrator.
    • Set the name variable to the name of the delegation rule.
    • Set the state variable to absent.

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

    ---
    - name: Delegation absent
      hosts: ipaserver
      become: true
    
      tasks:
      - name: Ensure delegation "basic manager attributes" is absent
        ipadelegation:
          ipaadmin_password: Secret123
          name: "basic manager attributes"
          state: absent
  5. Save the file.
  6. Run the Ansible playbook specifying the playbook file and the inventory file:

    $ ansible-playbook -v -i ~/MyPlaybooks/inventory delegation-absent-copy.yml

Additional resources

  • See Delegation rules.
  • See the README-delegation.md file in the /usr/share/doc/ansible-freeipa/ directory.
  • See the sample playbooks in the /usr/share/doc/ansible-freeipa/playbooks/ipadelegation directory.

25.5. Using Ansible to ensure that a delegation rule has specific attributes

The following procedure describes how to use an Ansible playbook to ensure that a delegation rule has specific settings. You can use this playbook to modify a delegation role you have previously created. In the example, you ensure the basic manager attributes delegation rule only has the departmentnumber member attribute.

Prerequisites

  • You know the IdM administrator password.
  • You have configured an Ansible control node that meets the following requirements:

    • You are using Ansible version 2.8 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 where you are configuring these options.
    • Your Ansible inventory file is located in the ~/MyPlaybooks/ directory.
  • The basic manager attributes delegation rule exists in IdM.

Procedure

  1. Navigate to the ~/MyPlaybooks/ directory:

    $ cd ~/MyPlaybooks/
  2. Make a copy of the delegation-member-present.yml file located in the /usr/share/doc/ansible-freeipa/playbooks/delegation/ directory:

    $ cp /usr/share/doc/ansible-freeipa/playbooks/delegation/delegation-member-present.yml delegation-member-present-copy.yml
  3. Open the delegation-member-present-copy.yml Ansible playbook file for editing.
  4. Adapt the file by setting the following variables in the ipadelegation task section:

    • Set the ipaadmin_password variable to the password of the IdM administrator.
    • Set the name variable to the name of the delegation rule to modify.
    • Set the attribute variable to departmentnumber.
    • Set the action variable to member.

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

    ---
    - name: Delegation member present
      hosts: ipaserver
      become: true
    
      tasks:
      - name: Ensure delegation "basic manager attributes" member attribute departmentnumber is present
        ipadelegation:
          ipaadmin_password: Secret123
          name: "basic manager attributes"
          attribute:
          - departmentnumber
          action: member
  5. Save the file.
  6. Run the Ansible playbook specifying the playbook file and the inventory file:

    $ ansible-playbook -v -i ~/MyPlaybooks/inventory delegation-member-present-copy.yml

Additional resources

  • See Delegation rules.
  • See the README-delegation.md file in the /usr/share/doc/ansible-freeipa/ directory.
  • See the sample playbooks in the /usr/share/doc/ansible-freeipa/playbooks/ipadelegation directory.

25.6. Using Ansible to ensure that a delegation rule does not have specific attributes

The following procedure describes how to use an Ansible playbook to ensure that a delegation rule does not have specific settings. You can use this playbook to make sure a delegation role does not grant undesired access. In the example, you ensure the basic manager attributes delegation rule does not have the employeenumber and employeetype member attributes.

Prerequisites

  • You know the IdM administrator password.
  • You have configured an Ansible control node that meets the following requirements:

    • You are using Ansible version 2.8 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 where you are configuring these options.
    • Your Ansible inventory file is located in the ~/MyPlaybooks/ directory.
  • The basic manager attributes delegation rule exists in IdM.

Procedure

  1. Navigate to the ~/MyPlaybooks/ directory:

    $ cd ~/MyPlaybooks/
  2. Make a copy of the delegation-member-absent.yml file located in the /usr/share/doc/ansible-freeipa/playbooks/delegation/ directory:

    $ cp /usr/share/doc/ansible-freeipa/playbooks/delegation/delegation-member-absent.yml delegation-member-absent-copy.yml
  3. Open the delegation-member-absent-copy.yml Ansible playbook file for editing.
  4. Adapt the file by setting the following variables in the ipadelegation task section:

    • Set the ipaadmin_password variable to the password of the IdM administrator.
    • Set the name variable to the name of the delegation rule to modify.
    • Set the attribute variable to employeenumber and employeetype.
    • Set the action variable to member.
    • Set the state variable to absent.

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

    ---
    - name: Delegation member absent
      hosts: ipaserver
      become: true
    
      tasks:
      - name: Ensure delegation "basic manager attributes" member attributes employeenumber and employeetype are absent
        ipadelegation:
          ipaadmin_password: Secret123
          name: "basic manager attributes"
          attribute:
          - employeenumber
          - employeetype
          action: member
          state: absent
  5. Save the file.
  6. Run the Ansible playbook specifying the playbook file and the inventory file:

    $ ansible-playbook -v -i ~/MyPlaybooks/inventory delegation-member-absent-copy.yml

Additional resources

  • See Delegation rules.
  • See the README-delegation.md file in the /usr/share/doc/ansible-freeipa/ directory.
  • See the sample playbooks in the /usr/share/doc/ansible-freeipa/playbooks/ipadelegation directory.

Chapter 26. Managing role-based access controls in IdM using the CLI

This chapter introduces role-based access control in Identity Management (IdM) and describes the following operations in the command-line interface (CLI):

26.1. Role-based access control in IdM

Role-based access control (RBAC) in IdM g