Chapter 11. Secret management system Users and system administrators 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, and 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 (such as a password or an SSH Private key) to values stored in a secret management system instead of providing them to automation controller directly. Automation controller provides a secret management system that include integrations for: AWS Secrets Manager Lookup Centrify Vault Credential Provider Lookup CyberArk Central Credential Provider Lookup (CCP) CyberArk Conjur Secrets Manager Lookup HashiCorp Vault Key-Value Store (KV) HashiCorp Vault SSH Secrets Engine Microsoft Azure Key Management System (KMS) Thycotic DevOps Secrets Vault Thycotic Secret Server GitHub app token lookup These external secret values are fetched before running a playbook that needs them. Additional resources For more information about specifying secret management system credentials in the user interface, see Managing user credentials . 11.1. Configuring and linking secret lookups When pulling a secret from a third-party system, you are 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 required value. The metadata input fields are part of the external credential type definition of the source credential. Automation controller provides a credential plugin interface for developers, integrators, system administrators, and power-users with the ability to add new external credential types to extend it to support other secret management systems. Use the following procedure to use automation controller to configure and use each of the supported third-party secret management systems. Procedure Create an external credential for authenticating with the secret management system. At minimum, give a name for the external credential and select one of the following for the Credential type field: AWS Secrets Manager Lookup Centrify Vault Credential Provider Lookup CyberArk Central Credential Provider (CCP) Lookup CyberArk Conjur Secrets Manager Lookup HashiCorp Vault Secret Lookup HashiCorp Vault Signed SSH Microsoft Azure Key Vault Thycotic DevOps Secrets Vault Thycotic Secret Server GitHub app token lookup In this example, the Demo Credential is the target credential. For any of the fields that follow the Type Details area that you want to link to the external credential, click the key icon in the input field to link one or more input fields to the external credential along with metadata for locating the secret in the external system. Select the input source to use to retrieve your secret information. Select the credential you want to link to, and click . This takes you to the Metadata tab of the input source. This example shows the Metadata prompt for HashiVault Secret Lookup. Metadata is specific to the input source you select. For more information, see the Metadata for credential input sources table. Click Test to verify connection to the secret management system. If the lookup is unsuccessful, an error message displays: Click OK . You return to the Details screen of your target credential. Repeat these steps, starting with Step 3 to complete the remaining input fields for the target credential. By linking the information in this manner, automation controller retrieves sensitive information, such as username, password, keys, certificates, and tokens from the third-party management systems and populates the remaining fields of the target credential form with that data. If necessary, supply any information manually for those fields that do not use linking as a way of retrieving sensitive information. For more information about each of the fields, see the appropriate Credential types . Click Save . Additional resources For more information, see the development documents for Credential plugins . 11.1.1. Metadata for credential input sources The information required for the Metadata tab of the input source. AWS Secrets Manager Lookup Metadata Description 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 Metadata Description 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 Metadata Description Object Query (Required) Lookup query for the object. Object Query Format Select Exact for a specific secret name, or Regexp for a secret that has a dynamically generated name. Object Property Specifies the name of the property to return. For example, UserName or Address other than the default of Content . Reason If required for the object's policy, supply a reason for checking out the secret, as CyberArk logs those. CyberArk Conjur Secrets Lookup Metadata Description 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 Metadata Description 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, /path/username . 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 Metadata Description Unsigned Public Key (required) Specify the public key of the certificate you want to have signed. It needs to be present in the authorized keys file of the target hosts. Path to Secret (required) Specify the path to where the secret information is stored; for example, /path/username . Role Name (required) A role is a collection of SSH settings and parameters that are stored in Hashi vault. Typically, you can specify some with different privileges or timeouts, for example. So you could have a role that is permitted to get a certificate 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, for example, ec2-user. Microsoft Azure KMS Metadata Description Secret Name (required) The name of the secret as it is referenced in Microsoft 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 Metadata Description Secret Path (required) Specify the path to where the secret information is stored, for example, /path/username. Thycotic Secret Server Metadata Description Secret ID (required) The identifier for the secret. Secret Field Specify the field to be used from the secret. 11.1.2. AWS Secrets Manager lookup This plugin enables Amazon Web Services to be used as a credential input source to pull secrets from the Amazon Web Services Secrets Manager. The 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 , give the following metadata to configure your lookup: AWS Access Key (required): give the access key used for communicating with AWS key management system AWS Secret Key (required): give the secret as obtained by the AWS IAM console 11.1.3. Centrify Vault Credential Provider Lookup You need the Centrify Vault web service running to store secrets for this integration to work. When you select Centrify Vault Credential Provider Lookup for Credential Type , give the following metadata to configure your lookup: Centrify Tenant URL (required): give the URL used for communicating with Centrify's secret management system Centrify API User (required): give the username Centrify API Password (required): give the password OAuth2 Application ID : specify the identifier given associated with the OAuth2 client OAuth2 Scope : specify the scope of the OAuth2 client 11.1.4. CyberArk Central Credential Provider (CCP) Lookup The CyberArk Central Credential Provider web service must be running to store secrets for this integration to work. When you select CyberArk Central Credential Provider Lookup for Credential Type , give the following metadata to configure your lookup: CyberArk CCP URL (required): give the URL used for communicating with CyberArk CCP's secret management system. It must include the URL scheme such as http or https. Optional: Web Service ID : specify the identifier for the web service. Leaving this 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 CERTIFICATE and END CERTIFICATE lines when pasting the certificate, if provided by CyberArk. Verify SSL Certificates : this option is only available when the URL uses HTTPS. Check this option to verify that the server's SSL/TLS certificate is valid and trusted. For environments that use internal or private CA's, leave this option unchecked to disable verification. 11.1.5. CyberArk Conjur Secrets Manager Lookup With a Conjur Cloud tenant available to target, configure the CyberArk Conjur Secrets Lookup external management system credential plugin. When you select CyberArk Conjur Secrets Manager Lookup for Credential Type , give the following metadata to configure your lookup: Conjur URL (required): provide the URL used for communicating with CyberArk Conjur's secret management system. This must include the URL scheme, such as http or https. 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 CERTIFICATE and END CERTIFICATE lines when pasting the public key, if provided by CyberArk 11.1.6. HashiCorp Vault Secret Lookup When you select HashiCorp Vault Secret Lookup for Credential Type , give the following metadata to configure your lookup: Server URL (required): give 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 authentication method, including any required intermediate certificates expected by Hashicorp Vault. Client Certificate Key : specify a PEM-encoded certificate private key when using the TLS authentication method. TLS Authentication Role : specify the role or certificate name in Hashicorp Vault that corresponds to your client certificate when using the TLS authentication method. If it is not provided, Hashicorp Vault attempts to match the certificate automatically. Namespace name : specify the Namespace name (Hashicorp 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 be used to authenticate this service. Path to Auth : specify a path if other than the default path of /approle . API Version (required): select v1 for static lookups and v2 for versioned lookups. LDAP authentication requires LDAP to be configured in HashiCorp's Vault UI and a policy added to the user. 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. To test the lookup, create another credential that uses Hashicorp Vault lookup. Additional resources For more detail about the LDAP authentication method and its fields, see the Vault documentation for LDAP auth method . For more information about AppRole authentication method and its fields, see the Vault documentation for AppRole auth method . For more information about the userpass authentication method and its fields, see the Vault documentation for userpass auth method . For more information about the Kubernetes auth method and its fields, see the Vault documentation for Kubernetes auth method . For more information about the TLS certificate auth method and its fields, see the Vault documentation for TLS certificates auth method . 11.1.7. HashiCorp Vault Signed SSH When you select HashiCorp Vault Signed SSH for Credential Type , give the following metadata to configure your lookup: Server URL (required): give 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 authentication method, including any required intermediate certificates expected by Hashicorp Vault. Client Certificate Key : specify a PEM-encoded certificate private key when using the TLS authentication method. TLS Authentication Role : specify the role or certificate name in Hashicorp Vault that corresponds to your client certificate when using the TLS authentication method. If it is not provided, Hashicorp Vault attempts to match the certificate automatically. Namespace name : specify the Namespace name (Hashicorp 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 be used to authenticate this service. Path to Auth : specify a path if other than the default path of /approle . Additional resources For more information about AppRole authentication method and its fields, see the Vault documentation for AppRole Auth Method . For more information about the Kubernetes authentication method and its fields, see the Vault documentation for Kubernetes auth method . For more information about the TLS certificate auth method and its fields, see the Vault documentation for TLS certificates auth method . 11.1.8. Microsoft Azure Key Vault When you select Microsoft Azure Key Vault for Credential Type , give the following metadata to configure your lookup: Vault URL (DNS Name) (required): give the URL used for communicating with Microsoft Azure's key management system Client ID (required): give the identifier as obtained by Microsoft Entra ID Client Secret (required): give the secret as obtained by Microsoft Entra ID Tenant ID (required): give the unique identifier that is associated with an Microsoft Entra ID instance within an Azure subscription Cloud Environment : select the applicable cloud environment to apply 11.1.9. Thycotic DevOps Secrets Vault When you select Thycotic DevOps Secrets Vault for Credential Type , give the following metadata to configure your lookup: Tenant (required): give the URL used for communicating with Thycotic's secret management system Top-level Domain (TLD) : give the top-level domain designation, for example .com, .edu, or .org, associated with the secret vault you want to integrate Client ID (required): give the identifier as obtained by the Thycotic secret management system Client Secret (required): give the secret as obtained by the Thycotic secret management system 11.1.10. Thycotic Secret Server When you select Thycotic Secrets Server for Credential Type , give the following metadata to configure your lookup: Secret Server URL (required): give the URL used for communicating with the Thycotic Secrets Server management system Username (required): specify the authenticated user for this service Domain : give the (application) user domain Password (required): give the password associated with the user 11.1.11. Configuring a GitHub App Installation Access Token Lookup With this plugin you can use a private GitHub App RSA key as a credential input source to pull access tokens from GitHub App installations. Platform gateway uses existing GitHub authorization from organizations' GitHub repositories. For more information, see Generating an installation access token for a GitHub App . Procedure Create a lookup credential that stores your secrets. For more information, see Creating new credentials . Select GitHub App Installation Access Token Lookup for Credential type , and enter the following attributes to properly configure your lookup: GitHub App ID : Enter the App ID provided by your instance of GitHub, this is what is used to authenticate. GitHub App Installation ID : Enter the ID of the application into your target organization where the access token is scoped. You must set it up to have access to your target repository. RSA Private Key : Enter the generated private key that your GitHub instance generated. You can get it from the GitHub App maintainer within GitHub. For more information, see Managing private keys for GitHub Apps . Click Create credential to confirm and save the credential. The following is an example of a configured GitHub App Installation Access Token Lookup credential: Create a target credential that searches for the lookup credential. To use your lookup in a private repository, select Source Control as your Credential type . Enter the following attributes to properly configure your target credential: Username : Enter the username x-access-token . Password : Click the icon for managing external credentials in the input field. You are prompted to set the input source to use to retrieve your secret information. This is the lookup credential that you have already created. Enter an optional description for the metadata requested and click Finish . Click Create credential to confirm and save the credential. Verify both your lookup credential and your target credential are now available on the Credentials list view. To use the target credential in a project, create a project and enter the following information: Name : Enter the name for your project. Organization : Select the name of the organization from the drop-down menu.. Execution environment : Optionally select an execution environment, if applicable. Source control type : If you are syncing with a private repository, select Git for your source control. The Type Details view opens for additional input. Enter the following information: Source control URL : Enter the URL of the private repository you want to access. The other related fields pertaining to branch/tag/commit and refspec are not relevant for use with a lookup credential. Source control credential : Select the target credential that you have already created. The following is an example of a configured target credential in a project: Click Create project and the project sync automatically starts. The project Details tab displays the progress of the job: Troubleshooting If your project sync fails, you might have to manually re-enter https://api.github.com in the GitHub API endpoint URL field from Step 2 and re-run your project sync.

Commands: