Chapter 24. Installing an Identity Management client using an Ansible playbook
24.1. Ansible and its advantages for installing IdM
Ansible is an automation tool used to configure systems, deploy software, and perform rolling updates. Ansible includes support for Identity Management (IdM), and you can use Ansible modules to automate installation tasks such as the setup of an IdM server, replica, client, or an entire IdM topology.
Advantages of using Ansible to install IdM
The following list presents advantages of installing Identity Management using Ansible in contrast to manual installation.
- You do not need to log into the managed node.
- You do not need to configure settings on each host to be deployed individually. Instead, you can have one inventory file to deploy a complete cluster.
- You can reuse an inventory file later for management tasks, for example to add users and hosts. You can reuse an inventory file even for such tasks as are not related to IdM.
24.2. IdM client installation using an Ansible playbook
The following sections describe 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.
Before installing an IdM client using Ansible, ensure that you understand Ansible and IdM concepts. Ensure that you understand the following terms that are used in this chapter:
- Ansible roles
- Ansible nodes
- Ansible inventory
- Ansible tasks
- Ansible modules
- Ansible plays and playbooks
Overview
The installation consists of the following parts:
- Installing the ansible-freeipa package;
Setting the parameters of the IdM client deployment to correspond to your deployment scenario:
- Setting the parameters of the inventory file for the autodiscovery client installation mode;
- Setting the parameters of the inventory file for when autodiscovery is not possible during client installation;
- Checking the parameters in install-client.yml;
- Deploying an IdM client using an Ansible playbook;
- Testing an Identity Management client after installation.
The chapter also includes a section describing how to uninstall an IdM client.
24.3. Installing the ansible-freeipa package
Prerequisites
On the managed node:
- Ensure that the managed node is a Red Hat Enterprise Linux 8 system with a static IP address and a working package manager.
On the controller:
- Ensure that the controller is a Red Hat Enterprise Linux system with a valid subscription. If this is not the case, see the official Ansible documentation Installation guide for alternative installation instructions.
-
Ensure that you can reach the managed node over the
SSH
protocol from the controller. Check that the managed node is listed in the/root/.ssh/known_hosts
file of the controller.
Procedure
Run the following procedure on the Ansible controller.
Enable the required repository:
# subscription-manager repos --enable ansible-2.8-for-rhel-8-x86_64-rpms
Install Ansible:
# yum install ansible
Install the IdM Ansible roles:
# yum install ansible-freeipa
The roles are installed to the
/usr/share/ansible/roles/
directory.
24.4. Ansible roles location in the file system
By default the ansible-freeipa
roles are installed to the /usr/share/ansible/roles/
directory. The structure of the ansible-freeipa
package is as follows:
The
/usr/share/ansible/roles/
directory stores theipaserver
,ipareplica
, andipaclient
roles on the Ansible controller. Each role directory stores examples, a basic overview, the licence and documentation about the role in a README.md Markdown file.[root@server]# ls -1 /usr/share/ansible/roles/ ipaclient ipareplica ipaserver
The
/usr/share/doc/ansible-freeipa/
directory stores the documentation about individual roles and the topology in README.md Markdown files. It also stores theplaybooks/
subdirectory (see below).[root@server]# ls -1 /usr/share/doc/ansible-freeipa/ playbooks README-client.md README.md README-replica.md README-server.md README-topology.md
The
/usr/share/doc/ansible-freeipa/playbooks/
directory stores the example playbooks:[root@server]# ls -1 /usr/share/doc/ansible-freeipa/playbooks/ install-client.yml install-cluster.yml install-replica.yml install-server.yml uninstall-client.yml uninstall-cluster.yml uninstall-replica.yml uninstall-server.yml
24.5. Setting the parameters of the IdM client deployment
Before you deploy a target host as an IdM client, configure the deployment instructions on the control node. Additionally, configure the target host parameters depending on which of the following options you are planning:
24.5.1. Setting the parameters of the inventory file for the autodiscovery client installation mode
To install an Identity Management client using an Ansible playbook, provide the following information in an inventory file, for example inventory/hosts
:
- 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.
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.
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 [...]
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: presentLess 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
.
-
This option is available if the system was previously enrolled as an Identity Management client. To use this authentication method, uncomment the
A random, one-time password (OTP) to be generated during the enrollment. To use this authentication method, use the
ipaclient_use_otp=yes
option in your inventory file. For example, you can uncomment theipaclient_use_otp=yes
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
Additional resources
-
For details on the options accepted by the
ipaclient
Ansible role, see the/usr/share/ansible/roles/ipaclient/README.md
README file.
24.5.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, provide the following information 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.
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.
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
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: presentLess 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. 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
.
-
This option is available if the system was previously enrolled as an Identity Management client. To use this authentication method, uncomment the
A random, one-time password (OTP) to be generated during the enrollment. To use this authentication method, use the
ipaclient_use_otp=yes
option in your inventory file. For example, you can uncomment the#ipaclient_use_otp=yes
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
Additional resources
-
For details on the options accepted by the
ipaclient
Ansible role, see the/usr/share/ansible/roles/ipaclient/README.md
README file.
24.5.3. Checking the parameters in the install-client.yml file
The install-client.yml
playbook file contains instructions for the IdM client deployment.
Open the file and check if the instructions in the playbook correspond to what you are planning for your deployment. The contents typically look like this:
--- - name: Playbook to configure IPA clients with username/password hosts: ipaclients become: true roles: - role: ipaclient state: present
This is what the individual entries mean:
-
The hosts entry specifies the section of the
inventory/hosts
file where the ansible script searches theFQDNs
of the hosts on which theipa-client-install
script shall be run. -
The
become: true
entry specifies that root’s credentials will be invoked during the execution of theipa-client-install
script. -
The
role: ipaclient
entry specifies the role that will be installed on the host: in this case, it is the ipa client role. -
The
state: present
entry specifies that the client should be installed rather than uninstalled (absent
).
-
The hosts entry specifies the section of the
24.5.4. Authorization options for IdM client enrollment using an Ansible playbook
This referential section presents individual authorization options for IdM client enrollment with examples of inventory and playbook files.
Table 24.1. Authorization options for IdM client enrollment using Ansible
Authorization option | Note | Example inventory file | Example install-client.yml playbook file |
---|---|---|---|
Password of a user authorized to enroll a client: Option 1 | Password stored in Ansible vault |
[ipaclients:vars] [...] |
- name: Playbook to configure IPA clients with username/password hosts: ipaclients become: true vars_files: - playbook_sensitive_data.yml roles: - role: ipaclient state: present |
Password of a user authorized to enroll a client: Option 2 | Password stored in inventory file |
[ipaclients:vars] ipaadmin_password=Secret123 |
- name: Playbook to configure IPA clients hosts: ipaclients become: true roles: - role: ipaclient state: true |
A random, one-time password (OTP): Option 1 | OTP + administrator password |
[ipaclients:vars] ipaadmin_password=Secret123 ipaclient_use_otp=yes |
- name: Playbook to configure IPA clients hosts: ipaclients become: true roles: - role: ipaclient state: true |
A random, one-time password (OTP): Option 2 | OTP + an admin keytab |
[ipaclients:vars] ipaadmin_keytab=/tmp/admin.keytab ipaclient_use_otp=yes |
- name: Playbook to configure IPA clients hosts: ipaclients become: true roles: - role: ipaclient state: true |
The client keytab from the previous enrollment |
[ipaclients:vars] ipaclient_keytab=/tmp/krb5.keytab |
- name: Playbook to configure IPA clients hosts: ipaclients become: true roles: - role: ipaclient state: true |
24.6. 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.
Procedure
To install an IdM client using an Ansible playbook, use the
ansible-playbook
command with the name of the playbook file, for exampleinstall-client.yml
. Specify the inventory file with the-i
option:$ ansible-playbook -v -i inventory/hosts install-client.yml
Specify the level of verbosity by using the
-v
,-vv
or-vvv
option.Ansible informs you about the execution of the Ansible playbook script. The following output shows that the script has run successfully as no tasks have failed:
PLAY RECAP client1.idm.example.com : ok=18 changed=10 unreachable=0 failed=0 skipped=21 rescued=0 ignored=0
NoteAnsible uses different colors to provide different types of information about the running process. You can modify the default colors in the
[colors]
section of the/etc/ansible/ansible.cfg
file:[colors] [...] #error = red #debug = dark gray #deprecate = purple #skip = cyan #unreachable = red #ok = green #changed = yellow [...]
You have now installed an IdM client on your host using an Ansible playbook.
24.7. 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 ~]$
24.8. 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.
Procedure
To uninstall the IdM client, use the
ansible-playbook
command with the name of the playbook file, for exampleuninstall-client.yml
. Specify the inventory file with the-i
option and, optionally, specify the level of verbosity by using the-v
,-vv
or-vvv
options:$ ansible-playbook -v -i inventory/hosts 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
- For more information on how to remove the IdM client configuration from both the host and the IdM environment completely, see the manual procedure for Uninstalling an IdM client.