AWS CLI Secrets Manager: In-Depth Tutorial With Examples

AWS CLI Secrets Manager: In-Depth Tutorial With Examples

The AWS Secrets Manager helps users manage and protect their sensitive information in the AWS cloud. It automates the process of securing, rotating, and retrieving secrets like database credentials or API keys so organizations reduce the risk of unauthorized access and maintain compliance with industry standards.

Users can interact with the service using the AWS Command Line Interface (CLI). It provides a simple and efficient way to manage secrets, create and update secret values, and configure rotation policies. With AWS CLI, Secrets Manager can be integrated into existing workflows to automate the management of secrets.

This article explores the top six commands for Secrets Manager in CLI. We also share additional tips on optimizing usage for enhanced protection and efficiency.

Useful AWS CLI Secrets Manager commands

The rest of the article discusses the most commonly used AWS CLI secrets manager commands in detail.

Setting up AWS CLI Secrets Manager

We will install and configure the AWS CLI before running the commands.

1. Download and install the package for your operating system from the AWS website.
2. Verify the installation by running aws --version command.
3. Follow this AWS guide to create an IAM user with the appropriate IAM role.

After creating an IAM user configure the CLI by running aws configure command as follows.

• Enter your AWS Access Key ID and AWS Secret Access Key when prompted
• Enter your preferred AWS region
• Enter your preferred output format.

The command examples in this article use JSON for their output format. After completing these steps, your AWS CLI should be installed and configured, ready to manage your AWS services.

Command—create secret

You can use the create-secret command to store sensitive information, such as database credentials, API keys, or other secrets that your applications and services need to access. Here are some useful `create-secret` command options:

• --name: The name of the secret you want to create. This name should be unique within your account and region.
• --secret-string: The actual secret value you want to store. This can be a plain text string or a JSON object containing multiple key-value pairs.
• --secret-binary: If your secret is in binary format, you can use this option to provide the secret as a base64-encoded string.
• --kms-key-id: The ID of the AWS Key Management Service (KMS) key used to encrypt the secret. If not specified, the default KMS key for your account is used.

For example, let's say you want to store the credentials for a database named mydb with a username dbuser and a password dbpassword. The following command creates a new secret named mydb-credentials with the given username and password.

1aws secretsmanager create-secret --name mydb-credentials --secret-string '{"username":"dbuser", "password":"dbpassword"}' --description "Credentials for mydb database"

1{
2	"ARN": "arn:aws:secretsmanager:ap-south-1:987654321098:secret:mydb-credentials-7hXy1a",
3	"Name": "mydb-credentials",
4	"VersionId": "d5e4c3b2-a198-7f6e-5d4c-3b2a1f0d9e8c"
5}

Command—get secret value

The get-secret-value command is used to retrieve the value of a secret stored in AWS Secrets Manager. This command is particularly helpful when you need to access the secret value for your application or service. These are the important options for this command.

• --secret-id: The name or ARN of the secret you want to retrieve.
• --version-stage: The version stage of the secret you want to retrieve. If not specified, the default version stage is used.
• --version-id: The ID of the version of the secret you want to retrieve. If not specified, the default version is used.

For example, let's say you want to retrieve the credentials for the mydb database stored previously in AWS Secrets Manager. The following command retrieves the secret value and information.

1aws secretsmanager get-secret-value --secret-id mydb-credentials

1{
2	"ARN": "arn:aws:secretsmanager:ap-south-1:987654321098:secret:mydb-credentials-7hXy1a",
3	"Name": "mydb-credentials",
4	"VersionId": "d5e4c3b2-a198-7f6e-5d4c-3b2a1f0d9e8c",
5	"SecretString": "{\"username\":\"dbuser\", \"password\":\"dbpassword\"}",
6	"VersionStages": [
7    	"AWSCURRENT"
8	],
9	"CreatedDate": "2023-09-12T10:30:00Z"
10}

Command—update secret

The update-secret command modifies an existing secret stored in AWS Secrets Manager. This command is particularly helpful when you need to update the value of a secret, such as changing a password or API key.

Here's a detailed explanation of the various options for the update-secret command and how to use them:

• --secret-id: The name or ARN of the secret you want to update.
• --secret-string: The new secret value you want to store. This can be a plain text string or a JSON object containing multiple key-value pairs.
• --secret-binary: If your new secret is in binary format, you can use this option to provide the secret as a base64-encoded string.
• --description: An optional new description for the secret.
• --kms-key-id: The ID of the AWS KMS key used to encrypt the secret. If not specified, the default KMS key for your account is used.

For example, let's say you need to update the password for the mydb database. The AWS CLI Secret Manager script for updates is as below.

1aws secretsmanager update-secret --secret-id mydb-credentials --secret-string '{"username":"dbuser", "password":"newpassword"}' --description "Updated credentials for mydb database"

Command—rotate secret

The rotate-secret command rotates a secret stored in AWS Secrets Manager. It can create rotation schedules and integrate with other AWS services like Aurora and RDS. It uses Lambda functions to automatically update the integrated applications and databases with the new secret value.

Here's a detailed explanation of the various options for the rotate-secret command and how to use them:

• --secret-id: The name or ARN of the secret you want to rotate.
• --client-request-token: An optional unique identifier for the request. If not specified, a UUID is generated automatically.
• --rotation-lambda-arn: The ARN of the AWS Lambda function is used to rotate the secret value. This Lambda function should be configured to retrieve the current secret value, generate a new secret value, and update the secret in AWS Secrets Manager.

For example, let's say you want to rotate the credentials for the mydb database every 30 days. You can rotate the secret with the following command:

1aws secretsmanager rotate-secret --secret-id mydb-credentials --rotation-lambda-arn arn:aws:lambda:us-east-1:123456789012:function:mydb-rotate

Command—put resource policy

You can use the put-resource-policy to put a resource policy on a secret stored in the AWS Secrets Manager. The resource policy is an additional layer of access control. A policy can give or deny other IAM roles and users permission to manage the secret. Note that attaching a policy to a secret is optional.

Here's a detailed explanation of the various options for the rotate-secret command and how to use them:

• --secret-id: The name or ARN of the secret you want to put a resource policy on.
• --resource-policy: The file path to resource policy
• --block-public-policy | --no-block-public-policy: Specifies whether to disallow putting policies that allow broad public access. By default, broad public access policies are allowed.

For example, if you want to allow your DB admin to access the database credentials secret, you can apply the policy using the following command.

1aws secretsmanager put-resource-policy --secret-id mydb-credentials --resource-policy file://mypolicy.json --block-public-policy

The policy file declares a policy to allow DB admin roles to have access to the secret.

1{
2    "Version": "2012-10-17",
3    "Statement": [
4        {
5            "Effect": "Allow",
6            "Principal": {
7                "AWS": "arn:aws:iam::987654321098:role/DBAdmin"
8            },
9            "Action": "secretsmanager:GetSecretValue",
10            "Resource": "arn:aws:secretsmanager:ap-south-1:987654321098:secret:mydb-credentials-7hXy1a"
11        }
12    ]
13}

Command—list secret version ids

You can use the list-secret-version-ids command to list all version IDs for a secret stored in AWS Secrets Manager. It is useful when you want to see the history of changes made to a secret over time or when you need to retrieve an older version of a secret.

Here's a detailed explanation of the various options for the list-secret-version-ids command and how to use them:

• --secret-id: The name or ARN of the secret you want to list the version IDs for.
• --max-results: The maximum number of version IDs to return in the response.
• --next-token: The token to use to retrieve the next page of results.

For example, let's say you want to view the different versions of the mydb-credentials secret stored in AWS Secrets Manager. You can list the version IDs with the following command:

1aws secretsmanager list-secret-version-ids --secret-id mydb-credentials

When you execute this command, you will receive a response that includes the version IDs, their metadata, and a NextToken value if there are more results to retrieve. You can use the NextToken value to retrieve the next page of results.

Tips for using the AWS CLI Secrets Manager

We share some additional tips below on how to best use the AWS CLI for Secrets Manager.

Rotating vs. updating secrets

The `rotate-secret` command should be preferred over the `update-secret` command for most production use cases. It automatically rotates the secrets while ensuring proper versioning is maintained. Moreover, it has in-built integration with AWS services like RDS and Aurora and also supports custom integrations via Lambda functions. The integrations allow updating consuming applications or databases with the new secret. This is the preferred method for maintaining secure access to resources.

Deleting secrets

AWS Secrets Manager is designed to ensure the security and availability of your sensitive information. When you update, rotate, or even delete a secret, it is not permanently removed from the system; instead, it undergoes a "soft delete" process. The secret is marked as deleted but remains recoverable for a certain configurable period between 7 and 30 days, allowing you to restore it using the `restore-secret` command. This feature protects against accidental deletion or modification of your secrets, ensuring that your critical data remains accessible for a few days, even if an unintended change occurs.

Organizing secrets

The AWS CLI only supports commands for AWS services. Moreover, the AWS Secrets Manager service has native integrations only for other AWS services. Users need to implement Lambda functions to integrate with other applications and services, making secret management a challenging task, particularly when dealing with applications and services running in non-AWS environments.

Doppler addresses the challenge of organizing secrets by providing a centralized, secure, and user-friendly platform for managing sensitive information across various environments and applications. It offers a unified dashboard that enables developers to access and manage secrets for different platforms and languages easily.

Doppler's environment-based approach allows developers to segregate secrets according to their respective environments, such as local development, staging, and production. It simplifies secret organization and ensures that the right secrets are used in the right context.

Conclusion

The AWS Secrets Manager is a powerful service that allows you to securely store and manage secrets such as database credentials, API keys, and other sensitive information. It provides an easy-to-use interface for managing secrets and integrates seamlessly with other AWS services. The AWS CLI for Secrets Manager makes it possible to create, retrieve, update, rotate, and manage the different versions of your secrets right from the terminal. However, the CLI has limitations and is restricted to the AWS environment. You can use Doppler to manage secrets across multiple environments, including AWS cloud.