Chapter 33. 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.14 or later.
  • You understand the general Ansible and IdM concepts.

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

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

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

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

33.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 previous 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 33.1. Sample inventory files
Authorization optionInventory file

A random, one-time password (OTP) + administrator password

[ipaclients:vars]
ipaadmin_password=Secret123
ipaclient_use_otp=true

A random, one-time password (OTP)

[ipaclients:vars]
ipaclient_otp=<W5YpARl=7M.>

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

[ipaclients:vars]
ipaadmin_keytab=/root/admin.keytab
ipaclient_use_otp=true

The client keytab from the previous enrollment

[ipaclients:vars]
ipaclient_keytab=/root/krb5.keytab

Password of an admin user stored in an inventory file

[ipaclients:vars]
ipaadmin_password=Secret123

Password of an admin user stored in an Ansible vault file

[ipaclients:vars]
[...]

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 33.2. User password stored in an Ansible vault
Inventory filePlaybook file
[ipaclients:vars]
[...]
- name: Playbook to configure IPA clients
  hosts: ipaclients
  become: true
  vars_files:
  - ansible_vault_file.yml

  roles:
  - role: ipaclient
    state: present

In all the other authorization scenarios described above, a basic playbook file could look as follows:

- name: Playbook to configure IPA clients
  hosts: ipaclients
  become: true

  roles:
  - role: ipaclient
    state: true
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.

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

Procedure

  • Run the Ansible playbook:

    $ ansible-playbook -v -i ~/MyPlaybooks/inventory ~/MyPlaybooks/install-client.yml

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

  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 8.7 or earlier, 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

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

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

    $ ansible-playbook -v -i ~/MyPlaybooks/inventory ~/MyPlaybooks/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

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.