terraform-aws-secretsmanager

Description

This repository contains a Terraform module to create and manage secrets in AWS Secrets Manager. It supports the creation of secrets with random or static values and secure access through IAM policies. The variable names is a list that will be used to create secrets for however many values are passed into the list.

Dependencies

No dependencies.

Resource List

• Secrets Manager Secret (e.g. username and/or password)
• Secret Policy
• Secret Version

Usage

The below examples demonstrate how you can call the AWS Secrets Manager module to create secrets as needed.

data "aws_organizations_organization" "current" {
  provider = aws.mgmt
}

module "credentials" {
  source = "github.com/Coalfire-CF/terraform-aws-secretsmanager?ref=v2.0.5"
  providers = {
    aws = aws.mgmt
  }

  kms_key_id = data.terraform_remote_state.account-setup.outputs.sm_kms_key_arn 

  secrets = [
    {
      secret_name        = "svc_paktesting"
      secret_description = "Creating test credentials for Pak Parties."
    }
  ]

  path                    = "${var.path}credentials/"
  partition               = local.partition
  recovery_window_in_days = var.recovery_window_in_days
  tags                    = local.global_tags

  # Random Password
  password_length = 20

  # Sharing
  shared = false #update to true and select utilize one of the options below
  #organization_ids  = [data.aws_organizations_organization.current.id] # Share with Organizations
  #cross_account_ids = [local.root_account_id]                          # Share across AWS Accounts, update local. to appropriate account ID
}

Environment Setup

Establish a secure connection to the Management AWS account used for the build:

IAM user authentication:

- Download and install the AWS CLI (https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
- Log into the AWS Console and create AWS CLI Credentials (https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)
- Configure the named profile used for the project, such as 'aws configure --profile example-mgmt'

SSO-based authentication (via IAM Identity Center SSO):

- Login to the AWS IAM Identity Center console, select the permission set for MGMT, and select the 'Access Keys' link.
- Choose the 'IAM Identity Center credentials' method to get the SSO Start URL and SSO Region values.
- Run the setup command 'aws configure sso --profile example-mgmt' and follow the prompts.
- Verify you can run AWS commands successfully, for example 'aws s3 ls --profile example-mgmt'.
- Run 'export AWS_PROFILE=example-mgmt' in your terminal to use the specific profile and avoid having to use '--profile' option.

Deployment Steps

1. Navigate to the Terraform project and create a parent directory in the upper level code, for example:

   ../aws/terraform/{REGION}/management-account/example

   If multi-account management plane:

   ../aws/terraform/{REGION}/{ACCOUNT_TYPE}-mgmt-account/example

2. Create a new branch. The branch name should provide a high level overview of what you're working on.

3. Create a properly defined main.tf file via the template found under 'Usage' while adjusting tfvars as needed. Note that many provided variables are outputs from other modules. Example parent directory:

   ├── Example/
   │   ├── prefix.auto.tfvars   
   │   ├── locals.tf
   │   ├── main.tf
   │   ├── outputs.tf
   │   ├── providers.tf
   │   ├── README.md
   │   ├── remote-data.tf
   │   ├── required-providers.tf
   │   ├── variables.tf
   │   ├── ...

4. Change directories to the secretsmanager directory.

5. Ensure that the prefix.auto.tfvars variables are correct (especially the profile) or create a new tfvars file with the correct variables

6. Customize code to meet requirements

7. From the secretsmanager directory run, initialize the Terraform working directory:

   terraform init

8. Standardized formatting in code:

   terraform fmt

9. Optional: Ensure proper syntax and "spell check" your code:

   terraform validate

10. Create an execution plan and verify everything looks correct:

    terraform plan

11. Apply the configuration:

    terraform apply

Requirements

Name	Version
terraform	>=1.10.0
aws	>= 5.85.0, < 6.0.0

Providers

Name	Version
aws	>= 5.85.0, < 6.0.0

Modules

No modules.

Resources

Name	Type
aws_secretsmanager_secret.this	resource
aws_secretsmanager_secret_policy.shared	resource
aws_secretsmanager_secret_version.this	resource
aws_iam_policy_document.resource_policy_MA	data source
aws_secretsmanager_random_password.random_passwords	data source

Inputs

Name	Description	Type	Default	Required
cross_account_ids	A list of strings containing the account IDs of AWS accounts that should have cross-account access to this secret	list(string)	[]	no
empty_value	Whether the secret should be generated without a value	bool	false	no
exclude_characters	String of the characters that you don't want in the password	string	"\" # $ % & ' ( ) * + , . / : ; < = > ? @ [ \\ ] ^ { | } ~"	no
exclude_lowercase	Specifies whether to exclude lowercase letters from the password	bool	false	no
exclude_numbers	Specifies whether to exclude numbers from the password	bool	false	no
exclude_punctuation	Specifies whether to exclude punctuation characters from the password: ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` {	} ~`	bool	false
exclude_uppercase	Specifies whether to exclude uppercase letters from the password	bool	false	no
global_tags	a map of strings that contains global level tags	map(string)	{}	no
include_space	Specifies whether to include the space character	bool	false	no
kms_key_id	Specifies the ARN or alias of the AWS KMS customer master key (CMK) to be used to encrypt the secret values in the versions stored in this secret.	string	n/a	yes
organization_ids	The AWS Organization ID to share secrets with. If specified, cross_account_ids will be ignored	list(string)	[]	no
partition	The AWS partition to use	string	n/a	yes
password_length	Length of the password	number	15	no
path	Path to organize secrets	string	n/a	yes
recovery_window_in_days	Number of days that AWS Secrets Manager waits before it can delete the secret.	number	30	no
regional_tags	a map of strings that contains regional level tags	map(string)	{}	no
replicas	List of regions to replicate the secret to. Each replica can optionally specify a KMS key	list(object({ region = string kms_key_arn = optional(string) }))	[]	no
require_each_included_type	Specifies whether to include at least one upper and lowercase letter, one number, and one punctuation	bool	true	no
secrets	Specifies the friendly name of the new secrets to be created as key and an optional value field for descriptions	list(map(string))	n/a	yes
shared	Whether secrets should be shared across accounts.	bool	false	no
tags	A mapping of tags to assign to the resource	map(string)	{}	no

Outputs

Name	Description
names	Returns list of secret names to be created.
path	Path to secret values
secret_arns	The ARN values of the generated secrets
secret_iam_policy_doc_json	JSON doc of the policy output to use on roles if desired
secrets	Returns all secrets generated by the secrets manager module

Contributing

Start Here

License

Contact Us

Coalfire

Copyright

Copyright © 2023 Coalfire Systems Inc.