11. Custom Credential Types

As a system administrator, you can define a custom credential type in a standard format using a YAML or JSON definition, and then create credentials of that type and use them in jobs and inventory updates. A custom credential type works in ways similar to the 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 inventory plugin 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)

A job template can use one credential of each credential type; Vault credentials are the exception, and you can attach several of them when each one has a different Vault identifier.

Note

When creating a new credential type, you are responsible for avoiding collisions in the extra_vars, env, and file namespaces. Environment variables that start with ANSIBLE_ are not allowed, because they may affect the configuration of Ansible, and neither are variables reserved by automation controller. Only system administrators can create and edit credential types.

Credential types created in the user interface are of kind cloud; through the API you can also create them with kind net. Credentials of the Ansible Galaxy/Automation Hub API Token type are the content sources from which project updates install collections and roles: they are assigned to organizations, in order of precedence. See Creating a New Organization and Using Collections via Hub.

11.1. Getting Started with Credential Types

Open Automation Execution > Infrastructure > Credential Types. The list shows the credential types provided by automation controller, marked Read-only, which cannot be edited or deleted, and the custom credential types that have been created.

Credential Types list with the read-only credential types and a custom one

To view more information about a credential type, click its name. Each credential type shows its configuration in the Input configuration and Injector configuration fields; both YAML and JSON formats are supported. The Credentials tab lists the credentials of that type.

11.2. Create a New Credential Type

To create a new credential type:

  1. Click Create credential type in the Credential Types list.

The Create credential type form

  1. Enter the Name (required) and an optional Description.

Note

When creating a new credential type, do not inject environment variables whose names start with ANSIBLE_, as they are invalid for custom credential types, and do not use tower as an input field ID, as it is reserved.

  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

JSON

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

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 injectors can only reference the input fields of the credential type. For the username and password inputs of the previous step, the configuration in JSON format below shows each kind of injector:

{
  "env": {
      "THIRD_PARTY_CLOUD_USERNAME": "{{ username }}",
      "THIRD_PARTY_CLOUD_PASSWORD": "{{ password }}"
  },
  "extra_vars": {
      "some_extra_var": "{{ username }}:{{ password }}"
  }
}

Credential Types can also generate temporary files to support .ini files or certificate/key data. For a credential type with an api_token input field:

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

In this example, automation controller 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 Create credential type when done. The details of the new credential type open:

Details of the Example API Token credential type

Click Edit credential type to modify it. Once credentials of a credential type exist, its Input configuration cannot be changed, and the credential type cannot be deleted: delete those credentials first. Deleting a credential type that is in use fails with the message “Credential types that are in use cannot be deleted”:

Delete window of a credential type in use, with the error message
  1. Verify that the newly created credential type can be selected in the Credential type field when creating a new credential:

The new credential type in the Credential type field of the Create credential form

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