Documentation

10. 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.

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.

10.1. Understanding How Credentials Work

Ansible Tower uses SSH to connect to remote hosts (or the Windows equivalent). In order to pass the key from Tower to SSH, the key must be decrypted before it can be written a named pipe. Tower then uses that pipe to send the key to SSH (so that it is never written to disk).

If passwords are used, Ansible Tower handles those by responding directly to the password prompt and decrypting the password before writing it to the prompt.

The encryption/decryption algorithm uses a variation of Fernet: a symmetric encryption cipher utilizing AES-256 in CBC mode alongside a SHA-256 HMAC. The 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-256 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 assigned auto-incremented record ID. 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.

10.2. Getting Started with Credentials

Access the Credentials page by clicking the Credentials (credentials-icon) icon from the left navigation bar. The Credentials page displays a search-able list of all available Credentials and can be sorted by Name.

Credentials - home with example credentials

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.

Note

If deleting items that are used by other work items, a message opens listing the items are affected by the deletion and prompts you to confirm the deletion. Some screens will contain items that are invalid or previously deleted, so they will fail to run. Below is an example of such a message:

_images/warning-deletion-dependencies.png

To help you get started, a Demo Credential has been created for your use.

Clicking on the link for the Demo Credential takes you to the Details view of this Credential.

Credentials - home with demo credential details

Clicking on Permissions shows you users and teams associated with this Credential and their granted roles (owner, admin, auditor, etc.)

Credentials - home with permissions credential details

You can click the add button to assign this Demo Credential to additional Users or Teams.

10.3. Add a New Credential

To create a new credential:

  1. Click the add button located in the upper right corner of the Credentials screen.

Create credential

  1. Enter the name for your new credential in the Name field.
  2. Optionally enter or select the name of the organization with which the credential is associated.
  3. Enter or select the credential type you want to create.
_images/credential-types-popup-window.png
  1. Enter the appropriate details depending on the type of credential selected, as described in the following sections.
  2. Click Save when done.

10.4. Credential Types

10.4.1. Amazon Web Services

Selecting this credential type enables synchronization of cloud inventory with Amazon Web Services.

Tower uses the following environment variables for AWS credentials and are fields prompted in the user interface:

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SECURITY_TOKEN

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

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.)

10.4.2. Ansible Tower

Selecting this credential allows you to access another Tower instance.

Credentials - create tower credential

Ansible Tower credentials have the following inputs that are required:

  • Ansible Tower Hostname: The base URL or IP address of the other Tower instance to connect to.
  • Username: The username to use to connect to it.
  • Password: The password to use to connect to it.

10.4.3. Google Compute Engine

Selecting this credential type enables synchronization of cloud inventory with Google Compute Engine (GCE).

Tower uses the following environment variables for GCE credentials and are fields prompted in the user interface:

GCE_EMAIL
GCE_PROJECT
GCE_CREDENTIALS_FILE_PATH

Credentials - create GCE credential

GCE credentials have the following inputs that are required:

  • Service Account Email Address: The email address assigned to the Google Compute Engine service account.
  • Project: Optionally provide the GCE assigned identification or the unique project ID you provided at project creation time.
  • Service Account JSON File: Optionally upload a GCE service account file. Use the folder (file-browser) icon to browse for the file that contains the special account information that can be used by services and applications running on your GCE instance to interact with other Google Cloud Platform APIs. This grants permissions to the service account and virtual machine instances.
  • RSA Private Key: The PEM file associated with the service account email.

10.4.4. Insights

Selecting this credential type enables synchronization of cloud inventory with Red Hat Insights.

Credentials - create Insights credential

Insights credentials consist of the Insights Username and Password, which is the user’s Red Hat Customer Portal Account username and password.

10.4.5. 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. Network connections (httpapi, netconf, and network_cli) use Machine for the credential type.

Machine/SSH credentials do not use environment variables. Instead, they pass the username via the ansible -u flag, and interactively write the SSH password when the underlying SSH client prompts for it.

Credentials - create machine credential

Machine credentials have several attributes that may be configured:

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

  • Password: The actual password to be used for SSH authentication. This password will be stored encrypted in the Tower database, if entered. Alternatively, you can configure Tower to ask the user for the password at launch time by selecting Prompt on launch. In these cases, a dialog opens when the job is launched, promoting the user to enter the password and password confirmation.

  • SSH Private Key: Copy or drag-and-drop the SSH private key for the machine credential.

  • 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 will be stored encrypted in the Tower database, if entered. Alternatively, you can configure Tower to ask the user for the password at launch time by selecting Prompt on launch. In these cases, a dialog opens when the job is launched, prompting the user to enter the password and password confirmation.

  • Privilege Escalation Method: 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 | dzdo | pmrun.

    • empty selection: Assigns no privilege escalation to this credential.
    • 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.
    • dzdo: An enhanced version of sudo that uses RBAC information in an Centrify’s Active Directory service (see Centrify’s site on DZDO)
    • pmrun: Requests that an application is run in a controlled account (refer to Privilege Manager for Unix 6.0)
    • runas: Allows you to run as current user.

    Credentials - create machine credential priv escalation

  • Privilege Escalation Username field is only seen if an option for privilege escalation is selected. Enter the username to use with escalation privileges on the remote system.

  • Privilege Escalation Password: field is only seen if an option for privilege escalation is selected. Enter the actual password to be used to authenticate the user via the selected privilege escalation type on the remote system. This password will be stored encrypted in the Tower database, if entered. Alternatively, you may configure Tower to ask the user for the password at launch time by selecting Prompt on launch. 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.

Warning

Credentials which are used in Scheduled Jobs must not be configured as “Prompt on launch”.

10.4.6. Microsoft Azure Resource Manager

Selecting this credential type enables synchronization of cloud inventory with Microsoft Azure Resource Manager.

Credentials - create Azure credential

Microsoft Azure Resource Manager credentials have several attributes that may be configured:

  • Subscription ID: The Subscription UUID for the Microsoft Azure account (required).
  • Username: The username to use to connect to the Microsoft Azure account.
  • Password: The password to use to connect to the Microsoft Azure account.
  • Client ID: The Client ID for the Microsoft Azure account.
  • Client Secret: The Client Secret for the Microsoft Azure account.
  • Tenant ID: The Tenant ID for the Microsoft Azure account.
  • Azure Cloud Environment: The variable associated with Azure cloud or Azure stack environments.

These fields are equivalent to the variables in the API. To pass service principal credentials, define the following variables:

AZURE_CLIENT_ID
AZURE_SECRET
AZURE_SUBSCRIPTION_ID
AZURE_TENANT
AZURE_CLOUD_ENVIRONMENT

To pass an Active Directory username/password pair, define the following variables:

AZURE_AD_USER
AZURE_PASSWORD
AZURE_SUBSCRIPTION_ID

You can also pass credentials as parameters to a task within a playbook. The order of precedence is parameters, then environment variables, and finally a file found in your home directory.

To pass credentials as parameters to a task, use the following parameters for service principal credentials:

client_id
secret
subscription_id
tenant
azure_cloud_environment

Or, pass the following parameters for Active Directory username/password:

ad_user
password
subscription_id

10.4.7. Network

Select the Network credential type only if you are using a local connection with provider to use Ansible networking modules to connect to and manage networking devices. When connecting to network devices, the credential type must match the connection type:

  • For local connections using provider, credential type should be Network
  • For all other network connections (httpapi, netconf, and network_cli), credential type should be Machine

For an overview of connection types available for network devices, refer to Multiple Communication Protocols.

Tower uses the following environment variables for Network credentials and are fields prompted in the user interface:

ANSIBLE_NET_USERNAME
ANSIBLE_NET_PASSWORD

Credentials - create network credential

Network credentials have several attributes that may be configured:

  • Username: The username to use in conjunction with the network device (required).
  • Password: The password to use in conjunction with the network device.
  • SSH Private Key: Copy or drag-and-drop the actual SSH Private Key to be used to authenticate the user to the network via SSH.
  • Private Key Passphrase: The actual passphrase for the private key to be used to authenticate the user to the network via SSH.
  • Authorize: Select this from the Options field to control whether or not to enter privileged mode.
  • If Authorize is checked, enter a password in the Authorize Password field to access privileged mode.

For more information, refer to the Inside Playbook blog, Porting Ansible Network Playbooks with New Connection Plugins.

10.4.8. OpenStack

Selecting this credential type enables synchronization of cloud inventory with OpenStack.

Credentials - create OpenStack credential

OpenStack credentials have the following inputs that are required:

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

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

10.4.9. Red Hat CloudForms

Selecting this credential type enables synchronization of cloud inventory with Red Hat CloudForms.

Tower writes a CloudForms configuration file based on fields prompted in the user interface. The absolute path to the file is set in the following environment variable:

CLOUDFORMS_INI_PATH

Credentials - create Red Hat CloudForms credential

CloudForms credentials have the following inputs that are required:

  • CloudForms URL: The CloudForms URL or IP address to connect to.
  • Username: The username to use to connect to CloudForms.
  • Password: The password to use to connect to CloudForms.

Additional Resources:

Refer to Red Hat’s blog post series on Ansible Tower Integration in Red Hat CloudForms 4.1 at http://cloudformsblog.redhat.com/2016/07/22/ansible-tower-in-cloudforms/.

10.4.10. Red Hat Satellite 6

Selecting this credential type enables synchronization of cloud inventory with Red Hat Satellite 6.

Tower writes a Satellite configuration file based on fields prompted in the user interface. The absolute path to the file is set in the following environment variable:

FOREMAN_INI_PATH

Credentials - create Red Hat Satellite 6 credential

Satellite credentials have the following inputs that are required:

  • Satellite 6 URL: The Satellite 6 URL or IP address to connect to.
  • Username: The username to use to connect to Satellite 6.
  • Password: The password to use to connect to Satellite 6.

10.4.11. Red Hat Virtualization

This credential allows Tower to access Ansible’s oVirt4.py dynamic inventory plugin, which is managed by Red Hat Virtualization (RHV).

Tower uses the following environment variables for Red Hat Virtualization credentials and are fields in the user interface:

OVIRT_URL
OVIRT_USERNAME
OVIRT_PASSWORD

Credentials - create rhv credential

RHV credentials have the following inputs that are required:

  • Host (Authentication URL): The host URL or IP address to connect to.
  • Username: The username to use to connect to oVirt4.
  • Password: The password to use to connect to it.
  • CA File: Optionally provide an absolute path to the oVirt certificate file (it may end in .pem, .cer and .crt extensions, but preferably .pem for consistency)

10.4.12. Source Control

SCM (source control) credentials are 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: Copy or drag-and-drop 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 “Prompt on launch”.

10.4.13. Vault

Selecting this credential type enables synchronization of inventory with Ansible Vault.

Credentials - create Vault credential

Vault credentials require the Vault Password and an optional Vault Identifier if applying multi-Vault credentialing. For more information on Ansible Tower Multi-Vault support, refer to the Multi-Vault Credentials section of the Ansible Tower Administration Guide.

You may configure Tower to ask the user for the password at launch time by selecting Prompt on launch. In these cases, a dialog opens when the job is launched, promoting the user to enter the password and password confirmation.

Warning

Credentials which are used in Scheduled Jobs must not be configured as “Prompt on launch”.

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

10.4.14. VMware vCenter

Selecting this credential type enables synchronization of inventory with VMware vCenter.

Tower uses the following environment variables for VMware vCenter credentials and are fields prompted in the user interface:

VMWARE_HOST
VMWARE_USER
VMWARE_PASSWORD
VMWARE_VALIDATE_CERTS

Credentials - create VMware credential

VMware credentials have the following inputs that are required:

  • 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.