Documentation

8. Credentials

Credentials are utilized by Tower for authentication when launching jobs against machines, synchronizing with inventory sources, and importing project content from a version control system.

Tower credentials are imported and stored encrypted in Tower, and are not retrievable in plain text on the command line by any user. Once a password or key has been entered into the Tower interface, it is encrypted and inserted into the Tower database, and cannot be retrieved from Tower. You can grant users and teams the ability to use these credentials, without actually exposing the credential to the user. If you have a user move to a different team or leave the organization, you don’t have to re-key all of your systems just because that credential was available in Tower.

Note

Tower encrypts passwords and key information in the Tower database and never makes secret information visible via the API.

8.1. Understanding How Credentials Work

The encryption/decryption algorithm uses Electronic Code Book (ECB) as the mode of operation with AES-128 as the block cipher. The 128-bit AES key is derived from the SECRET_KEY (found in the awx settings). Specific, sensitive, Model fields in Tower are encrypted and include:

Credential: password, ssh_key_data, ssh_key_unlock, become_password, vault_password
UnifiedJob: start_args

Data is encrypted before it is saved to the database and is decrypted as is needed in Tower. The encryption/decryption process derives the AES-128 bit encryption key from <SECRET_KEY, field_name, primary_key> where field_name is the name of the Model field and primary_key is the database primary key. Thus, if any attribute used in the key generation process changes, Tower fails to correctly decrypt the secret.

Note

The rules of encryption and decryption for Ansible Tower also apply to one field outside of credentials, the Unified Job start_args field, which is used through the job, ad_hoc_command, and system_job data types. Refer to Unified Job List API Endpoint in the Ansible Tower API Guide for more information.

8.2. Getting Started with Credentials

The Credentials link, accessible from the setup button displays a list of all available credentials. It can be sorted and searched by Name, Description, or Type.

Credentials - home with example credentials

Credentials can also be managed from either the Teams link or the Users link from the Setup (setup) menu. To manage credentials for teams, browse to the Teams tab and edit the appropriate team. To manage credentials for a user, browse to the Users tab and edit the appropriate user.

Credentials added to a Team are made available to all members of the team, whereas credentials added to a user are only available to that specific user by default.

Buttons located in the upper right corner of the Credentials screen provide the following actions:

  • Create a new credential
  • View Activity Stream

8.3. Add a New Credential

Create a new credential by selecting the plus button.

Create credential

Enter the appropriate details depending on the type of credential and select Save.

8.4. Credential Types

8.4.1. Machine

Machine credentials enable Tower to invoke Ansible on hosts under your management. Just like using Ansible on the command line, you can specify the SSH username, optionally provide a password, an SSH key, a key password, or even have Tower prompt the user for their password at deployment time. They define ssh and user-level privilege escalation access for playbooks, and are used when submitting jobs to run playbooks on a remote host.

Machine credentials have several attributes that may be configured:

  • Username: The username to be used for SSH authenticatation.

  • Password: The actual password to be used for SSH authenticatation. This password can be stored encrypted in the Tower database, if entered. Alternatively, you can configure Tower to ask the user for the password when necessary by selecting “Ask at runtime?”. In these cases, a dialog opens when the job is launched, promoting the user to enter the password and password confirmation.

  • Private Key: The actual SSH Private Key to be used to authenticate the user via SSH. This key is stored encrypted in the Tower database.

  • Private Key Passphrase: If the SSH Private Key used is protected by a password, you can configure a Key Password for the private key. This password may be stored encrypted in the Tower database, if entered. Alternatively, you can configure Tower to ask the user for the password as necessary by selecting “Ask at runtime?”. In these cases, a dialog opens when the job is launched, prompting the user to enter the password and password confirmation.

  • Privilege Escalation: Specifies the type of escalation privilege to assign to specific users. This is equivalent to specifying the --become-method=BECOME_METHOD parameter, where BECOME_METHOD could be sudo | su | pbrun | pfexec.

    • sudo: Performs single commands with super user (root user) privileges
    • su: Switches to the super user (root user) account (or to other user accounts)
    • pbrun: Requests that an application or command be run in a controlled account and provides for advanced root privilege delegation and keylogging.
    • pfexec: Executes commands with predefined process attributes, such as specific user or group IDs.

  • Privilege Escalation Username: The username to use with escalation privileges on the remote system.

  • Privilege Escalation Password: The actual password to be used to authenticate the user via the selected privilege escalation type on the remote system. This password may be stored encrypted in the Tower database, if entered. Alternatively, you may configure Tower to ask the user for the password when necessary by selecting “Ask at runtime?”. In these cases, a dialog opens when the job is launched, promoting the user to enter the password and password confirmation.

    Note

    Sudo Password must be used in combination with SSH passwords or SSH Private Keys, since Tower must first establish an authenticated SSH connection with the host prior to invoking sudo to change to the sudo user.

  • Vault Password: If your playbook uses Ansible Vault, add the Vault password to your credentials here. Alternatively, you may configure Tower to ask the user for the vault password when necessary by selecting “Ask at runtime?”. In these cases, a dialog opens when the job is launched, promoting the user to enter the password and password confirmation.

Credentials - create manual credential

For more information about Ansible Vault, refer to: http://docs.ansible.com/playbooks_vault.html

Warning

Credentials which are used in Scheduled Jobs must not be configured as “Ask at runtime?”.

8.4.2. Source Control

Used with Projects to clone and update local source code repositories from a remote revision control system such as Git, Subversion, or Mercurial.

Credentials - create SCM credential

Source Control credentials have several attributes that may be configured:

  • Username: The username to use in conjunction with the source control system.
  • Password: The password to use in conjunction with the source control system.
  • SCM Private Key: The actual SSH Private Key to be used to authenticate the user to the source control system via SSH.
  • Private Key Passphrase: If the SSH Private Key used is protected by a passphrase, you may configure a Key Passphrase for the private key.

Note

Source Control credentials cannot be configured as “Ask at runtime?”.

8.4.3. Amazon Web Services

Enables synchronization of cloud inventory with Amazon Web Services.

Credentials - create AWS credential

Traditional Amazon Web Services credentials consist of the AWS Access Key and Secret Key.

Ansible Tower version 2.4.0 introduced support for EC2 STS tokens (sometimes referred to as IAM STS credentials). Security Token Service (STS) is a web service that enables you to request temporary, limited-privilege credentials for AWS Identity and Access Management (IAM) users. To learn more about the IAM/EC2 STS Token, refer to: http://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html

AWS credentials consist of:

AWS_ACCESS_KEY
AWS_SECRET_KEY
AWS_SECURITY_TOKEN

Note

If the value of your tags in EC2 contain booleans (yes/no/true/false), you must remember to quote them.

Warning

To use implicit IAM role credentials, do not attach AWS cloud credentials in Tower when relying on IAM roles to access the AWS API. While it may seem to make sense to attach your AWS cloud credential to your job template, doing so will force the use of your AWS credentials and will not “fall through” to use your IAM role credentials (this is due to the use of the boto library.)

8.4.4. Rackspace

Enables synchronization of cloud inventory with Rackspace.

Credentials - create RAX credential

Rackspace credentials consist of the Rackspace Username and API Key.

8.4.5. VMware

Enables synchronization of inventory with VMware vCenter.

Credentials - create VMware credential

VMware credentials have several attributes that may be configured:

  • vCenter Host: The vCenter hostname or IP address to connect to.
  • Username: The username to use to connect to vCenter.
  • Password: The password to use to connect to vCenter.

Note

If the VMware guest tools are not running on the instance, VMware inventory sync may not return an IP address for that instance.

8.4.6. Google Compute Engine

Enables synchronization of cloud inventory with Google Compute Engine.

Credentials - create GCE credential

Google Compute Engine credentials have several attributes that may be configured:

  • Service Account Email Address: The email address assigned to the Google Compute Engine service account.
  • RSA Private Key: The PEM file associated with the service account email.
  • Project: The GCE assigned identification. It is constructed as two words followed by a three digit number, such as: squeamish-ossifrage-123.

8.4.7. Microsoft Azure

Enables synchronization of cloud inventory with Windows Azure.

Credentials - create Azure credential

Microsoft Azure credentials have several attributes that may be configured:

  • Subscription ID: The Subscription UUID for the Microsoft Azure account.
  • Management Certificate: The PEM file that corresponds to the certificate you uploaded in the Microsoft Azure console.

8.4.8. OpenStack

Enables synchronization of cloud inventory with OpenStack.

Credentials - create OpenStack credential

OpenStack credentials have several attributes that may be configured:

  • Host (Authentication URL): The host to be used for authentication.
  • Username: The username to use to connect to OpenStack.
  • Password (API Key): The password or API key to use to connect to OpenStack.
  • Project (Tenet Name/ID): The tenant name or tenant id used for OpenStack. This value is usually the same as the username.

If you are interested in using OpenStack Cloud Credentials, refer to Utilitzing Cloud Credentials for more information, including a sample playbook.