Configuring and managing Identity Management
Logging in to IdM and managing services, users, hosts, groups, access control rules, and certificates.
Abstract
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 ~]$
Verification
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
Verificiation
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
-
krb5.conf(5)
,kinit(1)
,klist(1)
, andkdestroy(1)
man pages on your system
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
-
ipa
man page on your system
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 .
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 ~]$
Verification
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.
- Configure a RADIUS server for OTP validation in IdM.
- Create OTP tokens and synchronize them with the FreeOTP app in your phone.
- Authenticate to the IdM Web UI with the combination of user password and one time password.
- Re-synchronize tokens in the Web UI.
- Retrieve an IdM ticket-granting ticket as an OTP or RADIUS user
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
Identity Management (IdM) administrators can enable two-factor authentication (2FA) for IdM users either globally or individually. The user enters the one-time password (OTP) after their regular password on the command line or in the dedicated field in the Web UI login dialog, with no space between these passwords.
Enabling 2FA is not the same as enforcing it. If you use logins based on LDAP-binds, IdM users can still authenticate by entering a password only. However, if you use krb5
-based logins, the 2FA is enforced. In a future release, Red Hat plans to provide a configuration option for administrators to select one of the following:
-
Allow users to set their own tokens. In this case, LDAP-binds are still not going to enforce 2FA though
krb5
-based logins are. -
Not allow users to set their own tokens. In this case, 2FA is going to be enforced in both LDAP-binds and
krb5
-based logins.
Complete this procedure to use the IdM Web UI to enable 2FA for the individual example.user IdM user.
Prerequisites
- Administration privileges
Procedure
-
Log in to the IdM Web UI with IdM
admin
privileges. Open the Identity → Users → Active users tab.
- Select example.user 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 for the IdM user.
Now you or example.user must assign a new token ID to the example.user account.
As of September 2024, a CVE-2024-3596 vulnerability exists in the RADIUS protocol. In the context of IdM, using RADIUS/TLS or RADIUS/DTLS in response to the CVE is not an option as IdM only supports RADIUS over UDP. To work around the problem, create a secure channel between IdM servers and your policy management platform instance by using, for example, a point-to-point VPN between IdM servers and a trusted system next to your policy management platform instance. Then make sure that the traffic to that remote RADIUS server connection is encapsulated through the VPN route. Additionally, configure your RADIUS server to accept requests from RHEL IdM without the Message-Authenticator attribute.
7.4. Configuring a RADIUS server for OTP validation in IdM
To enable the migration of a large deployment from a proprietary one-time password (OTP) solution to the Identity Management (IdM)-native OTP solution, IdM offers a way to offload OTP validation to a third-party RADIUS server for a subset of users. The administrator creates a set of RADIUS proxies where each proxy can only reference a single RADIUS server. If more than one server needs to be addressed, it is recommended to create a virtual IP solution that points to multiple RADIUS servers.
Such a solution must be built outside of RHEL IdM with the help of the keepalived
daemon, for example. The administrator then assigns one of these proxy sets to a user. As long as the user has a RADIUS proxy set assigned, IdM bypasses all other authentication mechanisms.
IdM does not provide any token management or synchronization support for tokens in the third-party system.
Complete the procedure to configure a RADIUS server for OTP validation and to add a user to the proxy server:
Prerequisites
- The radius user authentication method is enabled. See Enabling the one-time password in the Web UI for details.
Procedure
Add a RADIUS proxy:
$ ipa radiusproxy-add proxy_name --secret secret
The command prompts you for inserting the required information.
The configuration of the RADIUS proxy requires the use of a common secret between the client and the server to wrap credentials. Specify this secret in the
--secret
parameter.Assign a user to the added proxy:
ipa user-mod radiususer --radius=proxy_name
If required, configure the user name to be sent to RADIUS:
ipa user-mod radiususer --radius-username=radius_user
As a result, the RADIUS proxy server starts to process the user OTP authentication.
When the user is ready to be migrated to the IdM native OTP system, you can simply remove the RADIUS proxy assignment for the user.
7.4.1. Changing the timeout value of a KDC when running a RADIUS server in a slow network
In certain situations, such as running a RADIUS proxy in a slow network, the Identity Management (IdM) Kerberos Distribution Center (KDC) closes the connection before the RADIUS server responds because the connection timed out while waiting for the user to enter the token.
To change the timeout settings of the KDC:
Change the value of the
timeout
parameter in the[otp]
section in the/var/kerberos/krb5kdc/kdc.conf
file. For example, to set the timeout to120
seconds:[otp] DEFAULT = { timeout = 120 ... }
Restart the
krb5kdc
service:# systemctl restart krb5kdc
Additional resources
- The How to configure FreeRADIUS authentication in FIPS mode Knowledgebase article
7.5. Adding OTP tokens in the Web UI
The following section helps you to add token to the IdM Web UI and to your software token generator.
Prerequisites
- Active user account on the IdM server.
- Administrator has enabled OTP for the particular user account in the IdM Web UI.
- A software device generating OTP tokens, for example FreeOTP.
Procedure
- 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.6. Logging into the Web UI with a one time password
Follow this procedure to login for the first time into the IdM Web UI using a one time password (OTP).
Prerequisites
OTP configuration enabled on the Identity Management server for the user account you are using for the OTP authentication. Administrators as well as users themselves can enable OTP.
To enable the OTP configuration, see Enabling the one time password in the Web UI.
- A hardware or software device generating OTP tokens configured.
Procedure
- 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.7. Synchronizing OTP tokens using the Web UI
If the login with OTP (One Time Password) fails, OTP tokens are not synchronized correctly.
The following text describes token re-synchronization.
Prerequisites
- A login screen opened.
- A device generating OTP tokens configured.
Procedure
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.
Optional: Enter the token ID.
- Click Sync OTP Token.
After the successful synchronization, you can log in to the IdM server.
7.8. Changing expired passwords
Administrators of Identity Management can enforce you having to change your password at the next login. It means that you cannot successfully log in to the IdM Web UI until you change the password.
Password expiration can happen during your first login to the Web UI.
If the expiration password dialog appears, follow the instructions in the procedure.
Prerequisites
- A login screen opened.
- Active account to the IdM server.
Procedure
- 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.
7.9. Retrieving an IdM ticket-granting ticket as an OTP or RADIUS user
To retrieve a Kerberos ticket-granting ticket (TGT) as an OTP user, request an anonymous Kerberos ticket and enable Flexible Authentication via Secure Tunneling (FAST) channel to provide a secure connection between the Kerberos client and Kerberos Distribution Center (KDC).
Prerequisites
- Your IdM client and IdM servers use RHEL 8.7 or later.
- Your IdM client and IdM servers use SSSD 2.7.0 or later.
- You have enabled OTP for the required user account.
Procedure
Initialize the credentials cache by running the following command:
[root@client ~]# kinit -n @IDM.EXAMPLE.COM -c FILE:armor.ccache
Note that this command creates the
armor.ccache
file that you need to point to whenever you request a new Kerberos ticket.Request a Kerberos ticket by running the command:
[root@client ~]# kinit -T FILE:armor.ccache <username>@IDM.EXAMPLE.COM Enter your OTP Token Value.
Verification
Display your Kerberos ticket information:
[root@client ~]# klist -C Ticket cache: KCM:0:58420 Default principal: <username>@IDM.EXAMPLE.COM Valid starting Expires Service principal 05/09/22 07:48:23 05/10/22 07:03:07 krbtgt/IDM.EXAMPLE.COM@IDM.EXAMPLE.COM config: fast_avail(krbtgt/IDM.EXAMPLE.COM@IDM.EXAMPLE.COM) = yes 08/17/2022 20:22:45 08/18/2022 20:22:43 krbtgt/IDM.EXAMPLE.COM@IDM.EXAMPLE.COM config: pa_type(krbtgt/IDM.EXAMPLE.COM@IDM.EXAMPLE.COM) = 141
The
pa_type = 141
indicates OTP/RADIUS authentication.
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.
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
andsssctl
man pages on your system
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 on your system
8.12. Additional resources
Chapter 9. Preparing your environment for managing IdM using Ansible playbooks
As a system administrator managing Identity Management (IdM), when working with Red Hat Ansible Engine, it is good practice to do the following:
- Keep a subdirectory dedicated to Ansible playbooks in your home directory, for example ~/MyPlaybooks.
-
Copy and adapt sample Ansible playbooks from the
/usr/share/doc/ansible-freeipa/*
and/usr/share/doc/rhel-system-roles/*
directories and subdirectories into your ~/MyPlaybooks directory. - Include your inventory file in your ~/MyPlaybooks directory.
Using this practice, you can find all your playbooks in one place.
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
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 6-8 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
.
-
The target node, that is the node on which the
ansible-freeipa
module is executed, is part of the IdM domain as an IdM client, server or replica.
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
.
-
The target node, that is the node on which the
ansible-freeipa
module is executed, is part of the IdM domain as an IdM client, server or replica.
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
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
.
-
The target node, that is the node on which the
ansible-freeipa
module is executed, is part of the IdM domain as an IdM client, server or replica.
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
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 users as:
- Active — user accounts which can be actively used by their users.
- Stage — users cannot use these accounts. Create stage users 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 new user accounts. You can assign a UID manually by using the --uid=INT
option with the ipa user-add
command, but the server does not validate whether the UID number is unique. Consequently, multiple user entries might have the same UID number. A similar problem can occur with user private group IDs (GIDs) if you assign a GID to a user account manually by using the --gidnumber=INT
option. To check if you have multiple user entries with the same ID, enter ipa user-find --uid=<uid>
or ipa user-find --gidnumber=<gidnumber>
.
Red Hat recommends you do not have multiple entries with the same UIDs or GIDs. If you have objects with duplicate IDs, security identifiers (SIDs) are not generated correctly. SIDs are crucial for trusts between IdM and Active Directory and for Kerberos authentication to work correctly.
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
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.
IdM automatically assigns a unique user ID (UID) to new user accounts. You can assign a UID manually, or even modify an already existing UID. However, the server does not validate whether the new UID number is unique. Consequently, multiple user entries might have the same UID number assigned. A similar problem can occur with user private group IDs (GIDs) if you assign GIDs to user accounts manually. You can use the ipa user-find --uid=<uid>
or ipa user-find --gidnumber=<gidnumber>
commands on the IdM CLI to check if you have multiple user entries with the same ID.
Red Hat recommends you do not have multiple entries with the same UIDs or GIDs. If you have objects with duplicate IDs, security identifiers (SIDs) are not generated correctly. SIDs are crucial for trusts between IdM and Active Directory and for Kerberos authentication to work correctly.
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
.
-
The target node, that is the node on which the
ansible-freeipa
module is executed, is part of the IdM domain as an IdM client, server or replica.
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
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
.
-
The target node, that is the node on which the
ansible-freeipa
module is executed, is part of the IdM domain as an IdM client, server or replica.
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
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
.
-
The target node, that is the node on which the
ansible-freeipa
module is executed, is part of the IdM domain as an IdM client, server or replica.
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
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
.
-
The target node, that is the node on which the
ansible-freeipa
module is executed, is part of the IdM domain as an IdM client, server or replica.
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
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.
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
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
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
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)
14.13. Using Ansible to give a user ID override access to the local sound card on an IdM client
You can use the ansible-freeipa
group
and idoverrideuser
modules to make Identity Management (IdM) or Active Directory (AD) users members of the local audio
group on an IdM client. This grants the IdM or AD users privileged access to the sound card on the host. The procedure uses the example of the Default Trust View
ID view to which the aduser@addomain.com ID override is added in the first playbook task. In the next playbook task, an audio group is created in IdM with the GID of 63, which corresponds to the GID of local audio
groups on RHEL hosts. At the same time, the aduser@addomain.com ID override is added to the IdM audio group as a member.
Prerequisites
-
You have
root
access to the IdM client on which you want to perform the first part of the procedure. In the example, this is client.idm.example.com. 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. - You are using RHEL 8.10 or later.
- 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 AD forest is in trust with IdM. In the example, the name of the AD domain is addomain.com and the fully-qualified domain name (FQDN) of the AD user whose presence in the local
audio
group is being ensured is aduser@addomain.com. -
The target node, that is the node on which the
ansible-freeipa
module is executed, is part of the IdM domain as an IdM client, server or replica.
Procedure
On client.idm.example.com, add
[SUCCESS=merge]
to the/etc/nsswitch.conf
file:[...] # Allow initgroups to default to the setting for group. initgroups: sss [SUCCESS=merge] files
Identify the GID of the local
audio
group:$ getent group audio --------------------- audio:x:63
On your Ansible control node, create an add-aduser-to-audio-group.yml playbook with a task to add the aduser@addomain.com user override to the Default Trust View:
--- - name: Playbook to manage idoverrideuser hosts: ipaserver become: false tasks: - name: Add aduser@addomain.com user to the Default Trust View ipaidoverrideuser: ipaadmin_password: "{{ ipaadmin_password }}" idview: "Default Trust View" anchor: aduser@addomain.com
Use another playbook task in the same playbook to add the group audio to IdM with the
GID
of 63. Add the aduser idoverrideuser to the group:- name: Add the audio group with the aduser member and GID of 63 ipagroup: ipaadmin_password: "{{ ipaadmin_password }}" name: audio idoverrideuser: - aduser@addomain.com gidnumber: 63
- 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-aduser-to-audio-group.yml
Verification
Log in to the IdM client as the AD user:
$ ssh aduser@addomain.com@client.idm.example.com
Verify the group membership of the AD user:
$ id aduser@addomain.com uid=702801456(aduser@addomain.com) gid=63(audio) groups=63(audio)
Additional resources
-
The idoverrideuser and ipagroup
ansible-freeipa
upstream documentation - Enabling group merging for local and remote groups in IdM
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.
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
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
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.
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 target node, that is the node on which the
ansible-freeipa
module is executed, is part of the IdM domain as an IdM client, server or replica. - 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
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
.
-
The target node, that is the node on which the
ansible-freeipa
module is executed, is part of the IdM domain as an IdM client, server or replica.
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
.
-
The target node, that is the node on which the
ansible-freeipa
module is executed, is part of the IdM domain as an IdM client, server or replica. - 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
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 on your system.
16.7. Ensuring the absence of member managers in IdM user groups using Ansible playbooks
The followin