Using Centrify playbooks for Ansible

Installing Ansible

Ansible is widely available on Linux OS and can be installed using the Yum command on all RedHat type distributions. You can also use Ansible on additional distributions. For more information on additional distributions, refer to Ansible documentation .

Enabling Windows management with Ansible

Ansible is used to manage Windows systems using PowerShell commands and command lines over WinRM.

  • To enable Windows management by using the Ansible “winrm” module, install the Python module as documented by Ansible.
  • For details on enabling Windows management with Ansible, refer to Ansible documentation.

Preparing for Centrify Automation

Automation includes unattended silent installation and bypassing password type credentials reserved for interactive authentication. Centrify recommends the following practice for silent installation and automated management:

  • Centrify software deployment on Unix and Linux is supported using Centrify repository which can be addressed publicly (or mirrored if you are planning to use it for deployment onto systems that cannot access the Internet).
  • For Active Directory management operation, Centrify recommends using a privileged service account and to maintain a Kerberos keytab file to avoid using password authentication.
  • For Centrify Identity Platform Management operation, Centrify recommends using registration codes for system enrollment and OAuth2 protocol for REST API calls.

Configuring Centrify Repo

Ansible is used to manage the repository configuration (included into the sample Playbooks below). The Centrify repo should be configured first on your Ansible server using the appropriate configuration based on your Linux distribution. The setup example below shows how to setup a Yum repository assuming that the Ansible server is using RedHat Enterprise Linux or a RedHat derivative distribution (example: CentOS, Fedora, etc.).

Setup example using Yum repo:

  1. Obtain your repo key, by following instructions in the Centrify Customer Portal.
  1. Setup the repo by creating /etc/yum.repos.d/centrify.repo:
Copy
[centrify]
                name=centrify
                baseurl=https://username:password@repo.centrify.com/rpm-redhat/
                enabled=1
                repo_gpgcheck=1
                gpgcheck=1
                gpgkey=https://downloads.centrify.com/products/RPM-GPG-KEY-centrify
                3.    Verify proper operation
                $ sudo yum list Centrify*
                $ sudo yum info CentrifyDC

                centrify
                Available Packages
                Name        : CentrifyDC
                Arch        : i386
                Version     : 5.3.1
                Release     : 324
                Size        : 24 M
                Repo        : centrify
                Summary     : Centrify DirectControl Agent
                URL         : http://www.centrify.com/
            

For more details on all Centrify repos available, login to the Centrify Customer Portal and visit https://www.centrify.com/support/customer-support-portal/repos/.

Configuring the service account Kerberos secret

To join servers to the Active Directory using the Centrify agent requires privileged authentication to create or update data in the Active Directory domain. Centrify adjoin command support three different methods to perform the administrative operations in Active Directory:

  • Interactive authentication, using an Active Directory privileged user principal and providing credentials when prompted. This option is ideal for a manual join. Any automation scenario would use either options below instead, as they do not require password disclosure.
  • Kerberos authentication, using Kerberos ticket-granting-ticket of a privileged service account. In order to obtain a Kerberos ticket-granting-ticket for a service account principal, Centrify recommends using a Kerberos secret commonly named a keytab file (short for “key table”). A keytab is a file containing pairs of Kerberos principals and encrypted keys (which are derived from the Kerberos password). You can use a keytab file to authenticate to various remote systems using Kerberos without entering a password. However, when you change your Kerberos password, you will need to recreate all your keytabs. Keytab files are commonly used to allow scripts to automatically authenticate using Kerberos, without requiring human interaction or access to password stored in a plain-text file. The script is then able to use the acquired credentials to access files stored on a remote system.
  • Self-service authentication, using a pre-created computer account in Active Directory.

Creating a Kerberos secret named /etc/adjoin.keytab for service account:

Copy
[root@lnx-prodapp01 ~]# adkeytab --keytab /etc/adjoin.keytab --user admin-cathy@domain.com --adopt svc_centrifyadjoin
admin-cathy@DOMAIN.COM's password:
Success: Adopt Account: svc_centrifyadjoin
[root@lnx-prodapp01 ~]# ls -l /etc/adjoin.keytab
-rw-------. 1 root root 237 Mar 18 09:42 /etc/adjoin.keytab

Note:   The user specified to adopt the service account must be a privileged Active Directory user with permissions to change the password of the targeted service account. Service Account should be granted permissions to join computers to zones, remove computers from zones, and manage computer passwords.

You can verify the keytab file by listing the Keylist (Principals) using the Kerberos utility tool.

Copy
[root@lnx-prodapp01 ~]# ktutil
ktutil:  read_kt /etc/adjoin.keytab
ktutil:  list
slot KVNO Principal
---- ---- ---------------------------------------------------------------------
1    3          svc_centrifyadjoin@DOMAIN.COM
2    3          svc_centrifyadjoin@DOMAIN.COM
3    3          svc_centrifyadjoin@DOMAIN.COM
ktutil:  quit

As a final verification, use the keytab file to obtain a Kerberos ticket-granting-ticket for the service account principal.

Copy
[root@lnx-prodapp01 ~]# kinit -kt /etc/adjoin.keytab svc_centrifyadjoin@DOMAIN.COM
[root@lnx-prodapp01 ~]# klist
Ticket cache: FILE:/tmp/krb5cc_0
Default principal: svc_centrifyadjoin@DOMAIN.COM
Valid starting     Expires            Service principal
18/03/20 11:20:51  18/03/20 21:20:51  krbtgt/DOMAIN.COM@DOMAIN.COM
renew until 19/03/20 11:20:51

Note:   For the adjoin command to be able to validate the krbtgt for kerberised join, you must edit the Kerberos configuration file (/etc/krb5.conf) to list the Kerberos realm (Active Directory domain) to use.

Creating a Registration Code

To allow unattended enrollment of systems into the Centrify Identity Platform, create a registration code that will be used to authenticate and allow the enrollment of a system when using the cenroll command from the Centrify Client or a custom script using REST API.

Creating a registration code in Centrify Privileged Access Service portal:

  1. Login to the Centrify Privileged Access Service portal with an account member of System Administrators Role.
  2. Navigate to Settings > Enrollment > Enrollment Codes then click on Add button.
  3. On the Settings tab, choose a Centrify Role as owner of this registration code.

  1. On the IP Range Restrictions tab, it is recommended to list the public IP from which you will allow this code to be used (or internal IP and ranges if using a customer managed PAS installation instead of a Centrify Cloud tenant).
  2. On the System Sets Allowed tab, you can restrict the list of System Sets you allow the system to be added upon enrollment.
  3. After saving the registration code, you will be invited to copy the generated code for future use (you can view the registration code again any time by selecting an existing code and Actions).

Note:   The registration code can be limited in time by setting an expiration or a number of systems to be enrolled before expiration. You can create more than one registration codes at any time, which can help delegation of multiple environment. Owner of a registration code will have permissions automatically set on systems enrolled using the registration code.

Using Centrify Automation Playbooks

You can manage Centrify agent deployment thanks to Centrify public repository available for all Centrify Privilege Services customers. Below are examples of playbooks for simple Centrify agents management tasks. These examples use Yum assuming that managed servers are using RedHat Enterprise Linux or a RedHat derivative distributions (CentOS, Fedora, etc.). Feel free to edit those examples to support other platforms and package management solution (for example, you may prefer to use Aptitude on Debian and derivative distributions).

You can also combine those playbooks into shorter or longer lists of tasks according to your needs, as you may want to perform installation and Active Directory in one single playbook or add Centrify agent deployment to existing orchestration flow. Finally, and depending of your needs, you may want to add more error handling to make those playbooks fully idempotent in your environment.

Centrify Agents Installation Playbook

The playbook below performs the following tasks:

  • Create the configuration file for the Centrify repository if not already present.
  • Install CentrifyDC and CentrifyDA packages using Yum.

Playbook example installing Centrify agents:

Copy
---
- hosts: all
become: true
vars:
centrify_repo: /etc/yum.repos.d/centrify.repo
tasks:
- name: Check if centrify.repo exists
stat:
path: "{{centrify_repo}}"
register: filecheck
- name: Create centrify.repo if it doesn't exist
copy:
src: "{{centrify_repo}}"
dest: "{{centrify_repo}}"
owner: root
group: root
mode: '0644'
when: filecheck.stat.exists == false
- name: Install Centrify Agents packages
yum:
update_cache: yes
name:
- CentrifyDC
- CentrifyDA
state: latest

Using Centrify Agents Uninstall Playbook

The playbook below performs the following tasks:

  • Check if CentrifyDC package is installed (skip further actions if not installed).
  • Check if computer is joined to domain (skip further actions if not joined).
  • Uninstall CentrifyDC and CentrifyDA packages using Yum.

Playbook example uninstalling Centrify Agents:

Copy
---
- hosts: all
become: true
vars:
centrify_repo: /etc/yum.repos.d/centrify.repo
tasks:
- name: Check if CentrifyDC is installed
yum:
list: 'CentrifyDC'
register: yum_cmd
- name: Check if computer is joined to domain
command: adinfo
register: adinfo_cmd
changed_when: adinfo_cmd.rc == 10
failed_when: adinfo_cmd.rc != 10
- name: Remove Centrify Agents packages
block:
- name: Remove CentrifyDC, CentrifyDC-curl, CentrifyDC-openldap, CentrifyDC-openssl and CentrifyDA packages
yum:
name: CentrifyDC
state: absent
- name: Delete centrify.repo
file:
path: "{{centrify_repo}}"
state: absent
when:
- yum_cmd.results | selectattr("yumstate", "match", "installed") | list | length == 1
- adinfo_cmd.rc == 10

Centrify Agents Activation Playbook

The playbook below performs the following tasks:

  • Check if CentrifyDC package is installed (skip further actions if not installed).
  • Check if computer is joined to domain (skip further actions if already joined).
  • Copy Service Account keytab file for Kerberos join and obtain krbtgt.
  • Join computer to domain using krbtgt.
  • Destroy krbtgt and keytab file.

 

Playbook example running adjoin using Kerberos:

Copy
---
- hosts: all
become: true
vars:
domain_name: domain.com
user_principal: svc_centrifyadjoin@DOMAIN.COM
user_keytab: /etc/adjoin.keytab
container: domain.com/Centrify/Computers
zone: domain.com/Centrify/Zones/Global/Linux/Development
realm_config: /etc/krb5.conf
tasks:
- name: Check if CentrifyDC is installed
yum:
list: 'CentrifyDC'
register: yum_cmd
- name: Check if computer is joined to domain
command: adinfo
register: adinfo_cmd
changed_when: adinfo_cmd.rc == 10
failed_when:
- adinfo_cmd.rc != 10
- adinfo_cmd.rc != 0
- name: Join computer to Active Directory
block:
- name: Copy kerberos config file to guarantee finding realm
copy:
src: "{{realm_config}}"
dest: "{{realm_config}}"
owner: root
group: root
mode: '0644'
- name: Copy service account's keytab file
copy:
src: "{{user_keytab}}"
dest: "{{user_keytab}}"
owner: root
group: root
mode: '0600'
- name: Obtain service account's krbtgt
command: kinit -kt "{{user_keytab}}" "{{user_principal}}"
- name: Join the computer to Active Directory domain using kerberos
command: adjoin "{{domain_name}}" --container "{{container}}" --zone "{{zone}}" --verbose
- name: Destroy service account's krbtgt
command: kdestroy
- name: Securely remove service account's keytab file
command: shred --iterations=1 --remove "{{user_keytab}}"
when:
- yum_cmd.results | selectattr("yumstate", "match", "installed") | list | length == 1
- adinfo_cmd.rc == 10

The playbook below performs the following tasks:

  • Check if CentrifyDC package is installed (skip further actions if not installed).
  • Check if computer is joined to domain (skip further actions if already joined).
  • Join computer to domain using self-service.

Playbook example running self-service adjoin:

Copy
---
- hosts: all
become: true
vars:
domain_name: domain.com
tasks:
- name: Check if CentrifyDC is installed
yum:
list: 'CentrifyDC'
register: yum_cmd
- name: Check if computer is joined to domain
command: adinfo
register: adinfo_cmd
changed_when: adinfo_cmd.rc == 10
failed_when:
- adinfo_cmd.rc != 10
- adinfo_cmd.rc != 0
- name: Join computer to Active Directory
block:
- name: Join the computer to Active Directory domain using self-service
command: adjoin "{{domain_name}}" --selfserve --verbose
when:
- yum_cmd.results | selectattr("yumstate", "match", "installed") | list | length == 1
- adinfo_cmd.rc == 10

Note:   Self-service join requires pre-creation of a computer account in Active Directory domain, a computer profile in the target Centrify zone and delegate permissions to this computer to join the domain with self-service. This can be done by running the “Prepare UNIX Computer” wizard from the Access Manager console or using the PowerShell cmdlet New-CdmManagedComputer.

Centrify Agents Deactivation Playbook

The playbook below performs the following tasks:

  • Check if CentrifyDC package is installed (skip further actions if not installed).
  • Check if computer is joined to domain (skip further actions if not joined).
  • Copy Service Account keytab file for Kerberos join and obtain krbtgt.
  • Remove computer from domain using krbtgt.
  • Destroy krbtgt and keytab file.

Playbook example running adleave:using Kerberos

Copy
---
- hosts: all
become: true
vars:
user_principal: svc_centrifyadjoin@DOMAIN.COM
user_keytab: /etc/adjoin.keytab
tasks:
- name: Check if CentrifyDC is installed
yum:
list: 'CentrifyDC'
register: yum_cmd
- name: Check if computer is joined to domain
command: adinfo
register: adinfo_cmd
changed_when: adinfo_cmd.rc == 0
failed_when:
- adinfo_cmd.rc != 10
- adinfo_cmd.rc != 0
- name: Remove computer from Active Directory
block:
- name: Copy service account's keytab file
copy:
src: "{{user_keytab}}"
dest: "{{user_keytab}}"
owner: root
group: root
mode: '0600'
- name: Obtain service account's krbtgt
command: kinit -kt "{{user_keytab}}" "{{user_principal}}"
- name: Leave Active Directory domain
command: adleave --remove --verbose
- name: Destroy service account's krbtgt
command: kdestroy
- name: Securely remove service account's keytab file
command: shred --iterations=1 --remove "{{user_keytab}}"
when:
- yum_cmd.results | selectattr("yumstate", "match", "installed") | list | length == 1
- adinfo_cmd.rc == 0

Centrify Client Installation Playbook

The playbook below performs the following tasks:

  • Create the configuration file for the Centrify repository if not already present.
  • Install CentrifyCC package using Yum.

Playbook example installing Centrify Client:

Copy
---
- hosts: all
become: true
vars:
centrify_repo: /etc/yum.repos.d/centrify.repo
tasks:
- name: Check if centrify.repo exists
stat:
path: "{{centrify_repo}}"
register: filecheck
- name: Create centrify.repo if it doesn't exist
copy:
src: "{{centrify_repo}}"
dest: "{{centrify_repo}}"
owner: root
group: root
mode: '0644'
when: filecheck.stat.exists == false
- name: Install Centrify Agent package
yum:
update_cache: yes
name: CentrifyCC
state: latest

Centrify Client Uninstallation Playbook

The playbook below performs the following tasks:

  • Check if CentrifyCC package is installed (skip further actions if not installed).
  • Check if computer is enrolled with a Centrify tenant (skip further actions if not joined).
  • Uninstall CentrifyCC packages using Yum.

Playbook example uninstalling Centrify Client:

Copy
---
- hosts: all
become: true
vars:
centrify_repo: /etc/yum.repos.d/centrify.repo
tasks:
- name: Check if CentrifyCC is installed
yum:
list: CentrifyCC
register: yum_cmd
- name: Check if computer is joined to Centrify Identity Platform
command: cinfo
register: cinfo_cmd
changed_when: cinfo_cmd.rc == 10
failed_when:
- cinfo_cmd.rc != 10
- cinfo_cmd.rc != 0
- name: Remove Centrify Client package
block:
- name: Remove CentrifyCC package
yum:
name: CentrifyCC
state: absent
- name: Delete centrify.repo
file:
path: "{{centrify_repo}}"
state: absent
when:
- yum_cmd.results | selectattr("yumstate", "match", "installed") | list | length == 1
- cinfo_cmd.rc == 10

Centrify Client Enrollment Playbook

The playbook below performs the following tasks:

  • Check if CentrifyCC package is installed (skip further actions if not installed).
  • Check if computer is enrolled to a Centrify tenant (skip further actions if already joined).
  • Enroll computer to Centrify tenant using a registration code.
  • Enroll and manage password for the root account.

Playbook example running cenroll using registration code:

Copy
---
- hosts: all
become: true
vars:
tenant: <YourTenant>.my.centrify.net
code: <RegistrationCode>
tasks:
- name: Check if CentrifyCC is installed
yum:
list: 'CentrifyCC'
register: yum_cmd
- name: Check if computer is enrolled to Centrify Identity Platform
command: cinfo
register: cinfo_cmd
changed_when: cinfo_cmd.rc == 10
failed_when:
- cinfo_cmd.rc != 10
- cinfo_cmd.rc != 0
- name: Enroll computer to Centrify Identity Platform
block:
- name: Enroll the computer to Centrify tenant using registration code
command: cenroll --tenant "{{tenant}}" --code "{{code}}" --features all --force --verbose
when:
- yum_cmd.results | selectattr("yumstate", "match", "installed") | list | length == 1
- cinfo_cmd.rc == 10

Centrify Client Unenrollment Playbook

The playbook below performs the following tasks:

  • Check if CentrifyCC package is installed (skip further actions if not installed).
  • Check if computer is enrolled to a Centrify tenant (skip further actions if not joined).
  • Unenroll computer from Centrify tenant using machine credentials.

Playbook example running cunenroll:

Copy
---
- hosts: all
become: true
vars:
tasks:
- name: Check if CentrifyCC is installed
yum:
list: 'CentrifyCC'
register: yum_cmd
- name: Check if computer is enrolled to Centrify Identity Platform
command: cinfo
register: cinfo_cmd
changed_when: cinfo_cmd.rc == 0
failed_when:
- cinfo_cmd.rc != 10
- cinfo_cmd.rc != 0
- name: Unenroll computer from Centrify Identity Platform
block:
- name: Unenroll the computer from Centrify tenant without deleting System
command: cunenroll --machine --verbose
when:
- yum_cmd.results | selectattr("yumstate", "match", "installed") | list | length == 1
- cinfo_cmd.rc == 0