Documentation

16. User Authentication with Kerberos

User authentication via Active Directory (AD), also referred to as authentication through Kerberos, is supported through Ansible Tower.

To get started, first setup the Kerberos packages in the Tower system so that you can successfully generate a Kerberos ticket. To install the packages, use the following steps:

yum install krb5-workstation
yum install krb5-devel
yum install krb5-libs
pip install kerberos

Once installed, edit the /etc/krb.conf file, as follows, to provide the address of the AD, the domain, etc.:

[logging]
 default = FILE:/var/log/krb5libs.log
 kdc = FILE:/var/log/krb5kdc.log
 admin_server = FILE:/var/log/kadmind.log

[libdefaults]
 default_realm = WEBSITE.COM
 dns_lookup_realm = false
 dns_lookup_kdc = false
 ticket_lifetime = 24h
 renew_lifetime = 7d
 forwardable = true

[realms]
 WEBSITE.COM = {
  kdc = WIN-SA2TXZOTVMV.website.com
  admin_server = WIN-SA2TXZOTVMV.website.com
 }

[domain_realm]
 .website.com = WEBSITE.COM
 website.com = WEBSITE.COM

After the configuration file has been updated, you should be able to successfully authenticate and get a valid token. The following steps show how to authenticate and get a token:

[root@ip-172-31-26-180 ~]# kinit username
Password for username@WEBSITE.COM:
[root@ip-172-31-26-180 ~]#

Check if we got a valid ticket.

[root@ip-172-31-26-180 ~]# klist
Ticket cache: FILE:/tmp/krb5cc_0
Default principal: username@WEBSITE.COM

Valid starting     Expires            Service principal
01/25/16 11:42:56  01/25/16 21:42:53  krbtgt/WEBSITE.COM@WEBSITE.COM
  renew until 02/01/16 11:42:56
[root@ip-172-31-26-180 ~]#

Once you have a valid ticket, you can check to ensure that everything is working as expected from command line. To test this, make sure that your inventory looks like the following:

[windows]
win01.WEBSITE.COM

[windows:vars]
ansible_user = username@WEBSITE.COM
ansible_connection = winrm
ansible_port = 5986

You should also: - Ensure that the hostname is the proper client hostname matching the entry in AD and is not the IP address. - In the username declaration, ensure that the domain name (the text after @) is properly entered with regard to upper- and lower-case letters, as Kerberos is case sensitive. For Tower, you should also ensure that the inventory looks the same.

Note

If you encounter a Server not found in Kerberos database error message, and your inventory is configured using FQDNs (not IP addresses), ensure that the service principal name is not missing or mis-configured.

Now, running a playbook should run as expected. You can test this by running the playbook as the awx user.

Once you have verified that playbooks work properly, integration with Tower is easy. Generate the Kerberos ticket as the awx user and Tower should automatically pick up the generated ticket for authentication.

Note

The python kerberos package must be installed. Ansible is designed to check if kerberos package is installed and, if so, it uses kerberos authentication.

16.1. AD and Kerberos Credentials

Active Directory only:

  • If you are only planning to run playbooks against Windows machines with AD usernames and passwords as machine credentials, you can use “user@domain” format for the username and an associated password.

With Kerberos:

  • If Kerberos is installed, the password is unnecessary and the field can be left blank. Instead, you must kinit a ticket at the commandline as the awx user and have all the other inventory variables specified at the group level.

Kerberos needs the ticket created from kinit for authentication. Do not do this as the root user. Change to the awx user before you perform the kinit.

16.2. Working with Kerberos Tickets

Kerberos tickets are generated every 24 hours, as the default lifetime of a ticket is 24 hours. If you need to change this, edit the /etc/krb.conf file.

Another approach is to use cron to kinit the process every 24 hours. To automate this, you must generate a keytab file which stores the user password so that kinit will not prompt for the user password. Use the following steps to generate this keytab file and then get the kerberos ticket:

> ktutil
  ktutil:  addent -password -p username@WEBSITE.COM -k 1 -e aes256-cts-hmac-sha1-96
  provide password
  ktutil:  wkt username.keytab
  ktutil:  quit

Now, add the following command to cron:

kinit username@WEBSITE.COM -k -t username.keytab

Note

Make sure the system time is in sync between AD, Tower, and the clients.

Note

Client hostnames can looked up via DNS, both normally and reversed.