Documentation

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

Note

When creating a new credential type, you are responsible for avoiding collisions in the extra_vars, env, and file namespaces. 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. Backwards-Compatible API Considerations

With Ansible Tower version 3.2, new support for version 2 of the API (V2) means:

  • One-to-many relationship for Job Templates to credentials (including multi-cloud support)
  • Custom credentials will not be managed by the V1 API; if a user defines a custom credential type, its credentials will not show up in the V1 API
  • POSTs to V1 credential API will transparently work with migrated CredentialTypes/Credentials

Credentials have the concept of “Kind” that dictates:

  • How or where a credential can be used.
  • 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.

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

You may edit credential types with any of the valid options:

  • SSH: Used to authenticate to remote hosts (Inventories) when Job Templates are ran against them. Also used to define privilege escalation access.
  • Vault: Used to unlock sensitive data encrypted through Ansible Vault.
  • Network: Used by Ansible networking modules to authenticate to networking devices.
  • Source Control: Used to authenticate to source control-based Projects within Tower.
  • Cloud: Used to synchronize Inventory Sources. Can also be used for additional remote host (Inventory) authentication for Job Template runs.
  • Insights: Used to authenticate with Red Hat Insights.

Custom types are limited to cloud and network kinds.

Create credential type

11.2. Getting Started with Credential Types

The Credential Types link, accessible from the Setting (settings) button, displays a list of all existing and available Credential Types. It can be sorted and searched by Name and Type.

Credential Types - home with example credential types

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

The credential types that are included by default with Tower are read-only. Custom credential types are editable if you are a System Administrator or Superuser. Each credential type displays its categorization in the Kind field, and has 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. An example of Amazon Web Services’ credential type details is shown below:

Credential Types - AWS example

On the Credential Types main page, you can click the add button to create a custom credential type.

11.3. 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 and select either Network or Cloud from the Kind drop-down menu.
  2. 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'

    "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:
{
  "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.

  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.

  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.