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.
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:
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.
Enable the required repository:
# subscription-manager repos --enable ansible-2.8-for-rhel-8-x86_64-rpms
Install Ansible:
# yum install ansible
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 theipaserver
,ipareplica
, andipaclient
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 theplaybooks/
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
22.5.1. Setting the parameters for a deployment with 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.
Procedure
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 theFQDN
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.
- Specify the IdM domain and realm information.
-
Specify if you want the IdM server to have an integrated DNS and if you want it to use forwarders from the
/etc/resolv.conf
file. Specify the passwords for
admin
and for theDirectory 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.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 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
For details on installing the IdM server and the available options, see Part I, “Installing Identity Management”.
22.5.2. 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
Run the
ansible-playbook
command with the name of the playbook file, for exampleinstall-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
You have installed an IdM server on your host using an Ansible playbook.
22.6. Deploying an IdM server with an external CA as the root CA using an Ansible playbook
22.6.1. Setting the parameters for a deployment with 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.
Procedure
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 theFQDN
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.
- Specify the IdM domain and realm information.
-
Specify if you want the IdM server to have an integrated DNS and if you want it to use forwarders from the
/etc/resolv.conf
file. Specify the passwords for
admin
and for theDirectory 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.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 [...]
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.
Figure 22.1. Example playbook to set up an IdM server with an externally signed CA using admin and Directory Manager passwords stored in an Ansible Vault file: First step
Create another playbook for the final step of the installation.
Figure 22.2. Example playbook to set up an IdM server with an externally signed CA using admin and Directory Manager passwords stored in an Ansible Vault file: Final step
For details on the options available to you when installing an IdM server with an externally signed CA, see Chapter 3, Installing an IdM server: With integrated DNS, with an external CA as the root CA.
22.6.2. 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
Run the
ansible-playbook
command with the name of the playbook file that contains instructions for the first step of the installation, for exampleinstall-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
-
Locate the
ipa.csr
certificate signing request file on the controller and submit it to the external CA. - 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.
Run the
ansible-playbook
command with the name of the playbook file that contains instructions for the final step of the installation, for exampleinstall-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
You have installed an IdM server with an externally signed CA on your host using an Ansible playbook.