Menu Close
Managing IdM users, groups, hosts, and access control rules
Configuring users and hosts, managing them in groups, and controlling access with host-based (HBAC) and role-based access control (RBAC) rules
Abstract
Making open source more inclusive
Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.
Providing feedback on Red Hat documentation
We appreciate your input on our documentation. Please let us know how we could make it better.
For simple comments on specific passages:
- Make sure you are viewing the documentation in the Multi-page HTML format. In addition, ensure you see the Feedback button in the upper right corner of the document.
- Use your mouse cursor to highlight the part of text that you want to comment on.
- Click the Add Feedback pop-up that appears below the highlighted text.
- Follow the displayed instructions.
For submitting feedback via Bugzilla, create a new ticket:
- Go to the Bugzilla website.
- As the Component, use Documentation.
- Fill in the Description field with your suggestion for improvement. Include a link to the relevant part(s) of documentation.
- Click Submit Bug.
Chapter 1. Introduction to the IdM command-line utilities
The following sections describe 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.
1.1. What is the IPA command line interface
The IPA command line interface (CLI) is the basic command-line interface for Identity Management (IdM) administration.
It supports a lot of subcommands that are used to manage IdM, such as the ipa user-add
command to add a new user.
IPA CLI allows you to:
- Add, manage, or remove users, groups, hosts and other objects in the network.
- Manage certificates.
- Search entries.
- Display and list objects.
- Set access rights.
- Get help with the correct command syntax.
1.2. What is the IPA help
The IPA help is a built-in documentation system for the IdM server.
IPA command line interface (CLI) generates available help topics from loaded IdM plugin modules. If you want to run the IPA help successfully, you need to:
- Have an IdM server installed and running.
- Be authenticated with a valid Kerberos ticket.
Executing the ipa help
command without options displays information about basic help usage and the most common command examples.
Executing help with options has the following syntax:
$ ipa help [TOPIC | COMMAND | topics | commands]
-
[]
— Brackets mean that all parameters are optional and you can write justipa help
and the command will be executed. -
|
— The pipe character means or. Therefore, you can use TOPIC or COMMAND or topics or commands with the basicipa help
command. -
topics
— You can run the commandipa help topics
and it will execute correctly. The command displays a list of topics that are covered by IPA help, for example,user
,cert
,server
and many others. -
TOPIC
— The TOPIC with capital letters means variable, therefore, you can use the particular topic, for example,ipa help user
-
commands
— You can run the commandipa help commands
and it will execute correctly. The command displays a list of commands which are covered by the IPA help, for example,user-add
,ca-enable
,server-show
and many others. -
COMMAND
— The COMMAND with capital letters means variable, therefore, you can use the particular command, for example,ipa help user-add
1.3. Using IPA help topics
The following procedure helps you to understand using the IPA help in the command line interface.
Procedure
- Open 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 command is too long and you cannot see the whole text, use the following syntax:
$ ipa help user | less
You can then scroll down and read the whole help.
The IPA CLI displays a help page for the user
topic. After reading the overview, you can see many examples with patterns for working with topic commands.
1.4. Using IPA help commands
The following procedure helps you to understand creating the IPA help commands in the command line interface.
Procedure
- Open terminal and connect to the IdM server.
Enter
ipa help commands
to display a list of commands covered by help.$ ipa help commands
Select one of the commands and create a help command according to the following pattern:
ipa help <COMMAND>
, instead of the<COMMAND>
string, add one of the commands you listed in the previous step.$ ipa help user-add
Additional resources
-
The
ipa
man page.
1.5. Structure of IPA commands
The IPA CLI distinguishes the following types of commands:
- Built-in commands — Built-in commands are all available in the IdM server.
- Plug-in provided commands
Structure of IPA commands allows you to manage various types of objects. For example:
- Users,
- Hosts,
- DNS records,
- Certificates,
and many others.
For most of these objects, the IPA CLI includes commands to:
-
Add (
add
) -
Modify (
mod
) -
Delete (
del
) -
Search (
find
) -
Display (
show
)
Commands have the following structure:
ipa user-add
, ipa user-mod
, ipa user-del
, ipa user-find
, ipa user-show
ipa host-add
, ipa host-mod
, ipa host-del
, ipa host-find
, ipa host-show
ipa dnsrecord-add
, ipa dnsrecord-mod
, ipa dnsrecord-del
, ipa dnsrecord-find
, ipa dnrecord-show
You can create a user with the ipa user-add [options]
, where [options]
are optional. If you use just the ipa user-add
command, the script asks you for details one by one.
To change an existing object, you need to define the object, therefore the command includes also object: ipa user-mod USER_NAME [options]
.
1.6. Using an IPA command to add a user account to IdM
The following describes adding a new user to the Identity Management (IdM) database using command line.
Prerequisites
- You need to have administrator privileges to add user accounts to the IdM server.
Procedure
- Open terminal and connect to the IdM server.
Enter the command for adding a new user:
$ ipa user-add
The command runs a script where you can add basic data necessary for creating a user account.
- 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 if the suggested user name works for you.
User name must be unique for the whole IdM database. If an error occurs, that the user already exists, you need to start from the beginning with the
ipa user-add
command and try a different user name.
After you successfully added the user name, the user account has been added to the IdM database and the IPA command line interface (CLI) prints on the output the following log:
---------------------- Added user "euser" ---------------------- User login: euser First name: Example Last name: User Full name: Example User Display name: Example User Initials: EU Home directory: /home/euser GECOS: Example User Login shell: /bin/sh Principal name: euser@IDM.EXAMPLE.COM Principal alias: euser@IDM.EXAMPLE.COM Email address: euser@idm.example.com UID: 427200006 GID: 427200006 Password: False Member of groups: ipausers Kerberos keys available: False
As you can see, a user password is not set to the user account. If you want to add also password, use the ipa user-add
command in the following syntax:
$ ipa user-add --first=Example --last=User --password
The IPA CLI then asks you for adding or confirming a user name and password.
If the user has been already created, you can add only the password with the ipa user-mod
command.
Additional resources
-
Run the
ipa help user-add
command for more information about parameters.
1.7. Using an IPA command to modify a user account in IdM
You can change many parameters for each user account. For example, you can add a new password to the user.
Basic command syntax is different from the user-add
syntax because you need to define the existing user account for which you want to perform changes, for example, add a password.
Prerequisites
- You need to have administrator privileges to modify user accounts in the IdM server.
Procedure
- Open terminal and connect to the IdM server.
Enter the command 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.
After you successfully added the user name, the user account has been added to the IdM database and the IPA CLI prints on the output the following log:
---------------------- Modified user "euser" ---------------------- User login: euser First name: Example Last name: User Home directory: /home/euser Principal name: euser@IDM.EXAMPLE.COM Principal alias: euser@IDM.EXAMPLE.COM Email address: euser@idm.example.com UID: 427200006 GID: 427200006 Password: True Member of groups: ipausers Kerberos keys available: True
The user password is now set for the account and the user can log into IdM.
Additional resources
-
Run the
ipa help user-mod
command for more information about parameters.
1.8. How to supply a list of values to the IdM utilities
Identity Management (IdM) stores values for multi-valued attributes in lists.
IdM supports the following methods of supplying multi-valued lists:
Using the same command-line argument multiple times within the same command invocation:
$ ipa permission-add --right=read --permissions=write --permissions=delete ...
Alternatively, you can enclose the list in curly braces, in which case the shell performs the expansion:
$ ipa permission-add --right={read,write,delete} ...
Examples above show a command permission-add
which adds permissions to an object. The object is not mentioned in the example. Instead of …
you need to add the object for which you want to add permissions.
When you update such multi-valued attributes from the command line, IdM completely overwrites the previous list of values with a new list. Therefore, when updating a multi-valued attribute, you must specify the whole new list, not just a single value you want to add.
In the command above, the list of permissions includes reading, writing and deleting. When you decide to update the list with the permission-mod
command, you must add all values, otherwise those not mentioned will be deleted.
Example 1: — The ipa permission-mod
command updates all previously added permissions.
$ ipa permission-mod --right=read --right=write --right=delete ...
or
$ ipa permission-mod --right={read,write,delete} ...
Example 2 — The ipa permission-mod
command deletes the --right=delete
argument because it is not included in the command:
$ ipa permission-mod --right=read --right=write ...
or
$ ipa permission-mod --right={read,write} ...
1.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 2. Managing user accounts using the command line
This chapter includes basic description of user life cycle in IdM (Identity Management). The following sections show you how to:
- Create user accounts
- Activate stage user accounts
- Preserve user accounts
- Delete active, stage, or preserved user accounts
- Restore preserved user accounts
2.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.
2.2. Adding users using the command line
You can add user as:
- Active — user accounts which can be actively used by their users.
- Stage — users cannot use these accounts. Use it if you want to prepare new user accounts. When users are ready to use their accounts, then you can activate them.
The following procedure describes adding active users to the IdM server with the ipa user-add
command.
Similarly, you can create stage user accounts with the ipa stageuser-add
command.
IdM automatically assigns a unique user ID (UID) to the new user accounts. You can also do this manually, however, the server does not validate whether the UID number is unique. Due to this, multiple user entries might have the same ID number assigned. Red Hat recommends to prevent having multiple entries with the same UID.
Prerequisites
- Administrator privileges for managing IdM or User Administrator role.
- Obtained a Kerberos ticket. For details, see Using kinit to log in to IdM manually.
Procedure
- Open terminal and connect to the IdM server.
Add user login, user’s first name, last name and optionally, you can also add their email address.
$ ipa user-add user_login --first=first_name --last=last_name --email=email_address
IdM supports user names that can be described by the following regular expression:
[a-zA-Z0-9_.][a-zA-Z0-9_.-]{0,252}[a-zA-Z0-9_.$-]?
NoteUser names ending with the trailing dollar sign ($) are supported to enable Samba 3.x machine support.
If you add a user name containing uppercase characters, IdM automatically converts the name to lowercase when saving it. Therefore, IdM always requires to enter user names in lowercase when logging in. Additionally, it is not possible to add user names which differ only in letter casing, such as user and User.
The default maximum length for user names is 32 characters. To change it, use the
ipa config-mod --maxusername
command. For example, to increase the maximum user name length to 64 characters:$ ipa config-mod --maxusername=64 Maximum username length: 64 ...
The
ipa user-add
command includes a lot of parameters. To list them all, use the ipa help command:$ ipa help user-add
For details about
ipa help
command, see What is the IPA help.
You can verify if the new user account is successfully created by listing all IdM user accounts:
$ ipa user-find
This command lists all user accounts with details.
2.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.
2.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.
2.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.
2.6. Restoring users using the command line
You can restore a preserved users to:
-
Active users:
ipa user-undel
-
Stage users:
ipa user-stage
Restoring a user account does not restore all of the account’s previous attributes. For example, the user’s password is not restored and must be set again.
Prerequisites
- Administrator privileges for managing IdM or User Administrator role.
- Obtained a Kerberos ticket. For details, see Using kinit to log in to IdM manually.
Procedure
- Open terminal and connect to the IdM server.
Activate the user account with the following command:
$ ipa user-undel user_login ------------------------------ Undeleted user account "user_login" ------------------------------
Alternatively, you can restore user accounts as staged:
$ ipa user-stage user_login ------------------------------ Staged user account "user_login" ------------------------------
Verification steps
You can verify if the new user account is successfully created by listing all IdM user accounts:
$ ipa user-find
This command lists all user accounts with details.
Chapter 3. Managing user accounts using the IdM Web UI
Identity Management (IdM) provides several stages that can help you to manage various user work life situations:
- Creating a user account
Creating a stage user account before an employee starts their career in your company and be prepared in advance for the day when the employee appears in the office and want to activate the account.
You can omit this step and create the active user account directly. The procedure is similar to creating a stage user account.
- Activating a user account
- Activating the account the first working day of the employee.
- Disabling a user account
- If the user go to a parental leave for couple of months, you will need to disable the account temporarily.
- Enabling a user account
- When the user returns, you will need to re-enable the account.
- Preserving a user account
- If the user wants to leave the company, you will need to delete the account with a possibility to restore it because people can return to the company after some time.
- Restoring a user account
- Two years later, the user is back and you need to restore the preserved account.
- Deleting a user account
- If the employee the employee is dismissed you will delete the account without a backup.
3.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.
3.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.
3.3. Activating stage users in the IdM Web UI
A stage user account must be activated before the user can log in to IdM and before the user can be added to an IdM group. This section describes how to activate stage user accounts.
Prerequisites
- Administrator privileges for managing the IdM Web UI or User Administrator role.
- At least one staged user account in IdM.
Procedure
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.
- In the Confirmation dialog box, click on the OK button.
If the activation is successful, the IdM Web UI displays a green confirmation that the user has been activated and the user account has been moved to Active users. The account is active and the user can authenticate to the IdM domain and IdM Web UI. The user is prompted to change their password on the first login.
At this stage, you can add the active user account to user groups.
3.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.
3.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.
3.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.
3.7. Restoring users in the IdM Web UI
IdM (Identity Management) enables you to restore preserved user accounts back in the active state.
Prerequisites
- Administrator privileges for managing the IdM Web UI or User Administrator role.
Procedure
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.
3.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 4. 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.
4.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.
4.2. Ensuring the presence of an IdM user using an Ansible playbook
The following procedure describes ensuring the presence of a user in IdM using an Ansible playbook.
Prerequisites
- You know the IdM administator password.
- The ansible-freeipa package is installed on the Ansible controller.
Procedure
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 become: true tasks: - name: Create user idm_user ipauser: ipaadmin_password: MySecret123 name: idm_user first: Alice last: Acme uid: 1000111 gid: 10011 phone: "+555123457" email: idm_user@acme.com passwordexpiration: "2023-01-19 23:59:59" password: "Password123" update_password: on_create
You must use the following options to add a user:
- name: the login name
- first: the first name string
- last: the last name string
For the full list of available user options, see the
/usr/share/doc/ansible-freeipa/README-user.md
Markdown file.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 -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/add-IdM-user.yml
Verification steps
You can verify if the new user account exists in IdM by using the
ipa user-show
command:Log into
ipaserver
as admin:$ ssh admin@server.idm.example.com Password: [admin@server /]$
Request a Kerberos ticket for admin:
$ kinit admin Password for admin@IDM.EXAMPLE.COM:
Request information about idm_user:
$ ipa user-show idm_user User login: idm_user First name: Alice Last name: Acme ....
The user named idm_user is present in IdM.
4.3. Ensuring the presence of multiple IdM users using Ansible playbooks
The following procedure describes ensuring the presence of multiple users in IdM using an Ansible playbook.
Prerequisites
- You know the IdM administator password.
- You have installed the ansible-freeipa package on the Ansible controller.
Procedure
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 become: true tasks: - name: Create user idm_users ipauser: ipaadmin_password: MySecret123 users: - name: idm_user_1 first: Alice last: Acme uid: 10001 gid: 10011 phone: "+555123457" email: idm_user@acme.com passwordexpiration: "2023-01-19 23:59:59" password: "Password123" - name: idm_user_2 first: Bob last: Acme uid: 100011 gid: 10011 - name: idm_user_3 first: Eve last: Acme uid: 1000111 gid: 10011
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 -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/add-users.yml
Verification steps
You can verify if the user account exists in IdM by using the
ipa user-show
command:Log into
ipaserver
as administrator:$ ssh administrator@server.idm.example.com Password: [admin@server /]$
Display information about idm_user_1:
$ ipa user-show idm_user_1 User login: idm_user_1 First name: Alice Last name: Acme Password: True ....
The user named idm_user_1 is present in IdM.
4.4. Ensuring the presence of multiple IdM users from a JSON file using Ansible playbooks
The following procedure describes how you can ensure the presence of multiple users in IdM using an Ansible playbook. The users are stored in a JSON
file.
Prerequisites
- You know the IdM administator password.
- You have installed the ansible-freeipa package on the Ansible controller.
Procedure
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 become: true tasks: - name: Include users.json include_vars: file: users.json - name: Users present ipauser: ipaadmin_password: MySecret123 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 specifying the playbook file and the inventory file:
$ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-users-present-jsonfile.yml
Verification steps
You can verify if the user accounts are present in IdM using the
ipa user-show
command: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.
4.5. Ensuring the absence of users using Ansible playbooks
The following procedure describes how you can use an Ansible playbook to ensure that specific users are absent from IdM.
Prerequisites
- You know the IdM administator password.
- You have installed the ansible-freeipa package on the Ansible controller.
Procedure
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 become: true tasks: - name: Delete users idm_user_1, idm_user_2, idm_user_3 ipauser: ipaadmin_password: MySecret123 users: - name: idm_user_1 - name: idm_user_2 - name: idm_user_3 state: absent
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/delete-users.yml
Verification steps
You can verify that the user accounts do not exist in IdM by using the ipa user-show
command:
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.
4.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 5. Granting sudo access to an IdM user on an IdM client
This section describes how to grant sudo
access to users in Identity Management.
5.1. Sudo access on an IdM client
System administrators can grant sudo
access to allow non-root users to execute administrative commands that are normally reserved for the root
user. Consequently, when users need to perform an administrative command normally reserved for the root
user, they precede that command with sudo
. After entering their password, the command is executed as if they were the root
user. To execute a sudo
command as another user or group, such as a database service account, you can configure a RunAs alias for a sudo
rule.
If a Red Hat Enterprise Linux (RHEL) 8 host is enrolled as an Identity Management (IdM) client, you can specify sudo
rules defining which IdM users can perform which commands on the host in the following ways:
-
Locally in the
/etc/sudoers
file - Centrally in IdM
This section describes creating a central sudo
rule for an IdM client using the command line interface (CLI) and the IdM Web UI.
You can also configure password-less authentication for sudo
using the Generic Security Service Application Programming Interface (GSSAPI), the native way for UNIX-based operating systems to access and authenticate Kerberos services. You can use the pam_sss_gss.so
Pluggable Authentication Module (PAM) to invoke GSSAPI authentication via the SSSD service, allowing users to authenticate to the sudo
command with a valid Kerberos ticket.
Additional resources
- See Managing sudo access.
5.2. Granting sudo access to an IdM user on an IdM client using the CLI
In Identity Management (IdM), you can grant sudo
access for a specific command to an IdM user account on a specific IdM host. First, add a sudo
command and then create a sudo
rule for one or more commands.
For example, complete this procedure to create the idm_user_reboot
sudo
rule to grant the idm_user
account the permission to run the /usr/sbin/reboot
command on the idmclient
machine.
Prerequisites
- You are logged in as IdM administrator.
-
You have created a user account for
idm_user
in IdM and unlocked the account by creating a password for the user. For details on adding a new IdM user using the CLI, see Adding users using the command line. -
No local
idm_user
account is present on theidmclient
host. Theidm_user
user is not listed in the local/etc/passwd
file.
Procedure
Retrieve a Kerberos ticket as the IdM
admin
.[root@idmclient ~]# kinit admin
Add the
/usr/sbin/reboot
command to the IdM database ofsudo
commands:[root@idmclient ~]# ipa sudocmd-add /usr/sbin/reboot ------------------------------------- Added Sudo Command "/usr/sbin/reboot" ------------------------------------- Sudo Command: /usr/sbin/reboot
Create a
sudo
rule namedidm_user_reboot
:[root@idmclient ~]# ipa sudorule-add idm_user_reboot --------------------------------- Added Sudo Rule "idm_user_reboot" --------------------------------- Rule name: idm_user_reboot Enabled: TRUE
Add the
/usr/sbin/reboot
command to theidm_user_reboot
rule:[root@idmclient ~]# ipa sudorule-add-allow-command idm_user_reboot --sudocmds '/usr/sbin/reboot' Rule name: idm_user_reboot Enabled: TRUE Sudo Allow Commands: /usr/sbin/reboot ------------------------- Number of members added 1 -------------------------
Apply the
idm_user_reboot
rule to the IdMidmclient
host:[root@idmclient ~]# ipa sudorule-add-host idm_user_reboot --hosts idmclient.idm.example.com Rule name: idm_user_reboot Enabled: TRUE Hosts: idmclient.idm.example.com Sudo Allow Commands: /usr/sbin/reboot ------------------------- Number of members added 1 -------------------------
Add the
idm_user
account to theidm_user_reboot
rule:[root@idmclient ~]# ipa sudorule-add-user idm_user_reboot --users idm_user Rule name: idm_user_reboot Enabled: TRUE Users: idm_user Hosts: idmclient.idm.example.com Sudo Allow Commands: /usr/sbin/reboot ------------------------- Number of members added 1 -------------------------
Propagating the changes from the server to the client can take a few minutes.
Verification steps
-
Log in to the
idmclient
host as theidm_user
account. Display which
sudo
rules theidm_user
account is allowed to perform.[idm_user@idmclient ~]$ sudo -l Matching Defaults entries for idm_user on idmclient: !visiblepw, always_set_home, match_group_by_gid, always_query_group_plugin, env_reset, env_keep="COLORS DISPLAY HOSTNAME HISTSIZE KDEDIR LS_COLORS", env_keep+="MAIL PS1 PS2 QTDIR USERNAME LANG LC_ADDRESS LC_CTYPE", env_keep+="LC_COLLATE LC_IDENTIFICATION LC_MEASUREMENT LC_MESSAGES", env_keep+="LC_MONETARY LC_NAME LC_NUMERIC LC_PAPER LC_TELEPHONE", env_keep+="LC_TIME LC_ALL LANGUAGE LINGUAS _XKB_CHARSET XAUTHORITY KRB5CCNAME", secure_path=/sbin\:/bin\:/usr/sbin\:/usr/bin User idm_user may run the following commands on idmclient: (root) /usr/sbin/reboot
Reboot the machine using
sudo
. Enter the password foridm_user
when prompted:[idm_user@idmclient ~]$ sudo /usr/sbin/reboot [sudo] password for idm_user:
5.3. Granting sudo access to an IdM user on an IdM client using the IdM Web UI
In Identity Management (IdM), you can grant sudo
access for a specific command to an IdM user account on a specific IdM host. First, add a sudo
command and then create a sudo
rule for one or more commands.
Complete this procedure to create the idm_user_reboot
sudo rule to grant the idm_user
account the permission to run the /usr/sbin/reboot
command on the idmclient
machine.
Prerequisites
- You are logged in as IdM administrator.
-
You have created a user account for
idm_user
in IdM and unlocked the account by creating a password for the user. For details on adding a new IdM user using the command-line interface, see Adding users using the command line. -
No local
idm_user
account is present on theidmclient
host. Theidm_user
user is not listed in the local/etc/passwd
file.
Procedure
Add the
/usr/sbin/reboot
command to the IdM database ofsudo
commands:- Navigate to Policy → Sudo → Sudo Commands.
- Click Add in the upper right corner to open the Add sudo command dialog box.
Enter the command you want the user to be able to perform using
sudo
:/usr/sbin/reboot
.Figure 5.1. Adding IdM sudo command
- Click Add.
Use the new
sudo
command entry to create a sudo rule to allow idm_user to reboot the idmclient machine:- Navigate to Policy → Sudo → Sudo rules.
- Click Add in the upper right corner to open the Add sudo rule dialog box.
-
Enter the name of the
sudo
rule: idm_user_reboot. - Click Add and Edit.
Specify the user:
- In the Who section, check the Specified Users and Groups radio button.
- In the User category the rule applies to subsection, click Add to open the Add users into sudo rule "idm_user_reboot" dialog box.
- In the Add users into sudo rule "idm_user_reboot" dialog box in the Available column, check the idm_user checkbox, and move it to the Prospective column.
- Click Add.
Specify the host:
- In the Access this host section, check the Specified Hosts and Groups radio button.
- In the Host category this rule applies to subsection, click Add to open the Add hosts into sudo rule "idm_user_reboot" dialog box.
- In the Add hosts into sudo rule "idm_user_reboot" dialog box in the Available column, check the idmclient.idm.example.com checkbox, and move it to the Prospective column.
- Click Add.
Specify the commands:
- In the Command category the rule applies to subsection of the Run Commands section, check the Specified Commands and Groups radio button.
- In the Sudo Allow Commands subsection, click Add to open the Add allow sudo commands into sudo rule "idm_user_reboot" dialog box.
-
In the Add allow sudo commands into sudo rule "idm_user_reboot" dialog box in the Available column, check the
/usr/sbin/reboot
checkbox, and move it to the Prospective column. - Click Add to return to the idm_sudo_reboot page.
Figure 5.2. Adding IdM sudo rule
- Click Save in the top left corner.
The new rule is enabled by default.
Propagating the changes from the server to the client can take a few minutes.
Verification steps
-
Log in to
idmclient
asidm_user
. Reboot the machine using
sudo
. Enter the password foridm_user
when prompted:$ sudo /usr/sbin/reboot [sudo] password for idm_user:
If the sudo
rule is configured correctly, the machine reboots.
5.4. Creating a sudo rule on the CLI that runs a command as a service account on an IdM client
In IdM, you can configure a sudo
rule with a RunAs alias to run a sudo
command as another user or group. For example, you might have an IdM client that hosts a database application, and you need to run commands as the local service account that corresponds to that application.
Use this example to create a sudo
rule on the command line called run_third-party-app_report
to allow the idm_user
account to run the /opt/third-party-app/bin/report
command as the thirdpartyapp
service account on the idmclient
host.
Prerequisites
- You are logged in as IdM administrator.
-
You have created a user account for
idm_user
in IdM and unlocked the account by creating a password for the user. For details on adding a new IdM user using the CLI, see Adding users using the command line. -
No local
idm_user
account is present on theidmclient
host. Theidm_user
user is not listed in the local/etc/passwd
file. -
You have a custom application named
third-party-app
installed on theidmclient
host. -
The
report
command for thethird-party-app
application is installed in the/opt/third-party-app/bin/report
directory. -
You have created a local service account named
thirdpartyapp
to execute commands for thethird-party-app
application.
Procedure
Retrieve a Kerberos ticket as the IdM
admin
.[root@idmclient ~]# kinit admin
Add the
/opt/third-party-app/bin/report
command to the IdM database ofsudo
commands:[root@idmclient ~]# ipa sudocmd-add /opt/third-party-app/bin/report ---------------------------------------------------- Added Sudo Command "/opt/third-party-app/bin/report" ---------------------------------------------------- Sudo Command: /opt/third-party-app/bin/report
Create a
sudo
rule namedrun_third-party-app_report
:[root@idmclient ~]# ipa sudorule-add run_third-party-app_report -------------------------------------------- Added Sudo Rule "run_third-party-app_report" -------------------------------------------- Rule name: run_third-party-app_report Enabled: TRUE
Use the
--users=<user>
option to specify the RunAs user for thesudorule-add-runasuser
command:[root@idmclient ~]# ipa sudorule-add-runasuser run_third-party-app_report --users=thirdpartyapp Rule name: run_third-party-app_report Enabled: TRUE RunAs External User: thirdpartyapp ------------------------- Number of members added 1 -------------------------
The user (or group specified with the
--groups=*
option) can be external to IdM, such as a local service account or an Active Directory user. Do not add a%
prefix for group names.Add the
/opt/third-party-app/bin/report
command to theidm_user_reboot
rule:[root@idmclient ~]# ipa sudorule-add-allow-command run_third-party-app_report --sudocmds '/opt/third-party-app/bin/report' Rule name: run_third-party-app_report Enabled: TRUE Sudo Allow Commands: /opt/third-party-app/bin/report RunAs External User: thirdpartyapp ------------------------- Number of members added 1 -------------------------
Apply the
run_third-party-app_report
rule to the IdMidmclient
host:[root@idmclient ~]# ipa sudorule-add-host run_third-party-app_report --hosts idmclient.idm.example.com Rule name: run_third-party-app_report Enabled: TRUE Hosts: idmclient.idm.example.com Sudo Allow Commands: /opt/third-party-app/bin/report RunAs External User: thirdpartyapp ------------------------- Number of members added 1 -------------------------
Add the
idm_user
account to therun_third-party-app_report
rule:[root@idmclient ~]# ipa sudorule-add-user run_third-party-app_report --users idm_user Rule name: run_third-party-app_report Enabled: TRUE Users: idm_user Hosts: idmclient.idm.example.com Sudo Allow Commands: /opt/third-party-app/bin/report RunAs External User: thirdpartyapp ------------------------- Number of members added 1
Propagating the changes from the server to the client can take a few minutes.
Verification steps
-
Log in to the
idmclient
host as theidm_user
account. Test the new sudo rule:
Display which
sudo
rules theidm_user
account is allowed to perform.[idm_user@idmclient ~]$ sudo -l Matching Defaults entries for idm_user@idm.example.com on idmclient: !visiblepw, always_set_home, match_group_by_gid, always_query_group_plugin, env_reset, env_keep="COLORS DISPLAY HOSTNAME HISTSIZE KDEDIR LS_COLORS", env_keep+="MAIL PS1 PS2 QTDIR USERNAME LANG LC_ADDRESS LC_CTYPE", env_keep+="LC_COLLATE LC_IDENTIFICATION LC_MEASUREMENT LC_MESSAGES", env_keep+="LC_MONETARY LC_NAME LC_NUMERIC LC_PAPER LC_TELEPHONE", env_keep+="LC_TIME LC_ALL LANGUAGE LINGUAS _XKB_CHARSET XAUTHORITY KRB5CCNAME", secure_path=/sbin\:/bin\:/usr/sbin\:/usr/bin User idm_user@idm.example.com may run the following commands on idmclient: (thirdpartyapp) /opt/third-party-app/bin/report
Run the
report
command as thethirdpartyapp
service account.[idm_user@idmclient ~]$ sudo -u thirdpartyapp /opt/third-party-app/bin/report [sudo] password for idm_user@idm.example.com: Executing report... Report successful.
5.5. Creating a sudo rule in the IdM WebUI that runs a command as a service account on an IdM client
In IdM, you can configure a sudo
rule with a RunAs alias to run a sudo
command as another user or group. For example, you might have an IdM client that hosts a database application, and you need to run commands as the local service account that corresponds to that application.
Use this example to create a sudo
rule in the IdM WebUI called run_third-party-app_report
to allow the idm_user
account to run the /opt/third-party-app/bin/report
command as the thirdpartyapp
service account on the idmclient
host.
Prerequisites
- You are logged in as IdM administrator.
-
You have created a user account for
idm_user
in IdM and unlocked the account by creating a password for the user. For details on adding a new IdM user using the CLI, see Adding users using the command line. -
No local
idm_user
account is present on theidmclient
host. Theidm_user
user is not listed in the local/etc/passwd
file. -
You have a custom application named
third-party-app
installed on theidmclient
host. -
The
report
command for thethird-party-app
application is installed in the/opt/third-party-app/bin/report
directory. -
You have created a local service account named
thirdpartyapp
to execute commands for thethird-party-app
application.
Procedure
Add the
/opt/third-party-app/bin/report
command to the IdM database ofsudo
commands:- Navigate to Policy → Sudo → Sudo Commands.
- Click Add in the upper right corner to open the Add sudo command dialog box.
Enter the command:
/opt/third-party-app/bin/report
.- Click Add.
Use the new
sudo
command entry to create the newsudo
rule:- Navigate to Policy → Sudo → Sudo rules.
- Click Add in the upper right corner to open the Add sudo rule dialog box.
Enter the name of the
sudo
rule: run_third-party-app_report.- Click Add and Edit.
Specify the user:
- In the Who section, check the Specified Users and Groups radio button.
- In the User category the rule applies to subsection, click Add to open the Add users into sudo rule "run_third-party-app_report" dialog box.
In the Add users into sudo rule "run_third-party-app_report" dialog box in the Available column, check the idm_user checkbox, and move it to the Prospective column.
- Click Add.
Specify the host:
- In the Access this host section, check the Specified Hosts and Groups radio button.
- In the Host category this rule applies to subsection, click Add to open the Add hosts into sudo rule "run_third-party-app_report" dialog box.
In the Add hosts into sudo rule "run_third-party-app_report" dialog box in the Available column, check the idmclient.idm.example.com checkbox, and move it to the Prospective column.
- Click Add.
Specify the commands:
- In the Command category the rule applies to subsection of the Run Commands section, check the Specified Commands and Groups radio button.
- In the Sudo Allow Commands subsection, click Add to open the Add allow sudo commands into sudo rule "run_third-party-app_report" dialog box.
In the Add allow sudo commands into sudo rule "run_third-party-app_report" dialog box in the Available column, check the
/opt/third-party-app/bin/report
checkbox, and move it to the Prospective column.- Click Add to return to the run_third-party-app_report page.
Specify the RunAs user:
- In the As Whom section, check the Specified Users and Groups radio button.
- In the RunAs Users subsection, click Add to open the Add RunAs users into sudo rule "run_third-party-app_report" dialog box.
In the Add RunAs users into sudo rule "run_third-party-app_report" dialog box, enter the
thirdpartyapp
service account in the External box and move it to the Prospective column.- Click Add to return to the run_third-party-app_report page.
- Click Save in the top left corner.
The new rule is enabled by default.
Figure 5.3. Details of the sudo rule

Propagating the changes from the server to the client can take a few minutes.
Verification steps
-
Log in to the
idmclient
host as theidm_user
account. Test the new sudo rule:
Display which
sudo
rules theidm_user
account is allowed to perform.[idm_user@idmclient ~]$ sudo -l Matching Defaults entries for idm_user@idm.example.com on idmclient: !visiblepw, always_set_home, match_group_by_gid, always_query_group_plugin, env_reset, env_keep="COLORS DISPLAY HOSTNAME HISTSIZE KDEDIR LS_COLORS", env_keep+="MAIL PS1 PS2 QTDIR USERNAME LANG LC_ADDRESS LC_CTYPE", env_keep+="LC_COLLATE LC_IDENTIFICATION LC_MEASUREMENT LC_MESSAGES", env_keep+="LC_MONETARY LC_NAME LC_NUMERIC LC_PAPER LC_TELEPHONE", env_keep+="LC_TIME LC_ALL LANGUAGE LINGUAS _XKB_CHARSET XAUTHORITY KRB5CCNAME", secure_path=/sbin\:/bin\:/usr/sbin\:/usr/bin User idm_user@idm.example.com may run the following commands on idmclient: (thirdpartyapp) /opt/third-party-app/bin/report
Run the
report
command as thethirdpartyapp
service account.[idm_user@idmclient ~]$ sudo -u thirdpartyapp /opt/third-party-app/bin/report [sudo] password for idm_user@idm.example.com: Executing report... Report successful.
5.6. Enabling GSSAPI authentication for sudo on an IdM client
The following procedure describes enabling Generic Security Service Application Program Interface (GSSAPI) authentication on an IdM client for the sudo
and sudo -i
commands via the pam_sss_gss.so
PAM module. With this configuration, IdM users can authenticate to the sudo
command with their Kerberos ticket.
Prerequisites
-
You have created a
sudo
rule for an IdM user that applies to an IdM host. For this example, you have created theidm_user_reboot
sudo
rule to grant theidm_user
account the permission to run the/usr/sbin/reboot
command on theidmclient
host. -
You need
root
privileges to modify the/etc/sssd/sssd.conf
file and PAM files in the/etc/pam.d/
directory.
Procedure
-
Open the
/etc/sssd/sssd.conf
configuration file. Add the following entry to the
[domain/<domain_name>]
section.[domain/<domain_name>] pam_gssapi_services = sudo, sudo-i
-
Save and close the
/etc/sssd/sssd.conf
file. Restart the SSSD service to load the configuration changes.
[root@idmclient ~]# systemctl restart sssd
-
Open the
/etc/pam.d/sudo
PAM configuration file. Add the following entry as the first line of the
auth
section in the/etc/pam.d/sudo
file.#%PAM-1.0 auth sufficient pam_sss_gss.so auth include system-auth account include system-auth password include system-auth session include system-auth
-
Save and close the
/etc/pam.d/sudo
file. -
Open the
/etc/pam.d/sudo-i
PAM configuration file. Add the following entry as the first line of the
auth
section in the/etc/pam.d/sudo-i
file.#%PAM-1.0 auth sufficient pam_sss_gss.so auth include sudo account include sudo password include sudo session optional pam_keyinit.so force revoke session include sudo
-
Save and close the
/etc/pam.d/sudo-i
file.
Verification steps
Log into the host as the
idm_user
account.[root@idm-client ~]# ssh -l idm_user@idm.example.com localhost idm_user@idm.example.com's password:
Verify that you have a ticket-granting ticket as the
idm_user
account.[idmuser@idmclient ~]$ klist Ticket cache: KCM:1366201107 Default principal: idm_user@IDM.EXAMPLE.COM Valid starting Expires Service principal 01/08/2021 09:11:48 01/08/2021 19:11:48 krbtgt/IDM.EXAMPLE.COM@IDM.EXAMPLE.COM renew until 01/15/2021 09:11:44
(Optional) If you do not have Kerberos credentials for the
idm_user
account, destroy your current Kerberos credentials and request the correct ones.[idm_user@idmclient ~]$ kdestroy -A [idm_user@idmclient ~]$ kinit idm_user@IDM.EXAMPLE.COM Password for idm_user@idm.example.com:
Reboot the machine using
sudo
, without specifying a password.[idm_user@idmclient ~]$ sudo /usr/sbin/reboot
Additional resources
- The GSSAPI entry in the IdM terminology listing
- Granting sudo access to an IdM user on an IdM client using IdM Web UI
- Granting sudo access to an IdM user on an IdM client using the CLI.
-
pam_sss_gss (8)
man page -
sssd.conf (5)
man page
5.7. Enabling GSSAPI authentication and enforcing Kerberos authentication indicators for sudo on an IdM client
The following procedure describes enabling Generic Security Service Application Program Interface (GSSAPI) authentication on an IdM client for the sudo
and sudo -i
commands via the pam_sss_gss.so
PAM module. Additionally, only users who have logged in with a smart card will authenticate to those commands with their Kerberos ticket.
You can use this procedure as a template to configure GSSAPI authentication with SSSD for other PAM-aware services, and further restrict access to only those users that have a specific authentication indicator attached to their Kerberos ticket.
Prerequisites
-
You have created a
sudo
rule for an IdM user that applies to an IdM host. For this example, you have created theidm_user_reboot
sudo
rule to grant theidm_user
account the permission to run the/usr/sbin/reboot
command on theidmclient
host. -
You have configured smart card authentication for the
idmclient
host. -
You need
root
privileges to modify the/etc/sssd/sssd.conf
file and PAM files in the/etc/pam.d/
directory.
Procedure
-
Open the
/etc/sssd/sssd.conf
configuration file. Add the following entries to the
[domain/<domain_name>]
section.[domain/<domain_name>] pam_gssapi_services = sudo, sudo-i pam_gssapi_indicators_map = sudo:pkinit, sudo-i:pkinit
-
Save and close the
/etc/sssd/sssd.conf
file. Restart the SSSD service to load the configuration changes.
[root@idmclient ~]# systemctl restart sssd
-
Open the
/etc/pam.d/sudo
PAM configuration file. Add the following entry as the first line of the
auth
section in the/etc/pam.d/sudo
file.#%PAM-1.0 auth sufficient pam_sss_gss.so auth include system-auth account include system-auth password include system-auth session include system-auth
-
Save and close the
/etc/pam.d/sudo
file. -
Open the
/etc/pam.d/sudo-i
PAM configuration file. Add the following entry as the first line of the
auth
section in the/etc/pam.d/sudo-i
file.#%PAM-1.0 auth sufficient pam_sss_gss.so auth include sudo account include sudo password include sudo session optional pam_keyinit.so force revoke session include sudo
-
Save and close the
/etc/pam.d/sudo-i
file.
Verification steps
Log into the host as the
idm_user
account and authenticate with a smart card.[root@idmclient ~]# ssh -l idm_user@idm.example.com localhost PIN for smart_card
Verify that you have a ticket-granting ticket as the smart card user.
[idm_user@idmclient ~]$ klist Ticket cache: KEYRING:persistent:1358900015:krb_cache_TObtNMd Default principal: idm_user@IDM.EXAMPLE.COM Valid starting Expires Service principal 02/15/2021 16:29:48 02/16/2021 02:29:48 krbtgt/IDM.EXAMPLE.COM@IDM.EXAMPLE.COM renew until 02/22/2021 16:29:44
Display which
sudo
rules theidm_user
account is allowed to perform.[idm_user@idmclient ~]$ sudo -l Matching Defaults entries for idmuser on idmclient: !visiblepw, always_set_home, match_group_by_gid, always_query_group_plugin, env_reset, env_keep="COLORS DISPLAY HOSTNAME HISTSIZE KDEDIR LS_COLORS", env_keep+="MAIL PS1 PS2 QTDIR USERNAME LANG LC_ADDRESS LC_CTYPE", env_keep+="LC_COLLATE LC_IDENTIFICATION LC_MEASUREMENT LC_MESSAGES", env_keep+="LC_MONETARY LC_NAME LC_NUMERIC LC_PAPER LC_TELEPHONE", env_keep+="LC_TIME LC_ALL LANGUAGE LINGUAS _XKB_CHARSET XAUTHORITY KRB5CCNAME", secure_path=/sbin\:/bin\:/usr/sbin\:/usr/bin User idm_user may run the following commands on idmclient: (root) /usr/sbin/reboot
Reboot the machine using
sudo
, without specifying a password.[idm_user@idmclient ~]$ sudo /usr/sbin/reboot
Additional resources
- SSSD options controlling GSSAPI authentication for PAM services
- The GSSAPI entry in the IdM terminology listing
- Configuring Identity Management for smart card authentication
- Kerberos authentication indicators
- Granting sudo access to an IdM user on an IdM client using IdM Web UI
- Granting sudo access to an IdM user on an IdM client using the CLI.
-
pam_sss_gss (8)
man page -
sssd.conf (5)
man page
5.8. SSSD options controlling GSSAPI authentication for PAM services
You can use the following options for the /etc/sssd/sssd.conf
configuration file to adjust the GSSAPI configuration within the SSSD service.
- pam_gssapi_services
-
GSSAPI authentication with SSSD is disabled by default. You can use this option to specify a comma-separated list of PAM services that are allowed to try GSSAPI authentication using the
pam_sss_gss.so
PAM module. To explicitly disable GSSAPI authentication, set this option to-
. - pam_gssapi_indicators_map
This option only applies to Identity Management (IdM) domains. Use this option to list Kerberos authentication indicators that are required to grant PAM access to a service. Pairs must be in the format
<PAM_service>:_<required_authentication_indicator>_
.Valid authentication indicators are:
-
otp
for two-factor authentication -
radius
for RADIUS authentication -
pkinit
for PKINIT, smart card, or certificate authentication -
hardened
for hardened passwords
-
- pam_gssapi_check_upn
-
This option is enabled and set to
true
by default. If this option is enabled, the SSSD service requires that the user name matches the Kerberos credentials. Iffalse
, thepam_sss_gss.so
PAM module authenticates every user that is able to obtain the required service ticket.
Examples
The following options enable Kerberos authentication for the sudo
and sudo-i
services, requires that sudo
users authenticated with a one-time password, and user names must match the Kerberos principal. Because these settings are in the [pam]
section, they apply to all domains:
[pam] pam_gssapi_services = sudo, sudo-i pam_gssapi_indicators_map = sudo:otp pam_gssapi_check_upn = true
You can also set these options in individual [domain]
sections to overwrite any global values in the [pam]
section. The following options apply different GSSAPI settings to each domain:
- For the
idm.example.com
domain -
Enable GSSAPI authentication for the
sudo
andsudo -i
services. -
Require certificate or smart card authentication authenticators for the
sudo
command. -
Require one-time password authentication authenticators for the
sudo -i
command. - Enforce matching user names and Kerberos principals.
-
Enable GSSAPI authentication for the
- For the
ad.example.com
domain -
Enable GSSAPI authentication only for the
sudo
service. - Do not enforce matching user names and principals.
-
Enable GSSAPI authentication only for the
[domain/idm.example.com] pam_gssapi_services = sudo, sudo-i pam_gssapi_indicators_map = sudo:pkinit, sudo-i:otp pam_gssapi_check_upn = true ... [domain/ad.example.com] pam_gssapi_services = sudo pam_gssapi_check_upn = false ...
Additional resources
5.9. Troubleshooting GSSAPI authentication for sudo
If you are unable to authenticate to the sudo
service with a Kerberos ticket from IdM, use the following scenarios to troubleshoot your configuration.
Prerequisites
-
You have enabled GSSAPI authentication for the
sudo
service. See Enabling GSSAPI authentication for sudo on an IdM client. -
You need
root
privileges to modify the/etc/sssd/sssd.conf
file and PAM files in the/etc/pam.d/
directory.
Procedure
If you see the following error, the Kerberos service might not able to resolve the correct realm for the service ticket based on the host name:
Server not found in Kerberos database
In this situation, add the hostname directly to
[domain_realm]
section in the/etc/krb5.conf
Kerberos configuration file:[idm-user@idm-client ~]$ cat /etc/krb5.conf ... [domain_realm] .example.com = EXAMPLE.COM example.com = EXAMPLE.COM server.example.com = EXAMPLE.COM
If you see the following error, you do not have any Kerberos credentials:
No Kerberos credentials available
In this situation, retrieve Kerberos credentials with the
kinit
utility or authenticate with SSSD:[idm-user@idm-client ~]$ kinit idm-user@IDM.EXAMPLE.COM Password for idm-user@idm.example.com:
If you see either of the following errors in the
/var/log/sssd/sssd_pam.log
log file, the Kerberos credentials do not match the username of the user currently logged in:User with UPN [<UPN>] was not found. UPN [<UPN>] does not match target user [<username>].
In this situation, verify that you authenticated with SSSD, or consider disabling the
pam_gssapi_check_upn
option in the/etc/sssd/sssd.conf
file:[idm-user@idm-client ~]$ cat /etc/sssd/sssd.conf ... pam_gssapi_check_upn = false
For additional troubleshooting, you can enable debugging output for the
pam_sss_gss.so
PAM module.Add the
debug
option at the end of allpam_sss_gss.so
entries in PAM files, such as/etc/pam.d/sudo
and/etc/pam.d/sudo-i
:[root@idm-client ~]# cat /etc/pam.d/sudo #%PAM-1.0 auth sufficient pam_sss_gss.so debug auth include system-auth account include system-auth password include system-auth session include system-auth
[root@idm-client ~]# cat /etc/pam.d/sudo-i #%PAM-1.0 auth sufficient pam_sss_gss.so debug auth include sudo account include sudo password include sudo session optional pam_keyinit.so force revoke session include sudo
Try to authenticate with the
pam_sss_gss.so
module and review the console output. In this example, the user did not have any Kerberos credentials.[idm-user@idm-client ~]$ sudo ls -l /etc/sssd/sssd.conf pam_sss_gss: Initializing GSSAPI authentication with SSSD pam_sss_gss: Switching euid from 0 to 1366201107 pam_sss_gss: Trying to establish security context pam_sss_gss: SSSD User name: idm-user@idm.example.com pam_sss_gss: User domain: idm.example.com pam_sss_gss: User principal: pam_sss_gss: Target name: host@idm.example.com pam_sss_gss: Using ccache: KCM: pam_sss_gss: Acquiring credentials, principal name will be derived pam_sss_gss: Unable to read credentials from [KCM:] [maj:0xd0000, min:0x96c73ac3] pam_sss_gss: GSSAPI: Unspecified GSS failure. Minor code may provide more information pam_sss_gss: GSSAPI: No credentials cache found pam_sss_gss: Switching euid from 1366200907 to 0 pam_sss_gss: System error [5]: Input/output error
5.10. Using an Ansible playbook to ensure sudo access for an IdM user on an IdM client
In Identity Management (IdM), you can ensure sudo
access to a specific command is granted to an IdM user account on a specific IdM host.
Complete this procedure to ensure a sudo
rule named idm_user_reboot exists. The rule grants idm_user the permission to run the /usr/sbin/reboot
command on the idmclient machine.
Prerequisites
- You have installed the ansible-freeipa package on the Ansible controller.
- You know the IdM administrator password.
- You have ensured the presence of a user account for idm_user in IdM and unlocked the account by creating a password for the user. For details on adding a new IdM user using the command-line interface, see Adding users using the command line.
- You have ensured the presence of a user account for idm_user in IdM and unlocked the account by creating a password for the user. For details on adding a new IdM user using the command-line interface, see Adding users using the command line.
- You have ensured the presence of a user account for idm_user in IdM and unlocked the account by creating a password for the user. For details on adding a new IdM user using the command-line interface, see Adding users using the command line.
-
No local idm_user account exists on idmclient. The idm_user user is not listed in the
/etc/passwd
file on idmclient.
Procedure
Create an inventory file, for example
inventory.file
, and defineipaservers
in it:[ipaservers] server.idm.example.com
Add one or more
sudo
commands:Create an
ensure-reboot-sudocmd-is-present.yml
Ansible playbook that ensures the presence of the/usr/sbin/reboot
command in the IdM database ofsudo
commands. To simplify this step, you can copy and modify the example in the/usr/share/doc/ansible-freeipa/playbooks/sudocmd/ensure-sudocmd-is-present.yml
file:--- - name: Playbook to manage sudo command hosts: ipaserver become: true tasks: # Ensure sudo command is present - ipasudocmd: ipaadmin_password: MySecret123 name: /usr/sbin/reboot state: present
Run the playbook:
$ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-reboot-sudocmd-is-present.yml
Create a
sudo
rule that references the commands:Create an
ensure-sudorule-for-idmuser-on-idmclient-is-present.yml
Ansible playbook that uses thesudo
command entry to ensure the presence of a sudo rule. The sudo rule allows idm_user to reboot the idmclient machine. To simplify this step, you can copy and modify the example in the/usr/share/doc/ansible-freeipa/playbooks/sudorule/ensure-sudorule-is-present.yml
file:--- - name: Tests hosts: ipaserver become: true tasks: # Ensure a sudorule is present granting idm_user the permission to run /usr/sbin/reboot on idmclient - ipasudorule: ipaadmin_password: MySecret123 name: idm_user_reboot description: A test sudo rule. allow_sudocmd: /usr/sbin/reboot host: idmclient.idm.example.com user: idm_user state: present
Run the playbook:
$ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-sudorule-for-idmuser-on-idmclient-is-present.yml
Verification steps
Test that the sudo
rule whose presence you have ensured on the IdM server works on idmclient by verifying that idm_user can reboot idmclient using sudo
. Note that it can take a few minutes for the changes made on the server to take effect on the client.
- Log in to idmclient as idm_user.
Reboot the machine using
sudo
. Enter the password for idm_user when prompted:$ sudo /usr/sbin/reboot [sudo] password for idm_user:
If sudo
is configured correctly, the machine reboots.
Additional resources
-
See the
README-sudocmd.md
,README-sudocmdgroup.md
, andREADME-sudorule.md
files in the/usr/share/doc/ansible-freeipa/
directory.
Chapter 6. Using ldapmodify to manage IdM users externally
You can modify Identity Management (IdM) LDAP directly from the command-line interface (CLI) using the ldapmodify
and ldapdelete
utilities. The utilities provide full functionality for adding, editing, and deleting your directory contents. You can use these utilities to manage both the configuration entries of the server and the data in the user entries. The utilities can also be used to write scripts to perform bulk management of one or more directories.
6.1. Templates for managing IdM user accounts externally
This section describes templates for various user management operations in IdM. The templates show which attributes you must modify using ldapmodify
to achieve the following goals:
- Adding a new stage user
- Modifying a user’s attribute
- Enabling a user
- Disabling a user
- Preserving a user
The templates are formatted in the LDAP Data Interchange Format (LDIF). LDIF is a standard plain text data interchange format for representing LDAP directory content and update requests.
Using the templates, you can configure the LDAP provider of your provisioning system to manage IdM user accounts.
For detailed example procedures, see the following sections:
Templates for adding a new stage user
A template for adding a user with UID and GID assigned automatically. The distinguished name (DN) of the created entry must start with
uid=user_login
:dn: uid=user_login,cn=staged users,cn=accounts,cn=provisioning,dc=idm,dc=example,dc=com changetype: add objectClass: top objectClass: inetorgperson uid: user_login sn: surname givenName: first_name cn: full_name
A template for adding a user with UID and GID assigned statically:
dn: uid=user_login,cn=staged users,cn=accounts,cn=provisioning,dc=idm,dc=example,dc=com changetype: add objectClass: top objectClass: person objectClass: inetorgperson objectClass: organizationalperson objectClass: posixaccount uid: user_login uidNumber: UID_number gidNumber: GID_number sn: surname givenName: first_name cn: full_name homeDirectory: /home/user_login
You are not required to specify any IdM object classes when adding stage users. IdM adds these classes automatically after the users are activated.
Templates for modifying existing users
Modifying a user’s attribute:
dn: distinguished_name changetype: modify replace: attribute_to_modify attribute_to_modify: new_value
Disabling a user:
dn: distinguished_name changetype: modify replace: nsAccountLock nsAccountLock: TRUE
Enabling a user:
dn: distinguished_name changetype: modify replace: nsAccountLock nsAccountLock: FALSE
Updating the
nssAccountLock
attribute has no effect on stage and preserved users. Even though the update operation completes successfully, the attribute value remainsnssAccountLock: TRUE
.Preserving a user:
dn: distinguished_name changetype: modrdn newrdn: uid=user_login deleteoldrdn: 0 newsuperior: cn=deleted users,cn=accounts,cn=provisioning,dc=idm,dc=example,dc=com
Before modifying a user, obtain the user’s distinguished name (DN) by searching using the user’s login. In the following example, the user_allowed_to_modify_user_entries user is a user allowed to modify user and group information, for example activator or IdM administrator. The password in the example is this user’s password:
[...]
# ldapsearch -LLL -x -D "uid=user_allowed_to_modify_user_entries,cn=users,cn=accounts,dc=idm,dc=example,dc=com" -w "Secret123" -H ldap://r8server.idm.example.com -b "cn=users,cn=accounts,dc=idm,dc=example,dc=com" uid=test_user
dn: uid=test_user,cn=users,cn=accounts,dc=idm,dc=example,dc=com
memberOf: cn=ipausers,cn=groups,cn=accounts,dc=idm,dc=example,dc=com
6.2. Templates for managing IdM group accounts externally
This section describes templates for various user group management operations in IdM. The templates show which attributes you must modify using ldapmodify
to achieve the following aims:
- Creating a new group
- Deleting an existing group
- Adding a member to a group
- Removing a member from a group
The templates are formatted in the LDAP Data Interchange Format (LDIF). LDIF is a standard plain text data interchange format for representing LDAP directory content and update requests.
Using the templates, you can configure the LDAP provider of your provisioning system to manage IdM group accounts.
Creating a new group
dn: cn=group_name,cn=groups,cn=accounts,dc=idm,dc=example,dc=com changetype: add objectClass: top objectClass: ipaobject objectClass: ipausergroup objectClass: groupofnames objectClass: nestedgroup objectClass: posixgroup uid: group_name cn: group_name gidNumber: GID_number
Modifying groups
Deleting an existing group:
dn: group_distinguished_name changetype: delete
Adding a member to a group:
dn: group_distinguished_name changetype: modify add: member member: uid=user_login,cn=users,cn=accounts,dc=idm,dc=example,dc=com
Do not add stage or preserved users to groups. Even though the update operation completes successfully, the users will not be updated as members of the group. Only active users can belong to groups.
Removing a member from a group:
dn: distinguished_name changetype: modify delete: member member: uid=user_login,cn=users,cn=accounts,dc=idm,dc=example,dc=com
Before modifying a group, obtain the group’s distinguished name (DN) by searching using the group’s name.
# ldapsearch -YGSSAPI -H ldap://server.idm.example.com -b "cn=groups,cn=accounts,dc=idm,dc=example,dc=com" "cn=group_name"
dn: cn=group_name,cn=groups,cn=accounts,dc=idm,dc=example,dc=com
ipaNTSecurityIdentifier: S-1-5-21-1650388524-2605035987-2578146103-11017
cn: testgroup
objectClass: top
objectClass: groupofnames
objectClass: nestedgroup
objectClass: ipausergroup
objectClass: ipaobject
objectClass: posixgroup
objectClass: ipantgroupattrs
ipaUniqueID: 569bf864-9d45-11ea-bea3-525400f6f085
gidNumber: 1997010017
6.3. Preserving an IdM user with ldapmodify
This section describes how to use ldapmodify
to preserve an IdM user; that is, how to deactivate a user account after the employee has left the company.
Prerequisites
- You can authenticate as an IdM user with a role to preserve users.
Procedure
Log in as an IdM user with a role to preserve users:
$ kinit admin
Enter the
ldapmodify
command and specify the Generic Security Services API (GSSAPI) as the Simple Authentication and Security Layer (SASL) mechanism to be used for authentication:# ldapmodify -Y GSSAPI SASL/GSSAPI authentication started SASL username: admin@IDM.EXAMPLE.COM SASL SSF: 256 SASL data security layer installed.
Enter the
dn
of the user you want to preserve:dn: uid=user1,cn=users,cn=accounts,dc=idm,dc=example,dc=com
Enter modrdn as the type of change you want to perform:
changetype: modrdn
Specify the newrdn for the user:
newrdn: uid=user1
Indicate that you want to preserve the user:
deleteoldrdn: 0
Specify the new superior DN:
newsuperior: cn=deleted users,cn=accounts,cn=provisioning,dc=idm,dc=example,dc=com
Preserving a user moves the entry to a new location in the directory information tree (DIT). For this reason, you must specify the DN of the new parent entry as the new superior DN.
Press
Enter
again to confirm that this is the end of the entry:[Enter] modifying rdn of entry "uid=user1,cn=users,cn=accounts,dc=idm,dc=example,dc=com"
- Exit the connection using Ctrl + C.
Verification steps
Verify that the user has been preserved by listing all preserved users:
$ ipa user-find --preserved=true -------------- 1 user matched -------------- User login: user1 First name: First 1 Last name: Last 1 Home directory: /home/user1 Login shell: /bin/sh Principal name: user1@IDM.EXAMPLE.COM Principal alias: user1@IDM.EXAMPLE.COM Email address: user1@idm.example.com UID: 1997010003 GID: 1997010003 Account disabled: True Preserved user: True ---------------------------- Number of entries returned 1 ----------------------------
Chapter 7. Configuring IdM for external provisioning of users
As a system administrator, you can configure Identity Management (IdM) to support the provisioning of users by an external solution for managing identities.
Rather than use the ipa
utility, the administrator of the external provisioning system can access the IdM LDAP using the ldapmodify
utility. The administrator can add individual stage users from the CLI using ldapmodify or using an LDIF file.
The assumption is that you, as an IdM administrator, fully trust your external provisioning system to only add validated users. However, at the same time you do not want to assign the administrators of the external provisioning system the IdM role of User Administrator
to enable them to add new active users directly.
You can configure a script to automatically move the staged users created by the external provisioning system to active users automatically.
This chapter contains these sections:
- Preparing Identity Management (IdM) to use an external provisioning system to add stage users to IdM.
- Creating a script to move the users added by the external provisioning system from stage to active users.
Using an external provisioning system to add an IdM stage user. You can do that in two ways:
7.1. Preparing IdM accounts for automatic activation of stage user accounts
This procedure shows how to configure two IdM user accounts to be used by an external provisioning system. By adding the accounts to a group with an appropriate password policy, you enable the external provisioning system to manage user provisioning in IdM. In the following, the user account to be used by the external system to add stage users is named provisionator. The user account to be used to automatically activate the stage users is named activator.
Prerequisites
- The host on which you perform the procedure is enrolled into IdM.
Procedure
Log in as IdM administrator:
$ kinit admin
Create a user named provisionator with the privileges to add stage users.
- Add the provisionator user account:
$ ipa user-add provisionator --first=provisioning --last=account --password
Grant the provisionator user the required privileges.
Create a custom role,
System Provisioning
, to manage adding stage users:$ ipa role-add --desc "Responsible for provisioning stage users" "System Provisioning"
Add the
Stage User Provisioning
privilege to the role. This privilege provides the ability to add stage users:$ ipa role-add-privilege "System Provisioning" --privileges="Stage User Provisioning"
Add the provisionator user to the role:
$ ipa role-add-member --users=provisionator "System Provisioning"
- Verify that the provisionator exists in IdM:
$ ipa user-find provisionator --all --raw -------------- 1 user matched -------------- dn: uid=provisionator,cn=users,cn=accounts,dc=idm,dc=example,dc=com uid: provisionator [...]
Create a user, activator, with the privileges to manage user accounts.
Add the activator user account:
$ ipa user-add activator --first=activation --last=account --password
Grant the activator user the required privileges by adding the user to the default
User Administrator
role:$ ipa role-add-member --users=activator "User Administrator"
Create a user group for application accounts:
$ ipa group-add application-accounts
Update the password policy for the group. The following policy prevents password expiration and lockout for the account but compensates the potential risks by requiring complex passwords:
$ ipa pwpolicy-add application-accounts --maxlife=10000 --minlife=0 --history=0 --minclasses=4 --minlength=8 --priority=1 --maxfail=0 --failinterval=1 --lockouttime=0
(Optional) Verify that the password policy exists in IdM:
$ ipa pwpolicy-show application-accounts Group: application-accounts Max lifetime (days): 10000 Min lifetime (hours): 0 History size: 0 [...]
Add the provisioning and activation accounts to the group for application accounts:
$ ipa group-add-member application-accounts --users={provisionator,activator}
Change the passwords for the user accounts:
$ kpasswd provisionator $ kpasswd activator
Changing the passwords is necessary because new IdM users passwords expire immediately.
Additional resources:
7.2. Configuring automatic activation of IdM stage user accounts
This procedure shows how to create a script for activating stage users. The system runs the script automatically at specified time intervals. This ensures that new user accounts are automatically activated and available for use shortly after they are created.
The procedure assumes that the owner of the external provisioning system has already validated the users and that they do not require additional validation on the IdM side before the script adds them to IdM.
It is sufficient to enable the activation process on only one of your IdM servers.
Prerequisites
- The provisionator and activator accounts exist in IdM. For details, see Preparing IdM accounts for automatic activation of stage user accounts.
- You have root privileges on the IdM server on which you are running the procedure.
- You are logged in as IdM administrator.
- You trust your external provisioning system.
Procedure
Generate a keytab file for the activation account:
# ipa-getkeytab -s server.idm.example.com -p "activator" -k /etc/krb5.ipa-activation.keytab
If you want to enable the activation process on more than one IdM server, generate the keytab file on one server only. Then copy the keytab file to the other servers.
Create a script,
/usr/local/sbin/ipa-activate-all
, with the following contents to activate all users:#!/bin/bash kinit -k -i activator ipa stageuser-find --all --raw | grep " uid:" | cut -d ":" -f 2 | while read uid; do ipa stageuser-activate ${uid}; done
Edit the permissions and ownership of the
ipa-activate-all
script to make it executable:# chmod 755 /usr/local/sbin/ipa-activate-all # chown root:root /usr/local/sbin/ipa-activate-all
Create a systemd unit file,
/etc/systemd/system/ipa-activate-all.service
, with the following contents:[Unit] Description=Scan IdM every minute for any stage users that must be activated [Service] Environment=KRB5_CLIENT_KTNAME=/etc/krb5.ipa-activation.keytab Environment=KRB5CCNAME=FILE:/tmp/krb5cc_ipa-activate-all ExecStart=/usr/local/sbin/ipa-activate-all
Create a systemd timer,
/etc/systemd/system/ipa-activate-all.timer
, with the following contents:[Unit] Description=Scan IdM every minute for any stage users that must be activated [Timer] OnBootSec=15min OnUnitActiveSec=1min [Install] WantedBy=multi-user.target
Reload the new configuration:
# systemctl daemon-reload
Enable
ipa-activate-all.timer
:# systemctl enable ipa-activate-all.timer
Start
ipa-activate-all.timer
:# systemctl start ipa-activate-all.timer
(Optional) Verify that the
ipa-activate-all.timer
daemon is running:# systemctl status ipa-activate-all.timer ● ipa-activate-all.timer - Scan IdM every minute for any stage users that must be activated Loaded: loaded (/etc/systemd/system/ipa-activate-all.timer; enabled; vendor preset: disabled) Active: active (waiting) since Wed 2020-06-10 16:34:55 CEST; 15s ago Trigger: Wed 2020-06-10 16:35:55 CEST; 44s left Jun 10 16:34:55 server.idm.example.com systemd[1]: Started Scan IdM every minute for any stage users that must be activated.
7.3. Adding an IdM stage user defined in an LDIF file
This section describes how an administrator of an external provisioning system can access IdM LDAP and use an LDIF file to add stage users. While the example below shows adding one single user, multiple users can be added in one file in bulk mode.
Prerequisites
- IdM administrator has created the provisionator account and a password for it. For details, see Preparing IdM accounts for automatic activation of stage user accounts.
- You as the external administrator know the password of the provisionator account.
- You can SSH to the IdM server from your LDAP server.
You are able to supply the minimal set of attributes that an IdM stage user must have to allow the correct processing of the user life cycle, namely:
-
The
distinguished name
(dn) -
The
common name
(cn) -
The
last name
(sn) -
The
uid
-
The
Procedure
On the external server, create an LDIF file that contains information about the new user:
dn: uid=stageidmuser,cn=staged users,cn=accounts,cn=provisioning,dc=idm,dc=example,dc=com changetype: add objectClass: top objectClass: inetorgperson uid: stageidmuser sn: surname givenName: first_name cn: full_name
Transfer the LDIF file from the external server to the IdM server:
$ scp add-stageidmuser.ldif provisionator@server.idm.example.com:/provisionator/ Password: add-stageidmuser.ldif 100% 364 217.6KB/s 00:00
Use the
SSH
protocol to connect to the IdM server as provisionator:$ ssh provisionator@server.idm.example.com Password: [provisionator@server ~]$
On the IdM server, obtain the Kerberos ticket-granting ticket (TGT) for the provisionator account:
[provisionator@server ~]$ kinit provisionator
Enter the
ldapadd
command with the -f option and the name of the LDIF file. Specify the name of the IdM server and the port number:~]$ ldapadd -h server.idm.example.com -p 389 -f add-stageidmuser.ldif SASL/GSSAPI authentication started SASL username: provisionator@IDM.EXAMPLE.COM SASL SSF: 256 SASL data security layer installed. adding the entry "uid=stageidmuser,cn=staged users,cn=accounts,cn=provisioning,dc=idm,dc=example,dc=com"
7.4. Adding an IdM stage user directly from the CLI using ldapmodify
This section describes how an administrator of an external provisioning system can access the Identity Management (IdM) LDAP and use the ldapmodify
utility to add a stage user.
Prerequisites
- The IdM administrator has created the provisionator account and a password for it. For details, see Preparing IdM accounts for automatic activation of stage user accounts.
- You as the external administrator know the password of the provisionator account.
- You can SSH to the IdM server from your LDAP server.
You are able to supply the minimal set of attributes that an IdM stage user must have to allow the correct processing of the user life cycle, namely:
-
The
distinguished name
(dn) -
The
common name
(cn) -
The
last name
(sn) -
The
uid
-
The
Procedure
Use the
SSH
protocol to connect to the IdM server using your IdM identity and credentials:$ ssh provisionator@server.idm.example.com Password: [provisionator@server ~]$
Obtain the TGT of the provisionator account, an IdM user with a role to add new stage users:
$ kinit provisionator
Enter the
ldapmodify
command and specify Generic Security Services API (GSSAPI) as the Simple Authentication and Security Layer (SASL) mechanism to use for authentication. Specify the name of the IdM server and the port:# ldapmodify -h server.idm.example.com -p 389 -Y GSSAPI SASL/GSSAPI authentication started SASL username: provisionator@IDM.EXAMPLE.COM SASL SSF: 56 SASL data security layer installed.
Enter the
dn
of the user you are adding:dn: uid=stageuser,cn=staged users,cn=accounts,cn=provisioning,dc=idm,dc=example,dc=com
Enter add as the type of change you are performing:
changetype: add
Specify the LDAP object class categories required to allow the correct processing of the user life cycle:
objectClass: top objectClass: inetorgperson
You can specify additional object classes.
Enter the
uid
of the user:uid: stageuser
Enter the
cn
of the user:cn: Babs Jensen
Enter the last name of the user:
sn: Jensen
Press
Enter
again to confirm that this is the end of the entry:[Enter] adding new entry "uid=stageuser,cn=staged users,cn=accounts,cn=provisioning,dc=idm,dc=example,dc=com"
- Exit the connection using Ctrl + C.
Verification steps
Verify the contents of the stage entry to make sure your provisioning system added all required POSIX attributes and the stage entry is ready to be activated.
To display the new stage user’s LDAP attributes, enter the
ipa stageuser-show --all --raw
command:$ ipa stageuser-show stageuser --all --raw dn: uid=stageuser,cn=staged users,cn=accounts,cn=provisioning,dc=idm,dc=example,dc=com uid: stageuser sn: Jensen cn: Babs Jensen has_password: FALSE has_keytab: FALSE nsaccountlock: TRUE objectClass: top objectClass: inetorgperson objectClass: organizationalPerson objectClass: person
-
Note that the user is explicitly disabled by the
nsaccountlock
attribute.
-
Note that the user is explicitly disabled by the
7.5. Additional resources
Chapter 8. Managing self-service rules in IdM using the CLI
This chapter introduces self-service rules in Identity Management (IdM) and describes how to create and edit self-service access rules in the command-line interface (CLI).
8.1. Self-service access control in IdM
Self-service access control rules define which operations an Identity Management (IdM) entity can perform on its IdM Directory Server entry: for example, IdM users have the ability to update their own passwords.
This method of control allows an authenticated IdM entity to edit specific attributes within its LDAP entry, but does not allow add
or delete
operations on the entire entry.
Be careful when working with self-service access control rules: configuring access control rules improperly can inadvertently elevate an entity’s privileges.
8.2. Creating self-service rules using the CLI
This procedure describes creating self-service access rules in IdM using the command-line interface (CLI).
Prerequisites
- Administrator privileges for managing IdM or the User Administrator role.
- An active Kerberos ticket. For details, see Using kinit to log in to IdM manually.
Procedure
To add a self-service rule, use the
ipa selfservice-add
command and specify the following two options:--permissions
- sets the read and write permissions the Access Control Instruction (ACI) grants.
--attrs
- sets the complete list of attributes to which this ACI grants permission.
For example, to create a self-service rule allowing users to modify their own name details:
$ ipa selfservice-add "Users can manage their own name details" --permissions=write --attrs=givenname --attrs=displayname --attrs=title --attrs=initials ----------------------------------------------------------- Added selfservice "Users can manage their own name details" ----------------------------------------------------------- Self-service name: Users can manage their own name details Permissions: write Attributes: givenname, displayname, title, initials
8.3. Editing self-service rules using the CLI
This procedure describes editing self-service access rules in IdM using the command-line interface (CLI).
Prerequisites
- Administrator privileges for managing IdM or the User Administrator role.
- An active Kerberos ticket. For details, see Using kinit to log in to IdM manually.
Procedure
-
Optional: Display existing self-service rules with the
ipa selfservice-find
command. -
Optional: Display details for the self-service rule you want to modify with the
ipa selfservice-show
command. -
Use the
ipa selfservice-mod
command to edit a self-service rule.
For example:
$ ipa selfservice-mod "Users can manage their own name details" --attrs=givenname --attrs=displayname --attrs=title --attrs=initials --attrs=surname -------------------------------------------------------------- Modified selfservice "Users can manage their own name details" -------------------------------------------------------------- Self-service name: Users can manage their own name details Permissions: write Attributes: givenname, displayname, title, initials
Using the ipa selfservice-mod
command overwrites the previously defined permissions and attributes, so always include the complete list of existing permissions and attributes along with any new ones you want to define.
Verification steps
-
Use the
ipa selfservice-show
command to display the self-service rule you edited.
$ ipa selfservice-show "Users can manage their own name details" -------------------------------------------------------------- Self-service name: Users can manage their own name details Permissions: write Attributes: givenname, displayname, title, initials
8.4. Deleting self-service rules using the CLI
This procedure describes deleting self-service access rules in IdM using the command-line interface (CLI).
Prerequisites
- Administrator privileges for managing IdM or the User Administrator role.
- An active Kerberos ticket. For details, see Using kinit to log in to IdM manually.
Procedure
-
Use the
ipa selfservice-del
command to delete a self-service rule.
For example:
$ ipa selfservice-del "Users can manage their own name details" ----------------------------------------------------------- Deleted selfservice "Users can manage their own name details" -----------------------------------------------------------
Verification steps
-
Use the
ipa selfservice-find
command to display all self-service rules. The rule you just deleted should be missing.
Chapter 9. Managing self-service rules using the IdM Web UI
This chapter introduces self-service rules in Identity Management (IdM) and describes how to create and edit self-service access rules in the web interface (IdM Web UI).
9.1. Self-service access control in IdM
Self-service access control rules define which operations an Identity Management (IdM) entity can perform on its IdM Directory Server entry: for example, IdM users have the ability to update their own passwords.
This method of control allows an authenticated IdM entity to edit specific attributes within its LDAP entry, but does not allow add
or delete
operations on the entire entry.
Be careful when working with self-service access control rules: configuring access control rules improperly can inadvertently elevate an entity’s privileges.
9.2. Creating self-service rules using the IdM Web UI
This procedure describes how to create self-service access rules in IdM using the web interface (IdM Web UI).
Prerequisites
- Administrator privileges for managing IdM or the User Administrator role.
- You are logged-in to the IdM Web UI. For details, see Accessing the IdM Web UI in a web browser.
Procedure
- Open the Role-Based Access Control sub-menu in the IPA Server tab and select Self Service Permissions.
Click Add at the top-right of the list of the self-service access rules:
The Add Self Service Permission window opens. Enter the name of the new self-service rule in the Self-service name field. Spaces are allowed:
- Select the check boxes next to the attributes you want users to be able to edit.
Optional: If an attribute you would like to provide access to is not listed, you can add a listing for it:
- Click the Add button.
- Enter the attribute name in the Attribute text field of the following Add Custom Attribute window.
- Click the OK button to add the attribute
- Verify that the new attribute is selected
-
Click the Add button at the bottom of the form to save the new self-service rule.
Alternatively, you can save and continue editing the self-service rule by clicking the Add and Edit button, or save and add further rules by clicking the Add and Add another button.
9.3. Editing self-service rules using the IdM Web UI
This procedure describes how to edit self-service access rules in IdM using the web interface (IdM Web UI).
Prerequisites
- Administrator privileges for managing IdM or the User Administrator role.
- You are logged-in to the IdM Web UI. For details, see Accessing the IdM Web UI in a web browser.
Procedure
- Open the Role-Based Access Control sub-menu in the IPA Server tab and select Self Service Permissions.
Click on the name of the self-service rule you want to modify.
- The edit page only allows you to edit the list of attributes to you want to add or remove to the self-service rule. Select or deselect the appropriate check boxes.
- Click the Save button to save your changes to the self-service rule.
9.4. Deleting self-service rules using the IdM Web UI
This procedure describes how to delete self-service access rules in IdM using the web interface (IdM Web UI).
Prerequisites
- Administrator privileges for managing IdM or the User Administrator role.
- You are logged-in to the IdM Web UI. For details, see Accessing the IdM Web UI in a web browser.
Procedure
- Open the Role-Based Access Control sub-menu in the IPA Server tab and select Self Service Permissions.
Select the check box next to the rule you want to delete, then click on the Delete button on the right of the list.
- A dialog opens, click on Delete to confirm.
Chapter 10. Using Ansible playbooks to manage self-service rules in IdM
This section introduces self-service rules in Identity Management (IdM) and describes how to create and edit self-service access rules using Ansible playbooks. Self-service access control rules allow an IdM entity to perform specified operations on its IdM Directory Server entry.
This section covers the following topics:
- Self-service access control in IdM
- Using Ansible to ensure that a self-service rule is present
- Using Ansible to ensure that a self-service rule is absent
- Using Ansible to ensure that a self-service rule has specific attributes
- Using Ansible to ensure that a self-service rule does not have specific attributes
10.1. Self-service access control in IdM
Self-service access control rules define which operations an Identity Management (IdM) entity can perform on its IdM Directory Server entry: for example, IdM users have the ability to update their own passwords.
This method of control allows an authenticated IdM entity to edit specific attributes within its LDAP entry, but does not allow add
or delete
operations on the entire entry.
Be careful when working with self-service access control rules: configuring access control rules improperly can inadvertently elevate an entity’s privileges.
10.2. Using Ansible to ensure that a self-service rule is present
The following procedure describes how to use an Ansible playbook to define self-service rules and ensure their presence on an Identity Management (IdM) server. In this example, the new Users can manage their own name details rule grants users the ability to change their own givenname
, displayname
, title
and initials
attributes. This allows them to, for example, change their display name or initials if they want to.
Prerequisites
- You know the IdM administrator password.
You have configured an Ansible control node that meets the following requirements:
- You are using Ansible version 2.8 or later.
- You have installed the ansible-freeipa package.
- In the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server where you are configuring these options.
Procedure
Navigate to the ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
Make a copy of the
selfservice-present.yml
file located in the/usr/share/doc/ansible-freeipa/playbooks/selfservice/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/selfservice/selfservice-present.yml selfservice-present-copy.yml
-
Open the
selfservice-present-copy.yml
Ansible playbook file for editing. Adapt the file by setting the following variables in the
ipaselfservice
task section:-
Set the
ipaadmin_password
variable to the password of the IdM administrator. -
Set the
name
variable to the name of the new self-service rule. -
Set the
permission
variable to a comma-separated list of permissions to grant:read
andwrite
. -
Set the
attribute
variable to a list of attributes that users can manage themselves:givenname
,displayname
,title
, andinitials
.
This is the modified Ansible playbook file for the current example:
--- - name: Self-service present hosts: ipaserver become: true tasks: - name: Ensure self-service rule "Users can manage their own name details" is present ipaselfservice: ipaadmin_password: Secret123 name: "Users can manage their own name details" permission: read, write attribute: - givenname - displayname - title - initials
-
Set the
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i inventory selfservice-present-copy.yml
Additional resources
- See Self-service access control in IdM.
-
See the
README-selfservice.md
file in the/usr/share/doc/ansible-freeipa/
directory. -
See the
/usr/share/doc/ansible-freeipa/playbooks/selfservice
directory.
10.3. Using Ansible to ensure that a self-service rule is absent
The following procedure describes how to use an Ansible playbook to ensure a specified self-service rule is absent from your IdM configuration. The example below describes how to make sure the Users can manage their own name details self-service rule does not exist in IdM. This will ensure that users cannot, for example, change their own display name or initials.
Prerequisites
- You know the IdM administrator password.
You have configured an Ansible control node that meets the following requirements:
- You are using Ansible version 2.8 or later.
- You have installed the ansible-freeipa package.
- In the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server where you are configuring these options.
Procedure
Navigate to the ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
Make a copy of the
selfservice-absent.yml
file located in the/usr/share/doc/ansible-freeipa/playbooks/selfservice/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/selfservice/selfservice-absent.yml selfservice-absent-copy.yml
-
Open the
selfservice-absent-copy.yml
Ansible playbook file for editing. Adapt the file by setting the following variables in the
ipaselfservice
task section:-
Set the
ipaadmin_password
variable to the password of the IdM administrator. -
Set the
name
variable to the name of the self-service rule. -
Set the
state
variable toabsent
.
This is the modified Ansible playbook file for the current example:
--- - name: Self-service absent hosts: ipaserver become: true tasks: - name: Ensure self-service rule "Users can manage their own name details" is absent ipaselfservice: ipaadmin_password: Secret123 name: "Users can manage their own name details" state: absent
-
Set the
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i inventory selfservice-absent-copy.yml
Additional resources
- See Self-service access control in IdM.
-
See the
README-selfservice.md
file in the/usr/share/doc/ansible-freeipa/
directory. -
See the sample playbooks in the
/usr/share/doc/ansible-freeipa/playbooks/selfservice
directory.
10.4. Using Ansible to ensure that a self-service rule has specific attributes
The following procedure describes how to use an Ansible playbook to ensure that an already existing self-service rule has specific settings. In the example, you ensure the Users can manage their own name details self-service rule also has the surname
member attribute.
Prerequisites
- You know the IdM administrator password.
You have configured an Ansible control node that meets the following requirements:
- You are using Ansible version 2.8 or later.
- You have installed the ansible-freeipa package.
- In the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server where you are configuring these options.
- The Users can manage their own name details self-service rule exists in IdM.
Procedure
Navigate to the ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
Make a copy of the
selfservice-member-present.yml
file located in the/usr/share/doc/ansible-freeipa/playbooks/selfservice/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/selfservice/selfservice-member-present.yml selfservice-member-present-copy.yml
-
Open the
selfservice-member-present-copy.yml
Ansible playbook file for editing. Adapt the file by setting the following variables in the
ipaselfservice
task section:-
Set the
ipaadmin_password
variable to the password of the IdM administrator. -
Set the
name
variable to the name of the self-service rule to modify. -
Set the
attribute
variable tosurname
. -
Set the
action
variable tomember
.
This is the modified Ansible playbook file for the current example:
--- - name: Self-service member present hosts: ipaserver become: true tasks: - name: Ensure selfservice "Users can manage their own name details" member attribute surname is present ipaselfservice: ipaadmin_password: Secret123 name: "Users can manage their own name details" attribute: - surname action: member
-
Set the
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i inventory selfservice-member-present-copy.yml
Additional resources
- See Self-service access control in IdM.
-
See the
README-selfservice.md
file available in the/usr/share/doc/ansible-freeipa/
directory. -
See the sample playbooks in the
/usr/share/doc/ansible-freeipa/playbooks/selfservice
directory.
10.5. Using Ansible to ensure that a self-service rule does not have specific attributes
The following procedure describes how to use an Ansible playbook to ensure that a self-service rule does not have specific settings. You can use this playbook to make sure a self-service rule does not grant undesired access. In the example, you ensure the Users can manage their own name details self-service rule does not have the givenname
and surname
member attributes.
Prerequisites
- You know the IdM administrator password.
You have configured an Ansible control node that meets the following requirements:
- You are using Ansible version 2.8 or later.
- You have installed the ansible-freeipa package.
- In the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server where you are configuring these options.
- The Users can manage their own name details self-service rule exists in IdM.
Procedure
Navigate to the ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
Make a copy of the
selfservice-member-absent.yml
file located in the/usr/share/doc/ansible-freeipa/playbooks/selfservice/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/selfservice/selfservice-member-absent.yml selfservice-member-absent-copy.yml
-
Open the
selfservice-member-absent-copy.yml
Ansible playbook file for editing. Adapt the file by setting the following variables in the
ipaselfservice
task section:-
Set the
ipaadmin_password
variable to the password of the IdM administrator. -
Set the
name
variable to the name of the self-service rule you want to modify. -
Set the
attribute
variable togivenname
andsurname
. -
Set the
action
variable tomember
. -
Set the
state
variable toabsent
.
This is the modified Ansible playbook file for the current example:
--- - name: Self-service member absent hosts: ipaserver become: true tasks: - name: Ensure selfservice "Users can manage their own name details" member attributes givenname and surname are absent ipaselfservice: ipaadmin_password: Secret123 name: "Users can manage their own name details" attribute: - givenname - surname action: member state: absent
-
Set the
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i inventory selfservice-member-absent-copy.yml
Additional resources
- See Self-service access control in IdM.
-
See the
README-selfservice.md
file in the/usr/share/doc/ansible-freeipa/
directory. -
See the sample playbooks in the
/usr/share/doc/ansible-freeipa/playbooks/selfservice
directory.
Chapter 11. Managing user groups in IdM CLI
This chapter introduces user groups management using the IdM CLI.
A user group is a set of users with common privileges, password policies, and other characteristics.
A user group in Identity Management (IdM) can include:
- IdM users
- other IdM user groups
- external users, which are users that exist outside of IdM
11.1. The different group types in IdM
IdM supports the following types of groups:
- POSIX groups (the default)
POSIX groups support Linux POSIX attributes for their members. Note that groups that interact with Active Directory cannot use POSIX attributes.
POSIX attributes identify users as separate entities. Examples of POSIX attributes relevant to users include
uidNumber
, a user number (UID), andgidNumber
, a group number (GID).- Non-POSIX groups
Non-POSIX groups do not support POSIX attributes. For example, these groups do not have a GID defined.
All members of this type of group must belong to the IdM domain.
- External groups
Use external groups to add group members that exist in an identity store outside of the IdM domain, such as:
- A local system
- An Active Directory domain
- A directory service
External groups do not support POSIX attributes. For example, these groups do not have a GID defined.
Table 11.1. User groups created by default
Group name | Default group members |
---|---|
| All IdM users |
|
Users with administrative privileges, including the default |
| This is a legacy group that no longer has any special privileges |
| Users with privileges to manage the Active Directory trusts |
When you add a user to a user group, the user gains the privileges and policies associated with the group. For example, to grant administrative privileges to a user, add the user to the admins
group.
Do not delete the admins
group. As admins
is a pre-defined group required by IdM, this operation causes problems with certain commands.
In addition, IdM creates user private groups by default whenever a new user is created in IdM. For more information about private groups, see Adding users without a private group.
11.2. Direct and indirect group members
User group attributes in IdM apply to both direct and indirect members: when group B is a member of group A, all users in group B are considered indirect members of group A.
For example, in the following diagram:
- User 1 and User 2 are direct members of group A.
- User 3, User 4, and User 5 are indirect members of group A.
Figure 11.1. Direct and Indirect Group Membership

If you set a password policy for user group A, the policy also applies to all users in user group B.
11.3. Adding a user group using IdM CLI
This section describes how to add a user group using IdM CLI.
Prerequisites
- 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.-
Do not add local groups to IdM. The Name Service Switch (NSS) always resolves IdM users and groups before resolving local users and groups. This means that, for example, IdM group membership does not work for local users.
11.4. Searching for user groups using IdM CLI
This section describes how to search for existing user groups using IdM CLI.
Procedure
Display all user groups by using the
ipa group-find
command. To specify a group type, add options 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 on different group types, see The different group types in IdM.
-
Display all POSIX groups using the
11.5. Deleting a user group using IdM CLI
This section describes how to delete a user group using IdM CLI. Note that deleting a group does not delete the group members from IdM.
Prerequisites
- 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" --------------------------
11.6. Adding a member to a user group using IdM CLI
This section describes how to add a member to a user group using IdM CLI. You can add both users and user groups as members of a user group. For more information, see The different group types in IdM and Direct and indirect group members.
Prerequisites
- 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.
11.7. Adding users without a user private group
By default, IdM creates user private groups (UPGs) whenever a new user is created in IdM. UPGs are a specific group type:
- The UPG has the same name as the newly created user.
- The user is the only member of the UPG. The UPG cannot contain any other members.
- The GID of the private group matches the UID of the user.
However, it is possible to add users without creating a UPG.
11.7.1. Users without a user private group
If a NIS group or another system group already uses the GID that would be assigned to a user private group, it is necessary to avoid creating a UPG.
You can do this in two ways:
- 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.
11.7.2. Adding a user without a user private group when private groups are globally enabled
You can add a user without creating a user private group (UPG) even when UPGs are enabled on the system. This requires manually setting a GID for the new user. For details on why this is needed, see 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
11.7.3. Disabling user private groups globally for all users
You can disable user private groups (UPGs) globally. This prevents the creation of UPGs for all new users. Existing users are unaffected by this change.
Procedure
Obtain administrator privileges:
$ kinit admin
IdM uses the Directory Server Managed Entries Plug-in to manage UPGs. List the instances of the plug-in:
$ ipa-managed-entries --list
To ensure IdM does not create UPGs, disable the plug-in instance responsible for managing user private groups:
$ ipa-managed-entries -e "UPG Definition" disable Disabling Plugin
NoteTo re-enable the
UPG Definition
instance later, use theipa-managed-entries -e "UPG Definition" enable
command.Restart Directory Server to load the new configuration.
$ sudo systemctl restart dirsrv.target
To add a user after UPGs have been disabled, you need to specify a GID. For more information, see Adding a user when user private groups are globally disabled
Verification steps
To check if UPGs are globally disabled, use the disable command again:
$ ipa-managed-entries -e "UPG Definition" disable Plugin already disabled
11.7.4. Adding a user when user private groups are globally disabled
When user private groups (UPGs) are disabled globally, IdM does not assign a GID to a new user automatically. To successfully add a user, you must assign a GID manually or by using an automember rule. For details on why this is required, see 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.
11.8. Adding users or groups as member managers to an IdM user group using the IdM CLI
This section describes how to add users or groups as member managers to an IdM user group using the IdM CLI. Member managers can add users or groups to IdM user groups but cannot change the attributes of a group.
Prerequisites
- You must be logged in as the administrator. For details, see Using kinit to log in to IdM manually.
- You must have the name of the user or group you are adding as member managers and the name of the group you want them to manage.
Procedure
Add a user as a member manager to an IdM user group by using the
ipa group-add-member-manager
command.For example, to add the user
test
as a member manager ofgroup_a
:$ ipa group-add-member-manager group_a --users=test Group name: group_a GID: 1133400009 Membership managed by users: test ------------------------- Number of members added 1 -------------------------
User
test
can now manage members ofgroup_a
.Add a group as a member manager to an IdM user group by using the
ipa group-add-member-manager
command.For example, to add the group
group_admins
as a member manager ofgroup_a
:$ ipa group-add-member-manager group_a --groups=group_admins Group name: group_a GID: 1133400009 Membership managed by groups: group_admins Membership managed by users: test ------------------------- Number of members added 1 -------------------------
Group
group_admins
can now manage members ofgroup_a
.
After you add a member manager to a user group, the update may take some time to spread to all clients in your Identity Management environment.
Verification steps
Using the
ipa group-show
command to verify the user and group were added as member managers.$ ipa group-show group_a Group name: group_a GID: 1133400009 Membership managed by groups: group_admins Membership managed by users: test
Additional resources
-
See
ipa group-add-member-manager --help
for more details.
11.9. Viewing group members using IdM CLI
This section describes how to view members of a group using IdM CLI. You can view both direct and indirect group members. For more information, see Direct and indirect group members.
Procedure:
To list members of a group, use the
ipa group-show group_name
command. For example:$ ipa group-show group_a ... Member users: user_a Member groups: group_b Indirect Member users: user_b
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.
11.10. Removing a member from a user group using IdM CLI
This section describes how to remove a member from a user group using IdM CLI.
Prerequisites
- 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
-
11.11. Removing users or groups as member managers from an IdM user group using the IdM CLI
This section describes how to remove users or groups as member managers from an IdM user group using the IdM CLI. Member managers can remove users or groups from IdM user groups but cannot change the attributes of a group.
Prerequisites
- You must be logged in as the administrator. For details, see Using kinit to log in to IdM manually.
- You must have the name of the existing member manager user or group you are removing and the name of the group they are managing.
Procedure
Remove a user as a member manager of an IdM user group by using the
ipa group-remove-member-manager
command.For example, to remove the user
test
as a member manager ofgroup_a
:$ ipa group-remove-member-manager group_a --users=test Group name: group_a GID: 1133400009 Membership managed by groups: group_admins --------------------------- Number of members removed 1 ---------------------------
User
test
can no longer manage members ofgroup_a
.Remove a group as a member manager of an IdM user group by using the
ipa group-remove-member-manager
command.For example, to remove the group
group_admins
as a member manager ofgroup_a
:$ ipa group-remove-member-manager group_a --groups=group_admins Group name: group_a GID: 1133400009 --------------------------- Number of members removed 1 ---------------------------
Group
group_admins
can no longer manage members ofgroup_a
.
After you remove a member manager from a user group, the update may take some time to spread to all clients in your Identity Management environment.
Verification steps
Using the
ipa group-show
command to verify the user and group were removed as member managers.$ ipa group-show group_a Group name: group_a GID: 1133400009
Additional resources
-
See
ipa group-remove-member-manager --help
for more details.
Chapter 12. Managing user groups in IdM Web UI
This chapter introduces user groups management using the IdM web UI.
A user group is a set of users with common privileges, password policies, and other characteristics.
A user group in Identity Management (IdM) can include:
- IdM users
- other IdM user groups
- external users, which are users that exist outside of IdM
12.1. The different group types in IdM
IdM supports the following types of groups:
- POSIX groups (the default)
POSIX groups support Linux POSIX attributes for their members. Note that groups that interact with Active Directory cannot use POSIX attributes.
POSIX attributes identify users as separate entities. Examples of POSIX attributes relevant to users include
uidNumber
, a user number (UID), andgidNumber
, a group number (GID).- Non-POSIX groups
Non-POSIX groups do not support POSIX attributes. For example, these groups do not have a GID defined.
All members of this type of group must belong to the IdM domain.
- External groups
Use external groups to add group members that exist in an identity store outside of the IdM domain, such as:
- A local system
- An Active Directory domain
- A directory service
External groups do not support POSIX attributes. For example, these groups do not have a GID defined.
Table 12.1. User groups created by default
Group name | Default group members |
---|---|
| All IdM users |
|
Users with administrative privileges, including the default |
| This is a legacy group that no longer has any special privileges |
| Users with privileges to manage the Active Directory trusts |
When you add a user to a user group, the user gains the privileges and policies associated with the group. For example, to grant administrative privileges to a user, add the user to the admins
group.
Do not delete the admins
group. As admins
is a pre-defined group required by IdM, this operation causes problems with certain commands.
In addition, IdM creates user private groups by default whenever a new user is created in IdM. For more information about private groups, see Adding users without a private group.
12.2. Direct and indirect group members
User group attributes in IdM apply to both direct and indirect members: when group B is a member of group A, all users in group B are considered indirect members of group A.
For example, in the following diagram:
- User 1 and User 2 are direct members of group A.
- User 3, User 4, and User 5 are indirect members of group A.
Figure 12.1. Direct and Indirect Group Membership

If you set a password policy for user group A, the policy also applies to all users in user group B.
12.3. Adding a user group using IdM Web UI
This section describes how to add a user group using the IdM Web UI.
Prerequisites
- You are logged in to the IdM Web UI.
Procedure
- 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.
12.4. Deleting a user group using IdM Web UI
This section describes how to delete a user group using the IdM Web UI. Note that deleting a group does not delete the group members from IdM.
Prerequisites
- You are logged in to the IdM Web UI.
Procedure
- Click Identity → Groups and select User Groups.
- Select the group to delete.
- Click Delete.
- Click Delete to confirm.
12.5. Adding a member to a user group using IdM Web UI
You can add both users and user groups as members of a user group. For more information, see The different group types in IdM and Direct and indirect group members.
Prerequisites
- You are logged in to the IdM Web UI.
Procedure
- 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.
12.6. Adding users or groups as member managers to an IdM user group using the Web UI
This section describes how to add users or groups as member managers to an IdM user group using the Web UI. Member managers can add users or groups to IdM user groups but cannot change the attributes of a group.
Prerequisites
- You are logged in to the IdM Web UI.
- You must have the name of the user or group you are adding as member managers and the name of the group you want them to manage.
Procedure
- Click Identity → Groups and select User Groups in the left sidebar.
- Click the name of the group.
Select the type of group member manager you want to add: Users or User Groups.
- Click Add.
- Select the check box next to one or more members you want to add.
Click the rightward arrow to move the selected members to the group.
- Click Add to confirm.
After you add a member manager to a user group, the update may take some time to spread to all clients in your Identity Management environment.
Verification steps
Verify the newly added user or user group has been added to the member manager list of users or user groups:
Additional resources
-
See
ipa group-add-member-manager --help
for more information.
12.7. Viewing group members using IdM Web UI
This section describes how to view members of a group using the IdM Web UI. You can view both direct and indirect group members. For more information, see Direct and indirect group members.
Prerequisites
- You are logged in to the IdM Web UI.
Procedure
- 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.
12.8. Removing a member from a user group using IdM Web UI
This section describes how to remove a member from a user group using the IdM Web UI.
Prerequisites
- You are logged in to the IdM Web UI.
Procedure
- 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.
12.9. Removing users or groups as member managers from an IdM user group using the Web UI
This section describes how to remove users or groups as member managers from an IdM user group using the Web UI. Member managers can remove users or groups from IdM user groups but cannot change the attributes of a group.
Prerequisites
- You are logged in to the IdM Web UI.
- You must have the name of the existing member manager user or group you are removing and the name of the group they are managing.
Procedure
- Click Identity → Groups and select User Groups in the left sidebar.
- Click the name of the group.
Select the type of member manager you want to remove: Users or User Groups.
- Select the check box next to the member manager you want to remove.
- Click Delete.
- Click Delete to confirm.
After you remove a member manager from a user group, the update may take some time to spread to all clients in your Identity Management environment.
Verification steps
Verify the user or user group has been removed from the member manager list of users or user groups:
Additional resources
-
See
ipa group-add-member-manager --help
for more details.
Chapter 13. 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
- 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
13.1. The different group types in IdM
IdM supports the following types of groups:
- POSIX groups (the default)
POSIX groups support Linux POSIX attributes for their members. Note that groups that interact with Active Directory cannot use POSIX attributes.
POSIX attributes identify users as separate entities. Examples of POSIX attributes relevant to users include
uidNumber
, a user number (UID), andgidNumber
, a group number (GID).- Non-POSIX groups
Non-POSIX groups do not support POSIX attributes. For example, these groups do not have a GID defined.
All members of this type of group must belong to the IdM domain.
- External groups
Use external groups to add group members that exist in an identity store outside of the IdM domain, such as:
- A local system
- An Active Directory domain
- A directory service
External groups do not support POSIX attributes. For example, these groups do not have a GID defined.
Table 13.1. User groups created by default
Group name | Default group members |
---|---|
| All IdM users |
|
Users with administrative privileges, including the default |
| This is a legacy group that no longer has any special privileges |
| Users with privileges to manage the Active Directory trusts |
When you add a user to a user group, the user gains the privileges and policies associated with the group. For example, to grant administrative privileges to a user, add the user to the admins
group.
Do not delete the admins
group. As admins
is a pre-defined group required by IdM, this operation causes problems with certain commands.
In addition, IdM creates user private groups by default whenever a new user is created in IdM. For more information about private groups, see Adding users without a private group.
13.2. Direct and indirect group members
User group attributes in IdM apply to both direct and indirect members: when group B is a member of group A, all users in group B are considered indirect members of group A.
For example, in the following diagram:
- User 1 and User 2 are direct members of group A.
- User 3, User 4, and User 5 are indirect members of group A.
Figure 13.1. Direct and Indirect Group Membership

If you set a password policy for user group A, the policy also applies to all users in user group B.
13.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 installed the ansible-freeipa package on the Ansible controller.
- 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 become: true tasks: - name: Create group ops with gid 1234 ipagroup: ipaadmin_password: MySecret123 name: ops gidnumber: 1234 - name: Create group sysops ipagroup: ipaadmin_password: MySecret123 name: sysops user: - idm_user - name: Create group appops ipagroup: ipaadmin_password: MySecret123 name: appops - name: Add group members sysops and appops to group ops ipagroup: ipaadmin_password: MySecret123 name: ops group: - sysops - appops
Run the playbook:
$ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/add-group-members.yml
Verification steps
You can verify if the ops group contains sysops and appops as direct members and idm_user as an indirect member by using the ipa group-show
command:
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.
13.4. Ensuring the presence of member managers in IdM user groups using Ansible playbooks
The following procedure describes ensuring the presence of IdM member managers - both users and user groups - using an Ansible playbook.
Prerequisites
- You know the IdM administrator password.
- You have installed the ansible-freeipa package on the Ansible controller.
- You must have the name of the user or group you are adding as member managers and the name of the group you want them to manage.
Procedure
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 become: true tasks: - name: Ensure user test is present for group_a ipagroup: ipaadmin_password: MySecret123 name: group_a membermanager_user: test - name: Ensure group_admins is present for group_a ipagroup: ipaadmin_password: MySecret123 name: group_a membermanager_group: group_admins
Run the playbook:
$ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/add-member-managers-user-groups.yml
Verification steps
You can verify if the group_a group contains test as a member manager and group_admins is a member manager of group_a by using the ipa group-show
command:
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.
13.5. Ensuring the absence of member managers in IdM user groups using Ansible playbooks
The following procedure describes ensuring the absence of IdM member managers - both users and user groups - using an Ansible playbook.
Prerequisites
- You know the IdM administrator password.
- You have installed the ansible-freeipa package on the Ansible controller.
- You must have the name of the existing member manager user or group you are removing and the name of the group they are managing.
Procedure
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 become: true tasks: - name: Ensure member manager user and group members are absent for group_a ipagroup: ipaadmin_password: MySecret123 name: group_a membermanager_user: test membermanager_group: group_admins action: member state: absent
Run the playbook:
$ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-member-managers-are-absent.yml
Verification steps
You can verify if the group_a group does not contain test as a member manager and group_admins as a member manager of group_a by using the ipa group-show
command:
Log into
ipaserver
as administrator:$ ssh admin@server.idm.example.com Password: [admin@server /]$
Display information about group_a:
ipaserver]$ ipa group-show group_a Group name: group_a GID: 1133400009
Additional resources
-
See
ipa host-remove-member-manager --help
. -
See the
ipa
man page.
Chapter 14. Automating group membership using IdM CLI
Using automatic group membership allows you to assign users and hosts to groups automatically based on their attributes. For example, you can:
- Divide employees' user entries into groups based on the employees' manager, location, or any other attribute.
- Divide hosts based on their class, location, or any other attribute.
- Add all users or all hosts to a single global group.
This chapter covers the following topics:
- Benefits of automatic group membership
- Automember rules
- Adding an automember rule using IdM CLI
- Adding a condition to an automember rule using IdM CLI
- Viewing existing automember rules using IdM CLI
- Deleting an automember rule using IdM CLI
- Removing a condition from an automember rule using IdM CLI
- Applying automember rules to existing entries using IdM CLI
- Configuring a default automember group using IdM CLI
14.1. Benefits of automatic group membership
Using automatic membership for users allows you to:
Reduce the overhead of manually managing group memberships
You no longer have to assign every user and host to groups manually.
Improve consistency in user and host management
Users and hosts are assigned to groups based on strictly defined and automatically evaluated criteria.
Simplify the management of group-based settings
Various settings are defined for groups and then applied to individual group members, for example
sudo
rules, automount, or access control. Adding users and hosts to groups automatically makes managing these settings easier.
14.2. Automember rules
When configuring automatic group membership, the administrator defines automember rules. An automember rule applies to a specific user or host target group. It cannot apply to more than one group at a time.
After creating a rule, the administrator adds conditions to it. These specify which users or hosts get included or excluded from the target group:
Inclusive conditions
When a user or host entry meets an inclusive condition, it will be included in the target group.
Exclusive conditions
When a user or host entry meets an exclusive condition, it will not be included in the target group.
The conditions are specified as regular expressions in the Perl-compatible regular expressions (PCRE) format. For more information on PCRE, see the pcresyntax(3)
man page.
IdM evaluates exclusive conditions before inclusive conditions. In case of a conflict, exclusive conditions take precedence over inclusive conditions.
An automember rule applies to every entry created in the future. These entries will be automatically added to the specified target group. If an entry meets the conditions specified in multiple automember rules, it will be added to all the corresponding groups.
Existing entries are not affected by the new rule. If you want to change existing entries, see Applying automember rules to existing entries using IdM CLI.
14.3. Adding an automember rule using IdM CLI
This section describes adding an automember rule using the IdM CLI. For information about automember rules, see Automember rules.
After adding an automember rule, you can add conditions to it using the procedure described in Adding a condition to an automember rule.
Existing entries are not affected by the new rule. If you want to change existing entries, see Applying automember rules to existing entries using IdM CLI.
Prerequisites
- You must be logged in as the administrator. For details, see Using kinit to log in to IdM manually.
- The target group of the new rule must exist in IdM.
Procedure
-
Enter the
ipa automember-add
command to add an automember rule. When prompted, specify:
- Automember rule. This is the target group name.
- Grouping Type. This specifies whether the rule targets a user group or a host group. To target a user group, enter group. To target a host group, enter hostgroup.
For example, to add an automember rule for a user group named user_group:
$ ipa automember-add Automember Rule: user_group Grouping Type: group -------------------------------- Added automember rule "user_group" -------------------------------- Automember Rule: user_group
Verification steps
- You can display existing automember rules and conditions in IdM using Viewing existing automember rules using IdM CLI.
14.4. Adding a condition to an automember rule using IdM CLI
This section describes how to add a condition to an automember rule using the IdM CLI. For information about automember rules, see Automember rules.
Prerequisites
- You must be logged in as the administrator. For details, see Using kinit to log in to IdM manually.
- The target rule must exist in IdM. For details, see Adding an automember rule using IdM CLI.
Procedure
-
Define one or more inclusive or exclusive conditions using the
ipa automember-add-condition
command. When prompted, specify:
- Automember rule. This is the target rule name. See Automember rules for details.
- Attribute Key. This specifies the entry attribute to which the filter will apply. For example, uid for users.
- Grouping Type. This specifies whether the rule targets a user group or a host group. To target a user group, enter group. To target a host group, enter hostgroup.
- Inclusive regex and Exclusive regex. These specify one or more conditions as regular expressions. If you only want to specify one condition, press Enter when prompted for the other.
For example, the following condition targets all users with any value (.*) in their user login attribute (uid).
$ ipa automember-add-condition Automember Rule: user_group Attribute Key: uid Grouping Type: group [Inclusive Regex]: .* [Exclusive Regex]: ---------------------------------- Added condition(s) to "user_group" ---------------------------------- Automember Rule: user_group Inclusive Regex: uid=.* ---------------------------- Number of conditions added 1 ----------------------------
As another example, you can use an automembership rule to target all Windows users synchronized from Active Directory (AD). To achieve this, create a condition that that targets all users with ntUser in their objectClass attribute, which is shared by all AD users:
$ ipa automember-add-condition Automember Rule: ad_users Attribute Key: objectclass Grouping Type: group [Inclusive Regex]: ntUser [Exclusive Regex]: ------------------------------------- Added condition(s) to "ad_users" ------------------------------------- Automember Rule: ad_users Inclusive Regex: objectclass=ntUser ---------------------------- Number of conditions added 1 ----------------------------
Verification steps
- You can display existing automember rules and conditions in IdM using Viewing existing automember rules using IdM CLI.
14.5. Viewing existing automember rules using IdM CLI
This section describes how to view existing automember rules using the IdM CLI.
Prerequisites
- You must be logged in as the administrator. For details, see Using kinit to log in to IdM manually.
Procedure
-
Enter the
ipa automember-find
command. When prompted, specify the Grouping type:
- To target a user group, enter group.
To target a host group, enter hostgroup.
For example:
$ ipa automember-find Grouping Type: group --------------- 1 rules matched --------------- Automember Rule: user_group Inclusive Regex: uid=.* ---------------------------- Number of entries returned 1 ----------------------------
14.6. Deleting an automember rule using IdM CLI
This section describes how to delete an automember rule using the IdM CLI.
Deleting an automember rule also deletes all conditions associated with the rule. To remove only specific conditions from a rule, see Removing a condition from an automember rule using IdM CLI.
Prerequisites
- You must be logged in as the administrator. For details, see Using kinit to log in to IdM manually.
Procedure
-
Enter the
ipa automember-del
command. When prompted, specify:
- Automember rule. This is the rule you want to delete.
- Grouping rule. This specifies whether the rule you want to delete is for a user group or a host group. Enter group or hostgroup.
14.7. Removing a condition from an automember rule using IdM CLI
This section describes how to remove a specific condition from an automember rule.
Prerequisites
- You must be logged in as the administrator. For details, see Using kinit to log in to IdM manually.
Procedure
-
Enter the
ipa automember-remove-condition
command. When prompted, specify:
- Automember rule. This is the name of the rule from which you want to remove a condition.
- Attribute Key. This is the target entry attribute. For example, uid for users.
- Grouping Type. This specifies whether the condition you want to delete is for a user group or a host group. Enter group or hostgroup.
Inclusive regex and Exclusive regex. These specify the conditions you want to remove. If you only want to specify one condition, press Enter when prompted for the other.
For example:
$ ipa automember-remove-condition Automember Rule: user_group Attribute Key: uid Grouping Type: group [Inclusive Regex]: .* [Exclusive Regex]: ----------------------------------- Removed condition(s) from "user_group" ----------------------------------- Automember Rule: user_group ------------------------------ Number of conditions removed 1 ------------------------------
14.8. Applying automember rules to existing entries using IdM CLI
Automember rules apply automatically to user and host entries created after the rules were added. They are not applied retroactively to entries that existed before the rules were added.
To apply automember rules to previously added entries, you have to manually rebuild automatic membership. Rebuilding automatic membership re-evaluates all existing automember rules and applies them either to all user or hosts entries, or to specific entries.
Rebuilding automatic membership does not remove user or host entries from groups, even if the entries no longer match the group’s inclusive conditions. To remove them manually, see Removing a member from a user group using IdM CLI or Removing IdM host group members using the CLI.
Prerequisites
- You must be logged in as the administrator. For details, see Using kinit to log in to IdM manually.
Procedure
To rebuild automatic membership, enter the
ipa automember-rebuild
command. Use the following options to specify the entries to target:To rebuild automatic membership for all users, use the
--type=group
option:$ ipa automember-rebuild --type=group -------------------------------------------------------- Automember rebuild task finished. Processed (9) entries. --------------------------------------------------------
-
To rebuild automatic membership for all hosts, use the
--type=hostgroup
option. To rebuild automatic membership for a specified user or users, use the
--users=target_user
option:$ ipa automember-rebuild --users=target_user1 --users=target_user2 -------------------------------------------------------- Automember rebuild task finished. Processed (2) entries. --------------------------------------------------------
-
To rebuild automatic membership for a specified host or hosts, use the
--hosts=client.idm.example.com
option.
14.9. Configuring a default automember group using IdM CLI
When you configure a default automember group, new user or host entries that do not match any automember rule are automatically added to this default group.
Prerequisites
- You must be logged in as the administrator. For details, see Using kinit to log in to IdM manually.
- The target group you want to set as default exists in IdM.
Procedure
-
Enter the
ipa automember-default-group-set
command to configure a default automember group. When prompted, specify:
- Default (fallback) Group, which specifies the target group name.
Grouping Type, which specifies whether the target is a user group or a host group. To target a user group, enter group. To target a host group, enter hostgroup.
For example:
$ ipa automember-default-group-set Default (fallback) Group: default_user_group Grouping Type: group --------------------------------------------------- Set default (fallback) group for automember "default_user_group" --------------------------------------------------- Default (fallback) Group: cn=default_user_group,cn=groups,cn=accounts,dc=example,dc=com
NoteTo remove the current default automember group, enter the
ipa automember-default-group-remove
command.
Verification steps
To verify that the group is set correctly, enter the
ipa automember-default-group-show
command. The command displays the current default automember group. For example:$ ipa automember-default-group-show Grouping Type: group Default (fallback) Group: cn=default_user_group,cn=groups,cn=accounts,dc=example,dc=com
Chapter 15. Automating group membership using IdM Web UI
Using automatic group membership enables you to assign users and hosts to groups automatically based on their attributes. For example, you can:
- Divide employees' user entries into groups based on the employees' manager, location, or any other attribute.
- Divide hosts based on their class, location, or any other attribute.
- Add all users or all hosts to a single global group.
This chapter covers the following topics:
- Benefits of automatic group membership
- Automember rules
- Adding an automember rule using IdM Web UI
- Adding a condition to an automember rule using IdM Web UI
- Viewing existing automember rules and conditions using IdM Web UI
- Deleting an automember rule using IdM Web UI
- Removing a condition from an automember rule using IdM Web UI
- Applying automember rules to existing entries using IdM Web UI
- Configuring a default user group using IdM Web UI
- Configuring a default host group using IdM Web UI
15.1. Benefits of automatic group membership
Using automatic membership for users allows you to:
Reduce the overhead of manually managing group memberships
You no longer have to assign every user and host to groups manually.
Improve consistency in user and host management
Users and hosts are assigned to groups based on strictly defined and automatically evaluated criteria.
Simplify the management of group-based settings
Various settings are defined for groups and then applied to individual group members, for example
sudo
rules, automount, or access control. Adding users and hosts to groups automatically makes managing these settings easier.
15.2. Automember rules
When configuring automatic group membership, the administrator defines automember rules. An automember rule applies to a specific user or host target group. It cannot apply to more than one group at a time.
After creating a rule, the administrator adds conditions to it. These specify which users or hosts get included or excluded from the target group:
Inclusive conditions
When a user or host entry meets an inclusive condition, it will be included in the target group.
Exclusive conditions
When a user or host entry meets an exclusive condition, it will not be included in the target group.
The conditions are specified as regular expressions in the Perl-compatible regular expressions (PCRE) format. For more information on PCRE, see the pcresyntax(3)
man page.
IdM evaluates exclusive conditions before inclusive conditions. In case of a conflict, exclusive conditions take precedence over inclusive conditions.
An automember rule applies to every entry created in the future. These entries will be automatically added to the specified target group. If an entry meets the conditions specified in multiple automember rules, it will be added to all the corresponding groups.
Existing entries are not affected by the new rule. If you want to change existing entries, see Applying automember rules to existing entries using IdM Web UI.
15.3. Adding an automember rule using IdM Web UI
This section describes adding an automember rule using the IdM Web UI. For information about automember rules, see Automember rules.
Existing entries are not affected by the new rule. If you want to change existing entries, see Applying automember rules to existing entries using IdM Web UI.
Prerequisites
- You are logged in to the IdM Web UI.
-
You must be a member of the
admins
group. - The target group of the new rule exists in IdM.
Procedure
- Click Identity → Automember, and select either User group rules or Host group rules.
- Click Add.
In the Automember rule field, select the group to which the rule will apply. This is the target group name.
- Click Add to confirm.
- Optional: You can add conditions to the new rule using the procedure described in Adding a condition to an automember rule using IdM Web UI.
15.4. Adding a condition to an automember rule using IdM Web UI
This section describes how to add a condition to an automember rule using the IdM Web UI. For information about automember rules, see Automember rules.
Prerequisites
- You are logged in to the IdM Web UI.
-
You must be a member of the
admins
group. - The target rule exists in IdM.
Procedure
- Click Identity → Automember, and select either User group rules or Host group rules.
- Click on the rule to which you want to add a condition.
In the Inclusive or Exclusive sections, click Add.
- In the Attribute field, select the required attribute, for example uid.
- In the Expression field, define a regular expression.
Click Add.
For example, the following condition targets all users with any value (.*) in their user ID (uid) attribute.
15.5. Viewing existing automember rules and conditions using IdM Web UI
This section describes how to view existing automember rules and conditions using the IdM Web UI.
Prerequisites
- You are logged in to the IdM Web UI.
-
You must be a member of the
admins
group.
Procedure
- Click Identity → Automember, and select either User group rules or Host group rules to view the respective automember rules.
Optional: Click on a rule to see the conditions for that rule in the Inclusive or Exclusive sections.
15.6. Deleting an automember rule using IdM Web UI
This section describes how to delete an automember rule using the IdM Web UI.
Deleting an automember rule also deletes all conditions associated with the rule. To remove only specific conditions from a rule, see Removing a condition from an automember rule using IdM Web UI.
Prerequisites
- You are logged in to the IdM Web UI.
-
You must be a member of the
admins
group.
Procedure
- Click Identity → Automember, and select either User group rules or Host group rules to view the respective automember rules.
- Select the check box next to the rule you want to remove.
Click Delete.
- Click Delete to confirm.
15.7. Removing a condition from an automember rule using IdM Web UI
This section describes how to remove a specific condition from an automember rule using the IdM Web UI.
Prerequisites
- You are logged in to the IdM Web UI.
-
You must be a member of the
admins
group.
Procedure
- Click Identity → Automember, and select either User group rules or Host group rules to view the respective automember rules.
- Click on a rule to see the conditions for that rule in the Inclusive or Exclusive sections.
- Select the check box next to the conditions you want to remove.
Click Delete.
- Click Delete to confirm.
15.8. Applying automember rules to existing entries using IdM Web UI
Automember rules apply automatically to user and host entries created after the rules were added. They are not applied retroactively to entries that existed before the rules were added.
To apply automember rules to previously added entries, you have to manually rebuild automatic membership. Rebuilding automatic membership re-evaluates all existing automember rules and applies them either to all user or hosts entries, or to specific entries.
Rebuilding automatic membership does not remove user or host entries from groups, even if the entries no longer match the group’s inclusive conditions. To remove them manually, see Removing a member from a user group using IdM Web UI or Removing host group members in the IdM Web UI.
15.8.1. Rebuilding automatic membership for all users or hosts
This section describes how to rebuild automatic membership for all user or host entries.
Prerequisites
- You are logged in to the IdM Web UI.
-
You must be a member of the
admins
group.
Procedure
- Select Identity → Users or Hosts.
Click Actions → Rebuild auto membership.
15.8.2. Rebuilding automatic membership for a single user or host only
This section describes how to rebuild automatic membership for a specific user or host entry.
Prerequisites
- You are logged in to the IdM Web UI.
-
You must be a member of the
admins
group.
Procedure
- Select Identity → Users or Hosts.
- Click on the required user or host name.
Click Actions → Rebuild auto membership.
15.9. Configuring a default user group using IdM Web UI
When you configure a default user group, new user entries that do not match any automember rule are automatically added to this default group.
Prerequisites
- You are logged in to the IdM Web UI.
-
You must be a member of the
admins
group. - The target user group you want to set as default exists in IdM.
Procedure
- Click Identity → Automember, and select User group rules.
In the Default user group field, select the group you want to set as the default user group.
15.10. Configuring a default host group using IdM Web UI
When you configure a default host group, new host entries that do not match any automember rule are automatically added to this default group.
Prerequisites
- You are logged in to the IdM Web UI.
-
You must be a member of the
admins
group. - The target host group you want to set as default exists in IdM.
Procedure
- Click Identity → Automember, and select Host group rules.
In the Default host group field, select the group you want to set as the default host group.
Chapter 16. Using Ansible to automate group membership in IdM
Using automatic group membership, you can assign users and hosts user groups and host groups automatically, based on their attributes. For example, you can:
-
Divide employees' user entries into groups based on the employees' manager, location, position or any other attribute. You can list all attributes by entering
ipa user-add --help
on the command-line. -
Divide hosts into groups based on their class, location, or any other attribute. You can list all attributes by entering
ipa host-add --help
on the command-line. - Add all users or all hosts to a single global group.
You can use Red Hat Ansible Engine to automate the management of automatic group membership in Identity Management (IdM).
This section covers the following topics:
- Preparing your Ansible control node for managing IdM
- Using Ansible to ensure that an automember rule for an IdM user group is present
- Using Ansible to ensure that a condition is present in an IdM user group automember rule
- Using Ansible to ensure that a condition is absent in an IdM user group automember rule
- Using Ansible to ensure that an automember rule for an IdM group is absent
- Using Ansible to ensure that a condition is present in an IdM host group automember rule
16.1. Preparing your Ansible control node for managing IdM
As a system administrator managing Identity Management (IdM), when working with Red Hat Ansible Engine, it is good practice to do the following:
- Create a subdirectory dedicated to Ansible playbooks in your home directory, for example ~/MyPlaybooks.
-
Copy and adapt sample Ansible playbooks from the
/usr/share/doc/ansible-freeipa/*
and/usr/share/doc/rhel-system-roles/*
directories and subdirectories into your ~/MyPlaybooks directory. - Include your inventory file in your ~/MyPlaybooks directory.
By following this practice, you can find all your playbooks in one place and you can run your playbooks without invoking root privileges.
You only need root
privileges on the managed nodes to execute the ipaserver
, ipareplica
, ipaclient
and ipabackup
ansible-freeipa
roles. These roles require privileged access to directories and the dnf
software package manager.
This section describes how to create the ~/MyPlaybooks directory and configure it so that you can use it to store and run Ansible playbooks.
Prerequisites
- You have installed an IdM server on your managed nodes, server.idm.example.com and replica.idm.example.com.
- You have configured DNS and networking so you can log in to the managed nodes, server.idm.example.com and replica.idm.example.com, directly from the control node.
-
You know the IdM
admin
password.
Procedure
Create a directory for your Ansible configuration and playbooks in your home directory:
$ mkdir ~/MyPlaybooks/
Change into the ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks
Create the ~/MyPlaybooks/ansible.cfg file with the following content:
[defaults] inventory = /home/your_username/MyPlaybooks/inventory [privilege_escalation] become=True
Create the ~/MyPlaybooks/inventory file with the following content:
[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
You must enter the IdM
admin
password when you enter these commands.
Additional resources
16.2. Using Ansible to ensure that an automember rule for an IdM user group is present
The following procedure describes how to use an Ansible playbook to ensure an automember
rule for an Identity Management (IdM) group exists. In the example, the presence of an automember
rule is ensured for the testing_group user group.
Prerequisites
-
You know the IdM
admin
password. - The testing_group user group exists in IdM.
You have configured an Ansible control node that meets the following requirements:
- You are using Ansible version 2.8 or later.
- You have installed the ansible-freeipa package.
- In the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server where you are configuring these options.
Procedure
Navigate to your ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
Copy the
automember-group-present.yml
Ansible playbook file located in the/usr/share/doc/ansible-freeipa/playbooks/automember/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/automember/automember-group-present.yml automember-group-present-copy.yml
-
Open the
automember-group-present-copy.yml
file for editing. Adapt the file by setting the following variables in the
ipaautomember
task section:-
Set the
ipaadmin_password
variable to the password of the IdMadmin
. -
Set the
name
variable to testing_group. -
Set the
automember_type
variable to group. -
Ensure that the
state
variable is set topresent
.
This is the modified Ansible playbook file for the current example:
--- - name: Automember group present example hosts: ipaserver become: true tasks: - name: Ensure group automember rule admins is present ipaautomember: ipaadmin_password: Secret123 name: testing_group automember_type: group state: present
-
Set the
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i inventory automember-group-present-copy.yml
Additional resources
- See Benefits of automatic group membership and Automember rules.
- See Using Ansible to ensure that a condition is present in an IdM user group automember rule.
-
See the
README-automember.md
file in the/usr/share/doc/ansible-freeipa/
directory. -
See the
/usr/share/doc/ansible-freeipa/playbooks/automember
directory.
16.3. Using Ansible to ensure that a specified condition is present in an IdM user group automember rule
The following procedure describes how to use an Ansible playbook to ensure that a specified condition exists in an automember
rule for an Identity Management (IdM) group. In the example, the presence of a UID-related condition in the automember
rule is ensured for the testing_group group. By specifying the .* condition, you ensure that all future IdM users automatically become members of the testing_group.
Prerequisites
-
You know the IdM
admin
password. - The testing_group user group and automember user group rule exist in IdM.
You have configured an Ansible control node that meets the following requirements:
- You are using Ansible version 2.8 or later.
- You have installed the ansible-freeipa package.
- In the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server where you are configuring these options.
Procedure
Navigate to your ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
Copy the
automember-hostgroup-rule-present.yml
Ansible playbook file located in the/usr/share/doc/ansible-freeipa/playbooks/automember/
directory and name it, for example, automember-usergroup-rule-present.yml:$ cp /usr/share/doc/ansible-freeipa/playbooks/automember/automember-hostgroup-rule-present.yml automember-usergroup-rule-present.yml
-
Open the
automember-usergroup-rule-present.yml
file for editing. Adapt the file by modifying the following parameters:
- Rename the playbook to correspond to your use case, for example: Automember user group rule member present.
- Rename the task to correspond to your use case, for example: Ensure an automember condition for a user group is present.
Set the following variables in the
ipaautomember
task section:-
Set the
ipaadmin_password
variable to the password of the IdMadmin
. -
Set the
name
variable to testing_group. -
Set the
automember_type
variable togroup
. -
Ensure that the
state
variable is set topresent
. -
Ensure that the
action
variable is set tomember
. -
Set the
inclusive
key
variable toUID
. -
Set the
inclusive
expression
variable to .*
-
Set the
This is the modified Ansible playbook file for the current example:
--- - name: Automember user group rule member present hosts: ipaserver become: true tasks: - name: Ensure an automember condition for a user group is present ipaautomember: ipaadmin_password: Secret123 name: testing_group automember_type: group state: present action: member inclusive: - key: UID expression: .*
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i inventory automember-usergroup-rule-present.yml
Verification steps
Log in as an IdM administrator.
$ kinit admin
Add a user, for example:
$ ipa user-add user101 --first user --last 101 ----------------------- Added user "user101" ----------------------- User login: user101 First name: user Last name: 101 ... Member of groups: ipausers, testing_group ...
Additional resources
- See Applying automember rules to existing entries using the IdM CLI.
- See Benefits of automatic group membership and Automember rules.
-
See the
README-automember.md
file in the/usr/share/doc/ansible-freeipa/
directory. -
See the
/usr/share/doc/ansible-freeipa/playbooks/automember
directory.
16.4. Using Ansible to ensure that a condition is absent from an IdM user group automember rule
The following procedure describes how to use an Ansible playbook to ensure a condition is absent from an automember
rule for an Identity Management (IdM) group. In the example, the absence of a condition in the automember
rule is ensured that specifies that users whose initials
are dp should be included. The automember rule is applied to the testing_group group. By applying the condition, you ensure that no future IdM user whose initials are dp becomes a member of the testing_group.
Prerequisites
-
You know the IdM
admin
password. - The testing_group user group and automember user group rule exist in IdM.
You have configured an Ansible control node that meets the following requirements:
- You are using Ansible version 2.8 or later.
- You have installed the ansible-freeipa package.
- In the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server where you are configuring these options.
Procedure
Navigate to your ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
Copy the
automember-hostgroup-rule-absent.yml
Ansible playbook file located in the/usr/share/doc/ansible-freeipa/playbooks/automember/
directory and name it, for example, automember-usergroup-rule-absent.yml:$ cp /usr/share/doc/ansible-freeipa/playbooks/automember/automember-hostgroup-rule-absent.yml automember-usergroup-rule-absent.yml
-
Open the
automember-usergroup-rule-absent.yml
file for editing. Adapt the file by modifying the following parameters:
- Rename the playbook to correspond to your use case, for example: Automember user group rule member absent.
- Rename the task to correspond to your use case, for example: Ensure an automember condition for a user group is absent.
Set the following variables in the
ipaautomember
task section:-
Set the
ipaadmin_password
variable to the password of the IdMadmin
. -
Set the
name
variable to testing_group. -
Set the
automember_type
variable to group. -
Ensure that the
state
variable is set toabsent
. -
Ensure that the
action
variable is set tomember
. -
Set the
inclusive
key
variable toinitials
. -
Set the
inclusive
expression
variable to dp.
-
Set the
This is the modified Ansible playbook file for the current example:
--- - name: Automember user group rule member absent hosts: ipaserver become: true tasks: - name: Ensure an automember condition for a user group is absent ipaautomember: ipaadmin_password: Secret123 name: testing_group automember_type: group state: absent action: member inclusive: - key: initials expression: dp
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i inventory automember-usergroup-rule-absent.yml
Verification steps
Log in as an IdM administrator.
$ kinit admin
View the automember group:
$ ipa automember-show --type=group testing_group Automember Rule: testing_group
The absence of an Inclusive Regex: initials=dp
entry in the output confirms that the testing_group automember rule does not contain the condition specified.
Additional resources
- See Applying automember rules to existing entries using the IdM CLI.
- See Benefits of automatic group membership and Automember rules.
-
See the
README-automember.md
file in the/usr/share/doc/ansible-freeipa/
directory. -
See the
/usr/share/doc/ansible-freeipa/playbooks/automember
directory.
16.5. Using Ansible to ensure that an automember rule for an IdM user group is absent
The following procedure describes how to use an Ansible playbook to ensure an automember
rule is absent for an Identity Management (IdM) group. In the example, the absence of an automember
rule is ensured for the testing_group group.
Deleting an automember rule also deletes all conditions associated with the rule. To remove only specific conditions from a rule, see Using Ansible to ensure that a condition is absent in an IdM user group automember rule.
Prerequisites
-
You know the IdM
admin
password. You have configured an Ansible control node that meets the following requirements:
- You are using Ansible version 2.8 or later.
- You have installed the ansible-freeipa package.
- In the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server where you are configuring these options.
Procedure
Navigate to your ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
Copy the
automember-group-absent.yml
Ansible playbook file located in the/usr/share/doc/ansible-freeipa/playbooks/automember/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/automember/automember-group-absent.yml automember-group-absent-copy.yml
-
Open the
automember-group-absent-copy.yml
file for editing. Adapt the file by setting the following variables in the
ipaautomember
task section:-
Set the
ipaadmin_password
variable to the password of the IdMadmin
. -
Set the
name
variable to testing_group. -
Set the
automember_type
variable to group. -
Ensure that the
state
variable is set toabsent
.
This is the modified Ansible playbook file for the current example:
--- - name: Automember group absent example hosts: ipaserver become: true tasks: - name: Ensure group automember rule admins is absent ipaautomember: ipaadmin_password: Secret123 name: testing_group automember_type: group state: absent
-
Set the
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i inventory automember-group-absent.yml
Additional resources
- See Benefits of automatic group membership and Automember rules.
-
See the
README-automember.md
file in the/usr/share/doc/ansible-freeipa/
directory. -
See the
/usr/share/doc/ansible-freeipa/playbooks/automember
directory.
16.6. Using Ansible to ensure that a condition is present in an IdM host group automember rule
This section describes how to use Ansible to ensure that a condition is present in an IdM host group automember rule. The example describes how to ensure that hosts with the FQDN
of .*.idm.example.com are members of the primary_dns_domain_hosts host group and hosts whose FQDN
is .*.example.org are not members of the primary_dns_domain_hosts host group.
Prerequisites
-
You know the IdM
admin
password. - The primary_dns_domain_hosts host group and automember host group rule exist in IdM.
You have configured an Ansible control node that meets the following requirements:
- You are using Ansible version 2.8 or later.
- You have installed the ansible-freeipa package.
- In the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server where you are configuring these options.
Procedure
Navigate to your ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
Copy the
automember-hostgroup-rule-present.yml
Ansible playbook file located in the/usr/share/doc/ansible-freeipa/playbooks/automember/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/automember/automember-hostgroup-rule-present.yml automember-hostgroup-rule-present-copy.yml
-
Open the
automember-hostgroup-rule-present-copy.yml
file for editing. Adapt the file by setting the following variables in the
ipaautomember
task section:-
Set the
ipaadmin_password
variable to the password of the IdMadmin
. -
Set the
name
variable to primary_dns_domain_hosts. -
Set the
automember_type
variable to hostgroup. -
Ensure that the
state
variable is set topresent
. -
Ensure that the
action
variable is set tomember
. -
Ensure that the
inclusive
key
variable is set tofqdn
. -
Set the corresponding
inclusive
expression
variable to .*.idm.example.com. -
Set the
exclusive
key
variable tofqdn
. -
Set the corresponding
exclusive
expression
variable to .*.example.org.
This is the modified Ansible playbook file for the current example:
--- - name: Automember user group rule member present hosts: ipaserver become: true tasks: - name: Ensure an automember condition for a user group is present ipaautomember: ipaadmin_password: Secret123 name: primary_dns_domain_hosts automember_type: hostgroup state: present action: member inclusive: - key: fqdn expression: .*.idm.example.com exclusive: - key: fqdn expression: .*.example.org
-
Set the
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i inventory automember-hostgroup-rule-present-copy.yml
Additional resources
- See Applying automember rules to existing entries using the IdM CLI.
- See Benefits of automatic group membership and Automember rules.
-
See the
README-automember.md
file in the/usr/share/doc/ansible-freeipa/
directory. -
See the
/usr/share/doc/ansible-freeipa/playbooks/automember
directory.
16.7. Additional resources
Chapter 17. Delegating permissions to user groups to manage users using IdM CLI
Delegation is one of the access control methods in IdM, along with self-service rules and role-based access control (RBAC). You can use delegation to assign permissions to one group of users to manage entries for another group of users.
This section covers the following topics:
17.1. Delegation rules
You can delegate permissions to user groups to manage users by creating delegation rules.
Delegation rules allow a specific user group to perform write (edit) operations on specific attributes for users in another user group. This form of access control rule is limited to editing the values of a subset of attributes you specify in a delegation rule; it does not grant the ability to add or remove whole entries or control over unspecified attributes.
Delegation rules grant permissions to existing user groups in IdM. You can use delegation to, for example, allow the managers
user group to manage selected attributes of users in the employees
user group.
17.2. Creating a delegation rule using IdM CLI
This section describes how to create a delegation rule using the IdM CLI.
Prerequisites
-
You are logged in as a member of the
admins
group.
Procedure
Enter the
ipa delegation-add
command. Specify the following options:-
--group
: the group who is being granted permissions to the entries of users in the user group. -
--membergroup
: the group whose entries can be edited by members of the delegation group. -
--permissions
: whether users will have the right to view the given attributes (read) and add or change the given attributes (write). If you do not specify permissions, only the write permission will be added. -
--attrs
: the attributes which users in the member group are allowed to view or edit.
For example:
-
$ ipa delegation-add "basic manager attributes" --permissions=read --permissions=write --attrs=businesscategory --attrs=departmentnumber --attrs=employeetype --attrs=employeenumber --group=managers --membergroup=employees
-------------------------------------------
Added delegation "basic manager attributes"
-------------------------------------------
Delegation name: basic manager attributes
Permissions: read, write
Attributes: businesscategory, departmentnumber, employeetype, employeenumber
Member user group: employees
User group: managers
17.3. Viewing existing delegation rules using IdM CLI
This section describes how to view existing delegation rules using the IdM CLI.
Prerequisites
-
You are logged in as a member of the
admins
group.
Procedure
-
Enter the
ipa delegation-find
command:
$ ipa delegation-find
--------------------
1 delegation matched
--------------------
Delegation name: basic manager attributes
Permissions: read, write
Attributes: businesscategory, departmentnumber, employeenumber, employeetype
Member user group: employees
User group: managers
----------------------------
Number of entries returned 1
----------------------------
17.4. Modifying a delegation rule using IdM CLI
This section describes how to modify an existing delegation rule using the IdM CLI.
The --attrs
option overwrites whatever the previous list of supported attributes was, so always include the complete list of attributes along with any new attributes. This also applies to the --permissions
option.
Prerequisites
-
You are logged in as a member of the
admins
group.
Procedure
Enter the
ipa delegation-mod
command with the desired changes. For example, to add thedisplayname
attribute to thebasic manager attributes
example rule:$ ipa delegation-mod "basic manager attributes" --attrs=businesscategory --attrs=departmentnumber --attrs=employeetype --attrs=employeenumber --attrs=displayname ---------------------------------------------- Modified delegation "basic manager attributes" ---------------------------------------------- Delegation name: basic manager attributes Permissions: read, write Attributes: businesscategory, departmentnumber, employeetype, employeenumber, displayname Member user group: employees User group: managers
17.5. Deleting a delegation rule using IdM CLI
This section describes how to delete an existing delegation rule using the IdM CLI.
Prerequisites
-
You are logged in as a member of the
admins
group.
Procedure
-
Enter the
ipa delegation-del
command. When prompted, enter the name of the delegation rule you want to delete:
$ ipa delegation-del Delegation name: basic manager attributes --------------------------------------------- Deleted delegation "basic manager attributes" ---------------------------------------------
Chapter 18. Delegating permissions to user groups to manage users using IdM WebUI
Delegation is one of the access control methods in IdM, along with self-service rules and role-based access control (RBAC). You can use delegation to assign permissions to one group of users to manage entries for another group of users.
This section covers the following topics:
18.1. Delegation rules
You can delegate permissions to user groups to manage users by creating delegation rules.
Delegation rules allow a specific user group to perform write (edit) operations on specific attributes for users in another user group. This form of access control rule is limited to editing the values of a subset of attributes you specify in a delegation rule; it does not grant the ability to add or remove whole entries or control over unspecified attributes.
Delegation rules grant permissions to existing user groups in IdM. You can use delegation to, for example, allow the managers
user group to manage selected attributes of users in the employees
user group.
18.2. Creating a delegation rule using IdM WebUI
This section describes how to create a delegation rule using the IdM WebUI.
Prerequisites
-
You are logged in to the IdM Web UI as a member of the
admins
group.
Procedure
- From the IPA Server menu, click Role-Based Access Control → Delegations.
Click Add.
In the Add delegation window, do the following:
- Name the new delegation rule.
- Set the permissions by selecting the check boxes that indicate whether users will have the right to view the given attributes (read) and add or change the given attributes (write).
- In the User group drop-down menu, select the group who is being granted permissions to view or edit the entries of users in the member group.
- In the Member user group drop-down menu, select the group whose entries can be edited by members of the delegation group.
In the attributes box, select the check boxes by the attributes to which you want to grant permissions.
- Click the Add button to save the new delegation rule.
18.3. Viewing existing delegation rules using IdM WebUI
This section describes how to view existing delegation rules using the IdM WebUI.
Prerequisites
-
You are logged in to the IdM Web UI as a member of the
admins
group.
Procedure
From the IPA Server menu, click Role-Based Access Control → Delegations.
18.4. Modifying a delegation rule using IdM WebUI
This section describes how to modify an existing delegation rule using the IdM WebUI.
Prerequisites
-
You are logged in to the IdM Web UI as a member of the
admins
group.
Procedure
From the IPA Server menu, click Role-Based Access Control → Delegations.
- Click on the rule you want to modify.
Make the desired changes:
- Change the name of the rule.
- Change granted permissions by selecting the check boxes that indicate whether users will have the right to view the given attributes (read) and add or change the given attributes (write).
- In the User group drop-down menu, select the group who is being granted permissions to view or edit the entries of users in the member group.
- In the Member user group drop-down menu, select the group whose entries can be edited by members of the delegation group.
In the attributes box, select the check boxes by the attributes to which you want to grant permissions. To remove permissions to an attribute, uncheck the relevant check box.
- Click the Save button to save the changes.
18.5. Deleting a delegation rule using IdM WebUI
This section describes how to delete an existing delegation rule using the IdM WebUI.
Prerequisites
-
You are logged in to the IdM Web UI as a member of the
admins
group.
Procedure
- From the IPA Server menu, click Role-Based Access Control → Delegations.
- Select the check box next to the rule you want to remove.
Click Delete.
- Click Delete to confirm.
Chapter 19. Delegating permissions to user groups to manage users using Ansible playbooks
Delegation is one of the access control methods in IdM, along with self-service rules and role-based access control (RBAC). You can use delegation to assign permissions to one group of users to manage entries for another group of users.
This section covers the following topics:
- Delegation rules
- Creating the Ansible inventory file for IdM
- Using Ansible to ensure that a delegation rule is present
- Using Ansible to ensure that a delegation rule is absent
- Using Ansible to ensure that a delegation rule has specific attributes
- Using Ansible to ensure that a delegation rule does not have specific attributes
19.1. Delegation rules
You can delegate permissions to user groups to manage users by creating delegation rules.
Delegation rules allow a specific user group to perform write (edit) operations on specific attributes for users in another user group. This form of access control rule is limited to editing the values of a subset of attributes you specify in a delegation rule; it does not grant the ability to add or remove whole entries or control over unspecified attributes.
Delegation rules grant permissions to existing user groups in IdM. You can use delegation to, for example, allow the managers
user group to manage selected attributes of users in the employees
user group.
19.2. Creating an Ansible inventory file for IdM
When working with Ansible, it is good practice to create, in your home directory, a subdirectory dedicated to Ansible playbooks that you copy and adapt from the /usr/share/doc/ansible-freeipa/*
and /usr/share/doc/rhel-system-roles/*
subdirectories. This practice has the following advantages:
- You can find all your playbooks in one place.
-
You can run your playbooks without invoking
root
privileges.
Procedure
Create a directory for your Ansible configuration and playbooks in your home directory:
$ mkdir ~/MyPlaybooks/
Change into the ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks
Create the ~/MyPlaybooks/ansible.cfg file with the following content:
[defaults] inventory = /home/<username>/MyPlaybooks/inventory [privilege_escalation] become=True
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.
19.3. Using Ansible to ensure that a delegation rule is present
The following procedure describes how to use an Ansible playbook to define privileges for a new IdM delegation rule and ensure its presence. In the example, the new basic manager attributes delegation rule grants the managers
group the ability to read and write the following attributes for members of the employees
group:
-
businesscategory
-
departmentnumber
-
employeenumber
-
employeetype
Prerequisites
- You know the IdM administrator password.
You have configured an Ansible control node that meets the following requirements:
- You are using Ansible version 2.8 or later.
- You have installed the ansible-freeipa package.
- You have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server where you are configuring these options.
- Your Ansible inventory file is located in the ~/MyPlaybooks/ directory.
Procedure
Navigate to the ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
Make a copy of the
delegation-present.yml
file located in the/usr/share/doc/ansible-freeipa/playbooks/delegation/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/delegation/delegation-present.yml delegation-present-copy.yml
-
Open the
delegation-present-copy.yml
Ansible playbook file for editing. Adapt the file by setting the following variables in the
ipadelegation
task section:-
Set the
ipaadmin_password
variable to the password of the IdM administrator. -
Set the
name
variable to the name of the new delegation rule. -
Set the
permission
variable to a comma-separated list of permissions to grant:read
andwrite
. -
Set the
attribute
variable to a list of attributes the delegated user group can manage:businesscategory
,departmentnumber
,employeenumber
, andemployeetype
. -
Set the
group
variable to the name of the group that is being given access to view or modify attributes. -
Set the
membergroup
variable to the name of the group whose attributes can be viewed or modified.
This is the modified Ansible playbook file for the current example:
--- - name: Playbook to manage a delegation rule hosts: ipaserver become: true tasks: - name: Ensure delegation "basic manager attributes" is present ipadelegation: ipaadmin_password: Secret123 name: "basic manager attributes" permission: read, write attribute: - businesscategory - departmentnumber - employeenumber - employeetype group: managers membergroup: employees
-
Set the
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i ~/MyPlaybooks/inventory delegation-present-copy.yml
Additional resources
- See Delegation rules.
-
See the
README-delegation.md
file in the/usr/share/doc/ansible-freeipa/
directory. -
See the sample playbooks in the
/usr/share/doc/ansible-freeipa/playbooks/ipadelegation
directory.
19.4. Using Ansible to ensure that a delegation rule is absent
The following procedure describes how to use an Ansible playbook to ensure a specified delegation rule is absent from your IdM configuration. The example below describes how to make sure the custom basic manager attributes delegation rule does not exist in IdM.
Prerequisites
- You know the IdM administrator password.
You have configured an Ansible control node that meets the following requirements:
- You are using Ansible version 2.8 or later.
- You have installed the ansible-freeipa package.
- You have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server where you are configuring these options.
- Your Ansible inventory file is located in the ~/MyPlaybooks/ directory.
Procedure
Navigate to the ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks>/
Make a copy of the
delegation-absent.yml
file located in the/usr/share/doc/ansible-freeipa/playbooks/delegation/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/delegation/delegation-present.yml delegation-absent-copy.yml
-
Open the
delegation-absent-copy.yml
Ansible playbook file for editing. Adapt the file by setting the following variables in the
ipadelegation
task section:-
Set the
ipaadmin_password
variable to the password of the IdM administrator. -
Set the
name
variable to the name of the delegation rule. -
Set the
state
variable toabsent
.
This is the modified Ansible playbook file for the current example:
--- - name: Delegation absent hosts: ipaserver become: true tasks: - name: Ensure delegation "basic manager attributes" is absent ipadelegation: ipaadmin_password: Secret123 name: "basic manager attributes" state: absent
-
Set the
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i ~/MyPlaybooks/inventory delegation-absent-copy.yml
Additional resources
- See Delegation rules.
-
See the
README-delegation.md
file in the/usr/share/doc/ansible-freeipa/
directory. -
See the sample playbooks in the
/usr/share/doc/ansible-freeipa/playbooks/ipadelegation
directory.
19.5. Using Ansible to ensure that a delegation rule has specific attributes
The following procedure describes how to use an Ansible playbook to ensure that a delegation rule has specific settings. You can use this playbook to modify a delegation role you have previously created. In the example, you ensure the basic manager attributes delegation rule only has the departmentnumber
member attribute.
Prerequisites
- You know the IdM administrator password.
You have configured an Ansible control node that meets the following requirements:
- You are using Ansible version 2.8 or later.
- You have installed the ansible-freeipa package.
- You have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server where you are configuring these options.
- Your Ansible inventory file is located in the ~/MyPlaybooks/ directory.
- The basic manager attributes delegation rule exists in IdM.
Procedure
Navigate to the ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
Make a copy of the
delegation-member-present.yml
file located in the/usr/share/doc/ansible-freeipa/playbooks/delegation/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/delegation/delegation-member-present.yml delegation-member-present-copy.yml
-
Open the
delegation-member-present-copy.yml
Ansible playbook file for editing. Adapt the file by setting the following variables in the
ipadelegation
task section:-
Set the
ipaadmin_password
variable to the password of the IdM administrator. -
Set the
name
variable to the name of the delegation rule to modify. -
Set the
attribute
variable todepartmentnumber
. -
Set the
action
variable tomember
.
This is the modified Ansible playbook file for the current example:
--- - name: Delegation member present hosts: ipaserver become: true tasks: - name: Ensure delegation "basic manager attributes" member attribute departmentnumber is present ipadelegation: ipaadmin_password: Secret123 name: "basic manager attributes" attribute: - departmentnumber action: member
-
Set the
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i ~/MyPlaybooks/inventory delegation-member-present-copy.yml
Additional resources
- See Delegation rules.
-
See the
README-delegation.md
file in the/usr/share/doc/ansible-freeipa/
directory. -
See the sample playbooks in the
/usr/share/doc/ansible-freeipa/playbooks/ipadelegation
directory.
19.6. Using Ansible to ensure that a delegation rule does not have specific attributes
The following procedure describes how to use an Ansible playbook to ensure that a delegation rule does not have specific settings. You can use this playbook to make sure a delegation role does not grant undesired access. In the example, you ensure the basic manager attributes delegation rule does not have the employeenumber
and employeetype
member attributes.
Prerequisites
- You know the IdM administrator password.
You have configured an Ansible control node that meets the following requirements:
- You are using Ansible version 2.8 or later.
- You have installed the ansible-freeipa package.
- You have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server where you are configuring these options.
- Your Ansible inventory file is located in the ~/MyPlaybooks/ directory.
- The basic manager attributes delegation rule exists in IdM.
Procedure
Navigate to the ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
Make a copy of the
delegation-member-absent.yml
file located in the/usr/share/doc/ansible-freeipa/playbooks/delegation/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/delegation/delegation-member-absent.yml delegation-member-absent-copy.yml
-
Open the
delegation-member-absent-copy.yml
Ansible playbook file for editing. Adapt the file by setting the following variables in the
ipadelegation
task section:-
Set the
ipaadmin_password
variable to the password of the IdM administrator. -
Set the
name
variable to the name of the delegation rule to modify. -
Set the
attribute
variable toemployeenumber
andemployeetype
. -
Set the
action
variable tomember
. -
Set the
state
variable toabsent
.
This is the modified Ansible playbook file for the current example:
--- - name: Delegation member absent hosts: ipaserver become: true tasks: - name: Ensure delegation "basic manager attributes" member attributes employeenumber and employeetype are absent ipadelegation: ipaadmin_password: Secret123 name: "basic manager attributes" attribute: - employeenumber - employeetype action: member state: absent
-
Set the
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i ~/MyPlaybooks/inventory delegation-member-absent-copy.yml
Additional resources
- See Delegation rules.
-
See the
README-delegation.md
file in the/usr/share/doc/ansible-freeipa/
directory. -
See the sample playbooks in the
/usr/share/doc/ansible-freeipa/playbooks/ipadelegation
directory.
Chapter 20. Managing role-based access controls in IdM using the CLI
This chapter introduces role-based access control in Identity Management (IdM) and describes the following operations in the command-line interface (CLI):
20.1. Role-based access control in IdM
Role-based access control (RBAC) in IdM grants a very different kind of authority to users compared to self-service and delegation access controls.
Role-based access control is composed of three parts:
- Permissions grant the right to perform a specific task such as adding or deleting users, modifying a group, enabling read-access, etc.
- Privileges combine permissions, for example all the permissions needed to add a new user.
- Roles grant a set of privileges to users, user groups, hosts or host groups.
20.1.1. Permissions in IdM
Permissions are the lowest level unit of role-based access control, they define operations together with the LDAP entries to which those operations apply. Comparable to building blocks, permissions can be assigned to as many privileges as needed.
One or more rights define what operations are allowed:
-
write
-
read
-
search
-
compare
-
add
-
delete
-
all
These operations apply to three basic targets:
-
subtree
: a domain name (DN); the subtree under this DN -
target filter
: an LDAP filter -
target
: DN with possible wildcards to specify entries
Additionally, the following convenience options set the corresponding attribute(s):
-
type
: a type of object (user, group, etc); setssubtree
andtarget filter
-
memberof
: members of a group; sets atarget filter
-
targetgroup
: grants access to modify a specific group (such as granting the rights to manage group membership); sets atarget
With IdM permissions, you can control which users have access to which objects and even which attributes of these objects. IdM enables you to allow or block individual attributes or change the entire visibility of a specific IdM function, such as users, groups, or sudo, to all anonymous users, all authenticated users, or just a certain group of privileged users.
For example, the flexibility of this approach to permissions is useful for an administrator who wants to limit access of users or groups only to the specific sections these users or groups need to access and to make the other sections completely hidden to them.
A permission cannot contain other permissions.
20.1.2. Default managed permissions
Managed permissions are permissions that come by default with IdM. They behave like other permissions created by the user, with the following differences:
- You cannot delete them or modify their name, location, and target attributes.
They have three sets of attributes:
- Default attributes, the user cannot modify them, as they are managed by IdM
- Included attributes, which are additional attributes added by the user
- Excluded attributes, which are attributes removed by the user
A managed permission applies to all attributes that appear in the default and included attribute sets but not in the excluded set.
While you cannot delete a managed permission, setting its bind type to permission and removing the managed permission from all privileges effectively disables it.
Names of all managed permissions start with System:
, for example System: Add Sudo rule
or System: Modify Services
. Earlier versions of IdM used a different scheme for default permissions. For example, the user could not delete them and was only able to assign them to privileges. Most of these default permissions have been turned into managed permissions, however, the following permissions still use the previous scheme:
- Add Automember Rebuild Membership Task
- Add Configuration Sub-Entries
- Add Replication Agreements
- Certificate Remove Hold
- Get Certificates status from the CA
- Read DNA Range
- Modify DNA Range
- Read PassSync Managers Configuration
- Modify PassSync Managers Configuration
- Read Replication Agreements
- Modify Replication Agreements
- Remove Replication Agreements
- Read LDBM Database Configuration
- Request Certificate
- Request Certificate ignoring CA ACLs
- Request Certificates from a different host
- Retrieve Certificates from the CA
- Revoke Certificate
- Write IPA Configuration
If you attempt to modify a managed permission from the command line, the system does not allow you to change the attributes that you cannot modify, the command fails. If you attempt to modify a managed permission from the Web UI, the attributes that you cannot modify are disabled.
20.1.3. Privileges in IdM
A privilege is a group of permissions applicable to a role.
While a permission provides the rights to do a single operation, there are certain IdM tasks that require multiple permissions to succeed. Therefore, a privilege combines the different permissions required to perform a specific task.
For example, setting up an account for a new IdM user requires the following permissions:
- Creating a new user entry
- Resetting a user password
- Adding the new user to the default IPA users group
Combining these three low-level tasks into a higher level task in the form of a custom privilege named, for example, Add User makes it easier for a system administrator to manage roles. IdM already contains several default privileges. Apart from users and user groups, privileges are also assigned to hosts and host groups, as well as network services. This practice permits a fine-grained control of operations by a set of users on a set of hosts using specific network services.
A privilege may not contain other privileges.
20.1.4. Roles in IdM
A role is a list of privileges that users specified for the role possess.
In effect, permissions grant the ability to perform given low-level tasks (create a user entry, add an entry to a group, etc.), privileges combine one or more of these permissions needed for a higher-level task (such as creating a new user in a given group). Roles gather privileges together as needed: for example, a User Administrator role would be able to add, modify, and delete users.
Roles are used to classify permitted actions. They are not used as a tool to implement privilege separation or to protect from privilege escalation.
Roles can not contain other roles.
20.1.5. Predefined roles in Identity Management
Red Hat Identity Management provides the following range of pre-defined roles:
Table 20.1. Predefined Roles in Identity Management
Role | Privilege | Description |
---|---|---|
Enrollment Administrator | Host Enrollment | Responsible for client, or host, enrollment |
helpdesk | Modify Users and Reset passwords, Modify Group membership | Responsible for performing simple user administration tasks |
IT Security Specialist | Netgroups Administrators, HBAC Administrator, Sudo Administrator | Responsible for managing security policy such as host-based access controls, sudo rules |
IT Specialist | Host Administrators, Host Group Administrators, Service Administrators, Automount Administrators | Responsible for managing hosts |
Security Architect | Delegation Administrator, Replication Administrators, Write IPA Configuration, Password Policy Administrator | Responsible for managing the Identity Management environment, creating trusts, creating replication agreements |
User Administrator | User Administrators, Group Administrators, Stage User Administrators | Responsible for creating users and groups |
20.2. Managing IdM permissions in the CLI
This section describes how to manage Identity Management (IdM) permissions using the command-line interface (CLI).
Prerequisites
- Administrator privileges for managing IdM or the User Administrator role.
- An active Kerberos ticket. For details, see Using kinit to log in to IdM manually.
Procedure
Create new permission entries with the
ipa permission-add
command.
For example, to add a permission named dns admin:$ ipa permission-add "dns admin"
Specify the properties of the permission with the following options:
--bindtype
specifies the bind rule type. This option accepts theall
,anonymous
, andpermission
arguments. Thepermission
bindtype means that only the users who are granted this permission via a role can exercise it.
For example:$ ipa permission-add "dns admin" --bindtype=all
If you do not specify
--bindtype
, thenpermission
is the default value.NoteIt is not possible to add permissions with a non-default bind rule type to privileges. You also cannot set a permission that is already present in a privilege to a non-default bind rule type.
--right
lists the rights granted by the permission, it replaces the deprecated--permissions
option. The available values areadd
,delete
,read
,search
,compare
,write
,all
.You can set multiple attributes by using multiple
--right
options or with a comma-separated list inside curly braces. For example:$ ipa permission-add "dns admin" --right=read --right=write
$ ipa permission-add "dns admin" --right={read,write}
Noteadd
anddelete
are entry-level operations (for example deleting a user, adding a group, etc.) whileread
,search
,compare
andwrite
are more attribute-level: you can write touserCertificate
but not readuserPassword
.--attrs
gives the list of attributes over which the permission is granted.
You can set multiple attributes by using multiple--attrs
options or by listing the options in a comma-separated list inside curly braces. For example:$ ipa permission-add "dns admin" --attrs=description --attrs=automountKey
$ ipa permission-add "dns admin" --attrs={description,automountKey}
The attributes provided with
--attrs
must exist and be allowed attributes for the given object type, otherwise the command fails with schema syntax errors.--type
defines the entry object type to which the permission applies, such as user, host, or service. Each type has its own set of allowed attributes.
For example:$ ipa permission-add "manage service" --right=all --type=service --attrs=krbprincipalkey --attrs=krbprincipalname --attrs=managedby
--subtree
gives a subtree entry; the filter then targets every entry beneath this subtree entry. Provide an existing subtree entry;--subtree
does not accept wildcards or non-existent domain names (DNs). Include a DN within the directory.
Because IdM uses a simplified, flat directory tree structure,--subtree
can be used to target some types of entries, like automount locations, which are containers or parent entries for other configuration. For example:$ ipa permission-add "manage automount locations" --subtree="ldap://ldap.example.com:389/cn=automount,dc=example,dc=com" --right=write --attrs=automountmapname --attrs=automountkey --attrs=automountInformation
NoteThe
--type
and--subtree
options are mutually exclusive: you can see the inclusion of filters for--type
as a simplification of--subtree
, intending to make life easier for an admin.--filter
uses an LDAP filter to identify which entries the permission applies to.
IdM automatically checks the validity of the given filter. The filter can be any valid LDAP filter, for example:$ ipa permission-add "manage Windows groups" --filter="(!(objectclass=posixgroup))" --right=write --attrs=description
--memberof
sets the target filter to members of the given group after checking that the group exists. For example, to let the users with this permission modify the login shell of members of the engineers group:$ ipa permission-add ManageShell --right="write" --type=user --attr=loginshell --memberof=engineers
--targetgroup
sets target to the specified user group after checking that the group exists. For example, to let those with the permission write the member attribute in the engineers group (so they can add or remove members):$ ipa permission-add ManageMembers --right="write" --subtree=cn=groups,cn=accounts,dc=example,dc=test --attr=member --targetgroup=engineers
Optionally, you can specify a target domain name (DN):
-
--target
specifies the DN to apply the permission to. Wildcards are accepted. -
--targetto
specifies the DN subtree where an entry can be moved to. -
--targetfrom
specifies the DN subtree from where an entry can be moved.
-
20.3. Command options for existing permissions
Use the following variants to modify existing permissions as needed:
-
To edit existing permissions, use the
ipa permission-mod
command. You can use the same command options as for adding permissions. -
To find existing permissions, use the
ipa permission-find
command. You can use the same command options as for adding permissions. To view a specific permission, use the
ipa permission-show
command.
The--raw
argument shows the raw 389-ds ACI that is generated. For example:$ ipa permission-show <permission> --raw
-
The
ipa permission-del
command deletes a permission completely.
Additional resources
-
See the
ipa
man page. -
See the
ipa help
command.
20.4. Managing IdM privileges in the CLI
This section describes how to manage Identity Management (IdM) privileges using the command-line interface (CLI).
Prerequisites
- Administrator privileges for managing IdM or the User Administrator role.
- An active Kerberos ticket. For details, see Using kinit to log in to IdM manually.
- Existing permissions. For details about permissions, see Managing IdM permissions in the CLI.
Procedure
Add privilege entries using the
ipa privilege-add
command
For example, to add a privilege named managing filesystems with a description:$ ipa privilege-add "managing filesystems" --desc="for filesystems"
Assign the required permissions to the privilege group with the
privilege-add-permission
command
For example, to add the permissions named managing automount and managing ftp services to the managing filesystems privilege:$ ipa privilege-add-permission "managing filesystems" --permissions="managing automount" --permissions="managing ftp services"
20.5. Command options for existing privileges
Use the following variants to modify existing privileges as needed:
-
To modify existing privileges, use the
ipa privilege-mod
command. -
To find existing privileges, use the
ipa privilege-find
command. -
To view a specific privilege, use the
ipa privilege-show
command. -
The
ipa privilege-remove-permission
command removes one or more permissions from a privilege. -
The
ipa privilege-del
command deletes a privilege completely.
Additional resources
-
See the
ipa
man page. -
See the
ipa help
command.
20.6. Managing IdM roles in the CLI
This section describes how to manage Identity Management (IdM) roles using the command-line interface (CLI).
Prerequisites
- Administrator privileges for managing IdM or the User Administrator role.
- An active Kerberos ticket. For details, see Using kinit to log in to IdM manually.
- Existing privileges. For details about privileges, see Managing IdM privileges in the CLI.
Procedure
Add new role entries using the
ipa role-add
command:$ ipa role-add --desc="User Administrator" useradmin ------------------------ Added role "useradmin" ------------------------ Role name: useradmin Description: User Administrator
Add the required privileges to the role using the
ipa role-add-privilege
command:$ ipa role-add-privilege --privileges="user administrators" useradmin Role name: useradmin Description: User Administrator Privileges: user administrators ---------------------------- Number of privileges added 1 ----------------------------
Add the required members to the role using the
ipa role-add-member
command. Allowed member types are: users, groups, hosts and hostgroups.
For example, to add the group named useradmins to the previously created useradmin role:$ ipa role-add-member --groups=useradmins useradmin Role name: useradmin Description: User Administrator Member groups: useradmins Privileges: user administrators ------------------------- Number of members added 1 -------------------------
20.7. Command options for existing roles
Use the following variants to modify existing roles as needed:
-
To modify existing roles, use the
ipa role-mod
command. -
To find existing roles, use the
ipa role-find
command. -
To view a specific role, use the
ipa role-show
command. -
To remove a member from the role, use the
ipa role-remove-member
command. -
The
ipa role-remove-privilege
command removes one or more privileges from a role. -
The
ipa role-del
command deletes a role completely.
Additional resources
-
See the
ipa
man page -
See the
ipa help
command.
Chapter 21. Managing role-based access controls using the IdM Web UI
This chapter introduces role-based access control in Identity Management (IdM) and describes the following operations in the web interface (Web UI):
21.1. Role-based access control in IdM
Role-based access control (RBAC) in IdM grants a very different kind of authority to users compared to self-service and delegation access controls.
Role-based access control is composed of three parts:
- Permissions grant the right to perform a specific task such as adding or deleting users, modifying a group, enabling read-access, etc.
- Privileges combine permissions, for example all the permissions needed to add a new user.
- Roles grant a set of privileges to users, user groups, hosts or host groups.
21.1.1. Permissions in IdM
Permissions are the lowest level unit of role-based access control, they define operations together with the LDAP entries to which those operations apply. Comparable to building blocks, permissions can be assigned to as many privileges as needed.
One or more rights define what operations are allowed:
-
write
-
read
-
search
-
compare
-
add
-
delete
-
all
These operations apply to three basic targets:
-
subtree
: a domain name (DN); the subtree under this DN -
target filter
: an LDAP filter -
target
: DN with possible wildcards to specify entries
Additionally, the following convenience options set the corresponding attribute(s):
-
type
: a type of object (user, group, etc); setssubtree
andtarget filter
-
memberof
: members of a group; sets atarget filter
-
targetgroup
: grants access to modify a specific group (such as granting the rights to manage group membership); sets atarget
With IdM permissions, you can control which users have access to which objects and even which attributes of these objects. IdM enables you to allow or block individual attributes or change the entire visibility of a specific IdM function, such as users, groups, or sudo, to all anonymous users, all authenticated users, or just a certain group of privileged users.
For example, the flexibility of this approach to permissions is useful for an administrator who wants to limit access of users or groups only to the specific sections these users or groups need to access and to make the other sections completely hidden to them.
A permission cannot contain other permissions.
21.1.2. Default managed permissions
Managed permissions are permissions that come by default with IdM. They behave like other permissions created by the user, with the following differences:
- You cannot delete them or modify their name, location, and target attributes.
They have three sets of attributes:
- Default attributes, the user cannot modify them, as they are managed by IdM
- Included attributes, which are additional attributes added by the user
- Excluded attributes, which are attributes removed by the user
A managed permission applies to all attributes that appear in the default and included attribute sets but not in the excluded set.
While you cannot delete a managed permission, setting its bind type to permission and removing the managed permission from all privileges effectively disables it.
Names of all managed permissions start with System:
, for example System: Add Sudo rule
or System: Modify Services
. Earlier versions of IdM used a different scheme for default permissions. For example, the user could not delete them and was only able to assign them to privileges. Most of these default permissions have been turned into managed permissions, however, the following permissions still use the previous scheme:
- Add Automember Rebuild Membership Task
- Add Configuration Sub-Entries
- Add Replication Agreements
- Certificate Remove Hold
- Get Certificates status from the CA
- Read DNA Range
- Modify DNA Range
- Read PassSync Managers Configuration
- Modify PassSync Managers Configuration
- Read Replication Agreements
- Modify Replication Agreements
- Remove Replication Agreements
- Read LDBM Database Configuration
- Request Certificate
- Request Certificate ignoring CA ACLs
- Request Certificates from a different host
- Retrieve Certificates from the CA
- Revoke Certificate
- Write IPA Configuration
If you attempt to modify a managed permission from the command line, the system does not allow you to change the attributes that you cannot modify, the command fails. If you attempt to modify a managed permission from the Web UI, the attributes that you cannot modify are disabled.
21.1.3. Privileges in IdM
A privilege is a group of permissions applicable to a role.
While a permission provides the rights to do a single operation, there are certain IdM tasks that require multiple permissions to succeed. Therefore, a privilege combines the different permissions required to perform a specific task.
For example, setting up an account for a new IdM user requires the following permissions:
- Creating a new user entry
- Resetting a user password
- Adding the new user to the default IPA users group
Combining these three low-level tasks into a higher level task in the form of a custom privilege named, for example, Add User makes it easier for a system administrator to manage roles. IdM already contains several default privileges. Apart from users and user groups, privileges are also assigned to hosts and host groups, as well as network services. This practice permits a fine-grained control of operations by a set of users on a set of hosts using specific network services.
A privilege may not contain other privileges.
21.1.4. Roles in IdM
A role is a list of privileges that users specified for the role possess.
In effect, permissions grant the ability to perform given low-level tasks (create a user entry, add an entry to a group, etc.), privileges combine one or more of these permissions needed for a higher-level task (such as creating a new user in a given group). Roles gather privileges together as needed: for example, a User Administrator role would be able to add, modify, and delete users.
Roles are used to classify permitted actions. They are not used as a tool to implement privilege separation or to protect from privilege escalation.
Roles can not contain other roles.
21.1.5. Predefined roles in Identity Management
Red Hat Identity Management provides the following range of pre-defined roles:
Table 21.1. Predefined Roles in Identity Management
Role | Privilege | Description |
---|---|---|
Enrollment Administrator | Host Enrollment | Responsible for client, or host, enrollment |
helpdesk | Modify Users and Reset passwords, Modify Group membership | Responsible for performing simple user administration tasks |
IT Security Specialist | Netgroups Administrators, HBAC Administrator, Sudo Administrator | Responsible for managing security policy such as host-based access controls, sudo rules |
IT Specialist | Host Administrators, Host Group Administrators, Service Administrators, Automount Administrators | Responsible for managing hosts |
Security Architect | Delegation Administrator, Replication Administrators, Write IPA Configuration, Password Policy Administrator | Responsible for managing the Identity Management environment, creating trusts, creating replication agreements |
User Administrator | User Administrators, Group Administrators, Stage User Administrators | Responsible for creating users and groups |
21.2. Managing permissions in the IdM Web UI
This section describes how to manage permissions in Identity Management (IdM) using the web interface (IdM Web UI).
Prerequisites
- Administrator privileges for managing IdM or the User Administrator role.
- You are logged-in to the IdM Web UI. For details, see Accessing the IdM Web UI in a web browser.
Procedure
To add a new permission, open the Role-Based Access Control sub-menu in the IPA Server tab and select Permissions:
The list of permissions opens: Click the Add button at the top of the list of the permissions:
The Add Permission form opens. Specify the name of the new permission and define its properties accordingly:
Select the appropriate Bind rule type:
- permission is the default permission type, granting access through privileges and roles
- all specifies that the permission applies to all authenticated users
anonymous specifies that the permission applies to all users, including unauthenticated users
NoteIt is not possible to add permissions with a non-default bind rule type to privileges. You also cannot set a permission that is already present in a privilege to a non-default bind rule type.
- Choose the rights to grant with this permisthsion in Granted rights.
Define the method to identify the target entries for the permission:
- Type specifies an entry type, such as user, host, or service. If you choose a value for the Type setting, a list of all possible attributes which will be accessible through this ACI for that entry type appears under Effective Attributes. Defining Type sets Subtree and Target DN to one of the predefined values.
-
Subtree (required) specifies a subtree entry; every entry beneath this subtree entry is then targeted. Provide an existing subtree entry, as Subtree does not accept wildcards or non-existent domain names (DNs). For example:
cn=automount,dc=example,dc=com
-
Extra target filter uses an LDAP filter to identify which entries the permission applies to. The filter can be any valid LDAP filter, for example:
(!(objectclass=posixgroup))
IdM automatically checks the validity of the given filter. If you enter an invalid filter, IdM warns you about this when you attempt to save the permission. -
Target DN specifies the domain name (DN) and accepts wildcards. For example:
uid=*,cn=users,cn=accounts,dc=com
- Member of group sets the target filter to members of the given group. After you specify the filter settings and click Add, IdM validates the filter. If all the permission settings are correct, IdM will perform the search. If some of the permissions settings are incorrect, IdM will display a message informing you about which setting is set incorrectly.
Add attributes to the permission:
- If you set Type, choose the Effective attributes from the list of available ACI attributes.
If you did not use Type, add the attributes manually by writing them into the Effective attributes field. Add a single attribute at a time; to add multiple attributes, click Add to add another input field.
ImportantIf you do not set any attributes for the permission, then the permissions includes all attributes by default.
Finish adding the permissions with the Add buttons at the bottom of the form:
- Click the Add button to save the permission and go back to the list of permissions.
- Alternatively, you can save the permission and continue adding additional permissions in the same form by clicking the Add and Add another button
- The Add and Edit button enables you to save and continue editing the newly created permission.
- Optional. You can also edit the properties of an existing permission by clicking its name from the list of permissions to display the Permission settings page.
Optional. If you need to remove an existing permission, click the Delete button once you ticked the check box next to its name in the list, to display The Remove permissions dialog.
NoteOperations on default managed permissions are restricted: the attributes you cannot modify are disabled in the IdM Web UI and you cannot delete the managed permissions completely.
However, you can effectively disable a managed permission that has a bind type set to permission, by removing the managed permission from all privileges.
For example, to let those with the permission write the member attribute in the engineers group (so they can add or remove members):
21.3. Managing privileges in the IdM WebUI
This section describes how to manage privileges in IdM using the web interface (IdM Web UI).
Prerequisites
- Administrator privileges for managing IdM or the User Administrator role.
- You are logged-in to the IdM Web UI. For details, see Accessing the IdM Web UI in a web browser.
- Existing permissions. For details about permissions, see Managing permissions in the IdM Web UI.
Procedure
To add a new privilege, open the Role-Based Access Control sub-menu in the IPA Server tab and select Privileges:
The list of privileges opens. Click the Add button at the top of the list of privileges:
The Add Privilege form opens. Enter the name and a description of the privilege:
- Click the Add and Edit button in order to save the new privilege and continue to the privilege configuration page to add permissions.
- Edit the properties of privileges by clicking on the privileges name in the privileges list. The privileges configuration page opens.
The Permissions tab displays a list of permissions included in the selected privilege. Click the Add button at the top of the list to add permissions to the privilege:
Tick the check box next to the name of each permission to add, and use the > button to move the permissions to the Prospective column:
- Confirm by clicking the Add button.
- Optional. If you need to remove permissions, click the Delete button after you ticked the check box next to the relevant permission: the Remove privileges from permissions dialog opens.
- Optional. If you need to delete an existing privilege, click the Delete button after you ticked the check box next to its name in the list: the Remove privileges dialog opens.
21.4. Managing roles in the IdM Web UI
This section describes how to manage roles in Identity Management (IdM) using the web interface (IdM Web UI).
Prerequisites
- Administrator privileges for managing IdM or the User Administrator role.
- You are logged-in to the IdM Web UI. For details, see Accessing the IdM Web UI in a web browser.
- Existing privileges. For details about privileges, see Managing privileges in the IdM Web UI.
Procedure
To add a new role, open the Role-Based Access Control sub-menu in the IPA Server tab and select Roles:
The list of roles opens. Click the Add button at the top of the list of the role-based access control instructions.
The Add Role form opens. Enter the role name and a description:
- Click the Add and Edit button to save the new role and go to the role configuration page to add privileges and users.
- Edit the properties of roles by clicking on the roles name in the role list. The roles configuration page opens.
Add members using the Users, Users Groups, Hosts, Host Groups or Services tabs, by clicking the Add button on top of the relevant list(s).
In the window that opens, select the members on the left and use the > button to move them to the Prospective column.
At the top of the Privileges tab, click Add.
Select the privileges on the left and use the > button to move them to the Prospective column.
- Click the Add button to save.
- Optional. If you need to remove privileges or members from a role, click the Delete button after you ticked the check box next to the name of the entity you want to remove. A dialog opens.
- Optional. If you need to remove an existing role, click the Delete button after you ticked the check box next to its name in the list, to display the Remove roles dialog.
Chapter 22. Preparing your environment for managing IdM using Ansible playbooks
As a system administrator managing Identity Management (IdM), when working with Red Hat Ansible Engine, it is good practice to do the following:
- Create a subdirectory dedicated to Ansible playbooks in your home directory, for example ~/MyPlaybooks.
-
Copy and adapt sample Ansible playbooks from the
/usr/share/doc/ansible-freeipa/*
and/usr/share/doc/rhel-system-roles/*
directories and subdirectories into your ~/MyPlaybooks directory. - Include your inventory file in your ~/MyPlaybooks directory.
Using this practice, you can find all your playbooks in one place and you can run your playbooks without invoking root privileges.
You only need root
privileges on the managed nodes to execute the ipaserver
, ipareplica
, ipaclient
and ipabackup
ansible-freeipa
roles. These roles require privileged access to directories and the dnf
software package manager.
This section describes how to create the ~/MyPlaybooks directory and configure it so that you can use it to store and run Ansible playbooks.
Prerequisites
- You have installed an IdM server on your managed nodes, server.idm.example.com and replica.idm.example.com.
- You have configured DNS and networking so you can log in to the managed nodes, server.idm.example.com and replica.idm.example.com, directly from the control node.
-
You know the IdM
admin
password.
Procedure
Create a directory for your Ansible configuration and playbooks in your home directory:
$ mkdir ~/MyPlaybooks/
Change into the ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks
Create the ~/MyPlaybooks/ansible.cfg file with the following content:
[defaults] inventory = /home/your_username/MyPlaybooks/inventory [privilege_escalation] become=True
Create the ~/MyPlaybooks/inventory file with the following content:
[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.
Additional resources
Chapter 23. Using Ansible playbooks to manage role-based access control in IdM
Role-based access control (RBAC) is a policy-neutral access-control mechanism defined around roles and privileges. The components of RBAC in Identity Management (IdM) are roles, privileges and permissions:
- Permissions grant the right to perform a specific task such as adding or deleting users, modifying a group, enabling read-access, etc.
- Privileges combine permissions, for example all the permissions needed to add a new user.
- Roles grant a set of privileges to users, user groups, hosts or host groups.
Especially in large companies, using RBAC can help create a hierarchical system of administrators with their individual areas of responsibility.
This chapter describes the following operations performed when managing RBAC using Ansible playbooks:
- Using Ansible to ensure an IdM RBAC role with privileges is present
- Using Ansible to ensure an IdM RBAC role is absent
- Using Ansible to ensure that a group of users is assigned to an IdM RBAC role
- Using Ansible to ensure that specific users are not assigned to an IdM RBAC role
- Using Ansible to ensure a service is a member of an IdM RBAC role
- Using Ansible to ensure a host is a member of an IdM RBAC role
- Using Ansible to ensure a host group is a member of an IdM RBAC role
23.1. Permissions in IdM
Permissions are the lowest level unit of role-based access control, they define operations together with the LDAP entries to which those operations apply. Comparable to building blocks, permissions can be assigned to as many privileges as needed.
One or more rights define what operations are allowed:
-
write
-
read
-
search
-
compare
-
add
-
delete
-
all
These operations apply to three basic targets:
-
subtree
: a domain name (DN); the subtree under this DN -
target filter
: an LDAP filter -
target
: DN with possible wildcards to specify entries
Additionally, the following convenience options set the corresponding attribute(s):
-
type
: a type of object (user, group, etc); setssubtree
andtarget filter
-
memberof
: members of a group; sets atarget filter
-
targetgroup
: grants access to modify a specific group (such as granting the rights to manage group membership); sets atarget
With IdM permissions, you can control which users have access to which objects and even which attributes of these objects. IdM enables you to allow or block individual attributes or change the entire visibility of a specific IdM function, such as users, groups, or sudo, to all anonymous users, all authenticated users, or just a certain group of privileged users.
For example, the flexibility of this approach to permissions is useful for an administrator who wants to limit access of users or groups only to the specific sections these users or groups need to access and to make the other sections completely hidden to them.
A permission cannot contain other permissions.
23.2. Default managed permissions
Managed permissions are permissions that come by default with IdM. They behave like other permissions created by the user, with the following differences:
- You cannot delete them or modify their name, location, and target attributes.
They have three sets of attributes:
- Default attributes, the user cannot modify them, as they are managed by IdM
- Included attributes, which are additional attributes added by the user
- Excluded attributes, which are attributes removed by the user
A managed permission applies to all attributes that appear in the default and included attribute sets but not in the excluded set.
While you cannot delete a managed permission, setting its bind type to permission and removing the managed permission from all privileges effectively disables it.
Names of all managed permissions start with System:
, for example System: Add Sudo rule
or System: Modify Services
. Earlier versions of IdM used a different scheme for default permissions. For example, the user could not delete them and was only able to assign them to privileges. Most of these default permissions have been turned into managed permissions, however, the following permissions still use the previous scheme:
- Add Automember Rebuild Membership Task
- Add Configuration Sub-Entries
- Add Replication Agreements
- Certificate Remove Hold
- Get Certificates status from the CA
- Read DNA Range
- Modify DNA Range
- Read PassSync Managers Configuration
- Modify PassSync Managers Configuration
- Read Replication Agreements
- Modify Replication Agreements
- Remove Replication Agreements
- Read LDBM Database Configuration
- Request Certificate
- Request Certificate ignoring CA ACLs
- Request Certificates from a different host
- Retrieve Certificates from the CA
- Revoke Certificate
- Write IPA Configuration
If you attempt to modify a managed permission from the command line, the system does not allow you to change the attributes that you cannot modify, the command fails. If you attempt to modify a managed permission from the Web UI, the attributes that you cannot modify are disabled.
23.3. Privileges in IdM
A privilege is a group of permissions applicable to a role.
While a permission provides the rights to do a single operation, there are certain IdM tasks that require multiple permissions to succeed. Therefore, a privilege combines the different permissions required to perform a specific task.
For example, setting up an account for a new IdM user requires the following permissions:
- Creating a new user entry
- Resetting a user password
- Adding the new user to the default IPA users group
Combining these three low-level tasks into a higher level task in the form of a custom privilege named, for example, Add User makes it easier for a system administrator to manage roles. IdM already contains several default privileges. Apart from users and user groups, privileges are also assigned to hosts and host groups, as well as network services. This practice permits a fine-grained control of operations by a set of users on a set of hosts using specific network services.
A privilege may not contain other privileges.
23.4. Roles in IdM
A role is a list of privileges that users specified for the role possess.
In effect, permissions grant the ability to perform given low-level tasks (create a user entry, add an entry to a group, etc.), privileges combine one or more of these permissions needed for a higher-level task (such as creating a new user in a given group). Roles gather privileges together as needed: for example, a User Administrator role would be able to add, modify, and delete users.
Roles are used to classify permitted actions. They are not used as a tool to implement privilege separation or to protect from privilege escalation.
Roles can not contain other roles.
23.5. Predefined roles in Identity Management
Red Hat Identity Management provides the following range of pre-defined roles:
Table 23.1. Predefined Roles in Identity Management
Role | Privilege | Description |
---|---|---|
Enrollment Administrator | Host Enrollment | Responsible for client, or host, enrollment |
helpdesk | Modify Users and Reset passwords, Modify Group membership | Responsible for performing simple user administration tasks |
IT Security Specialist | Netgroups Administrators, HBAC Administrator, Sudo Administrator | Responsible for managing security policy such as host-based access controls, sudo rules |
IT Specialist | Host Administrators, Host Group Administrators, Service Administrators, Automount Administrators | Responsible for managing hosts |
Security Architect | Delegation Administrator, Replication Administrators, Write IPA Configuration, Password Policy Administrator | Responsible for managing the Identity Management environment, creating trusts, creating replication agreements |
User Administrator | User Administrators, Group Administrators, Stage User Administrators | Responsible for creating users and groups |
23.6. Using Ansible to ensure an IdM RBAC role with privileges is present
To exercise more granular control over role-based access (RBAC) to resources in Identity Management (IdM) than the default roles provide, create a custom role.
The following procedure describes how to use an Ansible playbook to define privileges for a new IdM custom role and ensure its presence. In the example, the new user_and_host_administrator role contains a unique combination of the following privileges that are present in IdM by default:
-
Group Administrators
-
User Administrators
-
Stage User Administrators
-
Group Administrators
Prerequisites
- You know the IdM administrator password.
- You have installed the ansible-freeipa package on the Ansible control node.
- You have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server on which you want to do the configuring.
- Your Ansible inventory file is located in the ~/<MyPlaybooks>/ directory.
Procedure
Navigate to the ~/<MyPlaybooks>/ directory:
$ cd ~/<MyPlaybooks>/
Make a copy of the
role-member-user-present.yml
file located in the/usr/share/doc/ansible-freeipa/playbooks/role/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/role/role-member-user-present.yml role-member-user-present-copy.yml
-
Open the
role-member-user-present-copy.yml
Ansible playbook file for editing. Adapt the file by setting the following variables in the
iparole
task section:-
Set the
ipaadmin_password
variable to the password of the IdM administrator. -
Set the
name
variable to the name of the new role. -
Set the
privilege
list to the names of the IdM privileges that you want to include in the new role. -
Optionally, set the
user
variable to the name of the user to whom you want to grant the new role. -
Optionally, set the
group
variable to the name of the group to which you want to grant the new role.
This is the modified Ansible playbook file for the current example:
--- - name: Playbook to manage IPA role with members. hosts: ipaserver become: yes gather_facts: no tasks: - iparole: ipaadmin_password: Secret123 name: user_and_host_administrator user: idm_user01 group: idm_group01 privilege: - Group Administrators - User Administrators - Stage User Administrators - Group Administrators
-
Set the
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i ~/<MyPlaybooks>/inventory role-member-user-present-copy.yml
Additional resources
- See Encrypting content with Ansible Vault.
- See Roles in IdM.
-
See the
README-role
file in the/usr/share/doc/ansible-freeipa/
directory. -
See the sample playbooks in the
/usr/share/doc/ansible-freeipa/playbooks/iparole
directory.
23.7. Using Ansible to ensure an IdM RBAC role is absent
As a system administrator managing role-based access control (RBAC) in Identity Management (IdM), you may want to ensure the absence of an obsolete role so that no administrator assigns it to any user accidentally.
The following procedure describes how to use an Ansible playbook to ensure a role is absent. The example below describes how to make sure the custom user_and_host_administrator role does not exist in IdM.
Prerequisites
- You know the IdM administrator password.
- You have installed the ansible-freeipa package on the Ansible control node.
- You have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server on which you want to do the configuring.
- Your Ansible inventory file is located in the ~/<MyPlaybooks>/ directory.
Procedure
Navigate to the ~/<MyPlaybooks>/ directory:
$ cd ~/<MyPlaybooks>/
Make a copy of the
role-is-absent.yml
file located in the/usr/share/doc/ansible-freeipa/playbooks/role/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/role/role-is-absent.yml role-is-absent-copy.yml
-
Open the
role-is-absent-copy.yml
Ansible playbook file for editing. Adapt the file by setting the following variables in the
iparole
task section:-
Set the
ipaadmin_password
variable to the password of the IdM administrator. -
Set the
name
variable to the name of the role. -
Ensure that the
state
variable is set toabsent
.
This is the modified Ansible playbook file for the current example:
--- - name: Playbook to manage IPA role with members. hosts: ipaserver become: yes gather_facts: no tasks: - iparole: ipaadmin_password: Secret123 name: user_and_host_administrator state: absent
-
Set the
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i ~/<MyPlaybooks>/inventory role-is-absent-copy.yml
Additional resources
- See Encrypting content with Ansible Vault.
- See Roles in IdM.
-
See the
README-role
Markdown file in the/usr/share/doc/ansible-freeipa/
directory. -
See the sample playbooks in the
/usr/share/doc/ansible-freeipa/playbooks/iparole
directory.
23.8. Using Ansible to ensure that a group of users is assigned to an IdM RBAC role
As a system administrator managing role-based access control (RBAC) in Identity Management (IdM), you may want to assign a role to a specific group of users, for example junior administrators.
The following example describes how to use an Ansible playbook to ensure the built-in IdM RBAC helpdesk role is assigned to junior_sysadmins.
Prerequisites
- You know the IdM administrator password.
- You have installed the ansible-freeipa package on the Ansible control node.
- You have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server on which you want to do the configuring.
- Your Ansible inventory file is located in the ~/<MyPlaybooks>/ directory.
Procedure
Navigate to the ~/<MyPlaybooks>/ directory:
$ cd ~/<MyPlaybooks>/
Make a copy of the
role-member-group-present.yml
file located in the/usr/share/doc/ansible-freeipa/playbooks/role/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/role/role-member-group-present.yml role-member-group-present-copy.yml
-
Open the
role-member-group-present-copy.yml
Ansible playbook file for editing. Adapt the file by setting the following variables in the
iparole
task section:-
Set the
ipaadmin_password
variable to the password of the IdM administrator. -
Set the
name
variable to the name of the role you want to assign. -
Set the
group
variable to the name of the group. -
Set the
action
variable tomember
.
This is the modified Ansible playbook file for the current example:
--- - name: Playbook to manage IPA role with members. hosts: ipaserver become: yes gather_facts: no tasks: - iparole: ipaadmin_password: Secret123 name: helpdesk group: junior_sysadmins action: member
-
Set the
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i ~/<MyPlaybooks>/inventory role-member-group-present-copy.yml
Additional resources
- See Encrypting content with Ansible Vault.
- See Roles in IdM.
-
See the
README-role
Markdown file in the/usr/share/doc/ansible-freeipa/
directory. -
See the sample playbooks in the
/usr/share/doc/ansible-freeipa/playbooks/iparole
directory.
23.9. Using Ansible to ensure that specific users are not assigned to an IdM RBAC role
As a system administrator managing role-based access control (RBAC) in Identity Management (IdM), you may want to ensure that an RBAC role is not assigned to specific users after they have, for example, moved to different positions within the company.
The following procedure describes how to use an Ansible playbook to ensure that the users named user_01 and user_02 are not assigned to the helpdesk role.
Prerequisites
- You know the IdM administrator password.
- You have installed the ansible-freeipa package on the Ansible control node.
- You have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server on which you want to do the configuring.
- Your Ansible inventory file is located in the ~/<MyPlaybooks>/ directory.
Procedure
Navigate to the ~/<MyPlaybooks>/ directory:
$ cd ~/<MyPlaybooks>/
Make a copy of the
role-member-user-absent.yml
file located in the/usr/share/doc/ansible-freeipa/playbooks/role/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/role/role-member-user-absent.yml role-member-user-absent-copy.yml
-
Open the
role-member-user-absent-copy.yml
Ansible playbook file for editing. Adapt the file by setting the following variables in the
iparole
task section:-
Set the
ipaadmin_password
variable to the password of the IdM administrator. -
Set the
name
variable to the name of the role you want to assign. -
Set the
user
list to the names of the users. -
Set the
action
variable tomember
. -
Set the
state
variable toabsent
.
This is the modified Ansible playbook file for the current example:
--- - name: Playbook to manage IPA role with members. hosts: ipaserver become: yes gather_facts: no tasks: - iparole: ipaadmin_password: Secret123 name: helpdesk user - user_01 - user_02 action: member state: absent
-
Set the
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i ~/<MyPlaybooks>/inventory role-member-user-absent-copy.yml
Additional resources
- See Encrypting content with Ansible Vault.
- See Roles in IdM.
-
See the
README-role
Markdown file in the/usr/share/doc/ansible-freeipa/
directory. -
See the sample playbooks in the
/usr/share/doc/ansible-freeipa/playbooks/iparole
directory.
23.10. Using Ansible to ensure a service is a member of an IdM RBAC role
As a system administrator managing role-based access control (RBAC) in Identity Management (IdM), you may want to ensure that a specific service that is enrolled into IdM is a member of a particular role. The following example describes how to ensure that the custom web_administrator role can manage the HTTP
service that is running on the client01.idm.example.com server.
Prerequisites
- You know the IdM administrator password.
- You have installed the ansible-freeipa package on the Ansible control node.
- You have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server on which you want to do the configuring.
- Your Ansible inventory file is located in the ~/<MyPlaybooks>/ directory.
- The web_administrator role exists in IdM.
- The HTTP/client01.idm.example.com@IDM.EXAMPLE.COM service exists in IdM.
Procedure
Navigate to the ~/<MyPlaybooks>/ directory:
$ cd ~/<MyPlaybooks>/
Make a copy of the
role-member-service-present.yml
file located in the/usr/share/doc/ansible-freeipa/playbooks/role/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/role/role-member-service-present-absent.yml role-member-service-present-copy.yml
-
Open the
role-member-service-present-copy.yml
Ansible playbook file for editing. Adapt the file by setting the following variables in the
iparole
task section:-
Set the
ipaadmin_password
variable to the password of the IdM administrator. -
Set the
name
variable to the name of the role you want to assign. -
Set the
service
list to the name of the service. -
Set the
action
variable tomember
.
This is the modified Ansible playbook file for the current example:
--- - name: Playbook to manage IPA role with members. hosts: ipaserver become: yes gather_facts: no tasks: - iparole: ipaadmin_password: Secret123 name: web_administrator service: - HTTP/client01.idm.example.com action: member
-
Set the
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i ~/<MyPlaybooks>/inventory role-member-service-present-copy.yml
Additional resources
- See Encrypting content with Ansible Vault.
- See Roles in IdM.
-
See the
README-role
Markdown file in the/usr/share/doc/ansible-freeipa/
directory. -
See the sample playbooks in the
/usr/share/doc/ansible-freeipa/playbooks/iparole
directory.
23.11. Using Ansible to ensure a host is a member of an IdM RBAC role
As a system administrator managing role-based access control in Identity Management (IdM), you may want to ensure that a specific host or host group is associated with a specific role. The following example describes how to ensure that the custom web_administrator role can manage the client01.idm.example.com IdM host on which the HTTP
service is running.
Prerequisites
- You know the IdM administrator password.
- You have installed the ansible-freeipa package on the Ansible control node.
- You have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server on which you want to do the configuring.
- Your Ansible inventory file is located in the ~/<MyPlaybooks>/ directory.
- The web_administrator role exists in IdM.
- The client01.idm.example.com host exists in IdM.
Procedure
Navigate to the ~/<MyPlaybooks>/ directory:
$ cd ~/<MyPlaybooks>/
Make a copy of the
role-member-host-present.yml
file located in the/usr/share/doc/ansible-freeipa/playbooks/role/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/role/role-member-host-present.yml role-member-host-present-copy.yml
-
Open the
role-member-host-present-copy.yml
Ansible playbook file for editing. Adapt the file by setting the following variables in the
iparole
task section:-
Set the
ipaadmin_password
variable to the password of the IdM administrator. -
Set the
name
variable to the name of the role you want to assign. -
Set the
host
list to the name of the host.
This is the modified Ansible playbook file for the current example:
--- - name: Playbook to manage IPA role with members. hosts: ipaserver become: yes gather_facts: no tasks: - iparole: ipaadmin_password: Secret123 name: web_administrator host: - client01.idm.example.com action: member
-
Set the
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i ~/<MyPlaybooks>/inventory role-member-host-present-copy.yml
Additional resources
- See Encrypting content with Ansible Vault.
- See Roles in IdM.
-
See the
README-role
Markdown file in the/usr/share/doc/ansible-freeipa/
directory. -
See the sample playbooks in the
/usr/share/doc/ansible-freeipa/playbooks/iparole
directory.
23.12. Using Ansible to ensure a host group is a member of an IdM RBAC role
As a system administrator managing role-based access control in Identity Management (IdM), you may want to ensure that a specific host or host group is associated with a specific role. The following example describes how to ensure that the custom web_administrator role can manage the web_servers group of IdM hosts on which the HTTP
service is running.
Prerequisites
- You know the IdM administrator password.
- You have installed the ansible-freeipa package on the Ansible control node.
- You have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server on which you want to do the configuring.
- Your Ansible inventory file is located in the ~/<MyPlaybooks>/ directory.
- The web_administrator role exists in IdM.
- The web_servers host group exists in IdM.
Procedure
Navigate to the ~/<MyPlaybooks>/ directory:
$ cd ~/<MyPlaybooks>/
Make a copy of the
role-member-hostgroup-present.yml
file located in the/usr/share/doc/ansible-freeipa/playbooks/role/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/role/role-member-hostgroup-present.yml role-member-hostgroup-present-copy.yml
-
Open the
role-member-hostgroup-present-copy.yml
Ansible playbook file for editing. Adapt the file by setting the following variables in the
iparole
task section:-
Set the
ipaadmin_password
variable to the password of the IdM administrator. -
Set the
name
variable to the name of the role you want to assign. -
Set the
hostgroup
list to the name of the hostgroup.
This is the modified Ansible playbook file for the current example:
--- - name: Playbook to manage IPA role with members. hosts: ipaserver become: yes gather_facts: no tasks: - iparole: ipaadmin_password: Secret123 name: web_administrator hostgroup: - web_servers action: member
-
Set the
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i ~/<MyPlaybooks>/inventory role-member-hostgroup-present-copy.yml
Additional resources
- See Encrypting content with Ansible Vault.
- See Roles in IdM.
-
See the
README-role
Markdown file in the/usr/share/doc/ansible-freeipa/
directory. -
See the sample playbooks in the
/usr/share/doc/ansible-freeipa/playbooks/iparole
directory.
Chapter 24. Using Ansible playbooks to manage RBAC privileges
Role-based access control (RBAC) is a policy-neutral access-control mechanism defined around roles, privileges, and permissions. Especially in large companies, using RBAC can help create a hierarchical system of administrators with their individual areas of responsibility.
This chapter describes the following operations for using Ansible playbooks to manage RBAC privileges in Identity Management (IdM):
- Using Ansible to ensure a custom RBAC privilege is present
- Using Ansible to ensure member permissions are present in a custom IdM RBAC privilege
- Using Ansible to ensure an IdM RBAC privilege does not include a permission
- Using Ansible to rename a custom IdM RBAC privilege
- Using Ansible to ensure an IdM RBAC privilege is absent
Prerequisites
- You understand the concepts and principles of RBAC.
24.1. Using Ansible to ensure a custom IdM RBAC privilege is present
To have a fully-functioning custom privilege in Identity Management (IdM) role-based access control (RBAC), you need to proceed in stages:
- Create a privilege with no permissions attached.
- Add permissions of your choice to the privilege.
The following procedure describes how to create an empty privilege using an Ansible playbook so that you can later add permissions to it. The example describes how to create a privilege named full_host_administration that is meant to combine all IdM permissions related to host administration.
Prerequisites
- You know the IdM administrator password.
- You have installed the ansible-freeipa package on the Ansible control node.
- You have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server on which you want to do the configuring.
- Your Ansible inventory file is located in the ~/MyPlaybooks/ directory.
Procedure
Navigate to the ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
Make a copy of the
privilege-present.yml
file located in the/usr/share/doc/ansible-freeipa/playbooks/privilege/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/privilege/privilege-present.yml privilege-present-copy.yml
-
Open the
privilege-present-copy.yml
Ansible playbook file for editing. Adapt the file by setting the following variables in the
ipaprivilege
task section:-
Set the
ipaadmin_password
variable to the password of the IdM administrator. -
Set the
name
variable to the name of the new privilege, full_host_administration. -
Optionally, describe the privilege using the
description
variable.
This is the modified Ansible playbook file for the current example:
--- - name: Privilege present example hosts: ipaserver become: true tasks: - name: Ensure privilege full_host_administration is present ipaprivilege: ipaadmin_password: Secret123 name: full_host_administration description: This privilege combines all IdM permissions related to host administration
-
Set the
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i inventory privilege-present-copy.yml
24.2. Using Ansible to ensure member permissions are present in a custom IdM RBAC privilege
To have a fully-functioning custom privilege in Identity Management (IdM) role-based access control (RBAC), you need to proceed in stages:
- Create a privilege with no permissions attached.
- Add permissions of your choice to the privilege.
The following procedure describes how to use an Ansible playbook to add permissions to a privilege created in the previous step. The example describes how to add all IdM permissions related to host administration to a privilege named full_host_administration. By default, the permissions are distributed between the Host Enrollment
, Host Administrators
and Host Group Administrator
privileges.
Prerequisites
- You know the IdM administrator password.
- You have installed the ansible-freeipa package on the Ansible control node.
- You have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server on which you want to do the configuring.
- Your Ansible inventory file is located in the ~/MyPlaybooks/ directory.
- The full_host_administration privilege exists. For information on how to create a privilege using Ansible, see Using Ansible to ensure a custom IdM RBAC privilege is present.
Procedure
Navigate to the ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
Make a copy of the
privilege-member-present.yml
file located in the/usr/share/doc/ansible-freeipa/playbooks/privilege/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/privilege/privilege-member-present.yml privilege-member-present-copy.yml
-
Open the
privilege-member-present-copy.yml
Ansible playbook file for editing. Adapt the file by setting the following variables in the
ipaprivilege
task section:-
Adapt the
name
of the task to correspond to your use case. -
Set the
ipaadmin_password
variable to the password of the IdM administrator. -
Set the
name
variable to the name of the privilege. -
Set the
permission
list to the names of the permissions that you want to include in the privilege. -
Make sure that the
action
variable is set tomember
.
This is the modified Ansible playbook file for the current example:
--- - name: Privilege member present example hosts: ipaserver become: true tasks: - name: Ensure that permissions are present for the "full_host_administration" privilege ipaprivilege: ipaadmin_password: Secret123 name: full_host_administration permission: - "System: Add krbPrincipalName to a Host" - "System: Enroll a Host" - "System: Manage Host Certificates" - "System: Manage Host Enrollment Password" - "System: Manage Host Keytab" - "System: Manage Host Principals" - "Retrieve Certificates from the CA" - "Revoke Certificate" - "System: Add Hosts" - "System: Add krbPrincipalName to a Host" - "System: Enroll a Host" - "System: Manage Host Certificates" - "System: Manage Host Enrollment Password" - "System: Manage Host Keytab" - "System: Manage Host Keytab Permissions" - "System: Manage Host Principals" - "System: Manage Host SSH Public Keys" - "System: Manage Service Keytab" - "System: Manage Service Keytab Permissions" - "System: Modify Hosts" - "System: Remove Hosts" - "System: Add Hostgroups" - "System: Modify Hostgroup Membership" - "System: Modify Hostgroups" - "System: Remove Hostgroups"
-
Adapt the
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i inventory privilege-member-present-copy.yml
24.3. Using Ansible to ensure an IdM RBAC privilege does not include a permission
As a system administrator of Identity Management (IdM), you can customize the IdM role-based access control.
The following procedure describes how to use an Ansible playbook to remove a permission from a privilege. The example describes how to remove the Request Certificates ignoring CA ACLs
permission from the default Certificate Administrators
privilege because, for example, the administrator considers it a security risk.
Prerequisites
- You know the IdM administrator password.
- You have installed the ansible-freeipa package on the Ansible control node.
- You have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server on which you want to do the configuring.
- Your Ansible inventory file is located in the ~/MyPlaybooks/ directory.
Procedure
Navigate to the ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
Make a copy of the
privilege-member-present.yml
file located in the/usr/share/doc/ansible-freeipa/playbooks/privilege/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/privilege/privilege-member-absent.yml privilege-member-absent-copy.yml
-
Open the
privilege-member-absent-copy.yml
Ansible playbook file for editing. Adapt the file by setting the following variables in the
ipaprivilege
task section:-
Adapt the
name
of the task to correspond to your use case. -
Set the
ipaadmin_password
variable to the password of the IdM administrator. -
Set the
name
variable to the name of the privilege. -
Set the
permission
list to the names of the permissions that you want to remove from the privilege. -
Make sure that the
action
variable is set tomember
. -
Make sure that the
state
variable is set toabsent
.
This is the modified Ansible playbook file for the current example:
--- - name: Privilege absent example hosts: ipaserver become: true tasks: - name: Ensure that the "Request Certificate ignoring CA ACLs" permission is absent from the "Certificate Administrators" privilege ipaprivilege: ipaadmin_password: Secret123 name: Certificate Administrators permission: - "Request Certificate ignoring CA ACLs" action: member state: absent
-
Adapt the
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i inventory privilege-member-absent-copy.yml
24.4. Using Ansible to rename a custom IdM RBAC privilege
As a system administrator of Identity Management (IdM), you can customize the IdM role-based access control.
The following procedure describes how to rename a privilege because, for example, you have removed a few permissions from it. As a result, the name of the privilege is no longer accurate. In the example, the administrator renames a full_host_administration privilege to limited_host_administration.
Prerequisites
- You know the IdM administrator password.
- You have installed the ansible-freeipa package on the Ansible control node.
- You have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server on which you want to do the configuring.
- Your Ansible inventory file is located in the ~/MyPlaybooks/ directory.
- The full_host_administration privilege exists. For more information on how to add a privilege, see Using Ansible to ensure a custom IdM RBAC privilege is present.
Procedure
Navigate to the ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
Make a copy of the
privilege-present.yml
file located in the/usr/share/doc/ansible-freeipa/playbooks/privilege/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/privilege/privilege-present.yml rename-privilege.yml
-
Open the
rename-privilege.yml
Ansible playbook file for editing. Adapt the file by setting the following variables in the
ipaprivilege
task section:-
Set the
ipaadmin_password
variable to the password of the IdM administrator. -
Set the
name
variable to the current name of the privilege. -
Add the
rename
variable and set it to the new name of the privilege. -
Add the
state
variable and set it torenamed
.
-
Set the
Rename the playbook itself, for example:
--- - name: Rename a privilege hosts: ipaserver become: true
Rename the task in the playbook, for example:
[...] tasks: - name: Ensure the full_host_administration privilege is renamed to limited_host_administration ipaprivilege: [...]
This is the modified Ansible playbook file for the current example:
--- - name: Rename a privilege hosts: ipaserver become: true tasks: - name: Ensure the full_host_administration privilege is renamed to limited_host_administration ipaprivilege: ipaadmin_password: Secret123 name: full_host_administration rename: limited_host_administration state: renamed
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i inventory rename-privilege.yml
24.5. Using Ansible to ensure an IdM RBAC privilege is absent
As a system administrator of Identity Management (IdM), you can customize the IdM role-based access control. The following procedure describes how to use an Ansible playbook to ensure that an RBAC privilege is absent. The example describes how to ensure that the CA administrator
privilege is absent. As a result of the procedure, the admin
administrator becomes the only user capable of managing certificate authorities in IdM.
Prerequisites
- You know the IdM administrator password.
- You have installed the ansible-freeipa package on the Ansible control node.
- You have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server on which you want to do the configuring.
- Your Ansible inventory file is located in the ~/MyPlaybooks/ directory.
Procedure
Navigate to the ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
Make a copy of the
privilege-absent.yml
file located in the/usr/share/doc/ansible-freeipa/playbooks/privilege/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/privilege/privilege-absent.yml privilege-absent-copy.yml
-
Open the
privilege-absent-copy.yml
Ansible playbook file for editing. Adapt the file by setting the following variables in the
ipaprivilege
task section:-
Set the
ipaadmin_password
variable to the password of the IdM administrator. -
Set the
name
variable to the name of the privilege you want to remove. -
Make sure that the
state
variable is set it toabsent
.
-
Set the
Rename the task in the playbook, for example:
[...] tasks: - name: Ensure privilege "CA administrator" is absent ipaprivilege: [...]
This is the modified Ansible playbook file for the current example:
--- - name: Privilege absent example hosts: ipaserver become: true tasks: - name: Ensure privilege "CA administrator" is absent ipaprivilege: ipaadmin_password: Secret123 name: CA administrator state: absent
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i inventory privilege-absent-copy.yml
24.6. Additional resources
- See Privileges in IdM.
- See Permissions in IdM.
-
See the
README-privilege
file available in the/usr/share/doc/ansible-freeipa/
directory. -
See the sample playbooks in the
/usr/share/doc/ansible-freeipa/playbooks/ipaprivilege
directory.
Chapter 25. Using Ansible playbooks to manage RBAC permissions in IdM
Role-based access control (RBAC) is a policy-neutral access control mechanism defined around roles, privileges, and permissions. Especially in large companies, using RBAC can help create a hierarchical system of administrators with their individual areas of responsibility.
This chapter describes the following operations performed when managing RBAC permissions in Identity Management (IdM) using Ansible playbooks:
- Using Ansible to ensure an RBAC permission is present
- Using Ansible to ensure an RBAC permission with an attribute is present
- Using Ansible to ensure an RBAC permission is absent
- Using Ansible to ensure an attribute is a member of an IdM RBAC permission
- Using Ansible to ensure an attribute is not a member of an IdM RBAC permission
- Using Ansible to rename an IdM RBAC permission
Prerequisites
- You understand the concepts and principles of RBAC.
25.1. Using Ansible to ensure an RBAC permission is present
As a system administrator of Identity Management (IdM), you can customize the IdM role-based access control (RBAC).
The following procedure describes how to use an Ansible playbook to ensure a permission is present in IdM so that it can be added to a privilege. The example describes how to ensure the following target state:
-
The
MyPermission
permission exists. -
The
MyPermission
permission can only be applied to hosts. A user granted a privilege that contains the permission can do all of the following possible operations on an entry:
- Write
- Read
- Search
- Compare
- Add
- Delete
Prerequisites
- You know the IdM administrator password.
- You have installed the ansible-freeipa package on the Ansible control node.
- The example assumes that you have created and configured the ~/MyPlaybooks/ directory as a central location to store copies of sample playbooks.
Procedure
Navigate to the ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
Make a copy of the
permission-present.yml
file located in the/usr/share/doc/ansible-freeipa/playbooks/permission/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/permission/permission-present.yml permission-present-copy.yml
-
Open the
permission-present-copy.yml
Ansible playbook file for editing. Adapt the file by setting the following variables in the
ipapermission
task section:-
Adapt the
name
of the task to correspond to your use case. -
Set the
ipaadmin_password
variable to the password of the IdM administrator. -
Set the
name
variable to the name of the permission. -
Set the
object_type
variable tohost
. -
Set the
right
variable toall
.
This is the modified Ansible playbook file for the current example:
--- - name: Permission present example hosts: ipaserver become: true tasks: - name: Ensure that the "MyPermission" permission is present ipapermission: ipaadmin_password: Secret123 name: MyPermission object_type: host right: all
-
Adapt the
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i inventory permission-present-copy.yml
25.2. Using Ansible to ensure an RBAC permission with an attribute is present
As a system administrator of Identity Management (IdM), you can customize the IdM role-based access control (RBAC).
The following procedure describes how to use an Ansible playbook to ensure a permission is present in IdM so that it can be added to a privilege. The example describes how to ensure the following target state:
- The MyPermission permission exists.
- The MyPermission permission can only be used to add hosts.
A user granted a privilege that contains the permission can do all of the following possible operations on a host entry:
- Write
- Read
- Search
- Compare
- Add
- Delete
-
The host entries created by a user that is granted a privilege that contains the MyPermission permission can have a
description
value.
The type of attribute that you can specify when creating or modifying a permission is not constrained by the IdM LDAP schema. However, specifying, for example, attrs: car_licence
if the object_type
is host
later results in the ipa: ERROR: attribute "car-license" not allowed
error message when you try to exercise the permission and add a specific car licence value to a host.
Prerequisites
- You know the IdM administrator password.
- You have installed the ansible-freeipa package on the Ansible control node.
- The example assumes that you have created and configured the ~/MyPlaybooks/ directory as a central location to store copies of sample playbooks.
Procedure
Navigate to the ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
Make a copy of the
permission-present.yml
file located in the/usr/share/doc/ansible-freeipa/playbooks/permission/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/permission/permission-present.yml permission-present-with-attribute.yml
-
Open the
permission-present-with-attribute.yml
Ansible playbook file for editing. Adapt the file by setting the following variables in the
ipapermission
task section:-
Adapt the
name
of the task to correspond to your use case. -
Set the
ipaadmin_password
variable to the password of the IdM administrator. -
Set the
name
variable to the name of the permission. -
Set the
object_type
variable tohost
. -
Set the
right
variable toall
. -
Set the
attrs
variable todescription
.
This is the modified Ansible playbook file for the current example:
--- - name: Permission present example hosts: ipaserver become: true tasks: - name: Ensure that the "MyPermission" permission is present with an attribute ipapermission: ipaadmin_password: Secret123 name: MyPermission object_type: host right: all attrs: description
-
Adapt the
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i inventory permission-present-with-attribute.yml
Additional resources
- See User and group schema in Linux Domain Identity, Authentication and Policy Guide in RHEL 7.
25.3. Using Ansible to ensure an RBAC permission is absent
As a system administrator of Identity Management (IdM), you can customize the IdM role-based access control (RBAC).
The following procedure describes how to use an Ansible playbook to ensure a permission is absent in IdM so that it cannot be added to a privilege.
Prerequisites
- You know the IdM administrator password.
- You have installed the ansible-freeipa package on the Ansible control node.
- The example assumes that you have created and configured the ~/MyPlaybooks/ directory as a central location to store copies of sample playbooks.
Procedure
Navigate to the ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
Make a copy of the
permission-absent.yml
file located in the/usr/share/doc/ansible-freeipa/playbooks/permission/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/permission/permission-absent.yml permission-absent-copy.yml
-
Open the
permission-absent-copy.yml
Ansible playbook file for editing. Adapt the file by setting the following variables in the
ipapermission
task section:-
Adapt the
name
of the task to correspond to your use case. -
Set the
ipaadmin_password
variable to the password of the IdM administrator. -
Set the
name
variable to the name of the permission.
This is the modified Ansible playbook file for the current example:
--- - name: Permission absent example hosts: ipaserver become: true tasks: - name: Ensure that the "MyPermission" permission is absent ipapermission: ipaadmin_password: Secret123 name: MyPermission state: absent
-
Adapt the
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i inventory permission-absent-copy.yml
25.4. Using Ansible to ensure an attribute is a member of an IdM RBAC permission
As a system administrator of Identity Management (IdM), you can customize the IdM role-based access control (RBAC).
The following procedure describes how to use an Ansible playbook to ensure that an attribute is a member of an RBAC permission in IdM. As a result, a user with the permission can create entries that have the attribute.
The example describes how to ensure that the host entries created by a user with a privilege that contains the MyPermission permission can have gecos
and description
values.
The type of attribute that you can specify when creating or modifying a permission is not constrained by the IdM LDAP schema. However, specifying, for example, attrs: car_licence
if the object_type
is host
later results in the ipa: ERROR: attribute "car-license" not allowed
error message when you try to exercise the permission and add a specific car licence value to a host.
Prerequisites
- You know the IdM administrator password.
- You have installed the ansible-freeipa package on the Ansible control node.
- The example assumes that you have created and configured the ~/MyPlaybooks/ directory as a central location to store copies of sample playbooks.
- The MyPermission permission exists.
Procedure
Navigate to the ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
Make a copy of the
permission-member-present.yml
file located in the/usr/share/doc/ansible-freeipa/playbooks/permission/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/permission/permission-member-present.yml permission-member-present-copy.yml
-
Open the
permission-member-present-copy.yml
Ansible playbook file for editing. Adapt the file by setting the following variables in the
ipapermission
task section:-
Adapt the
name
of the task to correspond to your use case. -
Set the
ipaadmin_password
variable to the password of the IdM administrator. -
Set the
name
variable to the name of the permission. -
Set the
attrs
list to thedescription
andgecos
variables. -
Make sure the
action
variable is set tomember
.
This is the modified Ansible playbook file for the current example:
--- - name: Permission member present example hosts: ipaserver become: true tasks: - name: Ensure that the "gecos" and "description" attributes are present in "MyPermission" ipapermission: ipaadmin_password: Secret123 name: MyPermission attrs: - description - gecos action: member
-
Adapt the
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i inventory permission-member-present-copy.yml
25.5. Using Ansible to ensure an attribute is not a member of an IdM RBAC permission
As a system administrator of Identity Management (IdM), you can customize the IdM role-based access control (RBAC).
The following procedure describes how to use an Ansible playbook to ensure that an attribute is not a member of an RBAC permission in IdM. As a result, when a user with the permission creates an entry in IdM LDAP, that entry cannot have a value associated with the attribute.
The example describes how to ensure the following target state:
- The MyPermission permission exists.
-
The host entries created by a user with a privilege that contains the MyPermission permission cannot have the
description
attribute.
Prerequisites
- You know the IdM administrator password.
- You have installed the ansible-freeipa package on the Ansible control node.
- The example assumes that you have created and configured the ~/MyPlaybooks/ directory as a central location to store copies of sample playbooks.
- The MyPermission permission exists.
Procedure
Navigate to the ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
Make a copy of the
permission-member-absent.yml
file located in the/usr/share/doc/ansible-freeipa/playbooks/permission/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/permission/permission-member-absent.yml permission-member-absent-copy.yml
-
Open the
permission-member-absent-copy.yml
Ansible playbook file for editing. Adapt the file by setting the following variables in the
ipapermission
task section:-
Adapt the
name
of the task to correspond to your use case. -
Set the
ipaadmin_password
variable to the password of the IdM administrator. -
Set the
name
variable to the name of the permission. -
Set the
attrs
variable todescription
. -
Set the
action
variable tomember
. -
Make sure the
state
variable is set toabsent
This is the modified Ansible playbook file for the current example:
--- - name: Permission absent example hosts: ipaserver become: true tasks: - name: Ensure that an attribute is not a member of "MyPermission" ipapermission: ipaadmin_password: Secret123 name: MyPermission attrs: description action: member state: absent
-
Adapt the
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i inventory permission-member-absent-copy.yml
25.6. Using Ansible to rename an IdM RBAC permission
As a system administrator of Identity Management (IdM), you can customize the IdM role-based access control.
The following procedure describes how to use an Ansible playbook to rename a permission. The example describes how to rename MyPermission to MyNewPermission.
Prerequisites
- You know the IdM administrator password.
- You have installed the ansible-freeipa package on the Ansible control node.
- The example assumes that you have created and configured the ~/MyPlaybooks/ directory as a central location to store copies of sample playbooks.
- The MyPermission exists in IdM.
- The MyNewPermission does not exist in IdM.
Procedure
Navigate to the ~/MyPlaybooks/ directory:
$ cd ~/MyPlaybooks/
Make a copy of the
permission-renamed.yml
file located in the/usr/share/doc/ansible-freeipa/playbooks/permission/
directory:$ cp /usr/share/doc/ansible-freeipa/playbooks/permission/permission-renamed.yml permission-renamed-copy.yml
-
Open the
permission-renamed-copy.yml
Ansible playbook file for editing. Adapt the file by setting the following variables in the
ipapermission
task section:-
Adapt the
name
of the task to correspond to your use case. -
Set the
ipaadmin_password
variable to the password of the IdM administrator. -
Set the
name
variable to the name of the permission.
This is the modified Ansible playbook file for the current example:
--- - name: Permission present example hosts: ipaserver become: true tasks: - name: Rename the "MyPermission" permission ipapermission: ipaadmin_password: Secret123 name: MyPermission rename: MyNewPermission state: renamed
-
Adapt the
- Save the file.
Run the Ansible playbook specifying the playbook file and the inventory file:
$ ansible-playbook -v -i inventory permission-renamed-copy.yml
25.7. Additional resources
- See Permissions in IdM.
- See Privileges in IdM.
-
See the
README-permission
file available in the/usr/share/doc/ansible-freeipa/
directory. -
See the sample playbooks in the
/usr/share/doc/ansible-freeipa/playbooks/ipapermission
directory.
Chapter 26. Using an ID view to override a user attribute value on an IdM client
If an Identity Management (IdM) user would like to override some of their user or group attributes stored in the IdM LDAP server, for example the login name, home directory, certificate used for authentication, or SSH
keys, you as IdM administrator can redefine these values for a specific IdM client, using IdM ID views. For example, you can specify a different home directory for a user on the IdM client that the user most commonly uses for logging in to IdM.
This chapter describes how to redefine a POSIX attribute value associated with an IdM user on a host enrolled into IdM as a client. Specifically, the chapter describes how to redefine the user login name and home directory.
This chapter includes the following sections:
- ID views
- Potential negative impact of ID views on SSSD performance
- Attributes an ID view can override
- Getting help for ID view commands
- Using an ID view to override the login name of an IdM user on a specific host
- Modifying an IdM ID view
- Adding an ID view to override an IdM user home directory on an IdM client
- Applying an ID view to an IdM host group
26.1. ID views
An ID view in Identity Management (IdM) is an IdM client-side view specifying the following information:
- New values for centrally defined POSIX user or group attributes
- The client host or hosts on which the new values apply.
An ID view contains one or more overrides. An override is a specific replacement of a centrally defined POSIX attribute value.
You can only define an ID view for an IdM client centrally on IdM servers. You cannot configure client-side overrides for an IdM client locally.
For example, you can use ID views to achieve the following goals:
-
Define different attribute values for different environments. For example, you can allow the IdM administrator or another IdM user to have different home directories on different IdM clients: you can configure
/home/encrypted/username
to be this user’s home directory on one IdM client and/dropbox/username
on another client. Using ID views in this situation is convenient as alternatively, for example, changingfallback_homedir
,override_homedir
or other home directory variables in the client’s/etc/sssd/sssd.conf
file would affect all users. See Adding an ID view to override an IdM user home directory on an IdM client for an example procedure. - Replace a previously generated attribute value with a different value, such as overriding a user’s UID. This ability can be useful when you want to achieve a system-wide change that would otherwise be difficult to do on the LDAP side, for example make 1009 the UID of an IdM user. IdM ID ranges, which are used to generate an IdM user UID, never start as low as 1000 or even 10000. If a reason exists for an IdM user to impersonate a local user with UID 1009 on all IdM clients, you can use ID views to override the UID of this IdM user that was generated when the user was created in IdM.
You can only apply ID views to IdM clients, not to IdM servers.
Additional resources
26.2. Potential negative impact of ID views on SSSD performance
When you define an ID view, IdM places the desired override value in the IdM server’s System Security Services Daemon (SSSD) cache. The SSSD running on an IdM client then retrieves the override value from the server cache.
Applying an ID view can have a negative impact on System Security Services Daemon (SSSD) performance, because certain optimizations and ID views cannot run at the same time. For example, ID views prevent SSSD from optimizing the process of looking up groups on the server:
- With ID views, SSSD must check every member on the returned list of group member names if the group name is overridden.
- Without ID views, SSSD can only collect the user names from the member attribute of the group object.
This negative effect becomes most apparent when the SSSD cache is empty or after you clear the cache, which makes all entries invalid.
26.3. Attributes an ID view can override
ID views consist of user and group ID overrides. The overrides define the new POSIX attribute values.
User and group ID overrides can define new values for the following POSIX attributes:
- User attributes
-
Login name (
uid
) -
GECOS entry (
gecos
) -
UID number (
uidNumber
) -
GID number (
gidNumber
) -
Login shell (
loginShell
) -
Home directory (
homeDirectory
) -
SSH public keys (
ipaSshPubkey
) -
Certificate (
userCertificate
)
-
Login name (
- Group attributes
-
Group name (
cn
) -
Group GID number (
gidNumber
)
-
Group name (
26.4. Getting help for ID view commands
You can get help for commands involving Identity Management (IdM) ID views on the IdM command-line interface (CLI).
Prerequisites
- You have obtained a Kerberos ticket for an IdM user.
Procedure
To display all commands used to manage ID views and overrides:
$ ipa help idviews ID Views Manage ID Views IPA allows to override certain properties of users and groups[...] [...] Topic commands: idoverridegroup-add Add a new Group ID override idoverridegroup-del Delete a Group ID override [...]
To display detailed help for a particular command, add the
--help
option to the command:$ ipa idview-add --help Usage: ipa [global-options] idview-add NAME [options] Add a new ID View. Options: -h, --help show this help message and exit --desc=STR Description [...]
26.5. Using an ID view to override the login name of an IdM user on a specific host
This section describes how you as an Identity Management (IdM) system administrator can create an ID view for a specific IdM client that overrides a POSIX attribute value associated with a specific IdM user. The procedure uses the example of an ID view that enables an IdM user named idm_user to log in to an IdM client named host1 using the user_1234 login name.
Prerequisites
- You are logged in as IdM administrator.
Procedure
Create a new ID view. For example, to create an ID view named
example_for_host1
:$ ipa idview-add example_for_host1 --------------------------- Added ID View "example_for_host1" --------------------------- ID View Name: example_for_host1
Add a user override to the example_for_host1 ID view. To override the user login:
-
Enter the
ipa idoverrideuser-add
command - Add the name of the ID view
- Add the user name, also called the anchor
Add the
--login
option:$ ipa idoverrideuser-add example_for_host1 idm_user --login=user_1234 ----------------------------- Added User ID override "idm_user" ----------------------------- Anchor to override: idm_user User login: user_1234
For a list of the available options, run ipa idoverrideuser-add --help.
NoteThe
ipa idoverrideuser-add --certificate
command replaces all existing certificates for the account in the specified ID view. To append an additional certificate, use theipa idoverrideuser-add-cert
command instead:$ ipa idoverrideuser-add-cert example_for_host1 user --certificate="MIIEATCC..."
-
Enter the
-
Optional: Using the
ipa idoverrideuser-mod
command, you can specify new attribute values for an existing user override. Apply
example_for_host1
to thehost1.idm.example.com
host:$ ipa idview-apply example_for_host1 --hosts=host1.idm.example.com ----------------------------- Applied ID View "example_for_host1" ----------------------------- hosts: host1.idm.example.com --------------------------------------------- Number of hosts the ID View was applied to: 1 ---------------------------------------------
NoteThe
ipa idview-apply
command also accepts the--hostgroups
option. The option applies the ID view to hosts that belong to the specified host group, but does not associate the ID view with the host group itself. Instead, the--hostgroups
option expands the members of the specified host group and applies the--hosts
option individually to every one of them.This means that if a host is added to the host group in the future, the ID view does not apply to the new host.
To apply the new configuration to the host1.idm.example.com system immediately:
SSH to the system as root:
$ ssh root@host1 Password:
Clear the SSSD cache:
root@host1 ~]# sss_cache -E
- Restart the SSSD daemon:
root@host1 ~]# systemctl restart sssd
Verification steps
If you have the credentials of user_1234, you can use them to log in to IdM on host1:
SSH to host1 using user_1234 as the login name:
[root@r8server ~]# ssh user_1234@host1.idm.example.com Password: Last login: Sun Jun 21 22:34:25 2020 from 192.168.122.229 [user_1234@host1 ~]$
Display the working directory:
[user_1234@host1 ~]$ pwd /home/idm_user/
Alternatively, if you have root credentials on host1, you can use them to check the output of the
id
command for idm_user and user_1234:[root@host1 ~]# id idm_user uid=779800003(user_1234) gid=779800003(idm_user) groups=779800003(idm_user) [root@host1 ~]# user_1234 uid=779800003(user_1234) gid=779800003(idm_user) groups=779800003(idm_user)
26.6. Modifying an IdM ID view
An ID view in Identity Management (IdM) overrides a POSIX attribute value associated with a specific IdM user. This section describes how to modify an existing ID view. Specifically, it describes how to modify an ID view to enable the user named idm_user to use the /home/user_1234/
directory as the user home directory instead of /home/idm_user/
on the host1.idm.example.com IdM client.
Prerequisites
- You have root access to host1.idm.example.com.
- You are logged in as a user with the required privileges, for example admin.
- You have an ID view configured for idm_user that applies to the host1 IdM client.
Procedure
As root, create the directory that you want idm_user to use on host1.idm.example.com as the user home directory:
[root@host1 /]# mkdir /home/user_1234/
Change the ownership of the directory:
[root@host1 /]# chown idm_user:idm_user /home/user_1234/
Display the ID view, including the hosts to which the ID view is currently applied. To display the ID view named
example_for_host1
:$ ipa idview-show example_for_host1 --all dn: cn=example_for_host1,cn=views,cn=accounts,dc=idm,dc=example,dc=com ID View Name: example_for_host1 User object override: idm_user Hosts the view applies to: host1.idm.example.com objectclass: ipaIDView, top, nsContainer
The output shows that the ID view currently applies to host1.idm.example.com.
Modify the user override of the example_for_host1 ID view. To override the user home directory:
-
Enter the
ipa idoverrideuser-add
command - Add the name of the ID view
- Add the user name, also called the anchor
Add the
--homedir
option:$ ipa idoverrideuser-mod example_for_host1 idm_user --homedir=/home/user_1234 ----------------------------- Modified an User ID override "idm_user" ----------------------------- Anchor to override: idm_user User login: user_1234 Home directory: /home/user_1234/
For a list of the available options, run
ipa idoverrideuser-mod --help
.-
Enter the
To apply the new configuration to the host1.idm.example.com system immediately:
SSH to the system as root:
$ ssh root@host1 Password:
Clear the SSSD cache:
root@host1 ~]# sss_cache -E
- Restart the SSSD daemon:
root@host1 ~]# systemctl restart sssd
Verification steps
SSH
to host1 as idm_user:[root@r8server ~]# ssh idm_user@host1.idm.example.com Password: Last login: Sun Jun 21 22:34:25 2020 from 192.168.122.229 [user_1234@host1 ~]$
Print the working directory:
[user_1234@host1 ~]$ pwd /home/user_1234/
Additional resources
26.7. Adding an ID view to override an IdM user home directory on an IdM client
An ID view in Identity Management (IdM) overrides a POSIX attribute value associated with a specific IdM user. This section describes how to create an ID view that applies to idm_user on an IdM client named host1 to enable the user to use the /home/user_1234/
directory as the user home directory instead of /home/idm_user/
.
Prerequisites
- You have root access to host1.idm.example.com.
- You are logged in as a user with the required privileges, for example admin.
Procedure
As root, create the directory that you want idm_user to use on host1.idm.example.com as the user home directory:
[root@host1 /]# mkdir /home/user_1234/
Change the ownership of the directory:
[root@host1 /]# chown idm_user:idm_user /home/user_1234/
Create an ID view. For example, to create an ID view named example_for_host1:
$ ipa idview-add example_for_host1 --------------------------- Added ID View "example_for_host1" --------------------------- ID View Name: example_for_host1
Add a user override to the example_for_host1 ID view. To override the user home directory:
-
Enter the
ipa idoverrideuser-add
command - Add the name of the ID view
- Add the user name, also called the anchor
-
Add the
--homedir
option:
$ ipa idoverrideuser-add example_for_host1 idm_user --homedir=/home/user_1234 ----------------------------- Added User ID override "idm_user" ----------------------------- Anchor to override: idm_user Home directory: /home/user_1234/
-
Enter the
Apply
example_for_host1
to thehost1.idm.example.com
host:$ ipa idview-apply example_for_host1 --hosts=host1.idm.example.com ----------------------------- Applied ID View "example_for_host1" ----------------------------- hosts: host1.idm.example.com --------------------------------------------- Number of hosts the ID View was applied to: 1 ---------------------------------------------
NoteThe
ipa idview-apply
command also accepts the--hostgroups
option. The option applies the ID view to hosts that belong to the specified host group, but does not associate the ID view with the host group itself. Instead, the--hostgroups
option expands the members of the specified host group and applies the--hosts
option individually to every one of them.This means that if a host is added to the host group in the future, the ID view does not apply to the new host.
To apply the new configuration to the host1.idm.example.com system immediately:
SSH to the system as root:
$ ssh root@host1 Password:
Clear the SSSD cache:
root@host1 ~]# sss_cache -E
- Restart the SSSD daemon:
root@host1 ~]# systemctl restart sssd
Verification steps
SSH
to host1 as idm_user:[root@r8server ~]# ssh idm_user@host1.idm.example.com Password: Activate the web console with: systemctl enable --now cockpit.socket Last login: Sun Jun 21 22:34:25 2020 from 192.168.122.229 [idm_user@host1 /]$
Print the working directory:
[idm_user@host1 /]$ pwd /home/user_1234/
26.8. Applying an ID view to an IdM host group
The ipa idview-apply
command accepts the --hostgroups
option. However, the option acts as a one-time operation that applies the ID view to hosts that currently belong to the specified host group, but does not dynamically associate the ID view with the host group itself. The --hostgroups
option expands the members of the specified host group and applies the --hosts
option individually to every one of them.
If you add a new host to the host group later, you must apply the ID view to the new host manually, using the ipa idview-apply
command with the --hosts
option.
Similarly, if you remove a host from a host group, the ID view is still assigned to the host after the removal. To unapply the ID view from the removed host, you must run the ipa idview-unapply id_view_name --hosts=name_of_the_removed_host
command.
This section describes how to achieve the following goals:
- How to create a host group and add hosts to it.
- How to apply an ID view to the host group.
- How to add a new host to the host group and apply the ID view to the new host.
Prerequisites
- Ensure that the ID view you want to apply to the host group exists in IdM. For example, to create an ID view to override the GID for an AD user, see Overriding Default Trust View attributes for an AD user on an IdM client with an ID view
Procedure
Create a host group and add hosts to it:
Create a host group. For example, to create a host group named baltimore:
[root@server ~]# ipa hostgroup-add --desc="Baltimore hosts" baltimore --------------------------- Added hostgroup "baltimore" --------------------------- Host-group: baltimore Description: Baltimore hosts
Add hosts to the host group. For example, to add the host102 and host103 to the baltimore host group:
[root@server ~]# ipa hostgroup-add-member --hosts={host102,host103} baltimore Host-group: baltimore Description: Baltimore hosts Member hosts: host102.idm.example.com, host103.idm.example.com ------------------------- Number of members added 2 -------------------------
Apply an ID view to the hosts in the host group. For example, to apply the example_for_host1 ID view to the baltimore host group:
[root@server ~]# ipa idview-apply --hostgroups=baltimore ID View Name: example_for_host1 ----------------------------------------- Applied ID View "example_for_host1" ----------------------------------------- hosts: host102.idm.example.com, host103.idm.example.com --------------------------------------------- Number of hosts the ID View was applied to: 2 ---------------------------------------------
Add a new host to the host group and apply the ID view to the new host:
Add a new host to the host group. For example, to add the somehost.idm.example.com host to the baltimore host group:
[root@server ~]# ipa hostgroup-add-member --hosts=somehost.idm.example.com baltimore Host-group: baltimore Description: Baltimore hosts Member hosts: host102.idm.example.com, host103.idm.example.com,somehost.idm.example.com ------------------------- Number of members added 1 -------------------------
Optionally, display the ID view information. For example, to display the details about the example_for_host1 ID view:
[root@server ~]# ipa idview-show example_for_host1 --all dn: cn=example_for_host1,cn=views,cn=accounts,dc=idm,dc=example,dc=com ID View Name: example_for_host1 [...] Hosts the view applies to: host102.idm.example.com, host103.idm.example.com objectclass: ipaIDView, top, nsContainer
The output shows that the ID view is not applied to somehost.idm.example.com, the newly-added host in the baltimore host group.
Apply the ID view to the new host. For example, to apply the example_for_host1 ID view to somehost.idm.example.com:
[root@server ~]# ipa idview-apply --host=somehost.idm.example.com ID View Name: example_for_host1 ----------------------------------------- Applied ID View "example_for_host1" ----------------------------------------- hosts: somehost.idm.example.com --------------------------------------------- Number of hosts the ID View was applied to: 1 ---------------------------------------------
Verification steps
Display the ID view information again:
[root@server ~]# ipa idview-show example_for_host1 --all dn: cn=example_for_host1,cn=views,cn=accounts,dc=idm,dc=example,dc=com ID View Name: example_for_host1 [...] Hosts the view applies to: host102.idm.example.com, host103.idm.example.com, somehost.idm.example.com objectclass: ipaIDView, top, nsContainer
The output shows that ID view is now applied to somehost.idm.example.com, the newly-added host in the baltimore host group.
26.9. Migrating NIS domains to Identity Management
You can use ID views to set host specific UIDs and GIDs for existing hosts to prevent changing permissions for files and directories when migrating NIS domains into IdM.
Prerequisites
-
You authenticated yourself as an admin using the
kinit admin
command.
Procedure
Add users and groups in the IdM domain.
-
Create users using the
ipa user-add
command. For more information see: Adding users to IdM. -
Create groups using the
ipa group-add
command. For more information see: Adding groups to IdM.
-
Create users using the
Override IDs IdM generated during the user creation:
-
Create a new ID view using
ipa idview-add
command. For more information see: Getting help for ID view commands. -
Add ID overrides for the users and groups to the ID view using
ipa idoverrideuser-add
andidoverridegroup-add
respectively.
-
Create a new ID view using
-
Assign the ID view to the specific hosts using
ipa idview-apply
command. - Decommission the NIS domains.
Verification
To check if all users and groups were added to the ID view correctly, use the
ipa idview-show
command.$ ipa idview-show example-view ID View Name: example-view User object overrides: example-user1 Group object overrides: example-group
Chapter 27. Using ID views for Active Directory users
You can use ID views to specify new values for the POSIX attributes of your Active Directory (AD) users in an IdM-AD Trust environment.
By default, IdM applies the Default Trust View to all AD users. You can configure additional ID views on individual IdM clients to further adjust which POSIX attributes specific users receive.
27.1. How the Default Trust View works
The Default Trust View is the default ID view that is always applied to AD users and groups in trust-based setups. It is created automatically when you establish the trust using the ipa-adtrust-install
command and cannot be deleted.
The Default Trust View only accepts overrides for AD users and groups, not for IdM users and groups.
Using the Default Trust View, you can define custom POSIX attributes for AD users and groups, thus overriding the values defined in AD.
Table 27.1. Applying the Default Trust View
Values in AD | Default Trust View | Result | |
---|---|---|---|
Login | ad_user | ad_user | ad_user |
UID | 111 | 222 | 222 |
GID | 111 | (no value) | 111 |
You can also configure additional ID Views to override the Default Trust View on IdM clients. IdM applies the values from the host-specific ID view on top of the Default Trust View:
- If an attribute is defined in the host-specific ID view, IdM applies the value from this ID view.
- If an attribute is not defined in the host-specific ID view, IdM applies the value from the Default Trust View.
Table 27.2. Applying a host-specific ID view on top of the Default Trust View
Values in AD | Default Trust View | Host-specific ID view | Result | |
---|---|---|---|---|
Login | ad_user | ad_user | (no value) | ad_user |
UID | 111 | 222 | 333 | 333 |
GID | 111 | (no value) | 333 | 333 |
You can only apply host-specific ID views to override the Default Trust View on IdM clients. IdM servers and replicas always apply the values from the Default Trust View.
Additional resources
27.2. Defining global attributes for an AD user by modifying the Default Trust View
If you want to override a POSIX attribute for an Active Directory (AD) user throughout your entire IdM deployment, modify the entry for that user in the Default Trust View. This procedure sets the GID for the AD user ad_user@ad.example.com
to 732000006.
Prerequisites
- You are working with an IdM server that is a Trust Controller or Trust Agent.
- You have authenticated as an IdM administator.
Procedure
As an IdM administrator, create an ID override for the AD user in the Default Trust View that changes the GID number to 732000006:
# ipa idoverrideuser-add 'Default Trust View' ad_user@ad.example.com --gidnumber=732000006
Clear the entry for the
ad_user@ad.example.com
user from the SSSD cache on all IdM servers and clients. This removes stale data and allows the new override value to apply.# sssctl cache-expire -u ad_user@ad.example.com
Verification
Retrieve information for the
ad_user@ad.example.com
user to verify the GID reflects the updated value.# id ad_user@ad.example.com uid=702801456(ad_user@ad.example.com) gid=732000006(ad_admins) groups=732000006(ad_admins),702800513(domain users@ad.example.com)
27.3. Overriding Default Trust View attributes for an AD user on an IdM client with an ID view
You might want to override some POSIX attributes from the Default Trust View for an Active Directory (AD) user. For example, you might need to give an AD user a different GID on one particular IdM client. You can use an ID view to override a value from the Default Trust View for an AD user and apply it to a single host. This procedure explains how to set the GID for the ad_user@ad.example.com
AD user on the host1.idm.example.com
IdM client to 732001337.
Prerequisites
-
You have root access to the
host1.idm.example.com
IdM client. -
You are logged in as a user with the required privileges, for example the
admin
user.
Procedure
Create an ID view. For example, to create an ID view named example_for_host1:
$ ipa idview-add example_for_host1 --------------------------- Added ID View "example_for_host1" --------------------------- ID View Name: example_for_host1
Add a user override to the example_for_host1 ID view. To override the user’s GID:
-
Enter the
ipa idoverrideuser-add
command - Add the name of the ID view
- Add the user name, also called the anchor
-
Add the
--gidnumber=
option:
$ ipa idoverrideuser-add example_for_host1 ad_user@ad.example.com --gidnumber=732001337 ----------------------------- Added User ID override "ad_user@ad.example.com" ----------------------------- Anchor to override: ad_user@ad.example.com GID: 732001337
-
Enter the
Apply
example_for_host1
to thehost1.idm.example.com
IdM client:$ ipa idview-apply example_for_host1 --hosts=host1.idm.example.com ----------------------------- Applied ID View "example_for_host1" ----------------------------- hosts: host1.idm.example.com --------------------------------------------- Number of hosts the ID View was applied to: 1 ---------------------------------------------
NoteThe
ipa idview-apply
command also accepts the--hostgroups
option. The option applies the ID view to hosts that belong to the specified host group, but does not associate the ID view with the host group itself. Instead, the--hostgroups
option expands the members of the specified host group and applies the--hosts
option individually to every one of them.This means that if a host is added to the host group in the future, the ID view does not apply to the new host.
Clear the entry for the
ad_user@ad.example.com
user from the SSSD cache on thehost1.idm.example.com
IdM client. This removes stale data and allows the new override value to apply.[root@host1 ~]# sssctl cache-expire -u ad_user@ad.example.com
Verification Steps
SSH
to host1 as ad_user@ad.example.com:[root@r8server ~]# ssh ad_user@ad.example.com@host1.idm.example.com
Retrieve information for the
ad_user@ad.example.com
user to verify the GID reflects the updated value.[ad_user@ad.example.com@host1 ~]$ id ad_user@ad.example.com uid=702801456(ad_user@ad.example.com) gid=732001337(admins2) groups=732001337(admins2),702800513(domain users@ad.example.com)
27.4. Applying an ID view to an IdM host group
The ipa idview-apply
command accepts the --hostgroups
option. However, the option acts as a one-time operation that applies the ID view to hosts that currently belong to the specified host group, but does not dynamically associate the ID view with the host group itself. The --hostgroups
option expands the members of the specified host group and applies the --hosts
option individually to every one of them.
If you add a new host to the host group later, you must apply the ID view to the new host manually, using the ipa idview-apply
command with the --hosts
option.
Similarly, if you remove a host from a host group, the ID view is still assigned to the host after the removal. To unapply the ID view from the removed host, you must run the ipa idview-unapply id_view_name --hosts=name_of_the_removed_host
command.
This section describes how to achieve the following goals:
- How to create a host group and add hosts to it.
- How to apply an ID view to the host group.
- How to add a new host to the host group and apply the ID view to the new host.
Prerequisites
- Ensure that the ID view you want to apply to the host group exists in IdM. For example, to create an ID view to override the GID for an AD user, see Overriding Default Trust View attributes for an AD user on an IdM client with an ID view
Procedure
Create a host group and add hosts to it:
Create a host group. For example, to create a host group named baltimore:
[root@server ~]# ipa hostgroup-add --desc="Baltimore hosts" baltimore --------------------------- Added hostgroup "baltimore" --------------------------- Host-group: baltimore Description: Baltimore hosts
Add hosts to the host group. For example, to add the host102 and host103 to the baltimore host group:
[root@server ~]# ipa hostgroup-add-member --hosts={host102,host103} baltimore Host-group: baltimore Description: Baltimore hosts Member hosts: host102.idm.example.com, host103.idm.example.com ------------------------- Number of members added 2 -------------------------
Apply an ID view to the hosts in the host group. For example, to apply the example_for_host1 ID view to the baltimore host group:
[root@server ~]# ipa idview-apply --hostgroups=baltimore ID View Name: example_for_host1 ----------------------------------------- Applied ID View "example_for_host1" ----------------------------------------- hosts: host102.idm.example.com, host103.idm.example.com --------------------------------------------- Number of hosts the ID View was applied to: 2 ---------------------------------------------
Add a new host to the host group and apply the ID view to the new host:
Add a new host to the host group. For example, to add the somehost.idm.example.com host to the baltimore host group:
[root@server ~]# ipa hostgroup-add-member --hosts=somehost.idm.example.com baltimore Host-group: baltimore Description: Baltimore hosts Member hosts: host102.idm.example.com, host103.idm.example.com,somehost.idm.example.com ------------------------- Number of members added 1 -------------------------
Optionally, display the ID view information. For example, to display the details about the example_for_host1 ID view:
[root@server ~]# ipa idview-show example_for_host1 --all dn: cn=example_for_host1,cn=views,cn=accounts,dc=idm,dc=example,dc=com ID View Name: example_for_host1 [...] Hosts the view applies to: host102.idm.example.com, host103.idm.example.com objectclass: ipaIDView, top, nsContainer
The output shows that the ID view is not applied to somehost.idm.example.com, the newly-added host in the baltimore host group.
Apply the ID view to the new host. For example, to apply the example_for_host1 ID view to somehost.idm.example.com:
[root@server ~]# ipa idview-apply --host=somehost.idm.example.com ID View Name: example_for_host1 ----------------------------------------- Applied ID View "example_for_host1" ----------------------------------------- hosts: somehost.idm.example.com --------------------------------------------- Number of hosts the ID View was applied to: 1 ---------------------------------------------
Verification steps
Display the ID view information again:
[root@server ~]# ipa idview-show example_for_host1 --all dn: cn=example_for_host1,cn=views,cn=accounts,dc=idm,dc=example,dc=com ID View Name: example_for_host1 [...] Hosts the view applies to: host102.idm.example.com, host103.idm.example.com, somehost.idm.example.com objectclass: ipaIDView, top, nsContainer
The output shows that ID view is now applied to somehost.idm.example.com, the newly-added host in the baltimore host group.
Chapter 28. Adjusting ID ranges manually
An IdM server generates unique user ID (UID) and group ID (GID) numbers. By creating and assigning different ID ranges to replicas, it also ensures that they never generate the same ID numbers. By default, this process is automatic. However, you can manually adjust the IdM ID range during the IdM server installation, or manually define a replica’s DNA ID range.
28.1. ID ranges
ID numbers are divided into ID ranges. Keeping separate numeric ranges for individual servers and replicas eliminates the chance that an ID number issued for an entry is already used by another entry on another server or replica.
Note that there are two distinct types of ID ranges:
- The IdM ID range, which is assigned during the installation of the first server. This range cannot be modified after it is created. However, you can create a new IdM ID range in addition to the original one. For more information, see Automatic ID ranges assignment and Adding a new IdM ID range.
The Distributed Numeric Assignment (DNA) ID ranges, which can be modified by the user. These have to fit within an existing IdM ID range. For more information, see Assigning DNA ID ranges manually.
Replicas can also have a next DNA ID range assigned. A replica uses its next range when it runs out of IDs in its current range. Next ranges are not assigned automatically when a replica is deleted and you must assign them manually.
The ranges are updated and shared between the server and replicas by the DNA plug-in, as part of the back end 389 Directory Server instance for the domain.
The DNA range definition is set by two attributes:
- The server’s next available number: the low end of the DNA range
- The range size: the number of ID’s in the DNA range
The initial bottom range is set during the plug-in instance configuration. After that, the plug-in updates the bottom value. Breaking the available numbers into ranges allows the servers to continually assign numbers without overlapping with each other.
28.2. Automatic ID ranges assignment
IdM ID ranges
By default, an IdM ID range is automatically assigned during the IdM server installation. The ipa-server-install
command randomly selects and assigns a range of 200,000 IDs from a total of 10,000 possible ranges. Selecting a random range in this way significantly reduces the probability of conflicting IDs in case you decide to merge two separate IdM domains in the future.
This IdM ID range cannot be modified after it is created. You can only manually adjust the Distributed Numeric Assignment (DNA) ID ranges, using the commands described in Assigning DNA ID ranges manually. A DNA range matching the IdM ID range is automatically created during installation.
DNA ID ranges
If you have a single IdM server installed, it controls the whole DNA ID range. When you install a new replica and the replica requests its own DNA ID range, the initial ID range for the server splits and is distributed between the server and replica: the replica receives half of the remaining DNA ID range that is available on the initial server. The server and replica then use their respective portions of the original ID range for new user or group entries. Also, if the replica is close to depleting its allocated ID range and fewer than 100 IDs remain, the replica contacts the other available servers to request a new DNA ID range.
When you install a replica, it does not immediately receive an ID range. A replica receives an ID range the first time the DNA plug-in is used, for example when you first add a user.
If the initial server stops functioning before the replica requests a DNA ID range from it, the replica is unable to contact the server to request the ID range. Attempting to add a new user on the replica then fails. In such situations, you can find out what ID range is assigned to the disabled server, and assign an ID range to the replica manually.
28.3. Assigning the IdM ID range manually during server installation
You can override the default behavior and set an IdM ID range manually instead of having it assigned randomly.
Do not set ID ranges that include UID values of 1000 and lower; these values are reserved for system use. Also, do not set an ID range that would include the 0 value; the SSSD service does not handle the 0 ID value.
Procedure
You can define the IdM ID range manually during server installation by using the following two options with
ipa-server-install
:-
--idstart
gives the starting value for UID and GID numbers. -
--idmax
gives the maximum UID and GID number; by default, the value is the--idstart
starting value plus 199,999.
-
Verification steps
To check if the ID range was assigned correctly, you can display the assigned IdM ID range by using the
ipa idrange-find
command:# ipa idrange-find --------------- 1 range matched --------------- Range name: IDM.EXAMPLE.COM_id_range First Posix ID of the range: 882200000 Number of IDs in the range: 200000 Range type: local domain range ---------------------------- Number of entries returned 1 ----------------------------
28.4. Adding a new IdM ID range
In some cases, you may want to create a new IdM ID range in addition to the original one; for example, when a replica has run out of IDs and the original IdM ID range is depleted.
Adding a new IdM ID range does not create new DNA ID ranges automatically. You must assign new DNA ID ranges to replicas manually as needed. For more information on how to do this, see assigning DNA ID ranges manually.
Procedure
To create a new IdM ID range, use the
ipa idrange-add
command. You must specify the new range name, the first ID number of the range and the range size:# ipa idrange-add IDM.EXAMPLE.COM_new_range --base-id=1000000 --range-size=200000 ------------------------------------------ Added ID range "IDM.EXAMPLE.COM_new_range" ------------------------------------------ Range name: IDM.EXAMPLE.COM_new_range First Posix ID of the range: 1000000 Number of IDs in the range: 200000 Range type: local domain range
Optional: Update the ID range immediately:
Clear the System Security Services Daemon (SSSD) cache:
# sss_cache -E
Restart the SSSD daemon:
# systemctl restart sssd
NoteIf you do not clear the SSSD cache and restart the service, it takes some time for SSSD to notice the new ID range. More specifically, it notices the range when it updates the domain list and other configuration data stored on the IdM server.
Verification steps
You can check if the new range is set correctly by using the
ipa idrange-find
command:# ipa idrange-find ---------------- 2 ranges matched ---------------- Range name: IDM.EXAMPLE.COM_id_range First Posix ID of the range: 882200000 Number of IDs in the range: 200000 Range type: local domain range Range name: IDM.EXAMPLE.COM_new_range First Posix ID of the range: 1000000 Number of IDs in the range: 200000 Range type: local domain range ---------------------------- Number of entries returned 2 ----------------------------
28.5. Removing an ID range after removing a trust to AD
If you have removed a trust between your IdM and Active Directory (AD) environments, you might want to remove the ID range associated with it.
IDs allocated to ID ranges associated with trusted domains might still be used for ownership of files and directories on systems enrolled into IdM.
If you remove the ID range that corresponds to an AD trust that you have removed, you will not be able to resolve the ownership of any files and directories owned by AD users.
Prerequisites
- You have removed a trust to an AD environment.
Procedure
Display all the ID ranges that are currently in use:
[root@server ~]# ipa idrange-find
-
Identify the name of the ID range associated with the trust you have removed. The first part of the name of the ID range is the name of the trust, for example
AD.EXAMPLE.COM_id_range
. Remove the range:
[root@server ~]# ipa idrange-del AD.EXAMPLE.COM_id_range
Restart the SSSD service to remove references to the ID range you have removed.
[root@server ~]# systemctl restart sssd
Additional resources
28.6. Displaying currently assigned DNA ID ranges
You can display both the currently active Distributed Numeric Assignment (DNA) ID range on a server, as well as its next DNA range if it has one assigned.
Procedure
To display which DNA ID ranges are configured for the servers in the topology, use the following commands:
ipa-replica-manage dnarange-show
displays the current DNA ID range that is set on all servers or, if you specify a server, only on the specified server, for example:# ipa-replica-manage dnarange-show serverA.example.com: 1001-1500 serverB.example.com: 1501-2000 serverC.example.com: No range set # ipa-replica-manage dnarange-show serverA.example.com serverA.example.com: 1001-1500
ipa-replica-manage dnanextrange-show
displays the next DNA ID range currently set on all servers or, if you specify a server, only on the specified server, for example:# ipa-replica-manage dnanextrange-show serverA.example.com: 2001-2500 serverB.example.com: No on-deck range set serverC.example.com: No on-deck range set # ipa-replica-manage dnanextrange-show serverA.example.com serverA.example.com: 2001-2500
28.7. Manual ID range assignment
In certain situations, it is necessary to manually assign a Distributed Numeric Assignment (DNA) ID range, for example when:
A replica has run out of IDs and the IdM ID range is depleted
A replica has exhausted the DNA ID range that was assigned to it, and requesting additional IDs failed because no more free IDs are available in the IdM range.
To solve this situation, extend the DNA ID range assigned to the replica. You can do this in two ways:
- Shorten the DNA ID range assigned to a different replica, then assign the newly available values to the depleted replica.
Create a new IdM ID range, then set a new DNA ID range for the replica within this created IdM range.
For information on how to create a new IdM ID range, see Adding a new IdM ID range.
A replica stopped functioning
A replica’s DNA ID range is not automatically retrieved when the replica stops functioning and must be deleted, which means the DNA ID range previously assigned to the replica becomes unavailable. You want to recover the DNA ID range and make it available for other replicas.
To do this, find out what the ID range values are, before manually assigning that range to a different server. Also, to avoid duplicate UIDs or GIDs, make sure that no ID value from the recovered range was previously assigned to a user or group; you can do this by examining the UIDs and GIDs of existing users and groups.
You can manually assign a DNA ID range to a replica using the commands in Assigning DNA ID ranges manually.
If you assign a new DNA ID range, the UIDs of the already existing entries on the server or replica stay the same. This does not pose a problem because even if you change the current DNA ID range, IdM keeps a record of what ranges were assigned in the past.
28.8. Assigning DNA ID ranges manually
In some cases, you may need to manually assign Distributed Numeric Assignment (DNA) ID ranges to existing replicas, for example to reassign a DNA ID range assigned to a non-functioning replica. For more information, see