11. Custom Credential Types

As a Tower administrator with superuser access, you can define a custom credential type in a standard format using a YAML/JSON-like definition, allowing the assignment of new credential types to jobs and inventory updates. This allows you to define a custom credential type that works in ways similar to existing credential types. For example, you could create a custom credential type that injects an API token for a third-party web service into an environment variable, which your playbook or custom inventory script could consume.

Custom credentials support the following ways of injecting their authentication information:

  • Environment variables

  • Ansible extra variables

  • File-based templating (i.e., generating .ini or .conf files that contain credential values)

You can attach one SSH and multiple cloud credentials to a Job Template. Each cloud credential must be of a different type. In other words, only one AWS credential, one GCE credential, etc., are allowed. In Ansible Tower 3.2 and later, vault credentials and machine credentials are separate entities.

When creating a new credential type, you are responsible for avoiding collisions in the extra_vars, env, and file namespaces. Also, avoid environment variable or extra variable names that start with ANSIBLE_ because they are reserved. You must have Superuser permissions to be able to create and edit a credential type (CredentialType) and to be able to view the CredentialType.injection field.

11.1. Content sourcing from collections

In 3.8, Tower introduced a new “managed by Tower” credential type of kind=galaxy, which represents a content source for fetching collections defined in requirements.yml when project updates are run (e.g., galaxy.ansible.com, cloud.redhat.com, on-premise Automation Hub). This new type will represent a URL and (optional) authentication details necessary to construct the environment variables when a project update runs ansible-galaxy collection install as described in the Ansible documentation, Configuring the ansible-galaxy client. It has fields which map directly to the configuration options exposed to the Ansible Galaxy CLI, e.g., per-server. An endpoint in the Tower API reflects an ordered list of these credentials at the Organization level:

/api/v2/organizations/N/galaxy_credentials/

Installations of Ansible Tower 3.8 migrates existing Galaxy-oriented setting values in such a way that post-upgrade, proper credentials are created and attached to every Organization in the Tower install. After upgrading to 3.8, every organization that existed prior to upgrade now has a list of (one or more) “Galaxy” credentials associated with it.

Additionally, post-upgrade, these settings are not be visible (or editable) from the /api/v2/settings/jobs/ endpoint.

Tower should still continue to fetch roles directly from public Galaxy even if galaxy.ansible.com is not the first credential in the list for the Organization. The global “Galaxy” settings are no longer configured at the jobs level, but at the Organization level in the Tower User Interface. The Organization’s Add and Edit windows have an optional Credential lookup field for credentials of kind=galaxy.

_images/organizations-galaxy-credentials.png

It is very important to specify the order of these credentials as order sets precedence for the sync and lookup of the content. For more information, see Creating a New Organization. For detail on how to set up a project using collections, see Using Collections in Tower.

11.2. Backwards-Compatible API Considerations

Support for version 2 of the API (api/v2/) means a one-to-many relationship for Job Templates to credentials (including multi-cloud support). Credentials can be filtered using the v2 API:

$ curl "https://tower.example.org/api/v2/credentials/?credential_type__namespace=aws"

In the V2 CredentialType model, the relationships are defined as follows:

Machine

SSH

Vault

Vault

Network

Sets environment variables (e.g., ANSIBLE_NET_AUTHORIZE)

SCM

Source Control

Cloud

EC2, AWS

 

Lots of others

Insights

Insights

Galaxy

galaxy.ansible.com, cloud.redhat.com

 

on-premise Automation Hub

11.3. Getting Started with Credential Types

Access the Credentials from clicking the Credential Types (credential-types-icon) icon from the left navigation bar. If no custom credential types have been created, the Credential Types view will not have any to display and will prompt you to add one:

Credential Types - home empty

If credential types have been created, this page displays a list of all existing and available Credential Types.

Credential Types - home with example credential types

To view more information about a credential type, click on its name or the Edit (edit) button from the Actions column.

Each credential type displays its own unique configurations in the Input Configuration field and the Injector Configuration field, if applicable. Both YAML and JSON formats are supported in the configuration fields.

11.4. Create a New Credential Type

To create a new credential type:

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

Create new credential type

  1. Enter the appropriate details in the Name and Description field.

Note

When creating a new credential type, do not use reserved variable names that start with ANSIBLE_ for the INPUT and INJECTOR names and IDs, as they are invalid for custom credential types.

  1. In the Input Configuration field, specify an input schema which defines a set of ordered fields for that type. The format can be in YAML or JSON, as shown:

YAML

fields:
  - type: string
    id: username
    label: Username
  - type: string
    id: password
    label: Password
    secret: true
required:
  - username
  - password

View more YAML examples at http://www.yaml.org/start.html.

JSON

{
"fields": [
  {
  "type": "string",
  "id": "username",
  "label": "Username"
  },
  {
  "secret": true,
  "type": "string",
  "id": "password",
  "label": "Password"
   }
  ],
 "required": ["username", "password"]
}

View more JSON examples at www.json.org.

The configuration in JSON format below show each field and how they are used:

{
  "fields": [{
    "id": "api_token",               # required - a unique name used to
                                     # reference the field value

    "label": "API Token",            # required - a unique label for the
                                     # field

    "help_text": "User-facing short text describing the field.",

    "type": ("string" | "boolean")   # defaults to 'string'

    "choices": ["A", "B", "C"]       # (only applicable to `type=string`)

    "format": "ssh_private_key"      # optional, can be used to enforce data
                                     # format validity for SSH private key
                                     # data (only applicable to `type=string`)

    "secret": true,                  # if true, the field value will be encrypted

    "multiline": false               # if true, the field should be rendered
                                     # as multi-line for input entry
                                     # (only applicable to `type=string`)
},{
    # field 2...
},{
    # field 3...
}],

"required": ["api_token"]            # optional; one or more fields can be marked as required
},

When type=string, fields can optionally specify multiple choice options:

{
  "fields": [{
      "id": "api_token",          # required - a unique name used to reference the field value
      "label": "API Token",       # required - a unique label for the field
      "type": "string",
      "choices": ["A", "B", "C"]
  }]
},
  1. In the Injector Configuration field, enter environment variables or extra variables that specify the values a credential type can inject. The format can be in YAML or JSON (see examples in the previous step). The configuration in JSON format below show each field and how they are used:

{
  "file": {
      "template": "[mycloud]\ntoken={{ api_token }}"
  },
  "env": {
      "THIRD_PARTY_CLOUD_API_TOKEN": "{{ api_token }}"
  },
  "extra_vars": {
      "some_extra_var": "{{ username }}:{{ password }}"
  }
}

Credential Types can also generate temporary files to support .ini files or certificate/key data:

{
  "file": {
      "template": "[mycloud]\ntoken={{ api_token }}"
  },
  "env": {
      "MY_CLOUD_INI_FILE": "{{ tower.filename }}"
  }
}

In this example, Tower will write a temporary file that contains:

[mycloud]\ntoken=SOME_TOKEN_VALUE

The absolute file path to the generated file will be stored in an environment variable named MY_CLOUD_INI_FILE.

An example of referencing multiple files in a custom credential template is as follows:

Inputs

{
  "fields": [{
    "id": "cert",
    "label": "Certificate",
    "type": "string"
  },{
    "id": "key",
    "label": "Key",
    "type": "string"
  }]
}

Injectors

  {
    "file": {
      "template.cert_file": "[mycert]\n{{ cert }}",
      "template.key_file": "[mykey]\n{{ key }}"
  },
  "env": {
      "MY_CERT_INI_FILE": "{{ tower.filename.cert_file }}",
      "MY_KEY_INI_FILE": "{{ tower.filename.key_file }}"
  }
}
  1. Click Save when done.

  2. Scroll down to the bottom of the screen and your newly created credential type appears on the list of credential types:

New credential type

Click edit to modify or delete to remove the credential type options under the Actions column.

Note

If deleting a credential type that is being used by a credential, you must delete the credential type from all the credentials that use it before you can delete it. Below is an example of such a message:

_images/credential-types-delete-confirmation.png
  1. Verify that the newly created credential type can be selected from the Credential Type selection window when creating a new credential:

Verify new credential type

For details on how to create a new credential, see Credentials.

 

12. Secret Management System

Users and admins upload machine and cloud credentials to Tower so that it can access machines and external services on their behalf. By default, sensitive credential values (such as SSH passwords, SSH private keys, API tokens for cloud services) in Tower are stored in the database after being encrypted. With external credentials backed by credential plugins, you can map credential fields (like a password or an SSH Private key) to values stored in a secret management system instead of providing them to Tower directly. Ansible Tower provides a secret management system that include integrations for:

  • CyberArk Application Identity Manager (AIM)

  • CyberArk Conjur

  • HashiCorp Vault Key-Value Store (KV)

  • HashiCorp Vault SSH Secrets Engine

  • Microsoft Azure Key Management System (KMS)

These external secret values will be fetched prior to running a playbook that needs them. For more information on specifying these credentials in the Tower User Interface, see Credentials.

13. Applications

Creating and configuring token-based authentication for external applications is available starting in Ansible Tower 3.3. This makes it easier for external applications such as ServiceNow and Jenkins to integrate with Ansible Tower. OAuth 2 allows you to use tokens to share certain data with an application without disclosing login information, and furthermore, these tokens can be scoped as “read-only”. In Tower, you create an application that is representative of the external application you are integrating with, then use it to create tokens for that application to use on behalf of the users of the external application.

Having these Tower-issued tokens associated to an application resource gives you the ability to manage all tokens issued for a particular application more easily. By separating token issuance under Applications, you can revoke all tokens based on the Application without having to revoke all tokens in the system.

When integrating an external web app with Ansible Tower that web app may need to create OAuth2 Tokens on behalf of users in that other web app. Creating an application in Tower with the Authorization Code grant type is the preferred way to do this because:

  • external applications can obtain a token from Tower for users, using their credentials

  • compartmentalized tokens issued for a particular application, allows those tokens to be easily managed (revoke all tokens associated with that application, for example)

13.1. Getting Started with Applications

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

Applications - home with example apps

If no other applications exist, only a gray box with a message to add applications displays.

_images/apps-list-view-empty.png

13.2. Create a new application

Token-based authentication for users can be configured in the Applications window.

  1. In the Ansible Tower User Interface, click the Applications (applications-icon) icon from the left navigation bar.

The Applications window opens.

  1. Click the add button located in the upper right corner of the Applications window.

The New Application window opens.

Create application

  1. Enter the following details in Create New Application window:

  • Name (required): provide a name for the application you want to create

  • Description: optionally provide a short description for your application

  • Organization (required): provide an organization for which this application is associated

  • Authorization Grant Type (required): Select from one of the grant types to use in order for the user to acquire tokens for this application. Refer to grant types in the Applications section of the Ansible Tower Administration Guide.

  • Redirect URIS: Provide a list of allowed URIs, separated by spaces. This is required if you specified the grant type to be Authorization code.

  • Client Type (required): Select the level of security of the client device

  1. When done, click Save or Cancel to abandon your changes

13.2.1. Applications – Tokens

Selecting the Tokens view displays a list of the users that have tokens to access the application.

Applications - tokens list

Tokens can only access resources that its associated user can access, and can be limited further by specifying the scope of the token.

13.2.1.1. Add Tokens

Tokens are added through the Users screen and can be associated with an application at that time. Specifying an application can be performed directly in the User’s token settings. You can create a token for your user in the Tokens configuration tab, meaning only you can create and see your tokens in your own user screen. To add a token:

  1. Access the Users list view by clicking the Users (users-icon) icon from the left navigation bar then click on your user to configure your OAuth 2 tokens.

Note:
You can only create OAuth 2 Tokens for your user via the API or UI, which means you can only access your own user profile in order to configure or view your tokens. If you are an admin and need to create or remove tokens for other users, see the revoke and create commands in the Token and session management section of the Ansible Tower Administration Guide.

  1. Click the Tokens tab from your user’s profile.

When no tokens are present, the Tokens screen prompts you to add them:

_images/users-tokens-empty.png

  1. Click the add button, which opens the Create Token window.

  2. Enter the following details in Create Token window:

  • Application: enter the name of the application with which you want to associate your token. Alternatively, you can search for it by clicking the search button. This opens a separate window that allows you to choose from the available options. Use the Search bar to filter by name if the list is extensive. Leave this field blank if you want to create a Personal Access Token (PAT) that is not linked to any application.

  • Description: optionally provide a short description for your token.

  • Scope (required): specify the level of access you want this token to have.

  1. When done, click Save or Cancel to abandon your changes.

After the token is saved, the newly created token for the user displays with the token information and when it expires.

_images/users-token-information-example.png

Note:
This is the only time the token value and associated refresh token value will ever be shown.

In the user’s profile, the application for which it is assigned to and its expiration displays in the token list view.

_images/users-token-assignment-example.png

To verify the application in the example above now shows the user with the appropriate token, go to the Tokens tab of the Applications window:

_images/apps-tokens-list-view-example2.png