Red Hat Training

A Red Hat training course is available for RHEL 8

Chapter 22. Installing an Identity Management server using an Ansible playbook

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

22.2. IdM server installation using an Ansible playbook

The following sections describe how to configure a system as an IdM server by using Ansible. Configuring a system as an IdM server establishes an IdM domain and enables the system to offer IdM services to IdM clients. The deployment is managed by the ipaserver Ansible role.

Note

Before installing an IdM server 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. Deploying an IdM server with an integrated CA using an Ansible playbook
  3. Deploying an IdM server with an external CA using an Ansible-playbook

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

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

22.5. Deploying an IdM server with an integrated CA as the root CA using an Ansible playbook

Before running the ansible-playbook utility, set the parameters that correspond to your scenario by choosing one of the following procedures:

22.5.1. Setting the parameters for a deployment with an integrated DNS and an integrated CA as the root CA

Complete this procedure to configure the inventory file for installing an IdM server with an integrated CA as the root CA in an environment that uses the IdM integrated DNS solution.

Procedure

  1. Open the inventory file for editing. Specify the fully-qualified domain names (FQDN) of the host you want to use as an IdM server. Ensure that the FQDN meets the following criteria:

    • Only alphanumeric characters and hyphens (-) are allowed. For example, underscores are not allowed and can cause DNS failures.
    • The host name must be all lower-case.
  2. Specify the IdM domain and realm information.

  3. Specify that you want to use integrated DNS by adding the following option: 

    ipaserver_setup_dns=yes

  4. Specify the DNS forwarding settings. Choose one of the following options:

    • Use the ipaserver_auto_forwarders=yes option if you want the installer to use forwarders from the /etc/resolv.conf file. This option is not recommended if the nameserver specified in the `/etc/resolv.conf file is the localhost 127.0.0.1 address or if you are on a virtual private network and the DNS servers you are using are normally unreachable from the public internet.
    • Use the ipaserver_forwarders option to specify your forwarders manually. The installation process adds the forwarder IP addresses to the /etc/named.conf file on the installed IdM server.

    • Use the ipaserver_no_forwarders=yes option to configure root DNS servers to be used instead.

      NOTE
      With no DNS forwarders, your environment will be isolated, and names from other DNS domains in your infrastructure will not be resolved.

  5. Specify the DNS reverse record and zone settings. Choose from the following options:

    • Use the ipaserver_allow_zone_overlap=yes option to allow the creation of a (reverse) zone even if the zone is already resolvable.
    • Use the ipaserver_reverse_zones option to specify your reverse zones manually.

    • Use the ipaserver_no_reverse=yes option if you do not want the installer to create reverse a DNS zone.

      NOTE
      Using IdM to manage reverse zones is optional. You can use an external DNS service for this purpose instead.
  6. Specify the passwords for admin and for the Directory Manager. Use the Ansible Vault to store the password, and reference the Vault file from the playbook file. Alternatively and less securely, specify the passwords directly in the inventory file.

  7. (Optional) Specify a custom firewalld zone to be used by the IdM server. If you do not set a custom zone, IdM will add its services to the default firewalld zone. The predefined default zone is public.

    Important

    The specified firewalld zone must exist and be permanent.

    Example of an inventory file with the required server information (excluding the passwords)

    [ipaserver]
server.idm.example.com

[ipaserver:vars]
ipaserver_domain=idm.example.com
ipaserver_realm=IDM.EXAMPLE.COM
ipaserver_setup_dns=yes
ipaserver_auto_forwarders=yes
[...]

    Example of an inventory file with the required server information (including the passwords)

    [ipaserver]
server.idm.example.com

[ipaserver:vars]
ipaserver_domain=idm.example.com
ipaserver_realm=IDM.EXAMPLE.COM
ipaserver_setup_dns=yes
ipaserver_auto_forwarders=yes
ipaadmin_password=MySecretPassword123
ipadm_password=MySecretPassword234

[...]

    Example of an inventory file with a custom firewalld zone

    [ipaserver]
server.idm.example.com

[ipaserver:vars]
ipaserver_domain=idm.example.com
ipaserver_realm=IDM.EXAMPLE.COM
ipaserver_setup_dns=yes
ipaserver_auto_forwarders=yes
ipaadmin_password=MySecretPassword123
ipadm_password=MySecretPassword234
ipaserver_firewalld_zone=custom zone

    Example playbook to set up an IdM server using admin and Directory Manager passwords stored in an Ansible Vault file

    ---
- name: Playbook to configure IPA server
  hosts: ipaserver
  become: true
  vars_files:
  - playbook_sensitive_data.yml

  roles:
  - role: ipaserver
    state: present

    Example playbook to set up an IdM server using admin and Directory Manager passwords from an inventory file

    ---
- name: Playbook to configure IPA server
  hosts: ipaserver
  become: true

  roles:
  - role: ipaserver
    state: present

Additional resources

  • For the forwarding policy default settings, see the --forward-policy description in the ipa-dns-install(1) man page.
  • For more information about DNS variables used by the ipaserver role, see the DNS Variables section in the README-server.md file in the /usr/share/doc/ansible-freeipa directory.

22.5.2. Setting the parameters for a deployment with external DNS and an integrated CA as the root CA

Complete this procedure to configure the inventory file for installing an IdM server with an integrated CA as the root CA in an environment that uses an external DNS solution.

Procedure

  1. Open the inventory file for editing. Specify the fully-qualified domain names (FQDN) of the host you want to use as an IdM server. Ensure that the FQDN meets the following criteria:

    • Only alphanumeric characters and hyphens (-) are allowed. For example, underscores are not allowed and can cause DNS failures.
    • The host name must be all lower-case.
  2. Specify the IdM domain and realm information.
  3. Make sure that the ipaserver_setup_dns option is set to no or that it is absent.
  4. Specify the passwords for admin and for the Directory Manager. Use the Ansible Vault to store the password, and reference the Vault file from the playbook file. Alternatively and less securely, specify the passwords directly in the inventory file.

  5. (Optional) Specify a custom firewalld zone to be used by the IdM server. If you do not set a custom zone, IdM will add its services to the default firewalld zone. The predefined default zone is public.

    Important

    The specified firewalld zone must exist and be permanent.

    Example of an inventory file with the required server information (excluding the passwords)

    [ipaserver]
server.idm.example.com

[ipaserver:vars]
ipaserver_domain=idm.example.com
ipaserver_realm=IDM.EXAMPLE.COM
ipaserver_setup_dns=no
[...]

    Example of an inventory file with the required server information (including the passwords)

    [ipaserver]
server.idm.example.com

[ipaserver:vars]
ipaserver_domain=idm.example.com
ipaserver_realm=IDM.EXAMPLE.COM
ipaserver_setup_dns=no
ipaadmin_password=MySecretPassword123
ipadm_password=MySecretPassword234

[...]

    Example of an inventory file with a custom firewalld zone

    [ipaserver]
server.idm.example.com

[ipaserver:vars]
ipaserver_domain=idm.example.com
ipaserver_realm=IDM.EXAMPLE.COM
ipaserver_setup_dns=no
ipaadmin_password=MySecretPassword123
ipadm_password=MySecretPassword234
ipaserver_firewalld_zone=custom zone

    Example playbook to set up an IdM server using admin and Directory Manager passwords stored in an Ansible Vault file

    ---
- name: Playbook to configure IPA server
  hosts: ipaserver
  become: true
  vars_files:
  - playbook_sensitive_data.yml

  roles:
  - role: ipaserver
    state: present

    Example playbook to set up an IdM server using admin and Directory Manager passwords from an inventory file

    ---
- name: Playbook to configure IPA server
  hosts: ipaserver
  become: true

  roles:
  - role: ipaserver
    state: present

22.5.3. Deploying an IdM server with an integrated CA as the root CA using an Ansible playbook

Complete this procedure to deploy an IdM server with an integrated certificate authority (CA) as the root CA using an Ansible playbook.

Procedure

  1. Run the ansible-playbook command with the name of the playbook file, for example install-server.yml. Specify the inventory file with the -i option: 

    $ ansible-playbook -v -i <path_to_inventory_directory>/hosts <path_to_playbooks_directory>/install-server.yml

    Specify the level of verbosity by using the -v, -vv, or -vvv option.

    You can view the output of the Ansible playbook script on the command-line interface (CLI). The following output shows that the script has run successfully as 0 tasks have failed: 

    PLAY RECAP
server.idm.example.com : ok=18   changed=10   unreachable=0    failed=0    skipped=21   rescued=0    ignored=0

  2. Choose one of the following options:

    • If your IdM deployment uses external DNS: add the DNS resource records contained in the /tmp/ipa.system.records.UFRPto.db file to the existing external DNS servers. The process of updating the DNS records varies depending on the particular DNS solution. 

      ...
Restarting the KDC
Please add records in this file to your DNS system: /tmp/ipa.system.records.UFRBto.db
Restarting the web server
...
    Important

    The server installation is not complete until you add the DNS records to the existing DNS servers.

    • If your IdM deployment uses integrated DNS:

      • Add DNS delegation from the parent domain to the IdM DNS domain. For example, if the IdM DNS domain is idm.example.com, add a name server (NS) record to the example.com parent domain.

        Important

        Repeat this step each time after an IdM DNS server is installed.

      • Add an _ntp._udp service (SRV) record for your time server to your IdM DNS. The presence of the SRV record for the time server of the newly-installed IdM server in IdM DNS ensures that future replica and client installations are automatically configured to synchronize with the time server used by this primary IdM server.

22.6. Deploying an IdM server with an external CA as the root CA using an Ansible playbook

Before running the ansible-playbook utility, set the parameters that correspond to your scenario by choosing one of the following procedures:

22.6.1. Setting the parameters for a deployment with an integrated DNS and an external CA as the root CA

Complete this procedure to configure the inventory file for installing an IdM server with an external CA as the root CA in an environment that uses the IdM integrated DNS solution.

Procedure

  1. Open the inventory file for editing. Specify the fully-qualified domain names (FQDN) of the host you want to use as an IdM server. Ensure that the FQDN meets the following criteria:

    • Only alphanumeric characters and hyphens (-) are allowed. For example, underscores are not allowed and can cause DNS failures.
    • The host name must be all lower-case.
  2. Specify the IdM domain and realm information.

  3. Specify that you want to use integrated DNS by adding the following option: 

    ipaserver_setup_dns=yes

  4. Specify the DNS forwarding settings. Choose one of the following options:

    • Use the ipaserver_auto_forwarders=yes option if you want the installation process to use forwarders from the /etc/resolv.conf file. This option is not recommended if the nameserver specified in the /etc/resolv.conf file is the localhost 127.0.0.1 address or if you are on a virtual private network and the DNS servers you are using are normally unreachable from the public internet.
    • Use the ipaserver_forwarders option to specify your forwarders manually. The installation process adds the forwarder IP addresses to the /etc/named.conf file on the installed IdM server.

    • Use the ipaserver_no_forwarders=yes option to configure root DNS servers to be used instead.

      NOTE
      With no DNS forwarders, your environment will be isolated, and names from other DNS domains in your infrastructure will not be resolved.

  5. Specify the DNS reverse record and zone settings. Choose from the following options:

    • Use the ipaserver_allow_zone_overlap=yes option to allow the creation of a (reverse) zone even if the zone is already resolvable.
    • Use the ipaserver_reverse_zones option to specify your reverse zones manually.

    • Use the ipaserver_no_reverse=yes option if you do not want the installation process to create reverse a DNS zone.

      NOTE
      Using IdM to manage reverse zones is optional. You can use an external DNS service for this purpose instead.
  6. Specify the passwords for admin and for the Directory Manager. Use the Ansible Vault to store the password, and reference the Vault file from the playbook file. Alternatively and less securely, specify the passwords directly in the inventory file.

  7. (Optional) Specify a custom firewalld zone to be used by the IdM server. If you do not set a custom zone, IdM will add its services to the default firewalld zone. The predefined default zone is public.

    Important

    The specified firewalld zone must exist and be permanent.

    Example of an inventory file with the required server information (excluding the passwords)

    [ipaserver]
server.idm.example.com

[ipaserver:vars]
ipaserver_domain=idm.example.com
ipaserver_realm=IDM.EXAMPLE.COM
ipaserver_setup_dns=yes
ipaserver_auto_forwarders=yes
[...]

    Example of an inventory file with the required server information (including the passwords)

    [ipaserver]
server.idm.example.com

[ipaserver:vars]
ipaserver_domain=idm.example.com
ipaserver_realm=IDM.EXAMPLE.COM
ipaserver_setup_dns=yes
ipaserver_auto_forwarders=yes
ipaadmin_password=MySecretPassword123
ipadm_password=MySecretPassword234

[...]

    Example of an inventory file with a custom firewalld zone

    [ipaserver]
server.idm.example.com

[ipaserver:vars]
ipaserver_domain=idm.example.com
ipaserver_realm=IDM.EXAMPLE.COM
ipaserver_setup_dns=yes
ipaserver_auto_forwarders=yes
ipaadmin_password=MySecretPassword123
ipadm_password=MySecretPassword234
ipaserver_firewalld_zone=custom zone

[...]

  8. Create a playbook for the first step of the installation. Enter instructions for generating the certificate signing request (CSR) and copying it from the controller to the managed node. 

    ---
- name: Playbook to configure IPA server Step 1
  hosts: ipaserver
  become: true
  vars_files:
  - playbook_sensitive_data.yml
  vars:
    ipaserver_external_ca: yes

  roles:
  - role: ipaserver
    state: present

  post_tasks:
  - name: Copy CSR /root/ipa.csr from node to "{{ groups.ipaserver[0] + '-ipa.csr' }}"
    fetch:
      src: /root/ipa.csr
      dest: "{{ groups.ipaserver[0] + '-ipa.csr' }}"
      flat: yes

  9. Create another playbook for the final step of the installation. 

    ---
- name: Playbook to configure IPA server Step -1
  hosts: ipaserver
  become: true
  vars_files:
  - playbook_sensitive_data.yml
  vars:
    ipaserver_external_cert_files: "/root/chain.crt"

  pre_tasks:
  - name: Copy "{{ groups.ipaserver[0] + '-chain.crt' }}" to /root/chain.crt on node
    copy:
      src: "{{ groups.ipaserver[0] + '-chain.crt' }}"
      dest: "/root/chain.crt"
      force: yes

  roles:
  - role: ipaserver
    state: present

Additional resources

  • For the forwarding policy default settings, see the --forward-policy description in the ipa-dns-install(1) man page.
  • For more information about DNS variables used by the ipaserver role, see the DNS Variables section in the README-server.md file in the /usr/share/doc/ansible-freeipa directory.

22.6.2. Setting the parameters for a deployment with external DNS and an external CA as the root CA

Complete this procedure to configure the inventory file for installing an IdM server with an external CA as the root CA in an environment that uses an external DNS solution.

Procedure

  1. Open the inventory file for editing. Specify the fully-qualified domain names (FQDN) of the host you want to use as an IdM server. Ensure that the FQDN meets the following criteria:

    • Only alphanumeric characters and hyphens (-) are allowed. For example, underscores are not allowed and can cause DNS failures.
    • The host name must be all lower-case.
  2. Specify the IdM domain and realm information.
  3. Make sure that the ipaserver_setup_dns option is set to no or that it is absent.
  4. Specify the passwords for admin and for the Directory Manager. Use the Ansible Vault to store the password, and reference the Vault file from the playbook file. Alternatively and less securely, specify the passwords directly in the inventory file.

  5. (Optional) Specify a custom firewalld zone to be used by the IdM server. If you do not set a custom zone, IdM will add its services to the default firewalld zone. The predefined default zone is public.

    Important

    The specified firewalld zone must exist and be permanent.

    Example of an inventory file with the required server information (excluding the passwords)

    [ipaserver]
server.idm.example.com

[ipaserver:vars]
ipaserver_domain=idm.example.com
ipaserver_realm=IDM.EXAMPLE.COM
ipaserver_setup_dns=no
[...]

    Example of an inventory file with the required server information (including the passwords)

    [ipaserver]
server.idm.example.com

[ipaserver:vars]
ipaserver_domain=idm.example.com
ipaserver_realm=IDM.EXAMPLE.COM
ipaserver_setup_dns=no
ipaadmin_password=MySecretPassword123
ipadm_password=MySecretPassword234

[...]

    Example of an inventory file with a custom firewalld zone

    [ipaserver]
server.idm.example.com

[ipaserver:vars]
ipaserver_domain=idm.example.com
ipaserver_realm=IDM.EXAMPLE.COM
ipaserver_setup_dns=no
ipaadmin_password=MySecretPassword123
ipadm_password=MySecretPassword234
ipaserver_firewalld_zone=custom zone

[...]

  6. Create a playbook for the first step of the installation. Enter instructions for generating the certificate signing request (CSR) and copying it from the controller to the managed node. 

    ---
- name: Playbook to configure IPA server Step 1
  hosts: ipaserver
  become: true
  vars_files:
  - playbook_sensitive_data.yml
  vars:
    ipaserver_external_ca: yes

  roles:
  - role: ipaserver
    state: present

  post_tasks:
  - name: Copy CSR /root/ipa.csr from node to "{{ groups.ipaserver[0] + '-ipa.csr' }}"
    fetch:
      src: /root/ipa.csr
      dest: "{{ groups.ipaserver[0] + '-ipa.csr' }}"
      flat: yes

  7. Create another playbook for the final step of the installation. 

    ---
- name: Playbook to configure IPA server Step -1
  hosts: ipaserver
  become: true
  vars_files:
  - playbook_sensitive_data.yml
  vars:
    ipaserver_external_cert_files: "/root/chain.crt"

  pre_tasks:
  - name: Copy "{{ groups.ipaserver[0] + '-chain.crt' }}" to /root/chain.crt on node
    copy:
      src: "{{ groups.ipaserver[0] + '-chain.crt' }}"
      dest: "/root/chain.crt"
      force: yes

  roles:
  - role: ipaserver
    state: present

Additional resources

22.6.3. Deploying an IdM server with an external CA as the root CA using an Ansible playbook

Complete this procedure to deploy an IdM server with an external certificate authority (CA) as the root CA using an Ansible playbook.

Procedure

  1. Run the ansible-playbook command with the name of the playbook file that contains instructions for the first step of the installation, for example install-server-step1.yml. Specify the inventory file with the -i option: 

    $ ansible-playbook -v -i <path_to_inventory_directory>/host.server <path_to_playbooks_directory>/install-server-step1.yml

    Specify the level of verbosity by using the -v, -vv or -vvv option.

    You can view the output of the Ansible playbook script on the command-line interface (CLI). The following output shows that the script has run successfully as 0 tasks have failed: 

    PLAY RECAP
server.idm.example.com : ok=18   changed=10   unreachable=0    failed=0    skipped=21   rescued=0    ignored=0
  2. Locate the ipa.csr certificate signing request file on the controller and submit it to the external CA.
  3. Place the IdM CA certificate signed by the external CA in the controller file system so that the playbook in the next step can find it.

  4. Run the ansible-playbook command with the name of the playbook file that contains instructions for the final step of the installation, for example install-server-step2.yml. Specify the inventory file with the -i option: 

    $ ansible-playbook -v -i <path_to_inventory_directory>/host.server <path_to_playbooks_directory>/install-server-step2.yml

  5. Choose one of the following options:

    • If your IdM deployment uses external DNS: add the DNS resource records contained in the /tmp/ipa.system.records.UFRPto.db file to the existing external DNS servers. The process of updating the DNS records varies depending on the particular DNS solution. 

      ...
Restarting the KDC
Please add records in this file to your DNS system: /tmp/ipa.system.records.UFRBto.db
Restarting the web server
...
    Important

    The server installation is not complete until you add the DNS records to the existing DNS servers.

    • If your IdM deployment uses integrated DNS:

      • Add DNS delegation from the parent domain to the IdM DNS domain. For example, if the IdM DNS domain is idm.example.com, add a name server (NS) record to the example.com parent domain.

        Important

        Repeat this step each time after an IdM DNS server is installed.

      • Add an _ntp._udp service (SRV) record for your time server to your IdM DNS. The presence of the SRV record for the time server of the newly-installed IdM server in IdM DNS ensures that future replica and client installations are automatically configured to synchronize with the time server used by this primary IdM server.

Additional resources