> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/harness-platform/use-harness-platform/secrets/secrets-management/add-an-aws-secret-manager.md). # Add an AWS secrets manager You can integrate AWS Secrets Manager to securely manage your Harness secrets. Unlike AWS KMS, AWS Secrets Manager stores both secrets and their encrypted keys. In contrast, AWS KMS requires Harness to store the secret in its own store while retrieving the encryption keys from KMS. For more details on using AWS KMS as a Secrets Manager, refer to [Add an AWS KMS Secrets Manager](/harness-platform/use-harness-platform/secrets/secrets-management/add-an-aws-kms-secrets-manager.md). This guide explains the steps to add an AWS Secrets Manager in Harness." {% hint style="info" %} **IMPORTANT** You can **only use Harness Built-in Secret Manager to** [**store authentication credentials**](/harness-platform/use-harness-platform/secrets/secrets-management/store-authentication-credentials.md) for access to the corresponding secret manager. Storing credentials from one secret manager within another can result in complex and challenging situations. Moreover, these configurations might introduce vulnerabilities, posing potential security risks. The Harness platform has several validations, including the disabling of self-references. {% endhint %} {% hint style="info" %} **THINGS TO KNOW** * If you're adding an AWS Secrets Manager on ROSA, set the environment variable `AWS_REGION` to the appropriate region, such as `AWS_REGION=us-east-1`. {% endhint %} #### Permissions: Test AWS Permissions Harness uses the same minimum IAM policies for AWS secret manager access as the AWS CLI. The AWS account you use for the AWS Secret Manager must have the following policies at a minimum: ```json { "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": [ "secretsmanager:Describe*", "secretsmanager:Get*", "secretsmanager:List*" ], "Resource": "*" } } ``` These policies let you list secrets which will allow you to add the secret manager and refer to secrets, but it will not let you read secrets values. The following policy list enables Harness to perform all the secrets operations you might need: ```json { "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": [ "secretsmanager:CreateSecret", "secretsmanager:DescribeSecret", "secretsmanager:DeleteSecret", "secretsmanager:GetRandomPassword", "secretsmanager:GetSecretValue", "secretsmanager:ListSecretVersionIds", "secretsmanager:ListSecrets", "secretsmanager:UpdateSecret", "secretsmanager:TagResource" ], "Resource": "*" } } ``` {% hint style="info" %} **ADDITIONAL PERMISSIONS FOR CUSTOM ENCRYPTION KEYS** If you plan to use customer-managed KMS keys for encrypting secrets, ensure the IAM policy includes the following KMS permissions: ```json { "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": [ "kms:GenerateDataKey", "kms:Decrypt", "kms:Encrypt" ], "Resource": "*" } } ``` These permissions allow Harness to encrypt and decrypt secrets using customer-managed keys. For more information on KMS key permissions, refer to the AWS documentation on [Key policies in AWS KMS](https://docs.aws.amazon.com/secretsmanager/latest/userguide/security-encryption.html#security-encryption-authz). {% endhint %} Refer to the AWS documentation on [Using Identity-based Policies (IAM Policies) for Secret Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_identity-based-policies.html). To test, use your AWS account and run the command [aws secretsmanager list-secrets](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/list-secrets.html#examples) on the Harness Delegate host or any other host. #### Step 1: Add a Secret Manager This topic assumes you have a Harness Project set up. If not, refer to [Create Organizations and Projects](/harness-platform/new-to-harness-platform/get-started.md#create-an-organization). You can add a connector from any module in your Project in Project SETUP, or in your Organization, or Account Resources. 1. Select one of the following settings: **Project**, **Organization**, or **Account**. 2. Navigate to **(Account/Organization/Project)-level Resources**. 3. Click on **Connectors**. 4. Click on **New Connectors**. 5. Scroll down and check for **Secret Manager**. 6. Select **AWS Secrets Manager**. Below is an example for adding to the **Account**. ![secret-manager](/files/qVGf706ALMffzI2ybfep) {% hint style="info" %} **NOTE** For information on restrictions on names and maximum quotas, go to [Quotas for AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_limits.html). {% endhint %} #### Step 2: Overview 1. Enter a **Name** for your secret manager. 2. You can either update the **ID** or keep it the same as your secret manager's name. For more information, visit [Entity Identifier Reference](/harness-platform/use-harness-platform/references/entity-identifier-reference.md). 3. Provide a **Description** for your secret manager. 4. Enter **Tags** for your secret manager. 5. Select **Continue**. #### Step 3: Credential Details When setting up your AWS Secrets Manager in Harness, you can choose one of the following **Credential Types** for authentication: 1. **AWS Access Key** 2. **Assume IAM Role on Delegate** 3. **Assume Role Using STS on Delegate** 4. **OIDC** **General Settings for All Credential Types** 1. Use **"put-secret-value"** Action to update secret value: * By default, Harness uses the `UpdateSecret` action to update secret values, which requires the `secretsmanager:UpdateSecret` permission for AWS Secrets Manager. Enable this option to use the `PutSecretValue` action instead, requiring the `secretsmanager:PutSecretValue` permission.

This item requires Harness Delegate version 24.11.84500. For more details about the Harness Delegate feature, please refer to the release notes.

2. Use as **Default Secrets Manager**: * Enable this option to set this Secrets Manager the default for all secret operations within your Harness account. 3. **Force delete without recovery**: * Force Delete Without Recovery: Enabling this option ensures that when a secret in AWS Secrets Manager is deleted, it will be permanently removed without any recovery window. The secret is deleted immediately, and recovery is not possible. * Recovery Window in Days (Optional): When specified, a delete request is made to AWS with the provided recovery window. Although the secret is deleted in Harness, it can be recovered in AWS Secrets Manager within the specified window. The recovery window can range from 7 to 30 days, with 30 days being the default if not specified. ![force-delete-without-recovery](/files/tbAqA7PG9IkKLz3cEsrA)

IMPORTANT NOTE

Force Delete without Recovery

- If a user attempts to create the same secret (as an inline secret) again in Harness, an exception will be thrown. - Additionally, **Force Delete Without Recovery** cannot be enabled when a recovery window value is provided. ![aws-encryted-text](../../../.gitbook/assets/aws-encryted-text.png)

``` #### Credential Types ``` #### 1. AWS Access Key Use your AWS IAM user login credentials for authentication. ![aws-secret-manager-access-key](/files/Wi2WaPZc25CONrYHd11Y) #### Prerequisites * **Access Key ID** and **Secret Access Key**: Obtain these from the JSON Key Policy or the AWS **IAM** console under **Encryption Keys**. * For detailed instructions, see [Finding the Key ID and ARN](https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html#find-cmk-id-arn) in the AWS documentation. #### Providing AWS Access Key ID You have two options for adding the **Access Key ID**: * **Plaintext**: * Enter the Access Key ID directly into the **AWS Access Key ID** field. * **Encrypted**: * Click **Create or Select a Secret**. * In the dialog, create or select a [Secret](/harness-platform/use-harness-platform/secrets/add-use-text-secrets.md) and enter the Access Key ID as the secret value. * Save and use the created secret for this configuration. #### Providing AWS Secret Access Key ``` - Click **Create or Select a Secret**. - Create or select an existing [Secret](../add-use-text-secrets.md) with the Secret Access Key as its value. ``` #### Additional Fields ``` - **Secret Name Prefix**: Add a prefix to all secrets stored under this Secrets Manager. For example, using `devops` as the prefix results in secrets like `devops/mysecret`. This is not a folder name. - **Region**: Select the appropriate AWS region for your Secrets Manager. ``` #### 2. Assume IAM Role on Delegate With this option, Harness uses the IAM role assigned to the AWS host running the selected Delegate for authentication. ![aws-secret-manager-iam-role](/files/2eK4GpOSYGaKLynMkQmj) {% hint style="info" %} **NOT VALID FOR IRSA-BASED DELEGATES** **Assume IAM Role on Delegate** isn't valid for IAM roles for service accounts (IRSA). If your Harness Delegate runs in an EKS cluster configured with IRSA, use IRSA instead. Go to [Assume IAM Role vs Use IRSA](/harness-platform/use-harness-platform/connectors/cloud-providers/ref-cloud-providers/aws-connector-settings-reference.md#assume-iam-role-vs-use-irsa) to determine which option your delegate needs. {% endhint %} #### Prerequisites * Ensure the Delegate host has the appropriate IAM role assigned. #### Additional Fields * Refer to the **Secret Name Prefix** and **Region** settings described under the AWS Access Key section above. #### 3. Assume Role Using STS on Delegate Harness uses AWS Security Token Service (STS) to assume a role. This option is commonly used for cross-account access or assuming roles within the same AWS account. ![aws-secret-manager-sts-on-delegate](/files/VWnZDym0uxiIivzAmhsu) #### Prerequisites * Configure an IAM role in the target AWS account. #### Required Fields * **Role ARN**: Enter the Amazon Resource Name (ARN) of the role you want to assume. * **External ID**: If provided by the account administrator, enter the External ID for additional security. See [AWS External ID documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html) for more details. * **Assume Role Duration**: Specify the session duration for the assumed role. For more information, refer to the [AssumeRole API documentation](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html). #### Additional Fields * Refer to the **Secret Name Prefix** and **Region** settings described under the AWS Access Key section above. #### 4. OIDC - OpenID Connect Harness uses OpenID Connect (OIDC) to authenticate and authorize users. This option is commonly used for secure identity federation across different applications or cloud platforms, enabling seamless authentication and access management. ![oidc-connect](/files/XMe8Vz0nZ3CZnMQVSVgM) * Configure an IAM role in the target AWS account. * Once your configuration is complete, set the IAM role and region below to proceed with the setup, as shown in the image above. * **Delegate Selectors for Access Control** (optional): You can use delegate selectors in OIDC tokens to restrict access to secrets based on which delegates execute tasks. This is useful for enforcing environment-level boundaries. For more information, go to [Delegate selectors as session tags](/harness-platform/use-harness-platform/connectors/cloud-providers/ref-cloud-providers/aws-connector-settings-reference.md#delegate-selectors-as-session-tags).
An additional step before proceeding. \#### Connectivity mode This additional step allows you to select the connectivity mode. Once you have selected OIDC, you will be able to select **connectivity mode**, based on the requirement you can select the provider that can be either connect through a **delegate** or through **Harness platform**. ![connetivity-mode](/files/IZ4QabSDaRTNqJljw52h)
#### Step 4: Setup Delegates In **Setup Delegates,** enter [**Selectors**](/harness-platform/use-harness-platform/delegates/delegate/manage-delegates/select-delegates-with-selectors.md#option-select-a-delegate-for-a-connector-using-tags) for specific **Delegates** that you want to allow to connect to this connector. #### Step 5: Test Connection Once the Test Connection succeeds, select **Finish**. You can now see the connector in **Connectors**. ### Inline Secret in AWS Secrets Manager Once you've configured your AWS Secrets Manager connector, you can create inline secrets directly in Harness. Inline secrets are secrets that Harness creates and manages in your AWS Secrets Manager. #### Create a Text or file Secret To create an inline text secret in AWS Secrets Manager: 1. In your Harness account, select **Account Settings**. 2. Select **Account Resources** and then select **Secrets**. You can also create secrets at the organization and project scopes based on your requirements. 3. Select **New Secret** and then select **Text**. The **Add new Encrypted Text** window appears. 4. Select the AWS Secrets Manager connector you created. 5. Enter a **Name** for your secret. 6. You can choose to update the **ID** or keep it the same as your secret's name. 7. Enter a **Description** and **Tags** for your secret (optional). 8. Select **Inline Secret Value**. 9. Enter the **Secret Value** in case of a text secret or upload the file secret. 10. **Encryption Key** (optional): Select the encryption key to use for encrypting this secret.
  1. Selecting a Customer managed Key (CMK) for encryption is supported in Harness Delegate version 25.11.87300 or later and is behind the feature flag PL_ENABLE_NON_DEFAULT_ENCRYPTION_KEY. Contact Harness Support to enable the feature.
  2. This option would be unavailable if the AWS Secret Manager connector has the option Use "put-secret-value" action to update secret value enabled.
* **Default**: `aws/secretsmanager` - If no encryption key is provided, the AWS-managed default encryption key for Secrets Manager is used. * **Customer-Managed Key**: Add the customer-managed KMS key available in your AWS account for encrypting the secret. The following are considered as valid inputs: * Alias: If alias is provided it should be in the following format `alias/`, eg, `alias/aws/secretsmanager` uses the AWS-managed default Secret Manager key. * Key ID * ARN Ensure your IAM role or user has the necessary KMS permissions as described in the [Permissions section](#permissions-test-aws-permissions).

You can encrypt using the default KMS key that AWS Secrets Manager creates or a customer-managed KMS key. Customer-managed keys provide additional control over key rotation, access policies, and auditing. Refer AWS documentation for more details.

11. Select **Save**. The secret is now created in AWS Secrets Manager and encrypted with your selected encryption key. #### Edit a Secret and change Encryption Key You can edit existing inline secrets stored in AWS Secrets Manager and change their encryption keys. When you change the encryption key, AWS Secrets Manager automatically re-encrypts the secret with the new key. To edit a secret and change its encryption key: 1. Navigate to your secrets list in Harness (Account, Organization, or Project level). 2. Locate the secret you want to edit. 3. Select the **More Options** menu (⋮) and select **Edit**. 4. In the edit dialog, you'll see the **Encryption Key** field displaying the currently selected encryption key.
  1. Selecting a Customer managed Key (CMK) for encryption is supported in Harness Delegate version 25.11.87300 or later and is behind the feature flag PL_ENABLE_NON_DEFAULT_ENCRYPTION_KEY. Contact Harness Support to enable the feature.
  2. This option would be unavailable if the AWS Secret Manager connector has the option Use "put-secret-value" action to update secret value enabled.
5. To change the encryption key, add a different key from the dropdown. The following are considered as valid inputs: * Alias: If alias is provided it should be in the following format `alias/`, eg, `alias/aws/secretsmanager` uses the AWS-managed default Secret Manager key. * Key ID * ARN 6. Select **Save**. {% hint style="info" %} When you change the encryption key for an existing secret, AWS Secrets Manager re-encrypts the secret with the new key. This operation is performed automatically and does not affect the secret's value or accessibility. For more information, refer to the AWS documentation on [Update the KMS key for a secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_update-encryption-key.html). {% endhint %} {% hint style="warning" %} The encryption key selection is only available for inline secrets. For referenced secrets, the encryption key is managed directly in AWS Secrets Manager. {% endhint %} ### Reference an AWS Secrets Manager Secret In order to reference your AWS Secrets Manager secret, customers have a few options to retrieve the secret They can either retrieve the secret directly through a Referenced JSON secret, or they can utilize a "referenced secret" type. The benefit to utilizing a referenced secret is that it allows for some more complicated conditions to be utilized, and customers can update the referenced secret at one location, instead at every reference point. #### Reference JSON secrets Harness allows you to manage the lifecycle of your secrets independently by referencing JSON secrets in the vault. For example, you can store a secret in vault with the following JSON. ```json { "key1": "value1", "key2": { "key21": "value21", "key22": "value22" }, "key3": { "key31": { "key311": "value311" } } } ``` Here are sample outputs for the respective JSONPath from the above JSON file: `test-secret` (without any # key) ```json { "key1": "value1", "key2": { "key21": "value21", "key22": "value22" }, "key3": { "key31": { "key311": "value311" } } } ``` `test-secret#key1` ``` "value1" ``` `test-secret#key2` ```json { "key21": "value21", "key22": "value22" } ``` `test-secret#key3` ```json { "key31": { "key311": "value311" } } ``` `test-secret#key3.key31` ```json { "key311": "value311" } ``` `test-secret#key3.key31.key311` ``` "value311" ``` {% hint style="info" %} You cannot use a JSON XPath for nested keys in expressions. For example, `<+secrets.getValue("account.YOUR_SECRET_MANAGER://myVault/harness/testpath/example")>`. Harness provides limited support for keys that include dots. Keys with dots only work when the key is present at first level in the JSON. For example: ```json { "key.abc": "some-value", "key": { "nested.key1": "some-value" }, "key.pqr": { "nestedKey": "some-value" }, "pqr.xyz": "some-value", "pqr": { "xyz": "some-nested-value" } } ``` Here are sample outputs for the respective JSONPath from the above JSON file: * `/path/to/secret#key.abc` returns `some-value`. * `/path/to/secret#key.pqr` returns `{"nestedKey": "some-value"}`. * `/path/to/secret#key.nested.key1` and `key.pqr.nestedKey` are not supported. * `/path/to/secret#pqr.xyz` returns `some-nested-value` and not `some-value`. (Hierarchical paths take precedence over keys with dots.) {% endhint %} {% hint style="warning" %} Harness does not recommend using keys that include dots and might deprecate support in future releases. {% endhint %} #### Referenced AWS Secrets Manager Secret Customers can create a referenced secret and establish a link to the secret within AWS and test that reference. [The following are instructions about how to establish the connection, and how to refer to the secret](/harness-platform/use-harness-platform/secrets/secrets-management/reference-existing-secret-manager-secrets.md#option-aws-secrets-manager-secrets). If the key or secret reference need to updated in the future, this also provides a centralized location to make the change. #### Cross Account AWS Secrets Manager Secrets Customers looking to reference Cross Account Secrets will need to use [Harness Secrets References](/harness-platform/use-harness-platform/secrets/secrets-management/reference-existing-secret-manager-secrets.md#option-aws-secrets-manager-secrets) to pull the secret from the correct account. This is because by default, any connector to an AWS secrets manager will utilize the role in the delegate, but the secret reference will default to the account that the role resides in. In Cross Account references, the user needs to be able to definie the account to access. **Example** The Cross Account Role resides in `AWSAccountEast`, and the team has set up an AWS Secrets Manager Connector. The team then needs to reference a key in `AWSAccountWest`. If teams attempt to call a secret directly using the expression for JSON Reference, `<+secrets.getValue("account.YOUR_SECRET_MANAGER://myVault/harness/testpath/example")>`, this will fail as there is no method to specify the account. It will end up looking for the secret in `AWSAccountEast` instead of `AWSAccountWest`. To reference that secret, Harness users should utilize secret references to get keys that reside in a cross-account, and not a direct reference. 1. Go to your Secrets, under your Harness Settings (Account/Org/Project level settings, depending on where the secret and AWS Secrets Manager Connector Reside) 2. Create a new `secret` ![](/files/HMQZe268isD4Q2k0hSzl) 3. Change the secrets manager to the `AWS Manager` that has been created already. (This should be residing in `AWSAccountEast` in our example) and click \`Apply Selected ![](/files/FeOBJ6zIISm9qNIO2Wkc) 4. Fill in all additional details such as the `Secrets Name`, `ID`, `Tags` and `Description`. 5. Change the radiobutton to the `Referenced Secret` choice. ![](/files/HIMpVzi28p6gbQr5IF6A) 6. In the field for the Reference Secret, enter the ARN and key that the team is accessing. The format should mimic `arn:aws:secretsmanager:REGION:ACCOUNT_ID:harness/testsecret#secrekey`, where the Region and Account match `AWSAccountWest` in our example. This now allows you to refer to the account you want to access the secret from, while still using the role in the correct base account. 7. Refer to the secret by its location and ID `<+secrets.getValue("account.secretname")>`