Introduction

AWS Secret Manager allows you to store sensitive data like passwords, API keys, certificates, and other secrets securely in the cloud. When you create a secret, you define what kind of information should be stored, how long it should last, and who has access to it. Secrets manager also provides additional features such as rotation of credentials, encryption at rest, and automatic expiration of credentials.

With Secrets Manager, you can replace hardcoded credentials in your code, including passwords. You can retrieve secrets programmatically with an API call to Secrets Manager.

In this article, we will look at how to use the AWS CLI to perform common Secrets Manager operations.

Table of contents

Prerequisites

  • AWS CLI
  • AWS Credentials: If you haven’t setup your AWS credentials before, this resource from AWS is helpful.

How to create a new secret?

We will be using the create-secret subcommand to create a new secret. The arguments needed for this command are:

  • name: Name of the secret you want to create
  • secret-binary: Value of the secret in binary format
  • secret-string: Value of the secret in string format
  • kms-key-id (optional): Custom KMS key to be used to encrypt the secret. By default, Secrets Manager uses the AWS managed key aws/secretsmanager.

You only need to provide either the secret value in binary or string format.

aws secretsmanager create-secret --name my-test-secret --secret-string test-secret-value

Output:

{
    "ARN": "arn:aws:secretsmanager:us-west-1:xxx:secret:my-test-secret-kOVjat",
    "Name": "my-test-secret",
    "VersionId": "773cae67-c42a-451d-a1b2-596142157a4b"
}

How to list all secrets?

We can use the list-secrets subcommand to list all the secrets in your AWS account.

aws secretsmanager list-secrets

Output:

{
    "SecretList": [
        {
            "ARN": "arn:aws:secretsmanager:us-west-1:xxx:secret:my-test-secret-kOVjat",
            "Name": "my-test-secret",
            "LastChangedDate": "2022-08-28T14:28:15.440000-07:00",
            "SecretVersionsToStages": {
                "773cae67-c42a-451d-a1b2-596142157a4b": [
                    "AWSCURRENT"
                ]
            },
            "CreatedDate": "2022-08-28T14:28:15.405000-07:00"
        }
    ]
}

How to retrieve a secret value?

We will use the get-secret-value subcommand to retrieve the value of the secret. The arguments needed for this command are:

  • secret-id: ARN or Name of the secret to retrieve.
  • version-id: ID of the version to retrieve
aws secretsmanager get-secret-value --secret-id my-test-secret

Output:

{
    "ARN": "arn:aws:secretsmanager:us-west-1:xxxx:secret:my-test-secret-kOVjat",
    "Name": "my-test-secret",
    "VersionId": "773cae67-c42a-451d-a1b2-596142157a4b",
    "SecretString": "test-secret-value",
    "VersionStages": [
        "AWSCURRENT"
    ],
    "CreatedDate": "2022-08-28T14:28:15.435000-07:00"
}

How to modify an existing secret?

We can update the secret using the update-secret subcommand. Secrets are immutable. update-secret does not modify the existing secret. Instead, it creates a new version of the secret.

aws secretsmanager update-secret --secret-id my-test-secret --secret-string update-secret-value

Output:

{
    "ARN": "arn:aws:secretsmanager:us-west-1:xxxx:secret:my-test-secret-kOVjat",
    "Name": "my-test-secret",
    "VersionId": "fd3381fb-260b-47a6-88ef-f2a8a56a10c8"
}

How to list all versions of a secret?

We can use the list-secret-version-ids command to list all versions of a particular secret.

aws secretsmanager list-secret-version-ids --secret-id my-test-secret

Output:


{
    "Versions": [
        {
            "VersionId": "773cae67-c42a-451d-a1b2-596142157a4b",
            "VersionStages": [
                "AWSPREVIOUS"
            ],
            "LastAccessedDate": "2022-08-27T17:00:00-07:00",
            "CreatedDate": "2022-08-28T14:28:15.435000-07:00",
            "KmsKeyIds": [
                "DefaultEncryptionKey"
            ]
        },
        {
            "VersionId": "fd3381fb-260b-47a6-88ef-f2a8a56a10c8",
            "VersionStages": [
                "AWSCURRENT"
            ],
            "CreatedDate": "2022-08-28T14:43:35.596000-07:00",
            "KmsKeyIds": [
                "DefaultEncryptionKey"
            ]
        }
    ],
    "ARN": "arn:aws:secretsmanager:us-west-1:xxx:secret:my-test-secret-kOVjat",
    "Name": "my-test-secret"
}

How to list all versions of a secret?

We can use the list-secret-version-ids command to list all versions of a particular secret.

aws secretsmanager list-secret-version-ids --secret-id my-test-secret

Output:


{
    "Versions": [
        {
            "VersionId": "773cae67-c42a-451d-a1b2-596142157a4b",
            "VersionStages": [
                "AWSPREVIOUS"
            ],
            "LastAccessedDate": "2022-08-27T17:00:00-07:00",
            "CreatedDate": "2022-08-28T14:28:15.435000-07:00",
            "KmsKeyIds": [
                "DefaultEncryptionKey"
            ]
        },
        {
            "VersionId": "fd3381fb-260b-47a6-88ef-f2a8a56a10c8",
            "VersionStages": [
                "AWSCURRENT"
            ],
            "CreatedDate": "2022-08-28T14:43:35.596000-07:00",
            "KmsKeyIds": [
                "DefaultEncryptionKey"
            ]
        }
    ],
    "ARN": "arn:aws:secretsmanager:us-west-1:xxx:secret:my-test-secret-kOVjat",
    "Name": "my-test-secret"
}

How to delete a secret?

We can use the delete-secret command to delete a secret and all its versions. By default, any deleted secrets can be retrieved within 30 days of deletion.

Arguments used in this command:

  • recovery-window-in-days: Number of days (between 7 to 30 days) that Secrets Manager waits before permanently deleting the secret
  • force-delete-without-recovery: Whether to delete the secret without any recovery
aws secretsmanager delete-secret --secret-id my-test-secret

Output:


{
    "ARN": "arn:aws:secretsmanager:us-west-1:xxxx:secret:my-test-secret-kOVjat",
    "Name": "my-test-secret",
    "DeletionDate": "2022-09-27T15:07:24.259000-07:00"
}