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

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

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

Note

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:

  1. Installing the ansible-freeipa package;

  2. Setting the parameters of the IdM client deployment to correspond to your deployment scenario:

  3. Checking the parameters in install-client.yml;
  4. Deploying an IdM client using an Ansible playbook;
  5. Testing an Identity Management client after installation.

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

  1. Enable the required repository: 

    # subscription-manager repos --enable ansible-2.8-for-rhel-8-x86_64-rpms

  2. Install Ansible: 

    # yum install ansible

  3. Install the IdM Ansible roles: 

    # yum install ansible-freeipa

    The roles are installed to the /usr/share/ansible/roles/ directory.

20.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 the ipaserver, ipareplica, and ipaclient 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 the playbooks/ 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

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

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

  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.

Additional resources

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

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

  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, 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 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 README file.

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

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

20.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 example install-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
    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.

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