Chapter 4. Installing an Identity Management client using an Ansible playbook
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.15 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. Note 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 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. Use the Ansible Vault to store the password, and reference 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 Less securely, provide the credentials of admin using the ipaadmin_password option in the [ipaclients:vars] section of the inventory/hosts file. Alternatively, to specify a different authorized user, use the ipaadmin_principal option for the user name, and the ipaadmin_password option for the password. The inventory/hosts inventory file and the install-client.yml playbook file can then look as follows: Example inventory hosts file Example Playbook using principal and password from inventory file The client keytab from the 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 of inventory/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 the inventory/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 the inventory/hosts file. The admin keytab , for example by providing a value for ipaadmin_keytab in the [ipaclients:vars] section of inventory/hosts . Optional: Specify the DNS resolver using the ipaclient_configure_dns_resolve and ipaclient_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: Note The 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. Note 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. 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 server Example of an inventory hosts file with the client FQDN, the server FQDN and the domain defined 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. Use the Ansible Vault to store the password, and reference 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 Less securely, the credentials of admin to be provided using the ipaadmin_password option in the [ipaclients:vars] section of the inventory/hosts file. Alternatively, to specify a different authorized user, use the ipaadmin_principal option for the user name, and the ipaadmin_password option for the password. The install-client.yml playbook file can then look as follows: Example inventory hosts file Example Playbook using principal and password from inventory file The client keytab from the 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 of inventory/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 the inventory/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 the inventory/hosts file. The admin keytab , for example by providing a value for ipaadmin_keytab in the [ipaclients:vars] section of inventory/hosts . 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 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: Table 4.1. Sample inventory files Authorization option Inventory file A random, one-time password (OTP) + administrator password A random, one-time password (OTP) This scenario assumes that the OTP was already generated by an IdM admin before the installation. A random, one-time password (OTP) + an admin keytab The client keytab from the enrollment Password of an admin user stored in an inventory file Password of an admin user stored in an Ansible vault file 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: Table 4.2. User password stored in an Ansible vault Inventory file Playbook file In all the other authorization scenarios described above, a basic playbook file could look as follows: Note 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: Setting the parameters of the inventory file for the autodiscovery client installation mode Setting the parameters of the inventory file when autodiscovery is not possible during client installation Procedure Run the Ansible playbook: 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 the Host 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.13 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 the Host Enrollment privilege and a permission to add DNS records: Generate an OTP for the new client: The --ip-address= <your_host_ip_address> option adds the host to IdM DNS with the specified IP address. Exit the IdM host: On the ansible controller, update the inventory file to include the random password: If your ansible controller is running RHEL 8.7 or earlier, install the kinit utility provided by the krb5-workstation package: Run the playbook to install the client: 4.6. Testing an Identity Management client after Ansible installation The command line (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: To test that authentication works correctly, su - as another already existing IdM user: 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 : Important 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 Uninstalling an IdM client
[ipaclients] client.idm.example.com [...] - name: Playbook to configure IPA clients with username/password hosts: ipaclients become: true vars_files: - playbook_sensitive_data.yml roles: - role: ipaclient state: present [...] [ipaclients:vars] ipaadmin_principal=my_admin ipaadmin_password=Secret123 - name: Playbook to unconfigure IPA clients hosts: ipaclients become: true roles: - role: ipaclient state: true [...] [ipaclients:vars] ipaadmin_password: "{{ ipaadmin_password }}" ipaclient_domain=idm.example.com ipaclient_configure_dns_resolver=true ipaclient_dns_servers=192.168.100.1 [ipaclients] client.idm.example.com [ipaservers] server.idm.example.com [ipaclients:vars] ipaclient_domain=idm.example.com [...] - name: Playbook to configure IPA clients with username/password hosts: ipaclients become: true vars_files: - playbook_sensitive_data.yml roles: - role: ipaclient state: present [...] [ipaclients:vars] ipaadmin_principal=my_admin ipaadmin_password=Secret123 - name: Playbook to unconfigure IPA clients hosts: ipaclients become: true roles: - role: ipaclient state: true [ipaclients:vars] ipaadmin_password=Secret123 ipaclient_use_otp=true [ipaclients:vars] ipaclient_otp=<W5YpARl=7M.> [ipaclients:vars] ipaadmin_keytab=/root/admin.keytab ipaclient_use_otp=true [ipaclients:vars] ipaclient_keytab=/root/krb5.keytab [ipaclients:vars] ipaadmin_password=Secret123 [ipaclients:vars] [...] [ipaclients:vars] [...] - name: Playbook to configure IPA clients hosts: ipaclients become: true vars_files: - ansible_vault_file.yml roles: - role: ipaclient state: present - name: Playbook to configure IPA clients hosts: ipaclients become: true roles: - role: ipaclient state: true ansible-playbook -v -i ~/MyPlaybooks/inventory ~/MyPlaybooks/install-client.yml ssh admin@server.idm.example.com [admin@server ~]USD 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 exit logout Connection to server.idm.example.com closed. [...] [ipaclients] client.idm.example.com [ipaclients:vars] ipaclient_domain=idm.example.com ipaclient_otp=W5YpARl=7M.n [...] sudo dnf install krb5-workstation ansible-playbook -i inventory install-client.yml [user@client1 ~]USD id admin uid=1254400000(admin) gid=1254400000(admins) groups=1254400000(admins) [user@client1 ~]USD su - idm_user Last login: Thu Oct 18 18:39:11 CEST 2018 from 192.168.122.1 on pts/0 [idm_user@client1 ~]USD ansible-playbook -v -i ~/MyPlaybooks/inventory ~/MyPlaybooks/uninstall-client.yml