Chapter 4. Installing an Identity Management client using an Ansible playbook
Learn more about how to configure a system as an Identity Management (IdM) client by using Ansible. Configuring a system as an IdM client enrolls it into an IdM domain and enables the system to use IdM services on IdM servers in the domain.
The deployment is managed by the ipaclient
Ansible role. By default, the role uses the autodiscovery mode for identifying the IdM servers, domain and other settings. The role can be modified to have the Ansible playbook use the settings specified, for example in the inventory file.
Prerequisites
- You have installed the ansible-freeipa package on the Ansible control node.
- You are using Ansible version 2.14 or later.
- You understand the general Ansible and IdM concepts.
4.1. Setting the parameters of the inventory file for the autodiscovery client installation mode
To install an Identity Management (IdM) client using an Ansible playbook, configure the target host parameters in an inventory file, for example inventory
:
- The information about the host
- The authorization for the task
The inventory file can be in one of many formats, depending on the inventory plugins you have. The INI-like
format is one of Ansible’s defaults and is used in the examples below.
To use smart cards with the graphical user interface in RHEL, ensure that you include the ipaclient_mkhomedir
variable in your Ansible playbook.
Procedure
-
Open your
inventory
file for editing. Specify the fully-qualified hostname (FQDN) of the host to become an IdM client. The fully qualified domain name must be a valid DNS name:
-
Only numbers, alphabetic characters, and hyphens (
-
) are allowed. For example, underscores are not allowed and can cause DNS failures. - The host name must be all lower-case. No capital letters are allowed.
If the SRV records are set properly in the IdM DNS zone, the script automatically discovers all the other required values.
Example of a simple inventory hosts file with only the client FQDN defined
[ipaclients] client.idm.example.com [...]
-
Only numbers, alphabetic characters, and hyphens (
Specify the credentials for enrolling the client. The following authentication methods are available:
The password of a user authorized to enroll clients. This is the default option.
Red Hat recommends using the Ansible Vault to store the password, and referencing the Vault file from the playbook file, for example
install-client.yml
, directly:Example playbook file using principal from inventory file and password from an Ansible Vault file
- name: Playbook to configure IPA clients with username/password hosts: ipaclients become: true vars_files: - playbook_sensitive_data.yml roles: - role: ipaclient state: present
Less securely, provide the credentials of
admin
using theipaadmin_password
option in the[ipaclients:vars]
section of theinventory/hosts
file. Alternatively, to specify a different authorized user, use theipaadmin_principal
option for the user name, and theipaadmin_password
option for the password. Theinventory/hosts
inventory file and theinstall-client.yml
playbook file can then look as follows:Example inventory hosts file
[...] [ipaclients:vars] ipaadmin_principal=my_admin ipaadmin_password=Secret123
Example Playbook using principal and password from inventory file
- name: Playbook to unconfigure IPA clients hosts: ipaclients become: true roles: - role: ipaclient state: true
The client keytab from the previous enrollment if it is still available.
This option is available if the system was previously enrolled as an Identity Management client. To use this authentication method, uncomment the
#ipaclient_keytab
option, specifying the path to the file storing the keytab, for example in the[ipaclient:vars]
section ofinventory/hosts
.A random, one-time password (OTP) to be generated during the enrollment. To use this authentication method, use the
ipaclient_use_otp=true
option in your inventory file. For example, you can uncomment theipaclient_use_otp=true
option in the[ipaclients:vars]
section of theinventory/hosts
file. Note that with OTP you must also specify one of the following options:-
The password of a user authorized to enroll clients, for example by providing a value for
ipaadmin_password
in the[ipaclients:vars]
section of theinventory/hosts
file. -
The admin keytab, for example by providing a value for
ipaadmin_keytab
in the[ipaclients:vars]
section ofinventory/hosts
.
-
The password of a user authorized to enroll clients, for example by providing a value for
Optional: Specify the DNS resolver using the
ipaclient_configure_dns_resolve
andipaclient_dns_servers
options (if available) to simplify cluster deployments. This is especially useful if your IdM deployment is using integrated DNS:An inventory file snippet specifying a DNS resolver:
[...] [ipaclients:vars] ipaadmin_password: "{{ ipaadmin_password }}" ipaclient_domain=idm.example.com ipaclient_configure_dns_resolver=true ipaclient_dns_servers=192.168.100.1
NoteThe
ipaclient_dns_servers
list must contain only IP addresses. Host names are not allowed.-
Starting with RHEL 8.9, you can also specify the
ipaclient_subid: true
option to have subid ranges configured for IdM users on the IdM level.
Additional resources
-
/usr/share/ansible/roles/ipaclient/README.md
- Managing subID ranges manually
4.2. Setting the parameters of the inventory file when autodiscovery is not possible during client installation
To install an Identity Management client using an Ansible playbook, configure the target host parameters in an inventory file, for example inventory/hosts
:
- The information about the host, the IdM server and the IdM domain or the IdM realm
- The authorization for the task
The inventory file can be in one of many formats, depending on the inventory plugins you have. The INI-like
format is one of Ansible’s defaults and is used in the examples below.
To use smart cards with the graphical user interface in RHEL, ensure that you include the ipaclient_mkhomedir
variable in your Ansible playbook.
Procedure
Specify the fully-qualified hostname (FQDN) of the host to become an IdM client. The fully qualified domain name must be a valid DNS name:
-
Only numbers, alphabetic characters, and hyphens (
-
) are allowed. For example, underscores are not allowed and can cause DNS failures. - The host name must be all lower-case. No capital letters are allowed.
-
Only numbers, alphabetic characters, and hyphens (
Specify other options in the relevant sections of the
inventory/hosts
file:-
The FQDN of the servers in the
[ipaservers]
section to indicate which IdM server the client will be enrolled with One of the two following options:
-
The
ipaclient_domain
option in the[ipaclients:vars]
section to indicate the DNS domain name of the IdM server the client will be enrolled with The
ipaclient_realm
option in the[ipaclients:vars]
section to indicate the name of the Kerberos realm controlled by the IdM serverExample of an inventory hosts file with the client FQDN, the server FQDN and the domain defined
[ipaclients] client.idm.example.com [ipaservers] server.idm.example.com [ipaclients:vars] ipaclient_domain=idm.example.com [...]
-
The
-
The FQDN of the servers in the
Specify the credentials for enrolling the client. The following authentication methods are available:
The password of a user authorized to enroll clients. This is the default option.
Red Hat recommends using the Ansible Vault to store the password, and referencing the Vault file from the playbook file, for example
install-client.yml
, directly:Example playbook file using principal from inventory file and password from an Ansible Vault file
- name: Playbook to configure IPA clients with username/password hosts: ipaclients become: true vars_files: - playbook_sensitive_data.yml roles: - role: ipaclient state: present
Less securely, the credentials of
admin
to be provided using theipaadmin_password
option in the[ipaclients:vars]
section of theinventory/hosts
file. Alternatively, to specify a different authorized user, use theipaadmin_principal
option for the user name, and theipaadmin_password
option for the password. Theinstall-client.yml
playbook file can then look as follows:Example inventory hosts file
[...] [ipaclients:vars] ipaadmin_principal=my_admin ipaadmin_password=Secret123
Example Playbook using principal and password from inventory file
- name: Playbook to unconfigure IPA clients hosts: ipaclients become: true roles: - role: ipaclient state: true
The client keytab from the previous enrollment if it is still available:
This option is available if the system was previously enrolled as an Identity Management client. To use this authentication method, uncomment the
ipaclient_keytab
option, specifying the path to the file storing the keytab, for example in the[ipaclient:vars]
section ofinventory/hosts
.A random, one-time password (OTP) to be generated during the enrollment. To use this authentication method, use the
ipaclient_use_otp=true
option in your inventory file. For example, you can uncomment the#ipaclient_use_otp=true
option in the[ipaclients:vars]
section of theinventory/hosts
file. Note that with OTP you must also specify one of the following options:-
The password of a user authorized to enroll clients, for example by providing a value for
ipaadmin_password
in the[ipaclients:vars]
section of theinventory/hosts
file. -
The admin keytab, for example by providing a value for
ipaadmin_keytab
in the[ipaclients:vars]
section ofinventory/hosts
.
-
The password of a user authorized to enroll clients, for example by providing a value for
-
Starting with RHEL 8.9, you can also specify the
ipaclient_subid: true
option to have subid ranges configured for IdM users on the IdM level.
Additional resources
-
/usr/share/ansible/roles/ipaclient/README.md
- Managing subID ranges manually
4.3. Authorization options for IdM client enrollment using an Ansible playbook
You can authorize IdM client enrollment by using any of the following methods:
- A random, one-time password (OTP) + administrator password
- A random, one-time password (OTP) + an admin keytab
- The client keytab from the previous enrollment
-
The password of a user authorized to enroll a client (
admin
) stored in an inventory file -
The password of a user authorized to enroll a client (
admin
) stored in an Ansible vault
It is possible to have the OTP generated by an IdM administrator before the IdM client installation. In that case, you do not need any credentials for the installation other than the OTP itself.
The following are sample inventory files for these methods:
Authorization option | Inventory file |
---|---|
A random, one-time password (OTP) + administrator password |
[ipaclients:vars] ipaadmin_password=Secret123 ipaclient_use_otp=true |
A random, one-time password (OTP) |
[ipaclients:vars] ipaclient_otp=<W5YpARl=7M.>
This scenario assumes that the OTP was already generated by an IdM |
A random, one-time password (OTP) + an admin keytab |
[ipaclients:vars] ipaadmin_keytab=/root/admin.keytab ipaclient_use_otp=true |
The client keytab from the previous enrollment |
[ipaclients:vars] ipaclient_keytab=/root/krb5.keytab |
Password of an |
[ipaclients:vars] ipaadmin_password=Secret123 |
Password of an |
[ipaclients:vars] [...] |
If you are using the password of an admin
user stored in an Ansible vault file, the corresponding playbook file must have an additional vars_files
directive:
Inventory file | Playbook file |
---|---|
[ipaclients:vars] [...] |
- name: Playbook to configure IPA clients hosts: ipaclients become: true vars_files: - ansible_vault_file.yml roles: - role: ipaclient state: present |
In all the other authorization scenarios described above, a basic playbook file could look as follows:
- name: Playbook to configure IPA clients hosts: ipaclients become: true roles: - role: ipaclient state: true
As of RHEL 8.8, in the two OTP authorization scenarios described above, the requesting of the administrator’s TGT by using the kinit
command occurs on the first specified or discovered IdM server. Therefore, no additional modification of the Ansible control node is required. Before RHEL 8.8, the krb5-workstation
package was required on the control node.
4.4. Deploying an IdM client using an Ansible playbook
Complete this procedure to use an Ansible playbook to deploy an IdM client in your IdM environment.
Prerequisites
- The managed node is a Red Hat Enterprise Linux 8 system with a static IP address and a working package manager.
You have set the parameters of the IdM client deployment to correspond to your deployment scenario:
Procedure
Run the Ansible playbook:
$ ansible-playbook -v -i ~/MyPlaybooks/inventory ~/MyPlaybooks/install-client.yml
4.5. Using the one-time password method in Ansible to install an IdM client
You can generate a one-time password (OTP) for a new host in Identity Management (IdM) and use it to enroll a system into the IdM domain. This procedure describes how to use Ansible to install an IdM client after generating an OTP for it on another IdM host.
This method of installing an IdM client is convenient if two system administrators with different privileges exist in your organisation:
- One that has the credentials of an IdM administrator.
-
Another that has the required Ansible credentials, including
root
access to the host to become an IdM client.
The IdM administrator performs the first part of the procedure in which the OTP password is generated. The Ansible administrator performs the remaining part of the procedure in which the OTP is used to install an IdM client.
Prerequisites
-
You have the IdM
admin
credentials or at least theHost Enrollment
privilege and a permission to add DNS records in IdM. - You have configured a user escalation method on the Ansible managed node to allow you to install an IdM client.
- If your Ansible control node is running on RHEL 8.7 or earlier, you must be able to install packages on your Ansible control node.
You have configured your Ansible control node to meet the following requirements:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package on the Ansible controller. - You have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
- The managed node is a Red Hat Enterprise Linux 8 system with a static IP address and a working package manager.
Procedure
SSH
to an IdM host as an IdM user with a role that has theHost Enrollment
privilege and a permission to add DNS records:$ ssh admin@server.idm.example.com
Generate an OTP for the new client:
[admin@server ~]$ ipa host-add client.idm.example.com --ip-address=172.25.250.11 --random -------------------------------------------------- Added host "client.idm.example.com" -------------------------------------------------- Host name: client.idm.example.com Random password: W5YpARl=7M.n Password: True Keytab: False Managed by: server.idm.example.com
The --ip-address=<your_host_ip_address> option adds the host to IdM DNS with the specified IP address.
Exit the IdM host:
$ exit logout Connection to server.idm.example.com closed.
On the ansible controller, update the inventory file to include the random password:
[...] [ipaclients] client.idm.example.com [ipaclients:vars] ipaclient_domain=idm.example.com ipaclient_otp=W5YpARl=7M.n [...]
If your ansible controller is running RHEL 8.7 or earlier, install the
kinit
utility provided by thekrb5-workstation
package:$ sudo dnf install krb5-workstation
Run the playbook to install the client:
$ ansible-playbook -i inventory install-client.yml
4.6. Testing an Identity Management client after Ansible installation
The command-line interface (CLI) informs you that the ansible-playbook
command was successful, but you can also do your own test.
To test that the Identity Management client can obtain information about users defined on the server, check that you are able to resolve a user defined on the server. For example, to check the default admin
user:
[user@client1 ~]$ id admin
uid=1254400000(admin) gid=1254400000(admins) groups=1254400000(admins)
To test that authentication works correctly, su -
as another already existing IdM user:
[user@client1 ~]$ su - idm_user
Last login: Thu Oct 18 18:39:11 CEST 2018 from 192.168.122.1 on pts/0
[idm_user@client1 ~]$
4.7. Uninstalling an IdM client using an Ansible playbook
Complete this procedure to use an Ansible playbook to uninstall your host as an IdM client.
Prerequisites
- IdM administrator credentials.
- The managed node is a Red Hat Enterprise Linux 8 system with a static IP address.
Procedure
Run the Ansible playbook with the instructions to uninstall the client, for example
uninstall-client.yml
:$ ansible-playbook -v -i ~/MyPlaybooks/inventory ~/MyPlaybooks/uninstall-client.yml
The uninstallation of the client only removes the basic IdM configuration from the host but leaves the configuration files on the host in case you decide to re-install the client. In addition, the uninstallation has the following limitations:
- It does not remove the client host entry from the IdM LDAP server. The uninstallation only unenrolls the host.
- It does not remove any services residing on the client from IdM.
- It does not remove the DNS entries for the client from the IdM server.
-
It does not remove the old principals for keytabs other than
/etc/krb5.keytab
.
Note that the uninstallation does remove all certificates that were issued for the host by the IdM CA.
Additional resources