Chapter 27. 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 understand Ansible and IdM concepts:

    • Ansible roles
    • Ansible nodes
    • Ansible inventory
    • Ansible tasks
    • Ansible modules
    • Ansible plays and playbooks

27.1. Setting the parameters of the inventory file for the autodiscovery client installation mode

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

Prerequisites

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.

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

  2. 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=yes option in your inventory file. For example, you can uncomment the ipaclient_use_otp=yes 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.

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

Additional resources

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

Prerequisites

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=yes option in your inventory file. For example, you can uncomment the #ipaclient_use_otp=yes 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.

Additional resources

  • For details on the options accepted by the ipaclient Ansible role, see the /usr/share/ansible/roles/ipaclient/README.md file.
  • Managing subID ranges manually

27.3. Checking the parameters in the install-client.yml file

The install-client.yml playbook file contains instructions for the IdM client deployment.

Procedure

  • 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 the FQDNs of the hosts on which the ipa-client-install script shall be run.
    • The become: true entry specifies that root’s credentials will be invoked during the execution of the ipa-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).

27.4. Authorization options for IdM client enrollment using an Ansible playbook

The individual authorization options for IdM client enrollment with examples of inventory and playbook files are as follows:

Table 27.1. Authorization options for IdM client enrollment using Ansible

Authorization optionNoteExample inventory fileExample 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=true
 
- 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=/root/admin.keytab
ipaclient_use_otp=true
 
- 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=/root/krb5.keytab
 
- name: Playbook to configure IPA clients
  hosts: ipaclients
  become: true

  roles:
  - role: ipaclient
    state: true
Note

As of RHEL 9.2, 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. Prior to RHEL 9.2, the krb5-workstation package was required on the control node.

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

Procedure

  • To install an IdM client using an Ansible playbook, use the ansible-playbook command with the name of the playbook file, for example install-client.yml. Specify the inventory file with the -i option: 

    $ ansible-playbook --vault-password-file=password_file -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
    Note

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

27.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 ~]$

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

Procedure

  • To uninstall the IdM client, use the ansible-playbook command with the name of the playbook file, for example uninstall-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 --vault-password-file=password_file -v -i inventory/hosts 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