Red Hat Security: Identity Management and Authentication
Prepare for installing servers, clients, and replicas in an IdM topology plan by using Ansible Playbooks.
Ansible is open source automation software that you can use to manage remote systems and control their desired state.
It can be used for configuration management, infrastructure provisioning, network automation, and many other tasks.
Ansible is provided in Red Hat Enterprise Linux 9 by the ansible package (ansible-core in RHEL 9.2 and later), or as part of the Red Hat Ansible Automation Platform product.
The ansible-freeipa RPM package provided by Red Hat Enterprise Linux contains an Ansible Content Collection named freeipa.ansible_freeipa, which provides Ansible content that you can use to automate IdM installation and configuration.
Red Hat recommends using this collection to install and manage IdM.
Ansible automates tasks defined in an Ansible Playbook, which is written in human-readable YAML syntax. An Ansible Role is a group of playbooks, variables, and conditions that perform a complex task. An Ansible Content Collection is a set of roles and modules that are used together to manage the lifecycle of an application.
Automation hub is a repository of Ansible Content Collections and documentation that are provided by Red Hat and certified Red Hat partners. Support is available for Red Hat Certified Ansible Content Collections published on this site. This means that if you have an issue with a certified collection provided by Red Hat or a partner on automation hub, Red Hat’s support team will help you with the issue directly. Alternatively, Ansible Galaxy is a community-maintained repository of roles and collections that can be downloaded by the public. Collections posted here are not maintained, tested, or checked for security issues by Red Hat.
Red Hat Enterprise Linux 9 provides a package, ansible-freeipa, that contains the freeipa.ansible_freeipa Ansible Content Collection.
Alternatively, the redhat.rhel_idm collection is a version of that collection that is provided under a different name through automation hub.
Ansible uses an inventory file to manage the list of hosts that it runs tasks against. You can use this inventory to group hosts and target the execution of playbooks to a specific group. For example, to install IdM, you must group the hosts by component type to distinguish the playbooks to run against each host.
The ansible-freeipa package is available from the Red Hat Enterprise Linux AppStream repository.
After you install the package, you can view playbook templates for IdM installation and administrative tasks in the /usr/share/doc/ansible-freeipa/playbooks/ directory.
In this directory you can also find documentation on playbook usage as well as examples.
[user@host ~]$sudo dnf install ansible-freeipa...output omitted... Complete! [user@host ~]$ls /usr/share/doc/ansible-freeipa/playbooks/...output omitted... hostgroup idrange install-client.yml install-cluster.yml install-replica.yml install-server.yml install-smartcard-clients.yml install-smartcard-replicas.yml install-smartcard-server.yml install-smartcard-servers.yml ...output omitted...
Note
In this section, you focus on the use of the IdM installation playbooks, such as install-server.yml and install-cluster.yml.
You can view the README.md file in each of the role directories to view the list of parameters to customize the component installation.
Similarly to the IdM interactive installation method, you can install an external CA, define DNS forwarders, and configure an AD trust.
The following output shows some variables used to install the IdM server.
[user@idm ~]$cat /usr/share/ansible/roles/ipaserver/README.md...output omitted... Variable | Description | Required -------- | ----------- | --------ipaserver| This group with the single IPA server full qualified hostname. | yesipadm_password| The password for the Directory Manager. | noipaadmin_password| The password for the IPA admin user. | noipaserver_domain| The primary DNS domain of an existing IPA deployment. | noipaserver_realm| The Kerberos realm of an existing IPA deployment. | no ...output omitted...ipaserver_setup_adtrust| Configure AD Trust capability. | noipaserver_setup_kra| Install and configure a KRA on this server. | noipaserver_setup_dns| Configure an integrated DNS server, create DNS zone specified by domain. | no ...output omitted...ipaserver_external_ca| Generate a CSR for the IPA CA certificate to be signed by an external CA. | noipaserver_external_ca_type| Type of the external CA. | no ...output omitted...ipaserver_reverse_zones| The reverse DNS zones to use. | noipaserver_no_reverse| Do not create reverse DNS zone. | noipaserver_forwarders| Add DNS forwarders to the DNS configuration. | noipaserver_no_forwarders| Do not add any DNS forwarders. Root DNS servers will be used instead. | no ...output omitted...
The variables to install server and replicas might differ.
Make sure to review the README.md file to define the correct variable for the topology component.
You can use the FreeIPA Ansible collection to install and manage an IdM topology.
The FreeIPA Ansible collection is available by installing the ansible-freeipa package included in Red Hat Enterprise Linux.
The installation procedure and the method that you choose to provide the variables for your IdM installation depend on many factors. Evaluate the infrastructure distribution, planned topology, and the organization needs to choose the appropriate playbooks and installation method.
Because of the large number of tasks and their complexity, some of these playbooks use Ansible roles for their execution.
For example, the install-server.yml playbook uses the ipaserver Ansible role in the /usr/share/ansible/roles/ directory.
This role can be used to install or uninstall an IdM server depending on the state defined in the playbook that calls the role.
[user@host ~]$ ls -l /usr/share/ansible/roles/
total 0
drwxr-xr-x. 7 root root 91 Apr 13 22:12 ipabackup
drwxr-xr-x. 9 root root 133 Apr 13 22:12 ipaclient
drwxr-xr-x. 8 root root 111 Apr 13 22:12 ipareplica
drwxr-xr-x. 8 root root 111 Apr 13 22:12 ipaserver
drwxr-xr-x. 8 root root 104 Apr 13 22:12 ipasmartcard_client
drwxr-xr-x. 8 root root 104 Apr 13 22:12 ipasmartcard_serverIn many scenarios, the playbook templates and roles might be inadequate to satisfy the requirements of your planned topology.
If you intend to modify these playbooks and roles, then you can copy them to a directory owned by your user to customize them.
This also avoids the need to become the root user to modify the playbooks.
[user@host ~]$cp -r /usr/share/ansible/roles/ipaserver/ ~/[user@host ~]$cp -r /usr/share/ansible/roles/ipaclient/ ~/[user@host ~]$cp -r /usr/share/ansible/roles/ipareplica/ ~/[user@host ~]$cp /usr/share/doc/ansible-freeipa/playbooks/install-cluster.yml ~/[user@host ~]$cp /usr/share/doc/ansible-freeipa/playbooks/install-server.yml ~/[user@host ~]$cp /usr/share/doc/ansible-freeipa/playbooks/install-replica.yml ~/[user@host ~]$cp /usr/share/doc/ansible-freeipa/playbooks/install-client.yml ~/[user@host ~]$sudo chown -R user:user ~/
You can use the install-server.yml, install-client.yml, and install-replica.yml playbooks to install IdM topology components separately.
This approach allows you to use separate playbooks to install replicas in different regions or to manage custom replication agreements.
You can also use the install-cluster.yml playbook to install all the topology components in one playbook execution.
This playbook might be useful when you install a large topology.
You can define these variables in the host inventory, by creating a variable file, or by providing them as command-line arguments to the ansible-playbook command.
The method you choose to provide the variables depends on your environment.
For example, some security policies might force you to use Ansible Vault to provide the admin user password and certificates.
Before you start the installation, ensure that the variables are complete and accurate.
In the following example, the variables are provided in the host inventory file, including the ipaadmin_password and ipadm_password variables, which might not be a suitable method for all environments.
Each IdM topology component has its own host group in the inventory and its own variables defined.
For the idmserver machine, the SSH port is 9327 instead of 22; you can define it in the inventory as well.
For all hosts in the ipaclients host group, you define the ansible_become_password to RedHat123 password.
[ipaserver] idmserver.lab.example.com ansible_port=9327 [ipaserver:vars] ipaserver_domain=lab.example.com ipaserver_realm=LAB.EXAMPLE.COM ipaserver_setup_dns=yes ipaserver_auto_forwarders=yes ipaadmin_password=RedHat123^ ipadm_password=RedHat123^ [ipaclients] client1.lab.example.com [ipaclients:vars] ipaclient_domain=lab.example.com ansible_become_password=RedHat123 [ipareplicas] replica1.lab.example.com [ipareplicas:vars] ipareplica_setup_ca=yes ipareplica_setup_dns=yes ipareplica_auto_forwarders=yes ipaadmin_principal=admin ipaadmin_password=RedHat123^
Although you can have the variables for all the topology components ready before you start the installation, you can define variables for one component and install it individually. This might be helpful if some information is not yet available or if you want to test the installation of a certain component.
IdM Server Installation
The following example shows the content of the install-server.yml playbook.
You should review the content of the playbook to ensure that the inventory has the correct targets for the installation.
[user@host ~]$cat install-server.yml--- - name: Playbook to configure IPA servers hosts: ipaserver become: true roles: - role: ipaserver state: present [user@host ~]$ansible-playbook -i hosts install-server.yml --list-hostsplaybook: install-server.yml play #1 (ipaserver): Playbook to configure IPA servers TAGS: [] pattern: ['ipaserver'] hosts (1): idmserver.lab.example.com
After you review the playbook, you can use the ansible-playbook command to start the installation.
The following example shows the installation of the IdM server using the install-server.yml playbook.
[user@host ~]$ansible-playbook -i hosts install-server.ymlPLAY [Playbook to configure IPA servers] ************************************* TASK [Gathering Facts] ******************************************************* ok: [idmserver.lab.example.com] ...output omitted... TASK [ipaserver : Install - Configure firewalld runtime] ********************* changed: [idmserver.lab.example.com] TASK [ipaserver : Cleanup temporary files] *********************************** ok: [idmserver.lab.example.com] => (item=/etc/ipa/.tmp_pkcs12_dirsrv) ok: [idmserver.lab.example.com] => (item=/etc/ipa/.tmp_pkcs12_http) ok: [idmserver.lab.example.com] => (item=/etc/ipa/.tmp_pkcs12_pkinit) TASK [ipaserver : Uninstall IPA server] ************************************** skipping: [idmserver.lab.example.com] PLAY RECAP *******************************************************************idmserver.lab.example.com : ok=39 changed=21 unreachable=0 failed=0 skipped=34 rescued=0 ignored=0
IdM Client Installation
The following example shows how to install a client by using a one-time password. To do so, you must update the inventory file to enable one-time password installation.
...output omitted...
[ipaclients]
client1.lab.example.com
[ipaclients:vars]
ipaclient_domain=lab.example.com
ansible_become_password=RedHat123
ipaclient_use_otp=yes
...output omitted...On the IdM server, add the corresponding DNS records and create the one-time password for the installation.
[user@idm ~]$ipa dnsrecord-addRecord name:client1Zone name:lab.example.comPlease choose a type of DNS resource record to be added The most common types for this type of zone are: A, AAAA DNS resource record type:AA IP Address:172.25.250.11Record name: client1 A record: 172.25.250.11 [user@idm ~]$ipa host-add client1.lab.example.com --random------------------------------------- Added host "client1.lab.example.com" ------------------------------------- Host name: client1.lab.example.com Random password:2Dc89iRcMBwq1hNHQOpdcKfPassword: True Keytab: False Managed by: client1.lab.example.com
The Ansible controller node must have the kinit utility installed if you use a one-time password to install the client.
Install the krb5-workstation package if you want to use this client installation method.
In this example, you provide the one-time password as the value of the ipaadmin_password variable in the ipaclients host group.
This method might not be ideal for a production environment; choose the method that best suits your needs.
[user@host ~]$sudo dnf install krb5-workstation...output omitted... Complete! [user@host ~]$cat hosts...output omitted... [ipaclients:vars] ipaclient_domain=lab.example.com ansible_become_password=RedHat123 ipaclient_use_otp=yesipaadmin_password=2Dc89iRcMBwq1hNHQOpdcKf...output omitted...
Run the install-client.yml playbook to install the client.
[user@host ~]$ansible-playbook -i hosts install-client.ymlPLAY [Playbook to configure IPA clients with username/password] *************** ...output omitted... TASK [ipaclient : Uninstall IPA client] *************************************** skipping: [client1.lab.example.com] PLAY RECAP ********************************************************************client1.lab.example.com : ok=23 changed=13 unreachable=0 failed=0skipped=18 rescued=0 ignored=0
IdM Replica Installation
You can use the install-cluster.yml playbook in an existing topology.
In this example, you use the install-cluster.yml playbook to ensure that the topology is synchronized with the current inventory definition.
This scenario might be useful when you want to manage the installation of an existing Ansible-installed topology with only one playbook.
Consider any modifications to the individual playbooks and update the install-cluster.yml playbook accordingly.
[user@host ~]$ansible-playbook -i hosts install-cluster.ymlPLAY [Install IPA servers] **************************************************** TASK [Gathering Facts] ******************************************************** ok: [idmserver.lab.example.com] ...output omitted... TASK [ipaclient : Uninstall IPA client] *************************************** skipping: [client1.lab.example.com] PLAY RECAP ******************************************************************** client1.lab.example.com : ok=5 changed=0 unreachable=0 failed=0 skipped=36 rescued=0 ignored=0 idmserver.lab.example.com : ok=8 changed=0 unreachable=0 failed=0 skipped=26 rescued=0 ignored=0replica1.lab.example.com : ok=55 changed=37 unreachable=0 failed=0 skipped=29rescued=0 ignored=0
You can define the installation of the DNS and CA services on replicas by using the ipareplica_setup_dns and ipareplica_setup_ca variables, respectively.
If the variables are not defined, the service is not installed.
The ansible-freeipa collection also provides playbooks to uninstall topology components.
The difference between the install and uninstall playbooks is the definition of the desired state for the target hosts.
[user@host ~]$ ls /usr/share/doc/ansible-freeipa/playbooks/
...output omitted...
uninstall-client.yml
uninstall-cluster.yml
uninstall-replica.yml
uninstall-server.yml
...output omitted...Red Hat recommends using the individual component playbooks to uninstall portions of the topology.
You can customize the inventory host groups to separate the regions or server where you want to uninstall IdM.
You can also use the --limit and --list-hosts options to delimit and review the hosts where you want to uninstall the service before the uninstallation begins.
[user@host ~]$ansible-playbook -i hosts uninstall-client.yml \--limit replica1.lab.example.com --list-hostsplaybook: uninstall-client.yml play #1 (ipaclients): Playbook to unconfigure IPA clients TAGS: [] pattern: ['ipaclients'] hosts (1): replica1.lab.example.com
In the following example, you uninstall the replica server.
[user@hosts ~]$ansible-playbook -i hosts uninstall-replica.ymlPLAY [Playbook to unconfigure IPA replicas] *********************************** ...output omitted... TASK [ipareplica : Uninstall IPA replica] ************************************* included: /usr/share/ansible/roles/ipareplica/tasks/uninstall.yml for replica1.lab.example.com TASK [ipareplica : Uninstall - Uninstall IPA replica] ************************* changed: [replica1.lab.example.com] PLAY RECAP ********************************************************************replica1.lab.example.com : ok=4 changed=1 unreachable=0 failed=0 skipped=1rescued=0 ignored=0
The playbook uninstalls IdM services from the machine; other data and configuration might still remain.
For example, replication agreements and DNS records might persist; you must delete those manually or use the playbooks in the topology and dnsrecord directories, respectively.
In the case that an installation fails, ensure that you have proper values in your inventory file for the component to be installed. Use the uninstall playbooks to uninstall the component and reboot the machine, then retry the installation.
References
For more information about the FreeIPA Ansible collection, refer to the FreeIPA Ansible repository at https://github.com/freeipa/ansible-freeipa
For more information about IdM automation, refer to the Using Ansible to Install and Manage Identity Management guide at https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html-single/using_ansible_to_install_and_manage_identity_management/index
For more information about installing IdM by using Ansible, refer to the Installing Identity Management guide at https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html-single/installing_identity_management/index#installing-an-Identity-Management-server-using-an-Ansible-playbook_installing-identity-management
