Red Hat Training
A Red Hat training course is available for RHEL 8
Configuring and managing Identity Management
Logging in to IdM and managing services, users, hosts, groups, access control rules, and certificates.
Abstract
Making open source more inclusive
Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.
In Identity Management, planned terminology replacements include:
- block list replaces blacklist
- allow list replaces whitelist
- secondary replaces slave
The word master is being replaced with more precise language, depending on the context:
- IdM server replaces IdM master
- CA renewal server replaces CA renewal master
- CRL publisher server replaces CRL master
- multi-supplier replaces multi-master
Providing feedback on Red Hat documentation
We appreciate your feedback on our documentation. Let us know how we can improve it.
Submitting feedback through Jira (account required)
- Log in to the Jira website.
- Click Create in the top navigation bar.
- Enter a descriptive title in the Summary field.
- Enter your suggestion for improvement in the Description field. Include links to the relevant parts of the documentation.
- Click Create at the bottom of the dialogue.
Chapter 1. Logging in to Identity Management from the command line
Identity Management (IdM) uses the Kerberos protocol to support single sign-on. Single sign-on means that the user enters the correct user name and password only once, and then accesses IdM services without the system prompting for the credentials again.
In IdM, the System Security Services Daemon (SSSD) automatically obtains a ticket-granting ticket (TGT) for a user after the user successfully logs in to the desktop environment on an IdM client machine with the corresponding Kerberos principal name. This means that after logging in, the user is not required to use the kinit utility to access IdM resources.
If you have cleared your Kerberos credential cache or your Kerberos TGT has expired, you need to request a Kerberos ticket manually to access IdM resources. The following sections present basic user operations when using Kerberos in IdM.
1.1. Using kinit to log in to IdM manually
Follow this procedure to use the kinit utility to authenticate to an Identity Management (IdM) environment manually. The kinit utility obtains and caches a Kerberos ticket-granting ticket (TGT) on behalf of an IdM user.
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
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 theadmin
user:[example_user@server ~]$ kinit admin Password for admin@EXAMPLE.COM: [example_user@server ~]$
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, onlyexample_user
is currently allowed to access IdM services:$ klist Ticket cache: KEYRING:persistent:0:0 Default principal: example_user@EXAMPLE.COM Valid starting Expires Service principal 11/10/2019 08:35:45 11/10/2019 18:35:45 krbtgt/EXAMPLE.COM@EXAMPLE.COM
1.2. Destroying a user’s active Kerberos ticket
Follow this procedure to clear the credentials cache that contains the user’s active Kerberos ticket.
Procedure
To destroy your Kerberos ticket:
[example_user@server ~]$ kdestroy
Optionally, to check that the Kerberos ticket has been destroyed:
[example_user@server ~]$ klist klist: Credentials cache keyring 'persistent:0:0' not found
1.3. Configuring an external system for Kerberos authentication
Follow this procedure to configure an external system so that Identity Management (IdM) users can log in to IdM from the external system using their Kerberos credentials.
Enabling Kerberos authentication on external systems is especially useful when your infrastructure includes multiple realms or overlapping domains. It is also useful if the system has not been enrolled into any IdM domain through ipa-client-install
.
To enable Kerberos authentication to IdM from a system that is not a member of the IdM domain, define an IdM-specific Kerberos configuration file on the external system.
Prerequisites
The
krb5-workstation
package is installed on the external system.To find out whether the package is installed, use the following CLI command:
# yum list installed krb5-workstation Installed Packages krb5-workstation.x86_64 1.16.1-19.el8 @BaseOS
Procedure
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
WarningDo not overwrite the existing
krb5.conf
file on the external system.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.-
Copy the Kerberos configuration snippets from the
/etc/krb5.conf.d/
directory to the external system.
Users on the external system can now use the kinit
utility to authenticate against the IdM server.
1.4. Additional resources
-
The
krb5.conf(5)
man page. -
The
kinit(1)
man page. -
The
klist(1)
man page. -
The
kdestroy(1)
man page.
Chapter 2. Viewing, starting and stopping the Identity Management services
Identity Management (IdM) servers are Red Hat Enterprise Linux systems that work as domain controllers (DCs). A number of different services are running on IdM servers, most notably the Directory Server, Certificate Authority (CA), DNS, and Kerberos.
2.1. The IdM services
There are many different services that can be installed and run on the IdM servers and clients.
List of services hosted by IdM servers
Most of the following services are not strictly required to be installed on the IdM server. For example, you can install services such as a certificate authority (CA) or DNS server on an external server outside the IdM domain.
- Kerberos
-
the
krb5kdc
andkadmin
services
IdM uses the Kerberos protocol to support single sign-on. With Kerberos, users only need to present the correct username and password once and can access IdM services without the system prompting for credentials again.
Kerberos is divided into two parts:
-
The
krb5kdc
service is the Kerberos Authentication service and Key Distribution Center (KDC) daemon. -
The
kadmin
service is the Kerberos database administration program.
For information about how to authenticate using Kerberos in IdM, see Logging in to Identity Management from the command line and Logging in to IdM in the Web UI: Using a Kerberos ticket.
- LDAP directory server
-
the
dirsrv
service
The IdM LDAP directory server instance stores all IdM information, such as information related to Kerberos, user accounts, host entries, services, policies, DNS, and others. The LDAP directory server instance is based on the same technology as Red Hat Directory Server. However, it is tuned to IdM-specific tasks.
- Certificate Authority
-
the
pki-tomcatd
service
The integrated certificate authority (CA) is based on the same technology as Red Hat Certificate System. pki
is the command-line interface for accessing Certificate System services.
You can also install the server without the integrated CA if you create and provide all required certificates independently.
For more information, see Planning your CA services.
- Domain Name System (DNS)
-
the
named
service
IdM uses DNS for dynamic service discovery. The IdM client installation utility can use information from DNS to automatically configure the client machine. After the client is enrolled in the IdM domain, it uses DNS to locate IdM servers and services within the domain. The BIND
(Berkeley Internet Name Domain) implementation of the DNS (Domain Name System) protocols in Red Hat Enterprise Linux includes the named
DNS server. named-pkcs11
is a version of the BIND DNS server built with native support for the PKCS#11 cryptographic standard.
For information, see Planning your DNS services and host names.
- Apache HTTP Server
-
the
httpd
service
The Apache HTTP web server provides the IdM Web UI, and also manages communication between the Certificate Authority and other IdM services.
- Samba / Winbind
-
smb
andwinbind
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.

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.

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.
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 Identity
→ Services
tab of the IdM web UI.
You can start or stop the entire server, or an individual service only.
To start, stop, or restart the entire IdM server, see:
To start, stop, or restart an individual IdM service, see:
To display the version of IdM software, see:
2.3. Starting and stopping the entire Identity Management server
Use the ipa
systemd service to stop, start, or restart the entire IdM server along with all the installed services. Using the systemctl
utility to control the ipa
systemd service ensures all services are stopped, started, or restarted in the appropriate order. The ipa
systemd service also upgrades the RHEL IdM configuration before starting the IdM services, and it uses the proper SELinux contexts when administrating with IdM services. You do not need to have a valid Kerberos ticket to run the systemctl ipa
commands.
ipa
systemd service commands
To start the entire IdM server:
# systemctl start ipa
To stop the entire IdM server:
# systemctl stop ipa
To restart the entire IdM server:
# systemctl restart ipa
To show the status of all the services that make up IdM, use the ipactl
utility:
# ipactl status
-
Do not directly use the
ipactl
utility to start, stop, or restart IdM services. Use thesystemctl ipa
commands instead, which call theipactl
utility in a predictable environment. -
You cannot use the IdM web UI to perform the
ipactl
commands.
2.4. Starting and stopping an individual Identity Management service
Changing IdM configuration files manually is generally not recommended. However, certain situations require that an administrator performs a manual configuration of specific services. In such situations, use the systemctl
utility to stop, start, or restart an individual IdM service.
For example, use systemctl
after customizing the Directory Server behavior, without modifying the other IdM services:
# systemctl restart dirsrv@REALM-NAME.service
Also, when initially deploying an IdM trust with Active Directory, modify the /etc/sssd/sssd.conf
file, adding:
- specific parameters to tune the timeout configuration options in an environment where remote servers have a high latency
- specific parameters to tune the Active Directory site affinity
- overrides for certain configuration options that are not provided by the global IdM settings
To apply the changes you have made in the /etc/sssd/sssd.conf
file:
# systemctl restart sssd.service
Running systemctl restart sssd.service
is required because the System Security Services Daemon (SSSD) does not automatically re-read or re-apply its configuration.
Note that for changes that affect IdM identity ranges, a complete server reboot is recommended.
To restart multiple IdM domain services, always use systemctl restart ipa
. Because of dependencies between the services installed with the IdM server, the order in which they are started and stopped is critical. The ipa
systemd service ensures that the services are started and stopped in the appropriate order.
Useful systemctl
commands
To start a particular IdM service:
# systemctl start name.service
To stop a particular IdM service:
# systemctl stop name.service
To restart a particular IdM service:
# systemctl restart name.service
To view the status of a particular IdM service:
# systemctl status name.service
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 Identity
→ Services
and selecting the service.
Additional resources
2.5. Methods for displaying IdM software version
You can display the IdM version number with:
- the IdM WebUI
-
ipa
commands -
rpm
commands
- Displaying version through the WebUI
In the IdM WebUI, the software version can be displayed by choosing
About
from the username menu at the upper-right.- 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 theipa-server
package that is currently installed.[root@server ~]# rpm -q ipa-server ipa-server-4.8.0-11.module+el8.1.0+4247+9f3fd721.x86_64
Chapter 3. Introduction to the IdM command-line utilities
Learn more about the basics of using the Identity Management (IdM) command-line utilities.
Prerequisites
Installed and accessible IdM server.
For details, see Installing Identity Management.
To use the IPA command-line interface, authenticate to IdM with a valid Kerberos ticket.
For details about obtaining a valid Kerberos ticket, see Logging in to Identity Management from the command line.
3.1. What is the IPA command line interface
The IPA command-line interface (CLI) is the basic command-line interface for Identity Management (IdM) administration.
It supports a lot of subcommands for managing IdM, such as the ipa user-add
command to add a new user.
IPA CLI allows you to:
- Add, manage, or remove users, groups, hosts and other objects in the network.
- Manage certificates.
- Search entries.
- Display and list objects.
- Set access rights.
- Get help with the correct command syntax.
3.2. What is the IPA help
The IPA help is a built-in documentation system for the IdM server.
The IPA command-line interface (CLI) generates available help topics from loaded IdM plugin modules. To use the IPA help utility, you must:
- Have an IdM server installed and running.
- Be authenticated with a valid Kerberos ticket.
Entering the ipa help
command without options displays information about basic help usage and the most common command examples.
You can use the following options for different ipa help
use cases:
$ ipa help [TOPIC | COMMAND | topics | commands]
-
[]
— Brackets mean that all parameters are optional and you can write justipa help
and the command will be executed. |
— The pipe character means or. Therefore, you can specify aTOPIC
, aCOMMAND
, ortopics
, orcommands
, with the basicipa help
command:-
topics
— You can run the commandipa help topics
to display a list of topics that are covered by the IPA help, such asuser
,cert
,server
and many others. -
TOPIC
— The TOPIC with capital letters is a variable. Therefore, you can specify a particular topic, for example,ipa help user
. -
commands
— You can enter the commandipa help commands
to display a list of commands which are covered by the IPA help, for example,user-add
,ca-enable
,server-show
and many others. -
COMMAND
— The COMMAND with capital letters is a variable. Therefore, you can specify a particular command, for example,ipa help user-add
.
-
3.3. Using IPA help topics
The following procedure describes how to use the IPA help in the command-line interface.
Procedure
- Open a terminal and connect to the IdM server.
Enter
ipa help topics
to display a list of topics covered by help.$ ipa help topics
Select one of the topics and create a command according to the following pattern:
ipa help [topic_name]
. Instead of thetopic_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
If the IPA help output is too long and you cannot see the whole text, use the following syntax:
$ ipa help user | less
You can then scroll down and read the whole help.
The IPA CLI displays a help page for the user
topic. After reading the overview, you can see many examples with patterns for working with topic commands.
3.4. Using IPA help commands
The following procedure describes how to create IPA help commands in the command-line interface.
Procedure
- Open a terminal and connect to the IdM server.
Enter
ipa help commands
to display a list of commands covered by help.$ ipa help commands
Select one of the commands and create a help command according to the following pattern:
ipa help <COMMAND>
. Instead of the<COMMAND>
string, add one of the commands you listed in the previous step.$ ipa help user-add
Additional resources
-
The
ipa
man page.
3.5. Structure of IPA commands
The IPA CLI distinguishes the following types of commands:
- Built-in commands — Built-in commands are all available in the IdM server.
- Plug-in provided commands
The structure of IPA commands allows you to manage various types of objects. For example:
- Users,
- Hosts,
- DNS records,
- Certificates,
and many others.
For most of these objects, the IPA CLI includes commands to:
-
Add (
add
) -
Modify (
mod
) -
Delete (
del
) -
Search (
find
) -
Display (
show
)
Commands have the following structure:
ipa user-add
, ipa user-mod
, ipa user-del
, ipa user-find
, ipa user-show
ipa host-add
, ipa host-mod
, ipa host-del
, ipa host-find
, ipa host-show
ipa dnsrecord-add
, ipa dnsrecord-mod
, ipa dnsrecord-del
, ipa dnsrecord-find
, ipa dnrecord-show
You can create a user with the ipa user-add [options]
, where [options]
are optional. If you use just the ipa user-add
command, the script asks you for details one by one.
To change an existing object, you need to define the object, therefore the command also includes an object: ipa user-mod USER_NAME [options]
.
3.6. Using an IPA command to add a user account to IdM
The following procedure describes how to add a new user to the Identity Management (IdM) database using the command line.
Prerequisites
- You need to have administrator privileges to add user accounts to the IdM server.
Procedure
- Open a terminal and connect to the IdM server.
Enter the command for adding a new user:
$ ipa user-add
The command runs a script that prompts you to provide basic data necessary for creating a user account.
- In the First name: field, enter the first name of the new user and press the Enter key.
- In the Last name: field, enter the last name of the new user and press the Enter key.
In the User login [suggested user name]: enter the user name, or just press the Enter key to accept the suggested user name.
The user name must be unique for the whole IdM database. If an error occurs because that user name already exists, repeat the process with the
ipa user-add
command and use a different, unique user name.
After you add the user name, the user account is added to the IdM database and the IPA command line interface (CLI) prints the following output:
---------------------- Added user "euser" ---------------------- User login: euser First name: Example Last name: User Full name: Example User Display name: Example User Initials: EU Home directory: /home/euser GECOS: Example User Login shell: /bin/sh Principal name: euser@IDM.EXAMPLE.COM Principal alias: euser@IDM.EXAMPLE.COM Email address: euser@idm.example.com UID: 427200006 GID: 427200006 Password: False Member of groups: ipausers Kerberos keys available: False
By default, a user password is not set for the user account. To add a password while creating a user account, use the ipa user-add
command with the following syntax:
$ ipa user-add --first=Example --last=User --password
The IPA CLI then prompts you to add or confirm a user name and password.
If the user has been created already, you can add the password with the ipa user-mod
command.
Additional resources
-
Run the
ipa help user-add
command for more information about parameters.
3.7. Using an IPA command to modify a user account in IdM
You can change many parameters for each user account. For example, you can add a new password to the user.
Basic command syntax is different from the user-add
syntax because you need to define the existing user account for which you want to perform changes, for example, add a password.
Prerequisites
- You need to have administrator privileges to modify user accounts.
Procedure
- Open a terminal and connect to the IdM server.
Enter the
ipa user-mod
command, specify the user to modify, and any options, such as--password
for adding a password:$ ipa user-mod euser --password
The command runs a script where you can add the new password.
- Enter the new password and press the Enter key.
The IPA CLI prints the following output:
---------------------- Modified user "euser" ---------------------- User login: euser First name: Example Last name: User Home directory: /home/euser Principal name: euser@IDM.EXAMPLE.COM Principal alias: euser@IDM.EXAMPLE.COM Email address: euser@idm.example.com UID: 427200006 GID: 427200006 Password: True Member of groups: ipausers Kerberos keys available: True
The user password is now set for the account and the user can log into IdM.
Additional resources
-
Run the
ipa help user-mod
command for more information about parameters.
3.8. How to supply a list of values to the IdM utilities
Identity Management (IdM) stores values for multi-valued attributes in lists.
IdM supports the following methods of supplying multi-valued lists:
Using the same command-line argument multiple times within the same command invocation:
$ ipa permission-add --right=read --permissions=write --permissions=delete ...
Alternatively, you can enclose the list in curly braces, in which case the shell performs the expansion:
$ ipa permission-add --right={read,write,delete} ...
The examples above show a command permission-add
which adds permissions to an object. The object is not mentioned in the example. Instead of …
you need to add the object for which you want to add permissions.
When you update such multi-valued attributes from the command line, IdM completely overwrites the previous list of values with a new list. Therefore, when updating a multi-valued attribute, you must specify the whole new list, not just a single value you want to add.
For example, in the command above, the list of permissions includes reading, writing and deleting. When you decide to update the list with the permission-mod
command, you must add all values, otherwise those not mentioned will be deleted.
Example 1: — The ipa permission-mod
command updates all previously added permissions.
$ ipa permission-mod --right=read --right=write --right=delete ...
or
$ ipa permission-mod --right={read,write,delete} ...
Example 2 — The ipa permission-mod
command deletes the --right=delete
argument because it is not included in the command:
$ ipa permission-mod --right=read --right=write ...
or
$ ipa permission-mod --right={read,write} ...
3.9. How to use special characters with the IdM utilities
When passing command-line arguments that include special characters to the ipa
commands, escape these characters with a backslash (\). For example, common special characters include angle brackets (< and >), ampersand (&), asterisk (*), or vertical bar (|).
For example, to escape an asterisk (*):
$ ipa certprofile-show certificate_profile --out=exported\*profile.cfg
Commands containing unescaped special characters do not work as expected because the shell cannot properly parse such characters.
Chapter 4. Searching Identity Management entries from the command line
The following sections describe how to use IPA commands, which helps you to find or show objects.
4.1. Overview of listing IdM entries
You can use the ipa *-find
commands to help you to search for particular types of IdM entries.
To list all the find
commands, use the following ipa help command:
$ ipa help commands | grep find
You may need to check if a particular user is included in the IdM database. You can then list all users with the following command:
$ ipa user-find
To list user groups whose specified attributes contain a keyword:
$ ipa group-find keyword
For example the ipa group-find admin
command lists all groups whose names or descriptions include string admin
:
---------------- 3 groups matched ---------------- Group name: admins Description: Account administrators group GID: 427200002 Group name: editors Description: Limited admins who can edit other users GID: 427200002 Group name: trust admins Description: Trusts administrators group
When searching user groups, you can also limit the search results to groups that contain a particular user:
$ ipa group-find --user=user_name
To search for groups that do not contain a particular user:
$ ipa group-find --no-user=user_name
4.2. Showing details for a particular entry
Use the ipa *-show
command to display details about a particular IdM entry.
Procedure
To display details about a host named server.example.com:
$ ipa host-show server.example.com Host name: server.example.com Principal name: host/server.example.com@EXAMPLE.COM ...
4.3. Adjusting the search size and time limit
Some queries, such as requesting a list of IdM users, can return a very large number of entries. By tuning these search operations, you can improve the overall server performance when running the ipa *-find
commands, such as ipa user-find
, and when displaying corresponding lists in the Web UI.
- Search size limit
Defines the maximum number of entries returned for a request sent to the server from a client’s CLI or from a browser accessing the IdM Web UI.
Default: 100 entries.
- Search time limit
Defines the maximum time (in seconds) that the server waits for searches to run. Once the search reaches this limit, the server stops the search and returns the entries discovered in that time.
Default: 2 seconds.
If you set the values to -1
, IdM will not apply any limits when searching.
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
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
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
-
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
- Log in to the IdM Web UI.
Click IPA Server.
- On the IPA Server tab, click Configuration.
Set the required values in the Search Options area.
Default values are:
- Search size limit: 100 entries
- Search time limit: 2 seconds
Click Save at the top of the page.
Chapter 5. Accessing the IdM Web UI in a web browser
The IdM (Identity Management) Web UI is a web application for IdM administration, a graphical alternative to the IdM command line interface (CLI)
5.1. What is the IdM Web UI
The IdM (Identity Management) Web UI is a web application for IdM administration. You can access the IdM Web UI as:
- IdM users: A limited set of operations depending on permissions granted to the user in the IdM server. Basically, active IdM users can log in to the IdM server and configure their own account. They cannot change settings of other users or the IdM server settings.
- Administrators: Full access rights to the IdM server.
- Active Directory users: A set of operations depending on permissions granted to the user. Active Directory users can now be administrators for Identity Management. For details, see Enabling AD users to administer IdM.
5.2. Web browsers supported for accessing the Web UI
Identity Management (IdM) supports the following browsers for connecting to the Web UI:
- Mozilla Firefox 38 and later
- Google Chrome 46 and later
You might experience problems accessing the IdM Web UI with a smart card if your browser attempts to use TLS v1.3:
[ssl:error] [pid 125757:tid 140436077168384] [client 999.999.999.999:99999] AH: verify client post handshake
[ssl:error] [pid 125757:tid 140436077168384] [client 999.999.999.999:99999] AH10158: cannot perform post-handshake authentication
[ssl:error] [pid 125757:tid 140436077168384] SSL Library Error: error:14268117:SSL routines:SSL_verify_client_post_handshake:extension not received
This is because the most recent versions of browsers do not have TLS Post-Handshake Authentication (PHA) enabled by default, or they do not support PHA. PHA is necessary to require a TLS client certificate for only a part of a web site, such as when accessing the IdM Web UI with smart card authentication.
To resolve this issue for Mozilla Firefox 68 and later, enable TLS PHA:
-
Enter
about:config
in the address bar to access the Mozilla Firefox preferences menu. -
Enter
security.tls.enable_post_handshake_auth
in the search bar. - Click the toggle button to set the parameter to true.
To resolve this issue for Chrome, which currently does not support PHA, disable TLS v1.3:
-
Open the
/etc/httpd/conf.d/ssl.conf
configuration file. Add
-TLSv1.3
to theSSLProtocol
option:SSLProtocol all -TLSv1 -TLSv1.1 -TLSv1.3
Restart the
httpd
service:service httpd restart
Note that IdM manages the ssl.conf
file and might overwrite its contents during package updates. Verify custom settings after updating IdM packages.
5.3. Accessing the Web UI
The following procedure describes the first logging in to the IdM (Identity Management) Web UI with a password.
After the first login you can configure your IdM server to authenticate with:
Kerberos ticket
For details, see Kerberos authentication in Identity Management.
Smart card
For details, see Configuring the IdM server for smart card authentication.
One time password (OTP) — this can be combined with password and Kerberos authentication.
For details, see One time password (OTP) authentication in Identity Management.
Procedure
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.
- 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.
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.
- Click Log in.
After the successful login, you can start configuring the IdM server.
Chapter 6. Logging in to IdM in the Web UI: Using a Kerberos ticket
Learn more about how to configure your environment to enable Kerberos login to the IdM Web UI and accessing IdM using Kerberos authentication.
Prerequisites
Installed IdM server in your network environment
For details, see Installing Identity Management in Red Hat Enterprise Linux 8
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:
the IdM client
For details, see Preparing the system for Identity Management client installation.
- the krb5conf package
6.2. Using kinit to log in to IdM manually
Follow this procedure to use the kinit utility to authenticate to an Identity Management (IdM) environment manually. The kinit utility obtains and caches a Kerberos ticket-granting ticket (TGT) on behalf of an IdM user.
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
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 theadmin
user:[example_user@server ~]$ kinit admin Password for admin@EXAMPLE.COM: [example_user@server ~]$
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, onlyexample_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
- Open the IdM Web UI login dialog in your web browser.
Click the link for browser configuration on the Web UI login screen.
Follow the steps on the configuration page.
After the setup, turn back to the IdM Web UI and click Log in.
6.4. Logging in to the web UI using a Kerberos ticket
Follow this procedure to log in to the IdM Web UI using a Kerberos ticket-granting ticket (TGT).
The TGT expires at a predefined time. The default time interval is 24 hours and you can change it in the IdM Web UI.
After the time interval expires, you need to renew the ticket:
- Using the kinit command.
- Using IdM login credentials in the Web UI login dialog.
Procedure
Open the IdM Web UI.
If Kerberos authentication works correctly and you have a valid ticket, you will be automatically authenticated and the Web UI opens.
If the ticket is expired, it is necessary to authenticate yourself with credentials first. However, next time the IdM Web UI will open automatically without opening the login dialog.
If you see an error message
Authentication with Kerberos failed
, verify that your browser is configured for Kerberos authentication. See Configuring the browser for Kerberos authentication.
6.5. Configuring an external system for Kerberos authentication
Follow this procedure to configure an external system so that Identity Management (IdM) users can log in to IdM from the external system using their Kerberos credentials.
Enabling Kerberos authentication on external systems is especially useful when your infrastructure includes multiple realms or overlapping domains. It is also useful if the system has not been enrolled into any IdM domain through ipa-client-install
.
To enable Kerberos authentication to IdM from a system that is not a member of the IdM domain, define an IdM-specific Kerberos configuration file on the external system.
Prerequisites
The
krb5-workstation
package is installed on the external system.To find out whether the package is installed, use the following CLI command:
# yum list installed krb5-workstation Installed Packages krb5-workstation.x86_64 1.16.1-19.el8 @BaseOS
Procedure
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
WarningDo not overwrite the existing
krb5.conf
file on the external system.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.-
Copy the Kerberos configuration snippets from the
/etc/krb5.conf.d/
directory to the external system. - 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
Additional resources
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.
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
- Log in to the IdM Web UI with your username and password.
Open the Identity → Users → Active users tab.
- Click your username to open the user settings.
- In the User authentication types, select Two factor authentication (password + OTP).
- 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
- Log in to the IdM Web UI with your user name and password.
- To create the token in your mobile phone, open the Authentication → OTP Tokens tab.
Click Add.
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.
- Copy the QR code into your mobile phone.
- Click OK to close the QR code.
Now you can generate one time passwords and log in with them to the IdM Web UI.
7.5. Logging into the Web UI with a one time password
Follow this procedure to login for the first time into the IdM Web UI using a one time password (OTP).
Prerequisites
OTP configuration enabled on the Identity Management server for the user account you are using for the OTP authentication. Administrators as well as users themselves can enable OTP.
To enable the OTP configuration, see Enabling the one time password in the Web UI.
- A hardware or software device generating OTP tokens configured.
Procedure
- In the Identity Management login screen, enter your user name or a user name of the IdM server administrator account.
- Add the password for the user name entered above.
- Generate a one time password on your device.
- Enter the one time password right after the password (without space).
Click Log in.
If the authentication fails, synchronize OTP tokens.
If your CA uses a self-signed certificate, the browser issues a warning. Check the certificate and accept the security exception to proceed with the login.
If the IdM Web UI does not open, verify the DNS configuration of your Identity Management server.
After successful login, the IdM Web UI appears.
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
On the IdM Web UI login screen, click Sync OTP Token.
- In the login screen, enter your username and the Identity Management password.
- Generate one time password and enter it in the First OTP field.
- Generate another one time password and enter it in the Second OTP field.
Optionally, enter the token ID.
- 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
- In the password expiration login screen, enter the user name.
- Add the password for the user name entered above.
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.
- Enter the new password twice for verification.
Click Reset Password.
After the successful password change, the usual login dialog displays. Log in with the new password.
Chapter 8. Troubleshooting authentication with SSSD in IdM
Authentication in an Identity Management (IdM) environment involves many components:
On the IdM client:
- The SSSD service.
- The Name Services Switch (NSS).
- Pluggable Authentication Modules (PAM).
On the IdM server:
- The SSSD service.
- The IdM Directory Server.
- The IdM Kerberos Key Distribution Center (KDC).
If you are authenticating as an Active Directory (AD) user:
- The Directory Server on an AD Domain Controller.
- The Kerberos server on an AD Domain Controller.
To authenticate users, you must be able to perform the following functions with the SSSD service:
- Retrieve user information from the authentication server.
- Prompt the user for their credentials, pass those credentials to the authentication server, and process the outcome.
To learn more about how information flows between the SSSD service and servers that store user information, so you can troubleshoot failing authentication attempts in your environment, see the following:
- Data flow when retrieving IdM user information with SSSD
- Data flow when retrieving AD user information with SSSD
- Data flow when authenticating as a user with SSSD in IdM
- Narrowing the scope of authentication issues
- SSSD log files and logging levels
- Enabling detailed logging for SSSD in the sssd.conf file
- Enabling detailed logging for SSSD with the sssctl command
- Gathering debugging logs from the SSSD service to troubleshoot authentication issues with an IdM server
- Gathering debugging logs from the SSSD service to troubleshoot authentication issues with an IdM client
- Tracking client requests in the SSSD backend
- Tracking client requests using the log analyzer tool
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>
.
-
The
getent
command triggers thegetpwnam
call from thelibc
library. -
The
libc
library references the/etc/nsswitch.conf
configuration file to check which service is responsible for providing user information, and discovers the entrysss
for the SSSD service. -
The
libc
library opens thenss_sss
module. -
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. -
If the user information is not in the memory-mapped cache, the request is passed to the SSSD
sssd_nss
responder process. -
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. -
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 settingid_provider=ipa
in thesssd.conf
configuration file. -
The
sssd_be
back-end process connects to the IdM server and requests the information from the IdM LDAP Directory Server. - The SSSD back-end on the IdM server responds to the SSSD back-end process on the IdM client.
- 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.
-
The
sssd_nss
front-end responder process retrieves the information from the SSSD cache. -
The
sssd_nss
responder sends the user information to thenss_sss
responder, completing the request. -
The
libc
library returns the user information to the application that requested it.
8.2. Data flow when retrieving AD user information with SSSD
If you have established a cross-forest trust between your IdM environment and an Active Directory (AD) domain, the information flow when retrieving AD user information about an IdM client is very similar to the information flow when retrieving IdM user information, with the additional step of contacting the AD user database.
The following diagram is a simplification of the information flow when a user requests information about an AD user with the command getent passwd <ad_user_name@ad.example.com>
. This diagram does not include the internal details discussed in the Data flow when retrieving IdM user information with SSSD section. It focuses on the communication between the SSSD service on an IdM client, the SSSD service on an IdM server, and the LDAP database on an AD Domain Controller.
- The IdM client looks to its local SSSD cache for AD user information.
-
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. - The SSSD service on the IdM server looks for the AD user information in its local cache.
- 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.
- The SSSD service on the IdM server receives the AD user information from the AD domain controller and stores it in its cache.
-
The
extdom_extop
plugin receives the information from the SSSD service on the IdM server, which completes the LDAP extended operation. - The SSSD service on the IdM client receives the AD user information from the LDAP extended operation.
- 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.
-
The authentication attempt with the
ssh
command triggers thelibpam
library. 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, thelibpam
library checks the/etc/pam.d/system-auth
configuration file and discovers thepam_sss.so
entry for the SSSD PAM:auth sufficient pam_sss.so
-
To determine which authentication methods are available, the
libpam
library opens thepam_sss
module and sends anSSS_PAM_PREAUTH
request to thesssd_pam
PAM responder of the SSSD service. -
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. -
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. Thesssd_pam
responder also performs a search for the groups that the user belongs to, since group membership might affect access control. -
The
sssd_pam
responder sends anSSS_PAM_PREAUTH
request to thesssd_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. -
The
sssd_be
responder spawns a temporarykrb5_child
process. -
The
krb5_child
process contacts the KDC on the IdM server and checks for available authentication methods. The KDC responds to the request:
-
The
krb5_child
process evaluates the reply and sends the results back to thesssd_be
backend process. -
The
sssd_be
backend process receives the result. -
The
sssd_pam
responder receives the result. -
The
pam_sss
module receives the result.
-
The
-
If password authentication is configured for the user, the
pam_sss
module prompts the user for their password. If smart card authentication is configured, thepam_sss
module prompts the user for their smart card PIN. The module sends an
SSS_PAM_AUTHENTICATE
request with the user name and password, which travels to:-
The
sssd_pam
responder. -
The
sssd_be
back-end process.
-
The
-
The
sssd_be
process spawns a temporarykrb5_child
process to contact the KDC. -
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. -
The
krb5_child
process receives the result of the authentication attempt. The
krb5_child
process:- Stores the TGT in a credential cache.
-
Returns the authentication result to the
sssd_be
back-end process.
The authentication result travels from the
sssd_be
process to:-
The
sssd_pam
responder. -
The
pam_sss
module.
-
The
-
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
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
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.
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.NoteBy 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.
-
Verify that the client can authenticate to the LDAP server and retrieve user information with
ldapsearch
commands.If your LDAP server is an IdM server, like
server.example.com
, retrieve a Kerberos ticket for the host and perform the database search authenticating with the host Kerberos principal:[user@client ~]$ kinit -k 'host/client.example.com@EXAMPLE.COM' [user@client ~]$ ldapsearch -LLL -Y GSSAPI -h server.example.com -b “dc=example,dc=com” uid=<user_name>
If your LDAP server is an Active Directory (AD) Domain Controller (DC), like
server.ad.example.com
, retrieve a Kerberos ticket for the host and perform the database search authenticating with the host Kerberos principal:[user@client ~]$ kinit -k 'CLIENT$@AD.EXAMPLE.COM' [user@client ~]$ ldapsearch -LLL -Y GSSAPI -h server.ad.example.com -b “dc=example,dc=com” sAMAccountname=<user_name>
If your LDAP server is a plain LDAP server, and you have set the
ldap_default_bind_dn
andldap_default_authtok
options in thesssd.conf
file, authenticate as the sameldap_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.
Since the SSSD service uses Kerberos encryption, verify you can obtain a Kerberos ticket as the user that is unable to log in.
If your LDAP server is an IdM server:
[user@client ~]$ kinit <user_name>
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.
Verify you can retrieve user information about the command line.
[user@client ~]$ getent passwd <user_name> [user@client ~]$ id <user_name>
If this step fails, verify that the SSSD service on the client can receive information from the user database:
-
Review errors in the
/var/log/messages
log file. - Enable detailed logging in the SSSD service, collect debugging logs, and review the logs for indications to the source of the issue.
- (Optional) Open a Red Hat Technical Support case and provide the troubleshooting information you have gathered.
-
Review errors in the
If you are allowed to run
sudo
on the host, use thesssctl
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:
-
Ensure that the user’s UID is equal to or higher than
UID_MIN
, which is defined in the/etc/login.defs
file. -
Review authorization errors in the
/var/log/secure
and/var/log/messages
log files. - Enable detailed logging in the SSSD service, collect debugging logs, and review the logs for indications to the source of the issue.
- (Optional) Open a Red Hat Technical Support case and provide the troubleshooting information you have gathered.
-
Ensure that the user’s UID is equal to or higher than
Additional resources
- Enabling detailed logging for SSSD in the sssd.conf file
- Enabling detailed logging for SSSD with the sssctl command
- Gathering debugging logs from the SSSD service to troubleshoot authentication issues with an IdM server
- Gathering debugging logs from the SSSD service to troubleshoot authentication issues with an IdM client
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 namedexample.com
, the SSSD service logs its information in a file namedsssd_example.com.log
. If a host is directly integrated with an AD domain namedad.example.com
, information is logged to a file namedsssd_ad.example.com.log
.NoteIf 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
Level | Description |
---|---|
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
-
Open the
/etc/sssd/sssd.conf
file in a text editor. 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
-
Save and close the
sssd.conf
file. 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
Enable detailed SSSD debug logging on the IdM server.
[root@server ~]# sssctl debug-level 6
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
Minimize the troubleshooting dataset by removing older SSSD logs.
[root@server ~]# sssctl logs-remove
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
(Optional) Lower the debug level if you do not wish to continue gathering detailed SSSD logs.
[root@server ~]# sssctl debug-level 2
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 thecn=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
If you are unable to determine the cause of the authentication issue:
Collect the SSSD logs you recently generated.
[root@server ~]# sssctl logs-fetch sssd-logs-Mar29.tar
Open a Red Hat Technical Support case and provide:
-
The SSSD logs:
sssd-logs-Mar29.tar
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
-
The SSSD logs:
8.9. Gathering debugging logs from the SSSD service to troubleshoot authentication issues with an IdM client
If you experience issues when attempting to authenticate as an IdM user to an IdM client, verify that you can retrieve user information about the IdM server. If you cannot retrieve the user information about an IdM server, you will not be able to retrieve it on an IdM client (which retrieves information from the IdM server).
After you have confirmed that authentication issues do not originate from the IdM server, gather SSSD debugging logs from both the IdM server and IdM client.
Prerequisites
- The user only has authentication issues on IdM clients, not IdM servers.
-
You need the root password to run the
sssctl
command and restart the SSSD service.
Procedure
-
On the client: Open the
/etc/sssd/sssd.conf
file in a text editor. 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 ...
-
On the client: Save and close the
sssd.conf
file. On the client: Restart the SSSD service to load the configuration changes.
[root@client ~]# systemctl restart sssd
On the server and client: Enable detailed SSSD debug logging.
[root@server ~]# sssctl debug-level 6
[root@client ~]# sssctl debug-level 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
On the server and client: Minimize the troubleshooting dataset by removing older SSSD logs.
[root@server ~]# sssctl logs-remove
[root@server ~]# sssctl logs-remove
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
(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
On the server and client: Review SSSD logs for information about the failed request.
- Review the request from the client in the client logs.
- Review the request from the client in the server logs.
- Review the result of the request in the server logs.
- Review the outcome of the client receiving the results of the request from the server.
If you are unable to determine the cause of the authentication issue:
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
Open a Red Hat Technical Support case and provide:
The SSSD debug logs:
-
sssd-logs-server-Mar29.tar
from the server -
sssd-logs-client-Mar29.tar
from the client
-
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
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
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
andRID#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.
Requests returned from the SSSD memory cache are not logged and cannot be tracked by the log analyzer tool.
Additional resources
-
sudo sssctl analyze request --help
-
sudo sssctl analyze --help
-
sssd.conf
man page -
sssctl
man page
8.11.2. Running the log analyzer tool
Follow this procedure to use the log analyzer tool to track client requests in SSSD.
Prerequisites
-
You must set
debug_level
to at least 7 in the [$responder] section, and [domain/$domain] section of the/etc/sssd/sssd.conf
file to enable log parsing functionality. -
Logs to analyze must be from a compatible version of SSSD built with
libtevent
chain ID support, that is SSSD in RHEL 8.5 and later.
Procedure
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.
NoteIf analyzing PAM requests, run the
sssctl analyze request list
command with the--pam
option.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
If required, you can run the log analyzer tool against log files, for example:
# sssctl analyze request --logdir=/tmp/var/log/sssd
Additional resources
-
sssctl analyze request list --help
-
sssctl analyze request show --help
-
sssctl
man page.
8.12. Additional resources
Chapter 9. Preparing your environment for managing IdM using Ansible playbooks
As a system administrator managing Identity Management (IdM), when working with Red Hat Ansible Engine, it is good practice to do the following:
- 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.
Using this practice, you can find all your playbooks in one place.
You can run your ansible-freeipa
playbooks without invoking root
privileges on the managed nodes. Exceptions include playbooks that use the ipaserver
, ipareplica
, ipaclient
, ipasmartcard_server
, ipasmartcard_client
and ipabackup
ansible-freeipa
roles. These roles require privileged access to directories and the dnf
software package manager.
The playbooks in the Red Hat Enterprise Linux IdM documentation assume the following security configuration:
-
The IdM
admin
is your remote Ansible user on the managed nodes. -
You store the IdM
admin
password encrypted in an Ansible vault. - You have placed the password that protects the Ansible vault in a password file.
- You block access to the vault password file to everyone except your local ansible user.
- You regularly remove and re-create the vault password file.
Consider also alternative security configurations.
9.1. Preparing a control node and managed nodes for managing IdM using Ansible playbooks
Follow this procedure to create the ~/MyPlaybooks directory and configure it so that you can use it to store and run Ansible playbooks.
Prerequisites
- You have installed an IdM server on your managed nodes, server.idm.example.com and replica.idm.example.com.
- You have configured DNS and networking so you can log in to the managed nodes, server.idm.example.com and replica.idm.example.com, directly from the control node.
-
You know the IdM
admin
password.
Procedure
Create a directory for your Ansible configuration and playbooks in your home directory:
$ mkdir ~/MyPlaybooks/
Change into the ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks
Create the ~/MyPlaybooks/ansible.cfg file with the following content:
[defaults] inventory = /home/your_username/MyPlaybooks/inventory remote_user = admin
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.
[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
Copy the SSH public key to the IdM
admin
account on each managed node:$ ssh-copy-id admin@server.idm.example.com $ ssh-copy-id admin@replica.idm.example.com
These commands require that you enter the IdM
admin
password.Create a password_file file that contains the vault password:
redhat
Change the permissions to modify the file:
$ chmod 0600 password_file
Create a secret.yml Ansible vault to store the IdM
admin
password:Configure password_file to store the vault password:
$ ansible-vault create --vault-password-file=password_file secret.yml
When prompted, enter the content of the secret.yml file:
ipaadmin_password: Secret123
To use the encrypted ipaadmin_password
in a playbook, you must use the vars_file
directive. For example, a simple playbook to delete an IdM user can look as follows:
--- - name: Playbook to handle users hosts: ipaserver vars_files: - /home/user_name/MyPlaybooks/secret.yml tasks: - name: Delete user robot ipauser: ipaadmin_password: "{{ ipaadmin_password }}" name: robot state: absent
When executing a playbook, instruct Ansible use the vault password to decrypt ipaadmin_password
by adding the --vault-password-file=password_file
option. For example:
ansible-playbook -i inventory --vault-password-file=password_file del-user.yml
For security reasons, remove the vault password file at the end of each session, and repeat steps 7-9 at the start of each new session.
9.2. Different methods to provide the credentials required for ansible-freeipa playbooks
There are advantages and disadvantages in the different methods for providing the credentials required for running playbooks that use ansible-freeipa
roles and modules.
Storing passwords in plain text in a playbook
Benefits:
- Not being prompted all the time you run the playbook.
- Easy to implement.
Drawbacks:
- Everyone with access to the file can read the password. Setting wrong permissions and sharing the file, for example in an internal or external repository, can compromise security.
- High maintenance work: if the password is changed, it needs to be changed in all playbooks.
Entering passwords interactively when you execute a playbook
Benefits:
- No-one can steal the password as it is not stored anywhere.
- You can update the password easily.
- Easy to implement.
Drawbacks:
- If you are using Ansible playbooks in scripts, the requirement to enter the password interactively can be inconvenient.
Storing passwords in an Ansible vault and the vault password in a file:
Benefits:
- The user password is stored encrypted.
- You can update the user password easily, by creating a new Ansible vault.
-
You can update the password file that protects the ansible vault easily, by using the
ansible-vault rekey --new-vault-password-file=NEW_VAULT_PASSWORD_FILE secret.yml
command. - If you are using Ansible playbooks in scripts, it is convenient not to have to enter the password protecting the Ansible vault interactively.
Drawbacks:
- It is vital that the file that contains the sensitive plain text password be protected through file permissions and other security measures.
Storing passwords in an Ansible vault and entering the vault password interactively
Benefits:
- The user password is stored encrypted.
- No-one can steal the vault password as it is not stored anywhere.
- You can update the user password easily, by creating a new Ansible vault.
-
You can update the vault password easily too, by using the
ansible-vault rekey file_name
command.
Drawbacks:
- If you are using Ansible playbooks in scripts, the need to enter the vault password interactively can be inconvenient.
Chapter 10. Configuring global IdM settings using Ansible playbooks
Using the Ansible config
module, you can retrieve and set global configuration parameters for Identity Management (IdM).
- Retrieving IdM configuration using an Ansible playbook
- Configuring the IdM CA renewal server using an Ansible playbook
- Configuring the default shell for IdM users using an Ansible playbook
- Configuring a NETBIOS name for an IdM domain by using Ansible
- Ensuring that IdM users and groups have SIDs by using Ansible
10.1. Retrieving IdM configuration using an Ansible playbook
The following procedure describes how you can use an Ansible playbook to retrieve information about the current global IdM configuration.
Prerequisites
- You know the IdM administrator password.
You have configured your Ansible control node to meet the following requirements:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package on the Ansible controller. - The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
-
The example assumes that the secret.yml Ansible vault stores your
ipaadmin_password
.
Procedure
Open the
/usr/share/doc/ansible-freeipa/playbooks/config/retrieve-config.yml
Ansible playbook file for editing:--- - name: Playbook to handle global IdM configuration hosts: ipaserver become: no gather_facts: no vars_files: - /home/user_name/MyPlaybooks/secret.yml tasks: - name: Query IPA global configuration ipaconfig: ipaadmin_password: "{{ ipaadmin_password }}" register: serverconfig - debug: msg: "{{ serverconfig }}"
Adapt the file by changing the following:
- The password of IdM administrator.
- Other values, if necessary.
- Save the file.
Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:
$ ansible-playbook --vault-password-file=password_file -v -i path_to_inventory_directory/inventory.file /usr/share/doc/ansible-freeipa/playbooks/config/retrieve-config.yml [...] TASK [debug] ok: [server.idm.example.com] => { "msg": { "ansible_facts": { "discovered_interpreter_ }, "changed": false, "config": { "ca_renewal_master_server": "server.idm.example.com", "configstring": [ "AllowNThash", "KDC:Disable Last Success" ], "defaultgroup": "ipausers", "defaultshell": "/bin/bash", "emaildomain": "idm.example.com", "enable_migration": false, "groupsearch": [ "cn", "description" ], "homedirectory": "/home", "maxhostname": "64", "maxusername": "64", "pac_type": [ "MS-PAC", "nfs:NONE" ], "pwdexpnotify": "4", "searchrecordslimit": "100", "searchtimelimit": "2", "selinuxusermapdefault": "unconfined_u:s0-s0:c0.c1023", "selinuxusermaporder": [ "guest_u:s0$xguest_u:s0$user_ ], "usersearch": [ "uid", "givenname", "sn", "telephonenumber", "ou", "title" ] }, "failed": false } }
10.2. Configuring the IdM CA renewal server using an Ansible playbook
In an Identity Management (IdM) deployment that uses an embedded certificate authority (CA), the CA renewal server maintains and renews IdM system certificates. It ensures robust IdM deployments.
For more details on the role of the IdM CA renewal server, see Using IdM CA renewal server.
The following procedure describes how you can use an Ansible playbook to configure the IdM CA renewal server.
Prerequisites
- You know the IdM administrator password.
You have configured your Ansible control node to meet the following requirements:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package on the Ansible controller. - The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
-
The example assumes that the secret.yml Ansible vault stores your
ipaadmin_password
.
Procedure
Optional: Identify the current IdM CA renewal server:
$ ipa config-show | grep 'CA renewal' IPA CA renewal master: server.idm.example.com
Create an inventory file, for example
inventory.file
, and defineipaserver
in it:[ipaserver] server.idm.example.com
Open the
/usr/share/doc/ansible-freeipa/playbooks/config/set-ca-renewal-master-server.yml
Ansible playbook file for editing:--- - name: Playbook to handle global DNS configuration hosts: ipaserver become: no gather_facts: no vars_files: - /home/user_name/MyPlaybooks/secret.yml tasks: - name: set ca_renewal_master_server ipaconfig: ipaadmin_password: "{{ ipaadmin_password }}" ca_renewal_master_server: carenewal.idm.example.com
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.
-
The password of IdM administrator set by the
- Save the file.
Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:
$ ansible-playbook --vault-password-file=password_file -v -i path_to_inventory_directory/inventory.file /usr/share/doc/ansible-freeipa/playbooks/config/set-ca-renewal-master-server.yml
Verification steps
You can verify that the CA renewal server has been changed:
Log into
ipaserver
as IdM administrator:$ ssh admin@server.idm.example.com Password: [admin@server /]$
Request the identity of the IdM CA renewal server:
$ ipa config-show | grep ‘CA renewal’ IPA CA renewal master: carenewal.idm.example.com
The output shows the carenewal.idm.example.com server is the new CA renewal server.
10.3. Configuring the default shell for IdM users using an Ansible playbook
The shell is a program that accepts and interprets commands. Several shells are available in Red Hat Enterprise Linux (RHEL), such as bash
, sh
, ksh
, zsh
, fish
, and others. Bash
, or /bin/bash
, is a popular shell on most Linux systems, and it is normally the default shell for user accounts on RHEL.
The following procedure describes how you can use an Ansible playbook to configure sh
, an alternative shell, as the default shell for IdM users.
Prerequisites
- You know the IdM administrator password.
You have configured your Ansible control node to meet the following requirements:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package on the Ansible controller. - The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
-
The example assumes that the secret.yml Ansible vault stores your
ipaadmin_password
.
Procedure
-
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. Create an inventory file, for example
inventory.file
, and defineipaserver
in it:[ipaserver] server.idm.example.com
Open the
/usr/share/doc/ansible-freeipa/playbooks/config/ensure-config-options-are-set.yml
Ansible playbook file for editing:--- - name: Playbook to ensure some config options are set hosts: ipaserver vars_files: - /home/user_name/MyPlaybooks/secret.yml tasks: # Set defaultlogin and maxusername - ipaconfig: ipaadmin_password: "{{ ipaadmin_password }}" defaultshell: /bin/bash maxusername: 64
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
.
-
The password of IdM administrator set by the
- Save the file.
Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:
$ ansible-playbook --vault-password-file=password_file -v -i path_to_inventory_directory/inventory.file /usr/share/doc/ansible-freeipa/playbooks/config/ensure-config-options-are-set.yml
Verification steps
You can verify that the default user shell has been changed by starting a new session in IdM:
Log into
ipaserver
as IdM administrator:$ ssh admin@server.idm.example.com Password: [admin@server /]$
Display the current shell:
[admin@server /]$ echo "$SHELL" /bin/sh
The logged-in user is using the
sh
shell.
10.4. Configuring a NetBIOS name for an IdM domain by using Ansible
The NetBIOS name is used for Microsoft Windows' (SMB) type of sharing and messaging. You can use NetBIOS names to map a drive or connect to a printer.
Follow this procedure to use an Ansible playbook to configure a NetBIOS name for your Identity Management (IdM) domain.
Prerequisites
You have configured your Ansible control node to meet the following requirements:
- You are using Ansible version 2.14 or later.
-
The
ansible-freeipa
package is installed.
Assumptions
- The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
-
The example assumes that the secret.yml Ansible vault stores your
ipaadmin_password
and that you know the vault file password.
Procedure
Navigate to your ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
- Create a netbios-domain-name-present.yml Ansible playbook file.
Add the following content to the file:
--- - name: Playbook to change IdM domain netbios name hosts: ipaserver become: no gather_facts: no vars_files: - /home/user_name/MyPlaybooks/secret.yml tasks: - name: Set IdM domain netbios name ipaconfig: ipaadmin_password: "{{ ipaadmin_password }}" netbios_name: IPADOM
- Save the file.
Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:
$ ansible-playbook --vault-password-file=password_file -v -i inventory netbios-domain-name-present.yml
When prompted, provide the vault file password.
Additional resources
10.5. Ensuring that IdM users and groups have SIDs by using Ansible
The Identity Management (IdM) server can assign unique security identifiers (SIDs) to IdM users and groups internally, based on the data from the ID ranges of the local domain. The SIDs are stored in the user and group objects.
The goal of ensuring that IdM users and groups have SIDs is to allow the generation of the Privileged Attribute Certificate (PAC), which is the first step towards IdM-IdM trusts. If IdM users and groups have SIDs, IdM is able to issue Kerberos tickets with PAC data.
Follow this procedure to achieve the following goals:
- Generate SIDs for already existing IdM users and user groups.
- Enable the generation of SIDs for IdM new users and groups.
Prerequisites
You have configured your Ansible control node to meet the following requirements:
- You are using Ansible version 2.14 or later.
-
The
ansible-freeipa
package is installed.
Assumptions
- The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
-
The example assumes that the secret.yml Ansible vault stores your
ipaadmin_password
and that you know the vault file password.
Procedure
Navigate to your ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
- Create a sids-for-users-and-groups-present.yml Ansible playbook file.
Add the following content to the file:
--- - name: Playbook to ensure SIDs are enabled and users and groups have SIDs hosts: ipaserver become: no gather_facts: no vars_files: - /home/user_name/MyPlaybooks/secret.yml tasks: - name: Enable SID and generate users and groups SIDS ipaconfig: ipaadmin_password: "{{ ipaadmin_password }}" enable_sid: true add_sids: true
The
enable_sid
variable enables SID generation for future IdM users and groups. Theadd_sids
variable generates SIDs for existing IdM users and groups.NoteWhen using
add_sids: true
, you must also set theenable_sid
variable totrue
.- Save the file.
Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:
$ ansible-playbook --vault-password-file=password_file -v -i inventory sids-for-users-and-groups-present.yml
When prompted, provide the vault file password.
Additional resources
10.6. Additional resources
-
See
README-config.md
in the/usr/share/doc/ansible-freeipa/
directory. -
See sample playbooks in the
/usr/share/doc/ansible-freeipa/playbooks/config
directory.
Chapter 11. Managing user accounts using the command line
There are several stages in the user life cycle in IdM (Identity Management), including the following:
- Create user accounts
- Activate stage user accounts
- Preserve user accounts
- Delete active, stage, or preserved user accounts
- Restore preserved user accounts
11.1. User life cycle
Identity Management (IdM) supports three user account states:
- Stage users are not allowed to authenticate. This is an initial state. Some of the user account properties required for active users cannot be set, for example, group membership.
- Active users are allowed to authenticate. All required user account properties must be set in this state.
- Preserved users are former active users that are considered inactive and cannot authenticate to IdM. Preserved users retain most of the account properties they had as active users, but they are not part of any user groups.
You can delete user entries permanently from the IdM database.
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.
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.
Do not add local users to IdM. The Name Service Switch (NSS) always resolves IdM users and groups before resolving local users and groups. This means that, for example, IdM group membership does not work for local users.
11.2. Adding users using the command line
You can add user as:
- Active — user accounts which can be actively used by their users.
- Stage — users cannot use these accounts. Use it if you want to prepare new user accounts. When users are ready to use their accounts, then you can activate them.
The following procedure describes adding active users to the IdM server with the ipa user-add
command.
Similarly, you can create stage user accounts with the ipa stageuser-add
command.
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
- Administrator privileges for managing IdM or User Administrator role.
- Obtained a Kerberos ticket. For details, see Using kinit to log in to IdM manually.
Procedure
- Open terminal and connect to the IdM server.
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_.$-]?
NoteUser names ending with the trailing dollar sign ($) are supported to enable Samba 3.x machine support.
If you add a user name containing uppercase characters, IdM automatically converts the name to lowercase when saving it. Therefore, IdM always requires to enter user names in lowercase when logging in. Additionally, it is not possible to add user names which differ only in letter casing, such as user and User.
The default maximum length for user names is 32 characters. To change it, use the
ipa config-mod --maxusername
command. For example, to increase the maximum user name length to 64 characters:$ ipa config-mod --maxusername=64 Maximum username length: 64 ...
The
ipa user-add
command includes a lot of parameters. To list them all, use the ipa help command:$ ipa help user-add
For details about
ipa help
command, see What is the IPA help.
You can verify if the new user account is successfully created by listing all IdM user accounts:
$ ipa user-find
This command lists all user accounts with details.
11.3. Activating users using the command line
To activate a user account by moving it from stage to active, use the ipa stageuser-activate
command.
Prerequisites
- Administrator privileges for managing IdM or User Administrator role.
- Obtained a Kerberos ticket. For details, see Using kinit to log in to IdM manually.
Procedure
- Open terminal and connect to the IdM server.
Activate the user account with the following command:
$ ipa stageuser-activate user_login ------------------------- Stage user user_login activated ------------------------- ...
You can verify if the new user account is successfully created by listing all IdM user accounts:
$ ipa user-find
This command lists all user accounts with details.
11.4. Preserving users using the command line
You can preserve a user account if you want to remove it, but keep the option to restore it later. To preserve a user account, use the --preserve
option with the ipa user-del
or ipa stageuser-del
commands.
Prerequisites
- Administrator privileges for managing IdM or User Administrator role.
- Obtained a Kerberos ticket. For details, see Using kinit to log in to IdM manually.
Procedure
- Open terminal and connect to the IdM server.
Preserve the user account with the following command:
$ ipa user-del --preserve user_login -------------------- Deleted user "user_login" --------------------
NoteDespite the output saying the user account was deleted, it has been preserved.
11.5. Deleting users using the command line
IdM (Identity Management) enables you to delete users permanently. You can delete:
-
Active users with the following command:
ipa user-del
-
Stage users with the following command:
ipa stageuser-del
-
Preserved users with the following command:
ipa user-del
When deleting multiple users, use the --continue
option to force the command to continue regardless of errors. A summary of the successful and failed operations is printed to the stdout
standard output stream when the command completes.
$ ipa user-del --continue user1 user2 user3
If you do not use --continue
, the command proceeds with deleting users until it encounters an error, after which it stops and exits.
Prerequisites
- Administrator privileges for managing IdM or User Administrator role.
- Obtained a Kerberos ticket. For details, see Using kinit to log in to IdM manually.
Procedure
- Open terminal and connect to the IdM server.
Delete the user account with the following command:
$ ipa user-del user_login -------------------- Deleted user "user_login" --------------------
The user account has been permanently deleted from IdM.
11.6. Restoring users using the command line
You can restore a preserved users to:
-
Active users:
ipa user-undel
-
Stage users:
ipa user-stage
Restoring a user account does not restore all of the account’s previous attributes. For example, the user’s password is not restored and must be set again.
Prerequisites
- Administrator privileges for managing IdM or User Administrator role.
- Obtained a Kerberos ticket. For details, see Using kinit to log in to IdM manually.
Procedure
- Open terminal and connect to the IdM server.
Activate the user account with the following command:
$ ipa user-undel user_login ------------------------------ Undeleted user account "user_login" ------------------------------
Alternatively, you can restore user accounts as staged:
$ ipa user-stage user_login ------------------------------ Staged user account "user_login" ------------------------------
Verification steps
You can verify if the new user account is successfully created by listing all IdM user accounts:
$ ipa user-find
This command lists all user accounts with details.
Chapter 12. Managing user accounts using the IdM Web UI
Identity Management (IdM) provides several stages that can help you to manage various user life cycle situations:
- Creating a user account
Creating a stage user account before an employee starts their career in your company and be prepared in advance for the day when the employee appears in the office and want to activate the account.
You can omit this step and create the active user account directly. The procedure is similar to creating a stage user account.
- Activating a user account
- Activating the account the first working day of the employee.
- Disabling a user account
- If the user go to a parental leave for couple of months, you will need to disable the account temporarily.
- Enabling a user account
- When the user returns, you will need to re-enable the account.
- Preserving a user account
- If the user wants to leave the company, you will need to delete the account with a possibility to restore it because people can return to the company after some time.
- Restoring a user account
- Two years later, the user is back and you need to restore the preserved account.
- Deleting a user account
- If the employee is dismissed, delete the account without a backup.
12.1. User life cycle
Identity Management (IdM) supports three user account states:
- Stage users are not allowed to authenticate. This is an initial state. Some of the user account properties required for active users cannot be set, for example, group membership.
- Active users are allowed to authenticate. All required user account properties must be set in this state.
- Preserved users are former active users that are considered inactive and cannot authenticate to IdM. Preserved users retain most of the account properties they had as active users, but they are not part of any user groups.
You can delete user entries permanently from the IdM database.
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.
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.
Do not add local users to IdM. The Name Service Switch (NSS) always resolves IdM users and groups before resolving local users and groups. This means that, for example, IdM group membership does not work for local users.
12.2. Adding users in the Web UI
Usually, you need to create a new user account before a new employee starts to work. Such a stage account is not accessible and you need to activate it later.
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
Log in to the IdM Web UI.
For details, see Accessing the IdM Web UI in a web browser.
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.
- Click the + Add icon.
- In the Add stage user dialog box, enter First name and Last name of the new user.
[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.
- [Optional] In the GID drop down menu, select groups in which the user should be included.
- [Optional] In the Password and Verify password fields, enter your password and confirm it, ensuring they both match.
Click on the Add button.
At this point, you can see the user account in the Stage Users table.
If you click on the user name, you can edit advanced settings, such as adding a phone number, address, or occupation.
12.3. Activating stage users in the IdM Web UI
You must follow this procedure to activate a stage user account, before the user can log in to IdM and before the user can be added to an IdM group.
Prerequisites
- Administrator privileges for managing the IdM Web UI or User Administrator role.
- At least one staged user account in IdM.
Procedure
Log in to the IdM Web UI.
For details, see Accessing the IdM Web UI in a web browser.
- Go to Users → Stage users tab.
- Click the check-box of the user account you want to activate.
Click on the Activate button.
- On the Confirmation dialog box, click OK.
If the activation is successful, the IdM Web UI displays a green confirmation that the user has been activated and the user account has been moved to Active users. The account is active and the user can authenticate to the IdM domain and IdM Web UI. The user is prompted to change their password on the first login.
At this stage, you can add the active user account to user groups.
12.4. Disabling user accounts in the Web UI
You can disable active user accounts. Disabling a user account deactivates the account, therefore, user accounts cannot be used to authenticate and using IdM services, such as Kerberos, or perform any tasks.
Disabled user accounts still exist within IdM and all of the associated information remains unchanged. Unlike preserved user accounts, disabled user accounts remain in the active state and can be a member of user groups.
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
Log in to the IdM Web UI.
For details, see Accessing the IdM Web UI in a web browser.
- Go to Users → Active users tab.
- Click the check-box of the user accounts you want to disable.
Click on the Disable button.
- 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.
12.5. Enabling user accounts in the Web UI
With IdM you can enable disabled active user accounts. Enabling a user account activates the disabled account.
Prerequisites
- Administrator privileges for managing the IdM Web UI or User Administrator role.
Procedure
- Log in to the IdM Web UI.
- Go to Users → Active users tab.
- Click the check-box of the user accounts you want to enable.
Click on the Enable button.
- In the Confirmation dialog box, click on the OK button.
If the change has been successful, you can verify in the Status column in the Active users table.
12.6. Preserving active users in the IdM Web UI
Preserving user accounts enables you to remove accounts from the Active users tab, yet keeping these accounts in IdM.
Preserve the user account if the employee leaves the company. If you want to disable user accounts for a couple of weeks or months (parental leave, for example), disable the account. For details, see Disabling user accounts in the Web UI. The preserved accounts are not active and users cannot use them to access your internal network, however, the account stays in the database with all the data.
You can move the restored accounts back to the active mode.
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
Log in to the IdM Web UI.
For details, see Accessing the IdM Web UI in a web browser.
- Go to Users → Active users tab.
- Click the check-box of the user accounts you want to preserve.
Click on the Delete button.
- In the Remove users dialog box, switch the Delete mode radio button to preserve.
Click on the Delete button.
As a result, the user account is moved to Preserved users.
If you need to restore preserved users, see the Restoring users in the IdM Web UI.
12.7. Restoring users in the IdM Web UI
IdM (Identity Management) enables you to restore preserved user accounts back to the active state. You can restore a preserved user to an active user or a stage user.
Prerequisites
- Administrator privileges for managing the IdM Web UI or User Administrator role.
Procedure
Log in to the IdM Web UI.
For details, see Accessing the IdM Web UI in a web browser.
- Go to Users → Preserved users tab.
- Click the check-box at the user accounts you want to restore.
Click on the Restore button.
- In the Confirmation dialog box, click on the OK button.
The IdM Web UI displays a green confirmation and moves the user accounts to the Active users tab.
12.8. Deleting users in the IdM Web UI
Deleting users is an irreversible operation, causing the user accounts to be permanently deleted from the IdM database, including group memberships and passwords. Any external configuration for the user, such as the system account and home directory, is not deleted, but is no longer accessible through IdM.
You can delete:
Active users — the IdM Web UI offers you with the options:
Preserving users temporarily
For details, see the Preserving active users in the IdM Web UI.
- Deleting them permanently
- 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
Log in to the IdM Web UI.
For details, see Accessing the IdM Web UI in a web browser.
Go to Users → Active users tab.
Alternatively, you can delete the user account in the Users → Stage users or Users → Preserved users.
- Click the Delete icon.
- In the Remove users dialog box, switch the Delete mode radio button to delete.
- Click on the Delete button.
The users accounts have been permanently deleted from IdM.
Chapter 13. Managing user accounts using Ansible playbooks
You can manage users in IdM using Ansible playbooks. After presenting the user life cycle, this chapter describes how to use Ansible playbooks for the following operations:
-
Ensuring the presence of a single user listed directly in the
YML
file. -
Ensuring the presence of multiple users listed directly in the
YML
file. -
Ensuring the presence of multiple users listed in a
JSON
file that is referenced from theYML
file. -
Ensuring the absence of users listed directly in the
YML
file.
13.1. User life cycle
Identity Management (IdM) supports three user account states:
- Stage users are not allowed to authenticate. This is an initial state. Some of the user account properties required for active users cannot be set, for example, group membership.
- Active users are allowed to authenticate. All required user account properties must be set in this state.
- Preserved users are former active users that are considered inactive and cannot authenticate to IdM. Preserved users retain most of the account properties they had as active users, but they are not part of any user groups.
You can delete user entries permanently from the IdM database.
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.
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.
Do not add local users to IdM. The Name Service Switch (NSS) always resolves IdM users and groups before resolving local users and groups. This means that, for example, IdM group membership does not work for local users.
13.2. Ensuring the presence of an IdM user using an Ansible playbook
The following procedure describes ensuring the presence of a user in IdM using an Ansible playbook.
Prerequisites
-
You know the IdM
admin
password. You have configured your Ansible control node to meet the following requirements:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package on the Ansible controller. - The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
-
The example assumes that the secret.yml Ansible vault stores your
ipaadmin_password
.
Procedure
Create an inventory file, for example
inventory.file
, and defineipaserver
in it:[ipaserver] server.idm.example.com
Create an Ansible playbook file with the data of the user whose presence in IdM you want to ensure. To simplify this step, you can copy and modify the example in the
/usr/share/doc/ansible-freeipa/playbooks/user/add-user.yml
file. For example, to create user named idm_user and add Password123 as the user password:--- - name: Playbook to handle users hosts: ipaserver vars_files: - /home/user_name/MyPlaybooks/secret.yml tasks: - name: Create user idm_user ipauser: ipaadmin_password: "{{ ipaadmin_password }}" name: idm_user first: Alice last: Acme uid: 1000111 gid: 10011 phone: "+555123457" email: idm_user@acme.com passwordexpiration: "2023-01-19 23:59:59" password: "Password123" update_password: on_create
You must use the following options to add a user:
- name: the login name
- first: the first name string
- last: the last name string
For the full list of available user options, see the
/usr/share/doc/ansible-freeipa/README-user.md
Markdown file.NoteIf 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.Run the playbook:
$ ansible-playbook --vault-password-file=password_file -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/add-IdM-user.yml
Verification steps
You can verify if the new user account exists in IdM by using the
ipa user-show
command:Log into
ipaserver
as admin:$ ssh admin@server.idm.example.com Password: [admin@server /]$
Request a Kerberos ticket for admin:
$ kinit admin Password for admin@IDM.EXAMPLE.COM:
Request information about idm_user:
$ ipa user-show idm_user User login: idm_user First name: Alice Last name: Acme ....
The user named idm_user is present in IdM.
13.3. Ensuring the presence of multiple IdM users using Ansible playbooks
The following procedure describes ensuring the presence of multiple users in IdM using an Ansible playbook.
Prerequisites
-
You know the IdM
admin
password. You have configured your Ansible control node to meet the following requirements:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package on the Ansible controller. - The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
-
The example assumes that the secret.yml Ansible vault stores your
ipaadmin_password
.
Procedure
Create an inventory file, for example
inventory.file
, and defineipaserver
in it:[ipaserver] server.idm.example.com
Create an Ansible playbook file with the data of the users whose presence you want to ensure in IdM. To simplify this step, you can copy and modify the example in the
/usr/share/doc/ansible-freeipa/playbooks/user/ensure-users-present.yml
file. For example, to create users idm_user_1, idm_user_2, and idm_user_3, and add Password123 as the password of idm_user_1:--- - name: Playbook to handle users hosts: ipaserver vars_files: - /home/user_name/MyPlaybooks/secret.yml tasks: - name: Create user idm_users ipauser: ipaadmin_password: "{{ ipaadmin_password }}" users: - name: idm_user_1 first: Alice last: Acme uid: 10001 gid: 10011 phone: "+555123457" email: idm_user@acme.com passwordexpiration: "2023-01-19 23:59:59" password: "Password123" - name: idm_user_2 first: Bob last: Acme uid: 100011 gid: 10011 - name: idm_user_3 first: Eve last: Acme uid: 1000111 gid: 10011
NoteIf 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.
Run the playbook:
$ ansible-playbook --vault-password-file=password_file -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/add-users.yml
Verification steps
You can verify if the user account exists in IdM by using the
ipa user-show
command:Log into
ipaserver
as administrator:$ ssh administrator@server.idm.example.com Password: [admin@server /]$
Display information about idm_user_1:
$ ipa user-show idm_user_1 User login: idm_user_1 First name: Alice Last name: Acme Password: True ....
The user named idm_user_1 is present in IdM.
13.4. Ensuring the presence of multiple IdM users from a JSON file using Ansible playbooks
The following procedure describes how you can ensure the presence of multiple users in IdM using an Ansible playbook. The users are stored in a JSON
file.
Prerequisites
-
You know the IdM
admin
password. You have configured your Ansible control node to meet the following requirements:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package on the Ansible controller. - The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
-
The example assumes that the secret.yml Ansible vault stores your
ipaadmin_password
.
Procedure
Create an inventory file, for example
inventory.file
, and defineipaserver
in it:[ipaserver] server.idm.example.com
Create an Ansible playbook file with the necessary tasks. Reference the
JSON
file with the data of the users whose presence you want to ensure. To simplify this step, you can copy and modify the example in the/usr/share/doc/ansible-freeipa/ensure-users-present-ymlfile.yml
file:--- - name: Ensure users' presence hosts: ipaserver vars_files: - /home/user_name/MyPlaybooks/secret.yml tasks: - name: Include users.json include_vars: file: users.json - name: Users present ipauser: ipaadmin_password: "{{ ipaadmin_password }}" users: "{{ users }}"
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" } ] }
Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:
$ ansible-playbook --vault-password-file=password_file -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-users-present-jsonfile.yml
Verification steps
You can verify if the user accounts are present in IdM using the
ipa user-show
command:Log into
ipaserver
as administrator:$ ssh administrator@server.idm.example.com Password: [admin@server /]$
Display information about idm_user_1:
$ ipa user-show idm_user_1 User login: idm_user_1 First name: Alice Last name: Acme Password: True ....
The user named idm_user_1 is present in IdM.
13.5. Ensuring the absence of users using Ansible playbooks
The following procedure describes how you can use an Ansible playbook to ensure that specific users are absent from IdM.
Prerequisites
-
You know the IdM
admin
password. You have configured your Ansible control node to meet the following requirements:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package on the Ansible controller. - The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
-
The example assumes that the secret.yml Ansible vault stores your
ipaadmin_password
.
Procedure
Create an inventory file, for example
inventory.file
, and defineipaserver
in it:[ipaserver] server.idm.example.com
Create an Ansible playbook file with the users whose absence from IdM you want to ensure. To simplify this step, you can copy and modify the example in the
/usr/share/doc/ansible-freeipa/playbooks/user/ensure-users-present.yml
file. For example, to delete users idm_user_1, idm_user_2, and idm_user_3:--- - name: Playbook to handle users hosts: ipaserver vars_files: - /home/user_name/MyPlaybooks/secret.yml tasks: - name: Delete users idm_user_1, idm_user_2, idm_user_3 ipauser: ipaadmin_password: "{{ ipaadmin_password }}" users: - name: idm_user_1 - name: idm_user_2 - name: idm_user_3 state: absent
Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:
$ ansible-playbook --vault-password-file=password_file -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/delete-users.yml
Verification steps
You can verify that the user accounts do not exist in IdM by using the ipa user-show
command:
Log into
ipaserver
as administrator:$ ssh administrator@server.idm.example.com Password: [admin@server /]$
Request information about idm_user_1:
$ ipa user-show idm_user_1 ipa: ERROR: idm_user_1: user not found
The user named idm_user_1 does not exist in IdM.
13.6. Additional resources
-
See the
README-user.md
Markdown file in the/usr/share/doc/ansible-freeipa/
directory. -
See sample Ansible playbooks in the
/usr/share/doc/ansible-freeipa/playbooks/user
directory.
Chapter 14. Managing user groups in IdM CLI
This chapter introduces user groups management using the IdM CLI.
A user group is a set of users with common privileges, password policies, and other characteristics.
A user group in Identity Management (IdM) can include:
- IdM users
- other IdM user groups
- external users, which are users that exist outside of IdM
14.1. The different group types in IdM
IdM supports the following types of groups:
- POSIX groups (the default)
POSIX groups support Linux POSIX attributes for their members. Note that groups that interact with Active Directory cannot use POSIX attributes.
POSIX attributes identify users as separate entities. Examples of POSIX attributes relevant to users include
uidNumber
, a user number (UID), andgidNumber
, 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 name | Default group members |
---|---|
| All IdM users |
|
Users with administrative privileges, including the default |
| This is a legacy group that no longer has any special privileges |
| 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.
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

If you set a password policy for user group A, the policy also applies to all users in user group B.
14.3. Adding a user group using IdM CLI
Follow this procedure to add a user group using the IdM CLI.
Prerequisites
- You must be logged in as the administrator. For details, see Using kinit to log in to IdM manually.
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 toipa group-add
:-
--nonposix
to create a non-POSIX group --external
to create an external groupFor details on group types, see The different group types in IdM.
You can specify a custom GID when adding a user group by using the
--gid=custom_GID
option. If you do this, be careful to avoid ID conflicts. If you do not specify a custom GID, IdM automatically assigns a GID from the available ID range.-
14.4. Searching for user groups using IdM CLI
Follow this procedure to search for existing user groups using the IdM CLI.
Procedure
Display all user groups by using the
ipa group-find
command. To specify a group type, add options toipa group-find
:-
Display all POSIX groups using the
ipa group-find --posix
command. -
Display all non-POSIX groups using the
ipa group-find --nonposix
command. Display all external groups using the
ipa group-find --external
command.For more information about different group types, see The different group types in IdM.
-
Display all POSIX groups using the
14.5. Deleting a user group using IdM CLI
Follow this procedure to delete a user group using IdM CLI. Note that deleting a group does not delete the group members from IdM.
Prerequisites
- You must be logged in as the administrator. For details, see Using kinit to log in to IdM manually.
Procedure
Delete a user group by using the
ipa group-del group_name
command. For example, to delete group_a:$ ipa group-del group_a -------------------------- Deleted group "group_a" --------------------------
14.6. Adding a member to a user group using IdM CLI
You can add both users and user groups as members of a user group. For more information, see The different group types in IdM and Direct and indirect group members. Follow this procedure to add a member to a user group by using the IdM CLI.
Prerequisites
- You must be logged in as the administrator. For details, see Using kinit to log in to IdM manually.
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 ofDOMAIN\user_name
oruser_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.
-
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.
After you add a member to a user group, the update may take some time to spread to all clients in your Identity Management environment. This is because when any given host resolves users, groups and netgroups, the System Security Services Daemon
(SSSD) first looks into its cache and performs server lookups only for missing or expired records.
14.7. Adding users without a user private group
By default, IdM creates user private groups (UPGs) whenever a new user is created in IdM. UPGs are a specific group type:
- The UPG has the same name as the newly created user.
- The user is the only member of the UPG. The UPG cannot contain any other members.
- The GID of the private group matches the UID of the user.
However, it is possible to add users without creating a UPG.
14.7.1. Users without a user private group
If a NIS group or another system group already uses the GID that would be assigned to a user private group, it is necessary to avoid creating a UPG.
You can do this in two ways:
- Add a new user without a UPG, without disabling private groups globally. See Adding a user without a user private group when private groups are globally enabled.
- Disable UPGs globally for all users, then add a new user. See Disabling user private groups globally for all users and Adding a user when user private groups are globally disabled.
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.
Specifying the GID does not create a new group. It only sets the GID attribute for the new user, because the attribute is required by IdM.
14.7.2. Adding a user without a user private group when private groups are globally enabled
You can add a user without creating a user private group (UPG) even when UPGs are enabled on the system. This requires manually setting a GID for the new user. For details on why this is needed, see Users without a user private group.
Procedure
To prevent IdM from creating a UPG, add the
--noprivate
option to theipa user-add
command.Note that for the command to succeed, you must specify a custom GID. For example, to add a new user with GID 10000:
$ ipa user-add jsmith --first=John --last=Smith --noprivate --gid 10000
14.7.3. Disabling user private groups globally for all users
You can disable user private groups (UPGs) globally. This prevents the creation of UPGs for all new users. Existing users are unaffected by this change.
Procedure
Obtain administrator privileges:
$ kinit admin
IdM uses the Directory Server Managed Entries Plug-in to manage UPGs. List the instances of the plug-in:
$ ipa-managed-entries --list
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
NoteTo re-enable the
UPG Definition
instance later, use theipa-managed-entries -e "UPG Definition" enable
command.Restart Directory Server to load the new configuration.
$ sudo systemctl restart dirsrv.target
To add a user after UPGs have been disabled, you need to specify a GID. For more information, see Adding a user when user private groups are globally disabled
Verification steps
To check if UPGs are globally disabled, use the disable command again:
$ ipa-managed-entries -e "UPG Definition" disable Plugin already disabled
14.7.4. Adding a user when user private groups are globally disabled
When user private groups (UPGs) are disabled globally, IdM does not assign a GID to a new user automatically. To successfully add a user, you must assign a GID manually or by using an automember rule. For details on why this is required, see Users without a user private group.
Prerequisities
- UPGs must be disabled globally for all users. For more information, see Disabling user private groups globally for all users
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 theipa user-add
command.- Use an automember rule to add the user to an existing group with a GID.
14.8. Adding users or groups as member managers to an IdM user group using the IdM CLI
Follow this procedure to add users or groups as member managers to an IdM user group using the IdM CLI. Member managers can add users or groups to IdM user groups but cannot change the attributes of a group.
Prerequisites
- You must be logged in as the administrator. For details, see Using kinit to log in to IdM manually.
- You must have the name of the user or group you are adding as member managers and the name of the group you want them to manage.
Procedure
Add a user as a member manager to an IdM user group by using the
ipa group-add-member-manager
command.For example, to add the user
test
as a member manager ofgroup_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 ofgroup_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 ofgroup_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 ofgroup_a
.
After you add a member manager to a user group, the update may take some time to spread to all clients in your Identity Management environment.
Verification steps
Using the
ipa group-show
command to verify the user and group were added as member managers.$ ipa group-show group_a Group name: group_a GID: 1133400009 Membership managed by groups: group_admins Membership managed by users: test
Additional resources
-
See
ipa group-add-member-manager --help
for more details.
14.9. Viewing group members using IdM CLI
Follow this procedure to view members of a group using IdM CLI. You can view both direct and indirect group members. For more information, see Direct and indirect group members.
Procedure:
To list members of a group, use the
ipa group-show group_name
command. For example:$ ipa group-show group_a ... Member users: user_a Member groups: group_b Indirect Member users: user_b
NoteThe list of indirect members does not include external users from trusted Active Directory domains. The Active Directory trust user objects are not visible in the Identity Management interface because they do not exist as LDAP objects within Identity Management.
14.10. Removing a member from a user group using IdM CLI
Follow this procedure to remove a member from a user group using IdM CLI.
Prerequisites
- You must be logged in as the administrator. For details, see Using kinit to log in to IdM manually.
Procedure
-
Optional. Use the
ipa group-show
command to confirm that the group includes the member you want to remove. 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 ofDOMAIN\user_name
oruser_name@domain
-
--groups
removes an IdM user group
For example, to remove user1, user2, and group1 from a group called group_name:
$ ipa group-remove-member group_name --users=user1 --users=user2 --groups=group1
-
14.11. Removing users or groups as member managers from an IdM user group using the IdM CLI
Follow this procedure to remove users or groups as member managers from an IdM user group using the IdM CLI. Member managers can remove users or groups from IdM user groups but cannot change the attributes of a group.
Prerequisites
- You must be logged in as the administrator. For details, see Using kinit to log in to IdM manually.
- You must have the name of the existing member manager user or group you are removing and the name of the group they are managing.
Procedure
Remove a user as a member manager of an IdM user group by using the
ipa group-remove-member-manager
command.For example, to remove the user
test
as a member manager ofgroup_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 ofgroup_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 ofgroup_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 ofgroup_a
.
After you remove a member manager from a user group, the update may take some time to spread to all clients in your Identity Management environment.
Verification steps
Using the
ipa group-show
command to verify the user and group were removed as member managers.$ ipa group-show group_a Group name: group_a GID: 1133400009
Additional resources
-
See
ipa group-remove-member-manager --help
for more details.
14.12. Enabling group merging for local and remote groups in IdM
Groups are either centrally managed, provided by a domain such as Identity Management (IdM) or Active Directory (AD), or they are managed on a local system in the etc/group
file. In most cases, users rely on a centrally managed store. However, in some cases software still relies on membership in known groups for managing access control.
If you want to manage groups from a domain controller and from the local etc/group
file, you can enable group merging. You can configure your nsswitch.conf
file to check both the local files and the remote service. If a group appears in both, the list of member users is combined and returned in a single response.
The steps below describe how to enable group merging for a user, idmuser.
Procedure
Add
[SUCCESS=merge]
to the/etc/nsswitch.conf
file:# Allow initgroups to default to the setting for group. initgroups: sss [SUCCESS=merge] files
Add the idmuser to IdM:
# ipa user-add idmuser First name: idm Last name: user --------------------- Added user "idmuser" --------------------- User login: idmuser First name: idm Last name: user Full name: idm user Display name: idm user Initials: tu Home directory: /home/idmuser GECOS: idm user Login shell: /bin/sh Principal name: idmuser@IPA.TEST Principal alias: idmuser@IPA.TEST Email address: idmuser@ipa.test UID: 19000024 GID: 19000024 Password: False Member of groups: ipausers Kerberos keys available: False
Verify the GID of the local
audio
group.$ getent group audio --------------------- audio:x:63
Add the group
audio
to IdM:$ ipa group-add audio --gid 63 ------------------- Added group "audio" ------------------- Group name: audio GID: 63
NoteThe GID you define when adding the
audio
group to IdM must be the same as the GID of the localaudio
group.Add idmuser user to the IdM
audio
group:$ ipa group-add-member audio --users=idmuser Group name: audio GID: 63 Member users: idmuser ------------------------- Number of members added 1 -------------------------
Verification
- Log in as the idmuser.
Verify the idmuser has the local group in their session:
$ id idmuser uid=1867800003(idmuser) gid=1867800003(idmuser) groups=1867800003(idmuser),63(audio),10(wheel)
Chapter 15. Managing user groups in IdM Web UI
This chapter introduces user groups management using the IdM web UI.
A user group is a set of users with common privileges, password policies, and other characteristics.
A user group in Identity Management (IdM) can include:
- IdM users
- other IdM user groups
- external users, which are users that exist outside of IdM
15.1. The different group types in IdM
IdM supports the following types of groups:
- POSIX groups (the default)
POSIX groups support Linux POSIX attributes for their members. Note that groups that interact with Active Directory cannot use POSIX attributes.
POSIX attributes identify users as separate entities. Examples of POSIX attributes relevant to users include
uidNumber
, a user number (UID), andgidNumber
, 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 name | Default group members |
---|---|
| All IdM users |
|
Users with administrative privileges, including the default |
| This is a legacy group that no longer has any special privileges |
| 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.
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

If you set a password policy for user group A, the policy also applies to all users in user group B.
15.3. Adding a user group using IdM Web UI
Follow this procedure to add a user group using the IdM Web UI.
Prerequisites
- You are logged in to the IdM Web UI.
Procedure
- Click Identity → Groups, and select User Groups in the left sidebar.
- Click Add to start adding the group.
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.
- Click Add to confirm.
15.4. Deleting a user group using IdM Web UI
Follow this procedure to delete a user group using the IdM Web UI. Note that deleting a group does not delete the group members from IdM.
Prerequisites
- You are logged in to the IdM Web UI.
Procedure
- Click Identity → Groups and select User Groups.
- Select the group to delete.
- Click Delete.
- Click Delete to confirm.
15.5. Adding a member to a user group using IdM Web UI
You can add both users and user groups as members of a user group. For more information, see The different group types in IdM and Direct and indirect group members.
Prerequisites
- You are logged in to the IdM Web UI.
Procedure
- Click Identity → Groups and select User Groups in the left sidebar.
- Click the name of the group.
Select the type of group member you want to add: Users, User Groups, or External.
- Click Add.
- Select the check box next to one or more members you want to add.
Click the rightward arrow to move the selected members to the group.
- Click Add to confirm.
15.6. Adding users or groups as member managers to an IdM user group using the Web UI
Follow this procedure to add users or groups as member managers to an IdM user group using the Web UI. Member managers can add users or groups to IdM user groups but cannot change the attributes of a group.
Prerequisites
- You are logged in to the IdM Web UI.
- You must have the name of the user or group you are adding as member managers and the name of the group you want them to manage.
Procedure
- Click Identity → Groups and select User Groups in the left sidebar.
- Click the name of the group.
Select the type of group member manager you want to add: Users or User Groups.
- Click Add.
- Select the check box next to one or more members you want to add.
Click the rightward arrow to move the selected members to the group.
- Click Add to confirm.
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:
Additional resources
-
See
ipa group-add-member-manager --help
for more information.
15.7. Viewing group members using IdM Web UI
Follow this procedure to view members of a group using the IdM Web UI. You can view both direct and indirect group members. For more information, see Direct and indirect group members.
Prerequisites
- You are logged in to the IdM Web UI.
Procedure
- Select Identity → Groups.
- Select User Groups in the left sidebar.
- Click the name of the group you want to view.
Switch between Direct Membership and Indirect Membership.
15.8. Removing a member from a user group using IdM Web UI
Follow this procedure to remove a member from a user group using the IdM Web UI.
Prerequisites
- You are logged in to the IdM Web UI.
Procedure
- Click Identity → Groups and select User Groups in the left sidebar.
- Click the name of the group.
Select the type of group member you want to remove: Users, User Groups, or External.
- Select the check box next to the member you want to remove.
- Click Delete.
- Click Delete to confirm.
15.9. Removing users or groups as member managers from an IdM user group using the Web UI
Follow this procedure to remove users or groups as member managers from an IdM user group using the Web UI. Member managers can remove users or groups from IdM user groups but cannot change the attributes of a group.
Prerequisites
- You are logged in to the IdM Web UI.
- You must have the name of the existing member manager user or group you are removing and the name of the group they are managing.
Procedure
- Click Identity → Groups and select User Groups in the left sidebar.
- Click the name of the group.
Select the type of member manager you want to remove: Users or User Groups.
- Select the check box next to the member manager you want to remove.
- Click Delete.
- Click Delete to confirm.
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:
Additional resources
-
See
ipa group-add-member-manager --help
for more details.
Chapter 16. Managing user groups using Ansible playbooks
This section introduces user group management using Ansible playbooks.
A user group is a set of users with common privileges, password policies, and other characteristics.
A user group in Identity Management (IdM) can include:
- IdM users
- other IdM user groups
- external users, which are users that exist outside of IdM
The section includes the following topics:
- The different group types in IdM
- Direct and indirect group members
- Ensuring the presence of IdM groups and group members using Ansible playbooks
- Using Ansible to enable AD users to administer IdM
- Ensuring the presence of member managers in IDM user groups using Ansible playbooks
- Ensuring the absence of member managers in IDM user groups using Ansible playbooks
16.1. The different group types in IdM
IdM supports the following types of groups:
- POSIX groups (the default)
POSIX groups support Linux POSIX attributes for their members. Note that groups that interact with Active Directory cannot use POSIX attributes.
POSIX attributes identify users as separate entities. Examples of POSIX attributes relevant to users include
uidNumber
, a user number (UID), andgidNumber
, a group number (GID).- Non-POSIX groups
Non-POSIX groups do not support POSIX attributes. For example, these groups do not have a GID defined.
All members of this type of group must belong to the IdM domain.
- External groups
Use external groups to add group members that exist in an identity store outside of the IdM domain, such as:
- A local system
- An Active Directory domain
- A directory service
External groups do not support POSIX attributes. For example, these groups do not have a GID defined.
Table 16.1. User groups created by default
Group name | Default group members |
---|---|
| All IdM users |
|
Users with administrative privileges, including the default |
| This is a legacy group that no longer has any special privileges |
| 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.
Do not delete the admins
group. As admins
is a pre-defined group required by IdM, this operation causes problems with certain commands.
In addition, IdM creates user private groups by default whenever a new user is created in IdM. For more information about private groups, see Adding users without a private group.
16.2. Direct and indirect group members
User group attributes in IdM apply to both direct and indirect members: when group B is a member of group A, all users in group B are considered indirect members of group A.
For example, in the following diagram:
- User 1 and User 2 are direct members of group A.
- User 3, User 4, and User 5 are indirect members of group A.
Figure 16.1. Direct and Indirect Group Membership

If you set a password policy for user group A, the policy also applies to all users in user group B.
16.3. Ensuring the presence of IdM groups and group members using Ansible playbooks
The following procedure describes ensuring the presence of IdM groups and group members - both users and user groups - using an Ansible playbook.
Prerequisites
- You know the IdM administrator password.
You have configured your Ansible control node to meet the following requirements:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package on the Ansible controller. - The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
-
The example assumes that the secret.yml Ansible vault stores your
ipaadmin_password
.
- The users you want to reference in your Ansible playbook exist in IdM. For details on ensuring the presence of users using Ansible, see Managing user accounts using Ansible playbooks.
Procedure
Create an inventory file, for example
inventory.file
, and defineipaserver
in it:[ipaserver] server.idm.example.com
Create an Ansible playbook file with the necessary user and group information:
--- - name: Playbook to handle groups hosts: ipaserver vars_files: - /home/user_name/MyPlaybooks/secret.yml tasks: - name: Create group ops with gid 1234 ipagroup: ipaadmin_password: "{{ ipaadmin_password }}" name: ops gidnumber: 1234 - name: Create group sysops ipagroup: ipaadmin_password: "{{ ipaadmin_password }}" name: sysops user: - idm_user - name: Create group appops ipagroup: ipaadmin_password: "{{ ipaadmin_password }}" name: appops - name: Add group members sysops and appops to group ops ipagroup: ipaadmin_password: "{{ ipaadmin_password }}" name: ops group: - sysops - appops
Run the playbook:
$ ansible-playbook --vault-password-file=password_file -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/add-group-members.yml
Verification steps
You can verify if the ops group contains sysops and appops as direct members and idm_user as an indirect member by using the ipa group-show
command:
Log into
ipaserver
as administrator:$ ssh admin@server.idm.example.com Password: [admin@server /]$
Display information about ops:
ipaserver]$ ipa group-show ops Group name: ops GID: 1234 Member groups: sysops, appops Indirect Member users: idm_user
The appops and sysops groups - the latter including the idm_user user - exist in IdM.
Additional resources
-
See the
/usr/share/doc/ansible-freeipa/README-group.md
Markdown file.
16.4. Using Ansible to add multiple IdM groups in a single task
You can use the ansible-freeipa
ipagroup
module to add, modify, and delete multiple Identity Management (IdM) user groups with a single Ansible task. For that, use the groups
option of the ipagroup
module.
Using the groups
option, you can also specify multiple group variables that only apply to a particular group. Define this group by the name
variable, which is the only mandatory variable for the groups
option.
Complete this procedure to ensure the presence of the sysops and the appops groups in IdM in a single task. Define the sysops group as a nonposix group and the appops group as an external group.
Prerequisites
On the control node:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package. - You have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server in the ~/MyPlaybooks/ directory.
- You are using RHEL 8.9 and later.
-
You have stored your
ipaadmin_password
in the secret.yml Ansible vault.
Procedure
Create your Ansible playbook file add-nonposix-and-external-groups.yml with the following content:
--- - name: Playbook to add nonposix and external groups hosts: ipaserver vars_files: - /home/user_name/MyPlaybooks/secret.yml tasks: - name: Add nonposix group sysops and external group appops ipagroup: ipaadmin_password: "{{ ipaadmin_password }}" groups: - name: sysops nonposix: true - name: appops external: true
Run the playbook:
$ ansible-playbook --vault-password-file=password_file -v -i <path_to_inventory_directory>/hosts <path_to_playbooks_directory>/add-nonposix-and-external-groups.yml
Additional resources
16.5. Using Ansible to enable AD users to administer IdM
Follow this procedure to use an Ansible playbook to ensure that a user ID override is present in an Identity Management (IdM) group. The user ID override is the override of an Active Directory (AD) user that you created in the Default Trust View after you established a trust with AD. As a result of running the playbook, an AD user, for example an AD administrator, is able to fully administer IdM without having two different accounts and passwords.
Prerequisites
-
You know the IdM
admin
password. - You have installed a trust with AD.
-
The user ID override of the AD user already exists in IdM. If it does not, create it with the
ipa idoverrideuser-add 'default trust view' ad_user@ad.example.com
command. - The group to which you are adding the user ID override already exists in IdM.
-
You are using the 4.8.7 version of IdM or later. To view the version of IdM you have installed on your server, enter
ipa --version
. You have configured your Ansible control node to meet the following requirements:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package on the Ansible controller. - The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
-
The example assumes that the secret.yml Ansible vault stores your
ipaadmin_password
.
Procedure
Navigate to your ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
Create an
add-useridoverride-to-group.yml
playbook with the following content:--- - name: Playbook to ensure presence of users in a group hosts: ipaserver - name: Ensure the ad_user@ad.example.com user ID override is a member of the admins group: ipagroup: ipaadmin_password: "{{ ipaadmin_password }}" name: admins idoverrideuser: - ad_user@ad.example.com
In the example:
-
Secret123 is the IdM
admin
password. -
admins
is the name of the IdM POSIX group to which you are adding the ad_user@ad.example.com ID override. Members of this group have full administrator privileges. - ad_user@ad.example.com is the user ID override of an AD administrator. The user is stored in the AD domain with which a trust has been established.
-
Secret123 is the IdM
- Save the file.
Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:
$ ansible-playbook --vault-password-file=password_file -v -i inventory add-useridoverride-to-group.yml
Additional resources
- ID overrides for AD users
- /usr/share/doc/ansible-freeipa/README-group.md
- /usr/share/doc/ansible-freeipa/playbooks/user
- Using ID views in Active Directory environments
- Enabling AD users to administer IdM
16.6. Ensuring the presence of member managers in IdM user groups using Ansible playbooks
The following procedure describes ensuring the presence of IdM member managers - both users and user groups - using an Ansible playbook.
Prerequisites
- You know the IdM administrator password.
You have configured your Ansible control node to meet the following requirements:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package on the Ansible controller. - The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
-
The example assumes that the secret.yml Ansible vault stores your
ipaadmin_password
.
- You must have the name of the user or group you are adding as member managers and the name of the group you want them to manage.
Procedure
Create an inventory file, for example
inventory.file
, and defineipaserver
in it:[ipaserver] server.idm.example.com
Create an Ansible playbook file with the necessary user and group member management information:
--- - name: Playbook to handle membership management hosts: ipaserver vars_files: - /home/user_name/MyPlaybooks/secret.yml tasks: - name: Ensure user test is present for group_a ipagroup: ipaadmin_password: "{{ ipaadmin_password }}" name: group_a membermanager_user: test - name: Ensure group_admins is present for group_a ipagroup: ipaadmin_password: "{{ ipaadmin_password }}" name: group_a membermanager_group: group_admins
Run the playbook:
$ ansible-playbook --vault-password-file=password_file -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/add-member-managers-user-groups.yml
Verification steps
You can verify if the group_a group contains test as a member manager and group_admins is a member manager of group_a by using the ipa group-show
command:
Log into
ipaserver
as administrator:$ ssh admin@server.idm.example.com Password: [admin@server /]$
Display information about managergroup1:
ipaserver]$ ipa group-show group_a Group name: group_a GID: 1133400009 Membership managed by groups: group_admins Membership managed by users: test
Additional resources
-
See
ipa host-add-member-manager --help
. -
See the
ipa
man page.
16.7. Ensuring the absence of member managers in IdM user groups using Ansible playbooks
The following procedure describes ensuring the absence of IdM member managers - both users and user groups - using an Ansible playbook.
Prerequisites
- You know the IdM administrator password.
You have configured your Ansible control node to meet the following requirements:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package on the Ansible controller. - The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
-
The example assumes that the secret.yml Ansible vault stores your
ipaadmin_password
.
- You must have the name of the existing member manager user or group you are removing and the name of the group they are managing.
Procedure
Create an inventory file, for example
inventory.file
, and defineipaserver
in it:[ipaserver] server.idm.example.com
Create an Ansible playbook file with the necessary user and group member management information:
--- - name: Playbook to handle membership management hosts: ipaserver vars_files: - /home/user_name/MyPlaybooks/secret.yml tasks: - name: Ensure member manager user and group members are absent for group_a ipagroup: ipaadmin_password: "{{ ipaadmin_password }}" name: group_a membermanager_user: test membermanager_group: group_admins action: member state: absent
Run the playbook:
$ ansible-playbook --vault-password-file=password_file -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-member-managers-are-absent.yml
Verification steps
You can verify if the group_a group does not contain test as a member manager and group_admins as a member manager of group_a by using the ipa group-show
command:
Log into
ipaserver
as administrator:$ ssh admin@server.idm.example.com Password: [admin@server /]$
Display information about group_a:
ipaserver]$ ipa group-show group_a Group name: group_a GID: 1133400009
Additional resources
-
See
ipa host-remove-member-manager --help
. -
See the
ipa
man page.
Chapter 17. Automating group membership using IdM CLI
Using automatic group membership allows you to assign users and hosts to groups automatically based on their attributes. For example, you can:
- Divide employees' user entries into groups based on the employees' manager, location, or any other attribute.
- Divide hosts based on their class, location, or any other attribute.
- Add all users or all hosts to a single global group.
This chapter covers the following topics:
- Benefits of automatic group membership
- Automember rules
- Adding an automember rule using IdM CLI
- Adding a condition to an automember rule using IdM CLI
- Viewing existing automember rules using IdM CLI
- Deleting an automember rule using IdM CLI
- Removing a condition from an automember rule using IdM CLI
- Applying automember rules to existing entries using IdM CLI
- Configuring a default automember group using IdM CLI
17.1. Benefits of automatic group membership
Using automatic membership for users allows you to:
Reduce the overhead of manually managing group memberships
You no longer have to assign every user and host to groups manually.
Improve consistency in user and host management
Users and hosts are assigned to groups based on strictly defined and automatically evaluated criteria.
Simplify the management of group-based settings
Various settings are defined for groups and then applied to individual group members, for example
sudo
rules, automount, or access control. Adding users and hosts to groups automatically makes managing these settings easier.
17.2. Automember rules
When configuring automatic group membership, the administrator defines automember rules. An automember rule applies to a specific user or host target group. It cannot apply to more than one group at a time.
After creating a rule, the administrator adds conditions to it. These specify which users or hosts get included or excluded from the target group:
Inclusive conditions
When a user or host entry meets an inclusive condition, it will be included in the target group.
Exclusive conditions
When a user or host entry meets an exclusive condition, it will not be included in the target group.
The conditions are specified as regular expressions in the Perl-compatible regular expressions (PCRE) format. For more information about PCRE, see the pcresyntax(3)
man page.
IdM evaluates exclusive conditions before inclusive conditions. In case of a conflict, exclusive conditions take precedence over inclusive conditions.
An automember rule applies to every entry created in the future. These entries will be automatically added to the specified target group. If an entry meets the conditions specified in multiple automember rules, it will be added to all the corresponding groups.
Existing entries are not affected by the new rule. If you want to change existing entries, see Applying automember rules to existing entries using IdM CLI.
17.3. Adding an automember rule using IdM CLI
Follow this procedure to add an automember rule using the IdM CLI. For information about automember rules, see Automember rules.
After adding an automember rule, you can add conditions to it using the procedure described in Adding a condition to an automember rule.
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
- You must be logged in as the administrator. For details, see Using kinit to log in to IdM manually.
- The target group of the new rule must exist in IdM.
Procedure
-
Enter the
ipa automember-add
command to add an automember rule. 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
- You can display existing automember rules and conditions in IdM using Viewing existing automember rules using IdM CLI.
17.4. Adding a condition to an automember rule using IdM CLI
After configuring automember rules, you can then add a condition to that automember rule using the IdM CLI. For information about automember rules, see Automember rules.
Prerequisites
- You must be logged in as the administrator. For details, see Using kinit to log in to IdM manually.
- The target rule must exist in IdM. For details, see Adding an automember rule using IdM CLI.
Procedure
-
Define one or more inclusive or exclusive conditions using the
ipa automember-add-condition
command. 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
- You can display existing automember rules and conditions in IdM using Viewing existing automember rules using IdM CLI.
17.5. Viewing existing automember rules using IdM CLI
Follow this procedure to view existing automember rules using the IdM CLI.
Prerequisites
- You must be logged in as the administrator. For details, see Using kinit to log in to IdM manually.
Procedure
-
Enter the
ipa automember-find
command. When prompted, specify the Grouping type:
- To target a user group, enter group.
To target a host group, enter hostgroup.
For example:
$ ipa automember-find Grouping Type: group --------------- 1 rules matched --------------- Automember Rule: user_group Inclusive Regex: uid=.* ---------------------------- Number of entries returned 1 ----------------------------
17.6. Deleting an automember rule using IdM CLI
Follow this procedure to delete an automember rule using the IdM CLI.
Deleting an automember rule also deletes all conditions associated with the rule. To remove only specific conditions from a rule, see Removing a condition from an automember rule using IdM CLI.
Prerequisites
- You must be logged in as the administrator. For details, see Using kinit to log in to IdM manually.
Procedure
-
Enter the
ipa automember-del
command. When prompted, specify:
- Automember rule. This is the rule you want to delete.
- Grouping rule. This specifies whether the rule you want to delete is for a user group or a host group. Enter group or hostgroup.
17.7. Removing a condition from an automember rule using IdM CLI
Follow this procedure to remove a specific condition from an automember rule.
Prerequisites
- You must be logged in as the administrator. For details, see Using kinit to log in to IdM manually.
Procedure
-
Enter the
ipa automember-remove-condition
command. When prompted, specify:
- Automember rule. This is the name of the rule from which you want to remove a condition.
- Attribute Key. This is the target entry attribute. For example, uid for users.
- Grouping Type. This specifies whether the condition you want to delete is for a user group or a host group. Enter group or hostgroup.
Inclusive regex and Exclusive regex. These specify the conditions you want to remove. If you only want to specify one condition, press Enter when prompted for the other.
For example:
$ ipa automember-remove-condition Automember Rule: user_group Attribute Key: uid Grouping Type: group [Inclusive Regex]: .* [Exclusive Regex]: ----------------------------------- Removed condition(s) from "user_group" ----------------------------------- Automember Rule: user_group ------------------------------ Number of conditions removed 1 ------------------------------
17.8. Applying automember rules to existing entries using IdM CLI
Automember rules apply automatically to user and host entries created after the rules were added. They are not applied retroactively to entries that existed before the rules were added.
To apply automember rules to previously added entries, you have to manually rebuild automatic membership. Rebuilding automatic membership re-evaluates all existing automember rules and applies them either to all user or hosts entries, or to specific entries.
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
- You must be logged in as the administrator. For details, see link: Using kinit to log in to IdM manually.
Procedure
To rebuild automatic membership, enter the
ipa automember-rebuild
command. Use the following options to specify the entries to target:To rebuild automatic membership for all users, use the
--type=group
option:$ ipa automember-rebuild --type=group -------------------------------------------------------- Automember rebuild task finished. Processed (9) entries. --------------------------------------------------------
-
To rebuild automatic membership for all hosts, use the
--type=hostgroup
option. To rebuild automatic membership for a specified user or users, use the
--users=target_user
option:$ ipa automember-rebuild --users=target_user1 --users=target_user2 -------------------------------------------------------- Automember rebuild task finished. Processed (2) entries. --------------------------------------------------------
-
To rebuild automatic membership for a specified host or hosts, use the
--hosts=client.idm.example.com
option.
17.9. Configuring a default automember group using IdM CLI
When you configure a default automember group, new user or host entries that do not match any automember rule are automatically added to this default group.
Prerequisites
- You must be logged in as the administrator. For details, see Using kinit to log in to IdM manually.
- The target group you want to set as default exists in IdM.
Procedure
-
Enter the
ipa automember-default-group-set
command to configure a default automember group. When prompted, specify:
- Default (fallback) Group, which specifies the target group name.
Grouping Type, which specifies whether the target is a user group or a host group. To target a user group, enter group. To target a host group, enter hostgroup.
For example:
$ ipa automember-default-group-set Default (fallback) Group: default_user_group Grouping Type: group --------------------------------------------------- Set default (fallback) group for automember "default_user_group" --------------------------------------------------- Default (fallback) Group: cn=default_user_group,cn=groups,cn=accounts,dc=example,dc=com
NoteTo remove the current default automember group, enter the
ipa automember-default-group-remove
command.
Verification steps
To verify that the group is set correctly, enter the
ipa automember-default-group-show
command. The command displays the current default automember group. For example:$ ipa automember-default-group-show Grouping Type: group Default (fallback) Group: cn=default_user_group,cn=groups,cn=accounts,dc=example,dc=com
Chapter 18. Automating group membership using IdM Web UI
Using automatic group membership enables you to assign users and hosts to groups automatically based on their attributes. For example, you can:
- Divide employees' user entries into groups based on the employees' manager, location, or any other attribute.
- Divide hosts based on their class, location, or any other attribute.
- Add all users or all hosts to a single global group.
This chapter covers the following topics:
- Benefits of automatic group membership
- Automember rules
- Adding an automember rule using IdM Web UI
- Adding a condition to an automember rule using IdM Web UI
- Viewing existing automember rules and conditions using IdM Web UI
- Deleting an automember rule using IdM Web UI
- Removing a condition from an automember rule using IdM Web UI
- Applying automember rules to existing entries using IdM Web UI
- Configuring a default user group using IdM Web UI
- Configuring a default host group using IdM Web UI
18.1. Benefits of automatic group membership
Using automatic membership for users allows you to:
Reduce the overhead of manually managing group memberships
You no longer have to assign every user and host to groups manually.
Improve consistency in user and host management
Users and hosts are assigned to groups based on strictly defined and automatically evaluated criteria.
Simplify the management of group-based settings
Various settings are defined for groups and then applied to individual group members, for example
sudo
rules, automount, or access control. Adding users and hosts to groups automatically makes managing these settings easier.
18.2. Automember rules
When configuring automatic group membership, the administrator defines automember rules. An automember rule applies to a specific user or host target group. It cannot apply to more than one group at a time.
After creating a rule, the administrator adds conditions to it. These specify which users or hosts get included or excluded from the target group:
Inclusive conditions
When a user or host entry meets an inclusive condition, it will be included in the target group.
Exclusive conditions
When a user or host entry meets an exclusive condition, it will not be included in the target group.
The conditions are specified as regular expressions in the Perl-compatible regular expressions (PCRE) format. For more information about PCRE, see the pcresyntax(3)
man page.
IdM evaluates exclusive conditions before inclusive conditions. In case of a conflict, exclusive conditions take precedence over inclusive conditions.
An automember rule applies to every entry created in the future. These entries will be automatically added to the specified target group. If an entry meets the conditions specified in multiple automember rules, it will be added to all the corresponding groups.
Existing entries are not affected by the new rule. If you want to change existing entries, see Applying automember rules to existing entries using IdM Web UI.
18.3. Adding an automember rule using IdM Web UI
Follow this procedure to add an automember rule using the IdM Web UI. For information about automember rules, see Automember rules.
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
- Click Identity → Automember, and select either User group rules or Host group rules.
- Click Add.
In the Automember rule field, select the group to which the rule will apply. This is the target group name.
- Click Add to confirm.
- Optional: You can add conditions to the new rule using the procedure described in Adding a condition to an automember rule using IdM Web UI.
18.4. Adding a condition to an automember rule using IdM Web UI
After configuring automember rules, you can then add a condition to that automember rule using the IdM Web UI. For information about automember rules, see Automember rules.
Prerequisites
- You are logged in to the IdM Web UI.
-
You must be a member of the
admins
group. - The target rule exists in IdM.
Procedure
- Click Identity → Automember, and select either User group rules or Host group rules.
- Click on the rule to which you want to add a condition.
In the Inclusive or Exclusive sections, click Add.
- In the Attribute field, select the required attribute, for example uid.
- In the Expression field, define a regular expression.
Click Add.
For example, the following condition targets all users with any value (.*) in their user ID (uid) attribute.
18.5. Viewing existing automember rules and conditions using IdM Web UI
Follow this procedure to view existing automember rules and conditions using the IdM Web UI.
Prerequisites
- You are logged in to the IdM Web UI.
-
You must be a member of the
admins
group.
Procedure
- Click Identity → Automember, and select either User group rules or Host group rules to view the respective automember rules.
Optional: Click on a rule to see the conditions for that rule in the Inclusive or Exclusive sections.
18.6. Deleting an automember rule using IdM Web UI
Follow this procedure to delete an automember rule using the IdM Web UI.
Deleting an automember rule also deletes all conditions associated with the rule. To remove only specific conditions from a rule, see Removing a condition from an automember rule using IdM Web UI.
Prerequisites
- You are logged in to the IdM Web UI.
-
You must be a member of the
admins
group.
Procedure
- Click Identity → Automember, and select either User group rules or Host group rules to view the respective automember rules.
- Select the check box next to the rule you want to remove.
Click Delete.
- Click Delete to confirm.
18.7. Removing a condition from an automember rule using IdM Web UI
Follow this procedure to remove a specific condition from an automember rule using the IdM Web UI.
Prerequisites
- You are logged in to the IdM Web UI.
-
You must be a member of the
admins
group.
Procedure
- Click Identity → Automember, and select either User group rules or Host group rules to view the respective automember rules.
- Click on a rule to see the conditions for that rule in the Inclusive or Exclusive sections.
- Select the check box next to the conditions you want to remove.
Click Delete.
- Click Delete to confirm.
18.8. Applying automember rules to existing entries using IdM Web UI
Automember rules apply automatically to user and host entries created after the rules were added. They are not applied retroactively to entries that existed before the rules were added.
To apply automember rules to previously added entries, you have to manually rebuild automatic membership. Rebuilding automatic membership re-evaluates all existing automember rules and applies them either to all user or hosts entries, or to specific entries.
Rebuilding automatic membership does not remove user or host entries from groups, even if the entries no longer match the group’s inclusive conditions. To remove them manually, see Removing a member from a user group using IdM Web UI or Removing host group members in the IdM Web UI.
18.8.1. Rebuilding automatic membership for all users or hosts
Follow this procedure to rebuild automatic membership for all user or host entries.
Prerequisites
- You are logged in to the IdM Web UI.
-
You must be a member of the
admins
group.
Procedure
- Select Identity → Users or Hosts.
Click Actions → Rebuild auto membership.
18.8.2. Rebuilding automatic membership for a single user or host only
Follow this procedure to rebuild automatic membership for a specific user or host entry.
Prerequisites
- You are logged in to the IdM Web UI.
-
You must be a member of the
admins
group.
Procedure
- Select Identity → Users or Hosts.
- Click on the required user or host name.
Click Actions → Rebuild auto membership.
18.9. Configuring a default user group using IdM Web UI
When you configure a default user group, new user entries that do not match any automember rule are automatically added to this default group.
Prerequisites
- You are logged in to the IdM Web UI.
-
You must be a member of the
admins
group. - The target user group you want to set as default exists in IdM.
Procedure
- Click Identity → Automember, and select User group rules.
In the Default user group field, select the group you want to set as the default user group.
18.10. Configuring a default host group using IdM Web UI
When you configure a default host group, new host entries that do not match any automember rule are automatically added to this default group.
Prerequisites
- You are logged in to the IdM Web UI.
-
You must be a member of the
admins
group. - The target host group you want to set as default exists in IdM.
Procedure
- Click Identity → Automember, and select Host group rules.
In the Default host group field, select the group you want to set as the default host group.
Chapter 19. Using Ansible to automate group membership in IdM
Using automatic group membership, you can assign users and hosts user groups and host groups automatically, based on their attributes. For example, you can:
-
Divide employees' user entries into groups based on the employees' manager, location, position or any other attribute. You can list all attributes by entering
ipa user-add --help
on the command-line. -
Divide hosts into groups based on their class, location, or any other attribute. You can list all attributes by entering
ipa host-add --help
on the command-line. - Add all users or all hosts to a single global group.
You can use Red Hat Ansible Engine to automate the management of automatic group membership in Identity Management (IdM).
This section covers the following topics:
- Preparing your Ansible control node for managing IdM
- Using Ansible to ensure that an automember rule for an IdM user group is present
- Using Ansible to ensure that a condition is present in an IdM user group automember rule
- Using Ansible to ensure that a condition is absent in an IdM user group automember rule
- Using Ansible to ensure that an automember rule for an IdM group is absent
- Using Ansible to ensure that a condition is present in an IdM host group automember rule
19.1. Preparing your Ansible control node for managing IdM
As a system administrator managing Identity Management (IdM), when working with Red Hat Ansible Engine, it is good practice to do the following:
- Create a subdirectory dedicated to Ansible playbooks in your home directory, for example ~/MyPlaybooks.
-
Copy and adapt sample Ansible playbooks from the
/usr/share/doc/ansible-freeipa/*
and/usr/share/doc/rhel-system-roles/*
directories and subdirectories into your ~/MyPlaybooks directory. - Include your inventory file in your ~/MyPlaybooks directory.
By following this practice, you can find all your playbooks in one place and you can run your playbooks without invoking root privileges.
You only need root
privileges on the managed nodes to execute the ipaserver
, ipareplica
, ipaclient
, ipabackup
, ipasmartcard_server
and ipasmartcard_client
ansible-freeipa
roles. These roles require privileged access to directories and the dnf
software package manager.
Follow this procedure to create the ~/MyPlaybooks directory and configure it so that you can use it to store and run Ansible playbooks.
Prerequisites
- You have installed an IdM server on your managed nodes, server.idm.example.com and replica.idm.example.com.
- You have configured DNS and networking so you can log in to the managed nodes, server.idm.example.com and replica.idm.example.com, directly from the control node.
-
You know the IdM
admin
password.
Procedure
Create a directory for your Ansible configuration and playbooks in your home directory:
$ mkdir ~/MyPlaybooks/
Change into the ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks
Create the ~/MyPlaybooks/ansible.cfg file with the following content:
[defaults] inventory = /home/your_username/MyPlaybooks/inventory [privilege_escalation] become=True
Create the ~/MyPlaybooks/inventory file with the following content:
[ipaserver] server.idm.example.com [ipareplicas] replica1.idm.example.com replica2.idm.example.com [ipacluster:children] ipaserver ipareplicas [ipacluster:vars] ipaadmin_password=SomeADMINpassword [ipaclients] ipaclient1.example.com ipaclient2.example.com [ipaclients:vars] ipaadmin_password=SomeADMINpassword
This configuration defines two host groups, eu and us, for hosts in these locations. Additionally, this configuration defines the ipaserver host group, which contains all hosts from the eu and us groups.
[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
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.
Additional resources
19.2. Using Ansible to ensure that an automember rule for an IdM user group is present
The following procedure describes how to use an Ansible playbook to ensure an automember
rule for an Identity Management (IdM) group exists. In the example, the presence of an automember
rule is ensured for the testing_group user group.
Prerequisites
-
You know the IdM
admin
password. - The testing_group user group exists in IdM.
You have configured your Ansible control node to meet the following requirements:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package on the Ansible controller. - The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
-
The example assumes that the secret.yml Ansible vault stores your
ipaadmin_password
.
Procedure
Navigate to your ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
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
-
Open the
automember-group-present-copy.yml
file for editing. Adapt the file by setting the following variables in the
ipaautomember
task section:-
Set the
ipaadmin_password
variable to the password of the IdMadmin
. -
Set the
name
variable to testing_group. -
Set the
automember_type
variable to group. -
Ensure that the
state
variable is set topresent
.
This is the modified Ansible playbook file for the current example:
--- - name: Automember group present example hosts: ipaserver vars_files: - /home/user_name/MyPlaybooks/secret.yml tasks: - name: Ensure group automember rule admins is present ipaautomember: ipaadmin_password: "{{ ipaadmin_password }}" name: testing_group automember_type: group state: present
-
Set the
- Save the file.
Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:
$ ansible-playbook --vault-password-file=password_file -v -i inventory automember-group-present-copy.yml
Additional resources
- See Benefits of automatic group membership and Automember rules.
- See Using Ansible to ensure that a condition is present in an IdM user group automember rule.
-
See the
README-automember.md
file in the/usr/share/doc/ansible-freeipa/
directory. -
See the
/usr/share/doc/ansible-freeipa/playbooks/automember
directory.
19.3. Using Ansible to ensure that a specified condition is present in an IdM user group automember rule
The following procedure describes how to use an Ansible playbook to ensure that a specified condition exists in an automember
rule for an Identity Management (IdM) group. In the example, the presence of a UID-related condition in the automember
rule is ensured for the testing_group group. By specifying the .* condition, you ensure that all future IdM users automatically become members of the testing_group.
Prerequisites
-
You know the IdM
admin
password. - The testing_group user group and automember user group rule exist in IdM.
You have configured your Ansible control node to meet the following requirements:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package on the Ansible controller. - The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
-
The example assumes that the secret.yml Ansible vault stores your
ipaadmin_password
.
Procedure
Navigate to your ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
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
-
Open the
automember-usergroup-rule-present.yml
file for editing. 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 IdMadmin
. -
Set the
name
variable to testing_group. -
Set the
automember_type
variable togroup
. -
Ensure that the
state
variable is set topresent
. -
Ensure that the
action
variable is set tomember
. -
Set the
inclusive
key
variable toUID
. -
Set the
inclusive
expression
variable to .*
-
Set the
This is the modified Ansible playbook file for the current example:
--- - name: Automember user group rule member present hosts: ipaserver vars_files: - /home/user_name/MyPlaybooks/secret.yml tasks: - name: Ensure an automember condition for a user group is present ipaautomember: ipaadmin_password: "{{ ipaadmin_password }}" name: testing_group automember_type: group state: present action: member inclusive: - key: UID expression: .*
- Save the file.
Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:
$ ansible-playbook --vault-password-file=password_file -v -i inventory automember-usergroup-rule-present.yml
Verification steps
Log in as an IdM administrator.
$ kinit admin
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
- See Applying automember rules to existing entries using the IdM CLI.
- See Benefits of automatic group membership and Automember rules.
-
See the
README-automember.md
file in the/usr/share/doc/ansible-freeipa/
directory. -
See the
/usr/share/doc/ansible-freeipa/playbooks/automember
directory.
19.4. Using Ansible to ensure that a condition is absent from an IdM user group automember rule
The following procedure describes how to use an Ansible playbook to ensure a condition is absent from an automember
rule for an Identity Management (IdM) group. In the example, the absence of a condition in the automember
rule is ensured that specifies that users whose initials
are dp should be included. The automember rule is applied to the testing_group group. By applying the condition, you ensure that no future IdM user whose initials are dp becomes a member of the testing_group.
Prerequisites
-
You know the IdM
admin
password. - The testing_group user group and automember user group rule exist in IdM.
You have configured your Ansible control node to meet the following requirements:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package on the Ansible controller. - The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
-
The example assumes that the secret.yml Ansible vault stores your
ipaadmin_password
.
Procedure
Navigate to your ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
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
-
Open the
automember-usergroup-rule-absent.yml
file for editing. 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 IdMadmin
. -
Set the
name
variable to testing_group. -
Set the
automember_type
variable to group. -
Ensure that the
state
variable is set toabsent
. -
Ensure that the
action
variable is set tomember
. -
Set the
inclusive
key
variable toinitials
. -
Set the
inclusive
expression
variable to dp.
-
Set the
This is the modified Ansible playbook file for the current example:
--- - name: Automember user group rule member absent hosts: ipaserver vars_files: - /home/user_name/MyPlaybooks/secret.yml tasks: - name: Ensure an automember condition for a user group is absent ipaautomember: ipaadmin_password: "{{ ipaadmin_password }}" name: testing_group automember_type: group state: absent action: member inclusive: - key: initials expression: dp
- Save the file.
Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:
$ ansible-playbook --vault-password-file=password_file -v -i inventory automember-usergroup-rule-absent.yml
Verification steps
Log in as an IdM administrator.
$ kinit admin
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
- See Applying automember rules to existing entries using the IdM CLI.
- See Benefits of automatic group membership and Automember rules.
-
See the
README-automember.md
file in the/usr/share/doc/ansible-freeipa/
directory. -
See the
/usr/share/doc/ansible-freeipa/playbooks/automember
directory.
19.5. Using Ansible to ensure that an automember rule for an IdM user group is absent
The following procedure describes how to use an Ansible playbook to ensure an automember
rule is absent for an Identity Management (IdM) group. In the example, the absence of an automember
rule is ensured for the testing_group group.
Deleting an automember rule also deletes all conditions associated with the rule. To remove only specific conditions from a rule, see Using Ansible to ensure that a condition is absent in an IdM user group automember rule.
Prerequisites
-
You know the IdM
admin
password. You have configured your Ansible control node to meet the following requirements:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package on the Ansible controller. - The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
-
The example assumes that the secret.yml Ansible vault stores your
ipaadmin_password
.
Procedure
Navigate to your ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
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
-
Open the
automember-group-absent-copy.yml
file for editing. Adapt the file by setting the following variables in the
ipaautomember
task section:-
Set the
ipaadmin_password
variable to the password of the IdMadmin
. -
Set the
name
variable to testing_group. -
Set the
automember_type
variable to group. -
Ensure that the
state
variable is set toabsent
.
This is the modified Ansible playbook file for the current example:
--- - name: Automember group absent example hosts: ipaserver vars_files: - /home/user_name/MyPlaybooks/secret.yml tasks: - name: Ensure group automember rule admins is absent ipaautomember: ipaadmin_password: "{{ ipaadmin_password }}" name: testing_group automember_type: group state: absent
-
Set the
- Save the file.
Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:
$ ansible-playbook --vault-password-file=password_file -v -i inventory automember-group-absent.yml
Additional resources
- See Benefits of automatic group membership and Automember rules.
-
See the
README-automember.md
file in the/usr/share/doc/ansible-freeipa/
directory. -
See the
/usr/share/doc/ansible-freeipa/playbooks/automember
directory.
19.6. Using Ansible to ensure that a condition is present in an IdM host group automember rule
Follow this procedure to use Ansible to ensure that a condition is present in an IdM host group automember rule. The example describes how to ensure that hosts with the FQDN
of .*.idm.example.com are members of the primary_dns_domain_hosts host group and hosts whose FQDN
is .*.example.org are not members of the primary_dns_domain_hosts host group.
Prerequisites
-
You know the IdM
admin
password. - The primary_dns_domain_hosts host group and automember host group rule exist in IdM.
You have configured your Ansible control node to meet the following requirements:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package on the Ansible controller. - The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
-
The example assumes that the secret.yml Ansible vault stores your
ipaadmin_password
.
Procedure
Navigate to your ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
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
-
Open the
automember-hostgroup-rule-present-copy.yml
file for editing. Adapt the file by setting the following variables in the
ipaautomember
task section:-
Set the
ipaadmin_password
variable to the password of the IdMadmin
. -
Set the
name
variable to primary_dns_domain_hosts. -
Set the
automember_type
variable to hostgroup. -
Ensure that the
state
variable is set topresent
. -
Ensure that the
action
variable is set tomember
. -
Ensure that the
inclusive
key
variable is set tofqdn
. -
Set the corresponding
inclusive
expression
variable to .*.idm.example.com. -
Set the
exclusive
key
variable tofqdn
. -
Set the corresponding
exclusive
expression
variable to .*.example.org.
This is the modified Ansible playbook file for the current example:
--- - name: Automember user group rule member present hosts: ipaserver vars_files: - /home/user_name/MyPlaybooks/secret.yml tasks: - name: Ensure an automember condition for a user group is present ipaautomember: ipaadmin_password: "{{ ipaadmin_password }}" name: primary_dns_domain_hosts automember_type: hostgroup state: present action: member inclusive: - key: fqdn expression: .*.idm.example.com exclusive: - key: fqdn expression: .*.example.org
-
Set the
- Save the file.
Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:
$ ansible-playbook --vault-password-file=password_file -v -i inventory automember-hostgroup-rule-present-copy.yml
Additional resources
- See Applying automember rules to existing entries using the IdM CLI.
- See Benefits of automatic group membership and Automember rules.
-
See the
README-automember.md
file in the/usr/share/doc/ansible-freeipa/
directory. -
See the
/usr/share/doc/ansible-freeipa/playbooks/automember
directory.
19.7. Additional resources
Chapter 20. Access control in IdM
Access control defines the rights or permissions users have been granted to perform operations on other users or objects, such as hosts or services. Identity Management (IdM) provides several access control areas to make it clear what kind of access is being granted and to whom it is granted. As part of this, IdM draws a distinction between access control to resources within the domain and access control to the IdM configuration itself.
This chapter outlines the different internal access control mechanisms that are available for IdM users both to the resources within the domain and to the IdM configuration itself.
20.1. Access control instructions in IdM
The Identity Management (IdM) access control structure is based on the 389 Directory Server access control. By using access control instructions (ACIs), you can grant or deny specific IdM users access over other entries. All entries, including IdM users, are stored in LDAP.
An ACI has three parts:
- Actor
- The entity that is being granted permission to do something. In LDAP access control models, you can, for example, specify that the ACI rule is applied only when a user binds to the directory using their distinguished name (DN). Such a specification is called the bind rule: it defines who the user is and can optionally require other limits on the bind attempt, such as restricting attempts to a certain time of day or a certain machine.
- Target
- The entry that the actor is allowed to perform operations on.
- Operation type
- Determines what kinds of actions the actor is allowed to perform. The most common operations are add, delete, write, read, and search. In IdM, the read and search rights of a non-administrative user are limited, and even more so in the IdM Web UI than the IdM CLI.
When an LDAP operation is attempted, the following occurs:
- The IdM client sends user credentials to an IdM server as part of the bind operation.
- The IdM server DS checks the user credentials.
- The IdM server DS checks the user account to see if the user has a permission to perform the requested operation.
20.2. Access control methods in IdM
Identity Management (IdM) divides access control methods into the following categories:
- Self-service rules
- Define what operations a user can perform on the user’s own personal entry. This access control type only allows write permissions to specific attributes within the user entry. Users can update the values of specific attributes but cannot add or delete the attributes as such.
- Delegation rules
- By using a delegation rule, you can allow a specific user group to perform write, that is edit, operations on specific attributes of users in another user group. Similarly to self-service rules, this form of access control rule is limited to editing the values of specific attributes. It does not grant the ability to add or remove whole entries or control over unspecified attributes.
- Role-based access control
Creates special access control groups that are then granted much broader authority over all types of entities in the IdM domain. Roles can be granted edit, add, and delete rights, meaning they can be granted complete control over entire entries, not just selected attributes.
Certain roles are already available in IdM by default, for example
Enrollment Administrator
,IT Security Specialist
, andIT Specialist
. You can create additional roles to manage any types of entries, such as hosts, automount configuration, netgroups, DNS settings, and IdM configuration.
Chapter 21. Managing self-service rules in IdM using the CLI
Learn about self-service rules in Identity Management (IdM) and how to create and edit self-service access rules in the command-line interface (CLI).
21.1. Self-service access control in IdM
Self-service access control rules define which operations an Identity Management (IdM) entity can perform on its IdM Directory Server entry: for example, IdM users have the ability to update their own passwords.
This method of control allows an authenticated IdM entity to edit specific attributes within its LDAP entry, but does not allow add
or delete
operations on the entire entry.
Be careful when working with self-service access control rules: configuring access control rules improperly can inadvertently elevate an entity’s privileges.
21.2. Creating self-service rules using the CLI
Follow this procedure to create self-service access rules in IdM using the command-line interface (CLI).
Prerequisites
- Administrator privileges for managing IdM or the User Administrator role.
- An active Kerberos ticket. For details, see Using kinit to log in to IdM manually.
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
21.3. Editing self-service rules using the CLI
Follow this procedure to edit self-service access rules in IdM using the command-line interface (CLI).
Prerequisites
- Administrator privileges for managing IdM or the User Administrator role.
- An active Kerberos ticket. For details, see Using kinit to log in to IdM manually.
Procedure
-
Optional: Display existing self-service rules with the
ipa selfservice-find
command. -
Optional: Display details for the self-service rule you want to modify with the
ipa selfservice-show
command. -
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
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
21.4. Deleting self-service rules using the CLI
Follow this procedure to delete self-service access rules in IdM using the command-line interface (CLI).
Prerequisites
- Administrator privileges for managing IdM or the User Administrator role.
- An active Kerberos ticket. For details, see Using kinit to log in to IdM manually.
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 22. Managing self-service rules using the IdM Web UI
Learn about self-service rules in Identity Management (IdM) and how to create and edit self-service access rules in the web interface (IdM Web UI).
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.
Be careful when working with self-service access control rules: configuring access control rules improperly can inadvertently elevate an entity’s privileges.
22.2. Creating self-service rules using the IdM Web UI
Follow this procedure to create self-service access rules in IdM using the web interface (IdM Web UI).
Prerequisites
- Administrator privileges for managing IdM or the User Administrator role.