11. Secret Management System
Users and admins upload machine and cloud credentials so that automation 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) 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 AWX directly. AWX provides a secret management system that include integrations for:
These external secret values will be fetched prior to running a playbook that needs them. For more information on specifying these credentials in the User Interface, see Credentials.
11.1. Configure and link secret lookups
When configuring AWX to pull a secret from a 3rd-party system, it is in essence linking credential fields to external systems. To link a credential field to a value stored in an external system, select the external credential corresponding to that system and provide metadata to look up the desired value. The metadata input fields are part of the external credential type definition of the source credential.
AWX provides a credential plugin interface for developers, integrators, admins, and power-users with the ability to add new external credential types to extend it to support other secret management systems. For more detail, see the development docs for credential plugins.
Use the AWX User Interface to configure and use each of the supported 3-party secret management systems.
First, create an external credential for authenticating with the secret management system. At minimum, provide a name for the external credential and select one of the following for the Credential Type:
Navigate to the credential form of the target credential and link one or more input fields to the external credential along with metadata for locating the secret in the external system. In this example, the Demo Credential is the target credential.
For any of the fields below the Type Details area that you want to link to the external credential, click the
button of the input field. You are prompted to set the input source to use to retrieve your secret information.
Select the credential you want to link to, and click Next. This takes you to the Metadata tab of the input source. Metadata is specific to the input source you select:
Input Source |
Metadata |
Description |
|---|---|---|
AWS Secrets Manager |
AWS Secrets Manager Region (required) |
The region where the secrets manager is located. |
AWS Secret Name (Required) |
Specify the AWS secret name that was generated by the AWS access key. |
|
Centrify Vault Credential Provider Lookup |
Account Name (Required) |
Name of the system account or domain associated with Centrify Vault. |
System Name |
Specify the name used by the Centrify portal. |
|
CyberArk Central Credential Provider Lookup |
Object Query (Required) |
Lookup query for the object. |
Object Query Format |
Select |
|
Object Property |
Specifies the name of the property to return (e.g., |
|
Reason |
If required per the object’s policy, supply a reason for checking out the secret, as CyberArk logs those. |
|
CyberArk Conjur Secrets Lookup |
Secret Identifier |
The identifier for the secret. |
Secret Version |
Specify a version of the secret, if necessary, otherwise, leave it empty to use the latest version. |
|
HashiVault Secret Lookup |
Name of Secret Backend |
Specify the name of the KV backend to use. Leave it blank to use the first path segment of the Path to Secret field instead. |
Path to Secret (required) |
Specify the path to where the secret information is stored; for example, |
|
Key Name (required) |
Specify the name of the key to look up the secret information. |
|
Secret Version (V2 Only) |
Specify a version if necessary, otherwise, leave it empty to use the latest version. |
|
HashiCorp Signed SSH |
Unsigned Public Key (required) |
Specify the public key of the cert you want to get signed. It needs to be present in the authorized keys file of the target host(s). |
Path to Secret (required) |
Specify the path to where the secret information is stored; for example, |
|
Role Name (required) |
A role is a collection of SSH settings and parameters that are stored in Hashi vault. Typically, you can specify a couple of them with different privileges, timeouts, etc. So you could have a role that is allowed to get a cert signed for root, and other less privileged ones, for example. |
|
Valid Principals |
Specify a user (or users) other than the default, that you are requesting vault to authorize the cert for the stored key. Hashi vault has a default user for whom it signs (e.g., ec2-user). |
|
Azure KMS |
Secret Name (required) |
The actual name of the secret as it is referenced in Azure’s Key vault app. |
Secret Version |
Specify a version of the secret, if necessary, otherwise, leave it empty to use the latest version. |
|
Thycotic DevOps Secrets Vault |
Secret Path (required) |
Specify the path to where the secret information is stored (e.g., /path/username). |
Thycotic Secret Server |
Secret ID (required) |
The identifier for the secret. |
Secret Field |
Specify the field to be used from the secret. |
This example shows the Metadata prompt for HashiVault Secret Lookup.
Click Test to verify connection to the secret management system. If the lookup is unsuccessful, an error message like this one displays:
When done, click OK. This closes the prompt window and returns you to the Details screen of your target credential. Repeat these steps, starting with step 3 above to complete the remaining input fields for the target credential. By linking the information in this manner, AWX retrieves sensitive information, such as username, password, keys, certificates, and tokens from the 3rd-party management systems and populates that data into the remaining fields of the target credential form.
If necessary, supply any information manually for those fields that do not use linking as a way of retrieving sensitive information. Refer to the appropriate Credential Types for more detail about each of the fields.
Click Save when done.
11.1.1. AWS Secrets Manager Lookup
This plugin allows AWS to be used as a credential input source to pull secrets from AWS SecretsManager. AWS Secrets Manager provides similar service to Microsoft Azure Key Vault, and the AWS collection provides a lookup plugin for it.
When AWS Secrets Manager lookup is selected for Credential Type, provide the following attributes to properly configure your lookup:
AWS Access Key (required): provide the access key used for communicating with AWS’ key management system
AWS Secret Key (required): provide the secret as obtained by the AWS IAM console
Below shows an example of a configured AWS Secret Manager credential.
11.1.2. Centrify Vault Credential Provider Lookup
You need the Centrify Vault web service running to store secrets in order for this integration to work. When Centrify Vault Credential Provider Lookup is selected for Credential Type, provide the following attributes to properly configure your lookup:
Centrify Tenant URL (required): provide the URL used for communicating with Centrify’s secret management system
Centrify API User (required): provide the username
Centrify API Password (required): provide the password
OAuth2 Application ID : specify the identifier given associated with the OAuth2 client
OAuth2 Scope : specify the scope of the OAuth2 client
Below shows an example of a configured CyberArk AIM credential.
11.1.3. CyberArk Central Credential Provider (CCP) Lookup
You need the CyberArk Central Credential Provider web service running to store secrets in order for this integration to work. When CyberArk Central Credential Provider Lookup is selected for Credential Type, provide the following attributes to properly configure your lookup:
CyberArk CCP URL (required): provide the URL used for communicating with CyberArk CCP’s secret management system; must include URL scheme (http, https, etc.)
Web Service ID: optionally specify the identifier for the web service; leaving it blank defaults to AIMWebService
Application ID (required): specify the identifier given by CyberArk CCP services
Client Key: paste the client key if provided by CyberArk
Client Certificate: include the
BEGIN CERTIFICATEandEND CERTIFICATElines when pasting the certificate, if provided by CyberArkVerify SSL Certificates: this option is only available when the URL uses HTTPS. Check this option to verify the server’s SSL certificate is valid and trusted. Environments that use internal or private CA’s should leave this option unchecked to disable verification.
Below shows an example of a configured CyberArk CCP credential.
11.1.4. CyberArk Conjur Secrets Manager Lookup
With a Conjur Cloud tenant available to target, configure the CyberArk Conjur Secrets Lookup external management system credential plugin as documented.
When CyberArk Conjur Secrets Manager Lookup is selected for Credential Type, provide the following attributes to properly configure your lookup:
Conjur URL (required): provide the URL used for communicating with CyberArk Conjur’s secret management system; must include URL scheme (http, https, etc.)
API Key (required): provide the key given by your Conjur admin
Account (required): the organization’s account name
Username (required): the specific authenticated user for this service
Public Key Certificate: include the
BEGIN CERTIFICATEandEND CERTIFICATElines when pasting the public key, if provided by CyberArk
Below shows an example of a configured CyberArk Conjur credential.
11.1.5. HashiCorp Vault Secret Lookup
When HashiCorp Vault Secret Lookup is selected for Credential Type, provide the following attributes to properly configure your lookup:
Server URL (required): provide the URL used for communicating with HashiCorp Vault’s secret management system
Token: specify the access token used to authenticate HashiCorp’s server
CA Certificate: specify the CA certificate used to verify HashiCorp’s server
Approle Role_ID: specify the ID if using Approle for authentication
Approle Secret_ID: specify the corresponding secret ID for Approle authentication
Client Certificate: specify a PEM-encoded client certificate when using the TLS auth method including any required intermediate certificates expected by Vault
Client Certificate Key: specify a PEM-encoded certificate private key when using the TLS auth method
TLS Authentication Role: specify the role or certificate name in Vault that corresponds to your client certificate when using the TLS auth method. If it is not provided, Vault will attempt to match the certificate automatically
Namespace name specify the namespace name (Vault Enterprise only)
Kubernetes role specify the role name when using Kubernetes authentication
Username: enter the username of the user to be used to authenticate this service
Password: enter the password associated with the user to authenticate this service
Path to Auth: specify a path if other than the default path of
/approleAPI Version (required): select v1 for static lookups and v2 for versioned lookups
For more detail about the Approle auth method and its fields, refer to the Vault documentation for Approle Auth Method.
LDAP authentication requires LDAP to be configured in HashiCorp’s Vault UI. A policy may be added to the user if they want access to a specific engine created. As long as the bind is set properly, the user should be able to successfully authenticate. Cubbyhole is the name of the default secret mount. If you have proper permissions, you can create other mounts and write key values to those. For more detail about the LDAP auth method and its fields, refer to the Vault documentation for LDAP auth method.
For more detail about the userpass auth method and its fields, refer to the Vault documentation for userpass auth method.
For more detail about the Kubernetes auth method and its fields, refer to the Vault documentation for Kubernetes auth method.
For more detail about the TLS certificate auth method and its fields, refer to the Vault documentation for TLS certificates auth method.
Below shows an example of a configured HashiCorp Vault Secret Lookup credential for LDAP.
To test the lookup, create another credential that uses the HashiCorp Vault lookup. The example below shows the attributes for a machine credential configured to look up HashiCorp Vault secret credentials:
11.1.6. HashiCorp Vault Signed SSH
When HashiCorp Vault Signed SSH is selected for Credential Type, provide the following attributes to properly configure your lookup:
Server URL (required): provide the URL used for communicating with HashiCorp Signed SSH’s secret management system
Token: specify the access token used to authenticate HashiCorp’s server
CA Certificate: specify the CA certificate used to verify HashiCorp’s server
Approle Role_ID: specify the ID for Approle authentication
Approle Secret_ID: specify the corresponding secret ID for Approle authentication
Client Certificate: specify a PEM-encoded client certificate when using the TLS auth method including any required intermediate certificates expected by Vault
Client Certificate Key: specify a PEM-encoded certificate private key when using the TLS auth method
TLS Authentication Role: specify the role or certificate name in Vault that corresponds to your client certificate when using the TLS auth method. If it is not provided, Vault will attempt to match the certificate automatically
Namespace name specify the namespace name (Vault Enterprise only)
Kubernetes role specify the role name when using Kubernetes authentication
Username: enter the username of the user to be used to authenticate this service
Password: enter the password associated with the user to authenticate this service
Path to Auth: specify a path if other than the default path of
/approle
For more detail about the Approle auth method and its fields, refer to the Vault documentation for Approle Auth Method.
For more detail about the Kubernetes auth method and its fields, refer to the Vault documentation for Kubernetes auth method.
For more detail about the TLS certificate auth method and its fields, refer to the Vault documentation for TLS certificates auth method.
Below shows an example of a configured HashiCorp SSH Secrets Engine credential.
11.1.7. Microsoft Azure Key Vault
When Microsoft Azure Key Vault is selected for Credential Type, provide the following attributes to properly configure your lookup:
Vault URL (DNS Name) (required): provide the URL used for communicating with MS Azure’s key management system
Client ID (required): provide the identifier as obtained by the Azure Active Directory
Client Secret (required): provide the secret as obtained by the Azure Active Directory
Tenant ID (required): provide the unique identifier that is associated with an Azure Active Directory instance within an Azure subscription
Cloud Environment: select the applicable cloud environment to apply
Below shows an example of a configured Microsoft Azure KMS credential.
11.1.8. Thycotic DevOps Secrets Vault
When Thycotic DevOps Secrets Vault is selected for Credential Type, provide the following attributes to properly configure your lookup:
Tenant (required): provide the URL used for communicating with Thycotic’s secret management system
Top-level Domain (TLD) : provide the top-level domain designation (e.g., com, edu, org) associated with the secret vault you want to integrate
Client ID (required): provide the identifier as obtained by the Thycotic secret management system
Client Secret (required): provide the secret as obtained by the Thycotic secret management system
Below shows an example of a configured Thycotic DevOps Secrets Vault credential.
11.1.9. Thycotic Secret Server
When Thycotic Secrets Server is selected for Credential Type, provide the following attributes to properly configure your lookup:
Secret Server URL (required): provide the URL used for communicating with the Thycotic Secrets Server management system
Username (required): specify the authenticated user for this service
Password (required): provide the password associated with the user
Below shows an example of a configured Thycotic Secret Server credential.
