Chapter 27. Installing an Identity Management client using an Ansible playbook

Procedure

1. Open your inventory file for editing.

2. 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
   [...]

3. 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 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

       [...]
       [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 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.

4. [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:

   [...]
   [ipaclients:vars]
   ipaadmin_password: "{{ ipaadmin_password }}"
   ipaclient_domain=idm.example.com
   ipaclient_configure_dns_resolver=true
   ipaclient_dns_servers=192.168.100.1

   Note

   The ipaclient_dns_servers list must contain only IP addresses. Host names are not allowed.

5. Starting with RHEL 9.3, you can also specify the ipaclient_subid: true option to have subid ranges configured for IdM users on the IdM level.

Procedure

1. 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.

2. 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

       [ipaclients]
       client.idm.example.com
       
       [ipaservers]
       server.idm.example.com
       
       [ipaclients:vars]
       ipaclient_domain=idm.example.com
       [...]

3. 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 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

     [...]
     [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 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.
4. Starting with RHEL 9.3, you can also specify the ipaclient_subid: true option to have subid ranges configured for IdM users on the IdM level.

Procedure

1. 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:

   $ ssh admin@server.idm.example.com

2. 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.

3. Exit the IdM host:

   $ exit
   logout
   Connection to server.idm.example.com closed.

4. 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
   [...]

5. If your ansible controller is running RHEL ⇐ 9.1, install the kinit utility provided by the krb5-workstation package:

   $ sudo dnf install krb5-workstation

6. Run the playbook to install the client:

   $ ansible-playbook -i inventory install-client.yml