Integrate with AWS Secrets Manager

HCP Vault Secrets allows users to automatically synchronize application secrets to AWS Secrets Manager. This guide walks you through the configuration process.

Prerequisites:

Ability to create AWS IAM roles
Ability to create AWS IAM policies
An Admin role in an HCP Project
An HCP Vault Secrets application and secret(s)

Configuration

Navigate to the HCP Vault Secrets app you would like to integrate with your AWS account. From the sidebar, select Integrations then click on the AWS Secrets Manager card to initiate the setup.
If this is your first time configuring an AWS integration, you will be presented with four fields:
- Destination Name is the unique identifier and display name for this integration. It cannot be changed.
- External ID is a unique auto-generated value used in your AWS account to securely delegate access to HCP Vault Secrets. It will be needed when configuring your AWS IAM role.
- Role ARN is a AWS IAM role identifier that HCP Vault Secrets will assume in your AWS account. Instructions to provision this role can be found below.
- Region is the AWS region where your app secrets will be stored.
Once all fields are populated, click Save and sync secrets to complete the configuration process. It will immediately sync all your existing app secrets into your AWS Secrets Manager.

Going forward, all modification to the app's secrets are automatically replicated in your AWS account almost instantly.

Create IAM Role

The following sections provide step-by-step guidance to configure the AWS IAM role in your AWS account that HCP Vault Secrets will assume using the AWS console or HashiCorp Terraform.

Navigate to the Create New Policy section in the AWS IAM service

Select the JSON tab

Paste the following into the permissions policy editor:

{
   "Version": "2012-10-17",
   "Statement": [
      {
            "Sid": "HCPVaultSecretsAccess",
            "Effect": "Allow",
            "Action": [
               "secretsmanager:DescribeSecret",
               "secretsmanager:GetSecretValue",
               "secretsmanager:CreateSecret",
               "secretsmanager:PutSecretValue",
               "secretsmanager:UpdateSecret",
               "secretsmanager:UpdateSecretVersionStage",
               "secretsmanager:DeleteSecret",
               "secretsmanager:RestoreSecret",
               "secretsmanager:TagResource",
               "secretsmanager:UntagResource"
            ],
            "Resource": "*"
      }
   ]
}

Optionally provide tags
Name your policy
Click Create Policy

Navigate to the Create New Role section in the AWS IAM service

Select Custom trust policy option

Paste the following into the trust policy editor:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::879554817125:role/HCPVaultSecrets_Sync"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "sts:ExternalId": "<AWS_EXTERNAL_ID>"
                }
            }
        }
    ]
}

Populate the <AWS_EXTERNAL_ID> value with the AWS External ID of your HCP project.
Note
Your External ID can be found by navigating to the AWS sync integration page in HCP.
Attach the Policy that was created in the previous step
Name your role
Click Create Role

View the Role you created and copy its ARN
You now have everything you need to complete the configuration process!

You can equally use the Terraform AWS provider to provision an AWS IAM role with the appropriate policy.

Follow the Terraform documentation to authenticate the AWS provider.

Use your preferred text editor and create a Terraform configuration file with the following resources:

provider "aws" {
  // See https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication-and-configuration
  // for options on how to configure this provider. The following parameters or environment
  // variables are typically used.

  // Parameters:
  // access_key = ""
  // secret_key = ""
  // region     = ""

  // Environment variables:
  // AWS_ACCESS_KEY_ID
  // AWS_SECRET_ACCESS_KEY
  // AWS_REGION
}

variable "external_id" {
  type = string
  description = "External ID to securely delegate access to HCP Vault Secrets"
  sensitive = true
}

resource "aws_iam_role" "hashicorp_vault_secrets_role" {
  name = "HCPVaultSecrets"
  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Action = "sts:AssumeRole"
        Effect = "Allow"
        Principal = {
          AWS = "arn:aws:iam::879554817125:role/HCPVaultSecrets_Sync"
        }
        Condition = {
          StringEquals = {
            "sts:ExternalId" = var.external_id
          }
        }
      }
    ]
  })

  inline_policy {
    name   = "HCPVaultSecrets"
    policy = data.aws_iam_policy_document.hashicorp_vault_secrets_policy.json
  }
}

data "aws_iam_policy_document" "hashicorp_vault_secrets_policy" {
  statement {
    effect = "Allow"
    actions = [
      "secretsmanager:DescribeSecret",
      "secretsmanager:GetSecretValue",
      "secretsmanager:CreateSecret",
      "secretsmanager:PutSecretValue",
      "secretsmanager:UpdateSecret",
      "secretsmanager:UpdateSecretVersionStage",
      "secretsmanager:DeleteSecret",
      "secretsmanager:RestoreSecret",
      "secretsmanager:TagResource",
      "secretsmanager:UntagResource"
    ]
    resources = ["*"]
  }
}

output "role_arn" {
  description = "Role ARN to configure the AWS Secrets Manager Integration"
  value = aws_iam_role.hashicorp_vault_secrets_role.arn
}

Initialize Terraform.

$ terraform init

This will prepare a working directory:

...snip...

Terraform has been successfully initialized!

Generate your AWS IAM role with the apply command:

$ terraform apply

When prompted, paste the External ID value of your HCP project:

Note

Your External ID can be found by navigating to the AWS sync integration page in HCP.

...snip...

var.external_id
  External ID to securely delegate access to HCP Vault Secrets

  Enter a value: <AWS_EXTERNAL_ID>

Review the actions Terraform is about to perform and say yes to accept the plan:

...snip...

Plan: 1 to add, 0 to change, 0 to destroy.

Changes to Outputs:
   + role_arn = (known after apply)

Do you want to perform these actions?
   Terraform will perform the actions described above.
   Only 'yes' will be accepted to approve.

Enter a value: yes

Copy the AWS IAM Role from the Terraform outputs:

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Outputs:

role_arn = "arn:aws:iam::123456789012:role/HCPVaultSecrets"

You now have everything you need to complete the configuration process!