Chapter 23. Custom credential types
Chapter 23. Custom credential types As a system administrator, you can define a custom credential type in a standard format by using a YAML or JSON-like definition. You can define a custom credential type that works in ways similar to existing credential types. For example, a custom credential type can inject an API token for a third-party web service into an environment variable, for your playbook or custom inventory script to consume. Custom credentials support the following ways of injecting their authentication information: Environment variables Ansible extra variables File-based templating, which means 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. Only one of each type of credential is permitted. Vault credentials and machine credentials are separate entities. Note When creating a new credential type, you must avoid collisions in the extra_vars , env , and file namespaces. Environment variable or extra variable names must not start with ANSIBLE_ because they are reserved. You must have System administrator (superuser) permissions to be able to create and edit a credential type ( CredentialType ) and to be able to view the CredentialType.injection field. 23.1. Content sourcing from collections A "managed" credential type of kind=galaxy represents a content source for fetching collections defined in requirements.yml when project updates are run. Examples of content sources are galaxy.ansible.com, console.redhat.com, or on-premise automation hub. This new credential type represents 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 that map directly to the configuration options exposed to the Ansible Galaxy CLI, for example, per-server. An endpoint in the API reflects an ordered list of these credentials at the Organization level: /api/v2/organizations/N/galaxy_credentials/ When installations of automation controller migrate existing Galaxy-oriented setting values, post-upgrade proper credentials are created and attached to every Organization. After upgrading to the latest version, every organization that existed before upgrade now has a list of one or more "Galaxy" credentials associated with it. Additionally, post-upgrade, these settings are not visible (or editable) from the /api/v2/settings/jobs/ endpoint. Automation controller continues 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 user interface. The organization's Create organization and Edit organization windows have an optional Galaxy credentials lookup field for credentials of kind=galaxy . It is 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 an organization . For more information about how to set up a project by using collections, see Using Collections with automation hub . 23.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 multicloud support). You can filter credentials the v2 API: curl "https://controller.example.org/api/v2/credentials/?credential_type__namespace=aws" In the V2 Credential Type model, the relationships are defined as follows: Machine SSH Vault Vault Network Sets environment variables, for example ANSIBLE_NET_AUTHORIZE SCM Source Control Cloud EC2, AWS Cloud Lots of others Insights Insights Galaxy galaxy.ansible.com, console.redhat.com Galaxy on-premise automation hub 23.3. Content verification Automation controller uses GNU Privacy Guard (GPG) to verify content. For more information, see The GNU Privacy Handbook . 23.4. Getting started with credential types Procedure From the navigation panel, select Automation Execution Infrastructure Credentials . If no custom credential types have been created, the Credential Types page prompts you to add one. If credential types have been created, this page displays a list of existing and available Credential Types. Select the name of a credential or the Edit icon to view more information about a credential type, . On the Details tab, 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. 23.5. Creating a new credential type To create a new credential type: Procedure From the navigation panel, select Automation Execution Infrastructure Credentials . In the Credential Types view, click Create credential type . 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. In the Input configuration field, specify an input schema that defines a set of ordered fields for that type. The format can be in YAML or JSON: YAML fields: - type: string id: username label: Username - type: string id: password label: Password secret: true required: - username - password View more YAML examples at the YAML page . JSON { "fields": [ { "type": "string", "id": "username", "label": "Username" }, { "secret": true, "type": "string", "id": "password", "label": "Password" } ], "required": ["username", "password"] } View more JSON examples at The JSON website . The following configuration in JSON format shows 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"] }] }, 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 step). The following configuration in JSON format shows 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 or key data: { "file": { "template": "[mycloud]\ntoken={{ api_token }}" }, "env": { "MY_CLOUD_INI_FILE": "{{ tower.filename }}" } } In this example, automation controller writes a temporary file that has: [mycloud]\ntoken=SOME_TOKEN_VALUE The absolute file path to the generated file is stored in an environment variable named MY_CLOUD_INI_FILE . The following is an example of referencing many files in a custom credential template: 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 }}" } } Click Create credential type . Your newly created credential type is displayed on the list of credential types: Click the Edit icon to modify the credential type options. Note In the Edit screen, you can modify the details or delete the credential. If the Delete option is disabled, this means that the credential type is being used by a credential, and you must delete the credential type from all the credentials that use it before you can delete it. Verification Verify that the newly created credential type can be selected from the Credential Type selection window when creating a new credential: Additional resources For information about how to create a new credential, see Creating a credential .
/api/v2/organizations/N/galaxy_credentials/ curl "https://controller.example.org/api/v2/credentials/?credential_type__namespace=aws" fields: - type: string id: username label: Username - type: string id: password label: Password secret: true required: - username - password { "fields": [ { "type": "string", "id": "username", "label": "Username" }, { "secret": true, "type": "string", "id": "password", "label": "Password" } ], "required": ["username", "password"] } { "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 }, { "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"] }] }, { "file": { "template": "[mycloud]\ntoken={{ api_token }}" }, "env": { "THIRD_PARTY_CLOUD_API_TOKEN": "{{ api_token }}" }, "extra_vars": { "some_extra_var": "{{ username }}:{{ password }}" } } { "file": { "template": "[mycloud]\ntoken={{ api_token }}" }, "env": { "MY_CLOUD_INI_FILE": "{{ tower.filename }}" } } [mycloud]\ntoken=SOME_TOKEN_VALUE { "fields": [{ "id": "cert", "label": "Certificate", "type": "string" },{ "id": "key", "label": "Key", "type": "string" }] } { "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 }}" } }