diff --git a/docs/docsite/rst/common/images/credential-types-drop-down-menu.png b/docs/docsite/rst/common/images/credential-types-drop-down-menu.png index 9ed1f34abd36..b5913215b7f4 100644 Binary files a/docs/docsite/rst/common/images/credential-types-drop-down-menu.png and b/docs/docsite/rst/common/images/credential-types-drop-down-menu.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-aws-secret-credential.png b/docs/docsite/rst/common/images/credentials-create-aws-secret-credential.png new file mode 100644 index 000000000000..9c07dd904aa0 Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-aws-secret-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-link-credential-prompt.png b/docs/docsite/rst/common/images/credentials-link-credential-prompt.png index 2eca4a3fba11..756dafa2d44c 100644 Binary files a/docs/docsite/rst/common/images/credentials-link-credential-prompt.png and b/docs/docsite/rst/common/images/credentials-link-credential-prompt.png differ diff --git a/docs/docsite/rst/common/images/credentials-link-metadata-prompt.png b/docs/docsite/rst/common/images/credentials-link-metadata-prompt.png index 33efcc91ca00..0e2e705057e5 100644 Binary files a/docs/docsite/rst/common/images/credentials-link-metadata-prompt.png and b/docs/docsite/rst/common/images/credentials-link-metadata-prompt.png differ diff --git a/docs/docsite/rst/common/images/credentials-machine-test-hashicorp-metadata.png b/docs/docsite/rst/common/images/credentials-machine-test-hashicorp-metadata.png index d6c7e1365043..813fe56f5e91 100644 Binary files a/docs/docsite/rst/common/images/credentials-machine-test-hashicorp-metadata.png and b/docs/docsite/rst/common/images/credentials-machine-test-hashicorp-metadata.png differ diff --git a/docs/docsite/rst/userguide/credential_plugins.rst b/docs/docsite/rst/userguide/credential_plugins.rst index 1da61ac64b6e..6ce53b862f7b 100644 --- a/docs/docsite/rst/userguide/credential_plugins.rst +++ b/docs/docsite/rst/userguide/credential_plugins.rst @@ -10,14 +10,15 @@ 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 :term:`secret management system` instead of providing them to AWX directly. AWX provides a secret management system that include integrations for: -- 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 +- :ref:`ug_credentials_aws_lookup` +- :ref:`ug_credentials_centrify` +- :ref:`ug_credentials_cyberarkccp` +- :ref:`ug_credentials_cyberarkconjur` +- :ref:`ug_credentials_hashivault` (KV) +- :ref:`ug_credentials_hashivaultssh` +- :ref:`ug_credentials_azurekeyvault` (KMS) +- :ref:`ug_credentials_thycoticvault` +- :ref:`ug_credentials_thycoticserver` 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 :ref:`ug_credentials`. @@ -49,149 +50,134 @@ Use the AWX User Interface to configure and use each of the supported 3-party se .. image:: ../common/images/credentials-link-credential-prompt.png :alt: Credential section of the external secret management system dialog -4. Select the credential you want to link to, and click **Next**. 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. See the :ref:`ug_metadata_creds_inputs` table for details. - -.. image:: ../common/images/credentials-link-metadata-prompt.png - :alt: Metadata section of the external secret management system dialog - -5. Click **Test** to verify connection to the secret management system. If the lookup is unsuccessful, an error message like this one displays: - -.. image:: ../common/images/credentials-link-metadata-test-error.png - :alt: Example exception dialog for credentials lookup - -6. 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 :ref:`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. - -7. 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 :ref:`ug_credentials_cred_types` for more detail about each of the fields. - -8. Click **Save** when done. - -.. _ug_metadata_creds_inputs: - -Metadata for credential input sources -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -**Centrify Vault Credential Provider Lookup** +4. 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: .. list-table:: - :widths: 25 50 + :widths: 10 10 25 + :width: 1400px :header-rows: 1 - * - Metadata + * - Input Source + - Metadata - Description - * - Account Name (Required) + * - *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 + * - + - System Name - Specify the name used by the Centrify portal. - -**CyberArk Central Credential Provider Lookup** - -.. list-table:: - :widths: 25 50 - :header-rows: 1 - - * - Metadata - - Description - * - Object Query (Required) + * - *CyberArk Central Credential Provider Lookup* + - Object Query (Required) - Lookup query for the object. - * - Object Query Format + * - + - Object Query Format - Select ``Exact`` for a specific secret name, or ``Regexp`` for a secret that has a dynamically generated name. - * - Object Property + * - + - Object Property - Specifies the name of the property to return (e.g., ``UserName``, ``Address``, etc.) other than the default of ``Content``. - * - Reason + * - + - Reason - If required per the object's policy, supply a reason for checking out the secret, as CyberArk logs those. - -**CyberArk Conjur Secrets Lookup** - -.. list-table:: - :widths: 25 50 - :header-rows: 1 - - * - Metadata - - Description - * - Secret Identifier + * - *CyberArk Conjur Secrets Lookup* + - Secret Identifier - The identifier for the secret. - * - Secret Version + * - + - Secret Version - Specify a version of the secret, if necessary, otherwise, leave it empty to use the latest version. - -**HashiVault Secret Lookup** - -.. list-table:: - :widths: 25 50 - :header-rows: 1 - - * - Metadata - - Description - * - Name of Secret Backend + * - *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) + * - + - Path to Secret (required) - Specify the path to where the secret information is stored; for example, ``/path/username``. - * - Key Name (required) + * - + - Key Name (required) - Specify the name of the key to look up the secret information. - * - Secret Version (V2 Only) + * - + - Secret Version (V2 Only) - Specify a version if necessary, otherwise, leave it empty to use the latest version. - -**HashiCorp Signed SSH** - -.. list-table:: - :widths: 25 50 - :header-rows: 1 - - * - Metadata - - Description - * - Unsigned Public Key (required) + * - *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) + * - + - Path to Secret (required) - Specify the path to where the secret information is stored; for example, ``/path/username``. - * - Role Name (required) + * - + - 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 + * - + - 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. -**Azure KMS** +This example shows the Metadata prompt for HashiVault Secret Lookup. -.. list-table:: - :widths: 25 50 - :header-rows: 1 +.. image:: ../common/images/credentials-link-metadata-prompt.png + :alt: Metadata section of the external secret management system dialog - * - Metadata - - Description - * - 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** +5. Click **Test** to verify connection to the secret management system. If the lookup is unsuccessful, an error message like this one displays: -.. list-table:: - :widths: 25 50 - :header-rows: 1 +.. image:: ../common/images/credentials-link-metadata-test-error.png + :alt: Example exception dialog for credentials lookup + +6. 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 :ref:`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. - * - Metadata - - Description - * - Secret Path (required) - - Specify the path to where the secret information is stored (e.g., /path/username). +7. 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 :ref:`ug_credentials_cred_types` for more detail about each of the fields. -**Thycotic Secret Server** +8. Click **Save** when done. -.. list-table:: - :widths: 25 50 - :header-rows: 1 - * - Metadata - - Description - * - Secret ID (required) - - The identifier for the secret. - * - Secret Field - - Specify the field to be used from the secret. +.. _ug_credentials_aws_lookup: + +AWS Secrets Manager Lookup +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: + pair: credential types; AWS + +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 :ref:`ug_credentials_azurekeyvault`, 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. + +.. image:: ../common/images/credentials-create-aws-secret-credential.png + :width: 1400px + :alt: Example new AWS Secret Manager credential lookup dialog + .. _ug_credentials_centrify: Centrify Vault Credential Provider Lookup -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. index:: pair: credential types; Centrify -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 metadata to properly configure your 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 @@ -208,12 +194,12 @@ Below shows an example of a configured CyberArk AIM credential. .. _ug_credentials_cyberarkccp: CyberArk Central Credential Provider (CCP) Lookup -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. index:: single: CyberArk CCP pair: credential; CyberArk CCP -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 metadata to properly configure your 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 @@ -230,14 +216,14 @@ Below shows an example of a configured CyberArk CCP credential. .. _ug_credentials_cyberarkconjur: CyberArk Conjur Secrets Manager Lookup -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. index:: single: CyberArk Conjur pair: credential; CyberArk Conjur 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 metadata to properly configure your lookup: +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 @@ -253,12 +239,12 @@ Below shows an example of a configured CyberArk Conjur credential. .. _ug_credentials_hashivault: HashiCorp Vault Secret Lookup -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. index:: single: HashiCorp Secret Lookup pair: credential; HashiCorp KV -When **HashiCorp Vault Secret Lookup** is selected for **Credential Type**, provide the following metadata to properly configure your 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 @@ -291,7 +277,7 @@ Below shows an example of a configured HashiCorp Vault Secret Lookup credential .. image:: ../common/images/credentials-create-hashicorp-kv-credential.png :alt: Example new HashiCorp Vault Secret lookup dialog -To test the lookup, create another credential that uses the HashiCorp Vault lookup. The example below shows the metadata for a machine credential configured to look up HashiCorp Vault secret credentials: +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: .. image:: ../common/images/credentials-machine-test-hashicorp-metadata.png :alt: Example machine credential lookup metadata for HashiCorp Vault. @@ -300,12 +286,12 @@ To test the lookup, create another credential that uses the HashiCorp Vault look .. _ug_credentials_hashivaultssh: HashiCorp Vault Signed SSH -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. index:: single: HashiCorp SSH Secrets Engine pair: credential; HashiCorp SSH Secrets Engine -When **HashiCorp Vault Signed SSH** is selected for **Credential Type**, provide the following metadata to properly configure your lookup: +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 @@ -335,13 +321,13 @@ Below shows an example of a configured HashiCorp SSH Secrets Engine credential. .. _ug_credentials_azurekeyvault: Microsoft Azure Key Vault -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. index:: single: MS Azure KMS pair: credential; MS Azure KMS triple: credential; Azure; KMS -When **Microsoft Azure Key Vault** is selected for **Credential Type**, provide the following metadata to properly configure your lookup: +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 @@ -357,12 +343,12 @@ Below shows an example of a configured Microsoft Azure KMS credential. .. _ug_credentials_thycoticvault: Thycotic DevOps Secrets Vault -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. index:: single: Thycotic DevOps Secrets Vault pair: credential; Thycotic DevOps Secrets Vault -When **Thycotic DevOps Secrets Vault** is selected for **Credential Type**, provide the following metadata to properly configure your lookup: +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 @@ -379,12 +365,12 @@ Below shows an example of a configured Thycotic DevOps Secrets Vault credential. .. _ug_credentials_thycoticserver: Thycotic Secret Server -^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~ .. index:: single: Thycotic Secret Server pair: credential; Thycotic Secret Server -When **Thycotic Secrets Server** is selected for **Credential Type**, provide the following metadata to properly configure your lookup: +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 diff --git a/docs/docsite/rst/userguide/credentials.rst b/docs/docsite/rst/userguide/credentials.rst index 38187fc2d495..b5b9112d69a2 100644 --- a/docs/docsite/rst/userguide/credentials.rst +++ b/docs/docsite/rst/userguide/credentials.rst @@ -128,7 +128,7 @@ The following credential types are supported with AWX: .. contents:: :local: -The credential types associated with Centrify, CyberArk, HashiCorp Vault, Microsoft Azure Key Management System (KMS), and Thycotic are part of the credential plugins capability that allows an external system to lookup your secrets information. See the :ref:`ug_credential_plugins` section for further detail. +The credential types associated with AWS Secrets Manager, Centrify, CyberArk, HashiCorp Vault, Microsoft Azure Key Management System (KMS), and Thycotic are part of the credential plugins capability that allows an external system to lookup your secrets information. See the :ref:`ug_credential_plugins` section for further detail. .. _ug_credentials_aws: @@ -166,6 +166,10 @@ AWX provides support for EC2 STS tokens (sometimes referred to as IAM STS creden To use implicit IAM role credentials, do not attach AWS cloud credentials in AWX when relying on IAM roles to access the AWS API. While it may seem to make sense to attach your AWS cloud credential to your job template, doing so will force the use of your AWS credentials and will not "fall through" to use your IAM role credentials (this is due to the use of the boto library.) +AWS Secrets Manager +^^^^^^^^^^^^^^^^^^^^^ +This is considered part of the secret management capability. See :ref:`ug_credentials_aws_lookup` for more detail. + Ansible Galaxy/Automation Hub API Token ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^