Quick Outline
In this article, we will learn:
- What is the AWS Secret Manager?
- What is the “get-secret-value” Command in AWS CLI?
- How to Use the “get-secret-value” Command in AWS CLI?
- Common Exceptions in the “get-secret-value” Command and their Solutions
- Final Thoughts
What is the AWS Secret Manager?
AWS Secret Manager is used to protect the confidential data of users such as OAuth tokens, database credentials, passwords, API keys, etc. This confidential information is known as a secret. By using the secrets, AWS Secret Manager eliminates the traditional practice of hard coding the credentials or storing them within the code. Hence, it improves the security posture of the application.
With AWS Secret Manager, the user can retrieve, manage, and rotate the secrets. The information within these secrets is accessed by making a run-time call to the AWS Secret Manager. The Secret Manager supports various services such as lambda, S3 buckets, etc. The user can interact with this service via the Console and CLI.
What is the “get-secret-value” Command in AWS CLI?
The “get-secret-value” command of AWS Secret Manager is used to retrieve the contents of the secrets. This one-line command reduces the number of steps and allows the user to retrieve the current as well as the previous version of a secret. Similarly, there are different parameters available that can be used in combination with this command such as version ID, secret ID, etc.
Prerequisites
There are a few prerequisites of this tutorial given as follows:
- AWS CLI is installed on Windows.
- AWS CLI credentials configured.
Read more: How to Configure AWS CLI Credentials on Windows, Linux, and Mac?
How to Use the “get-secret-value” Command in AWS CLI?
Before executing this command, ensure that the currently logged-in user has the “GetSecretValue” permission. Furthermore, to access an encrypted KMS secret, the user must be equipped with the “kms:Decrypt” permissions.
Syntax
The syntax for using this command in AWS CLI is given as follows:
A brief description of the <OptionalParameters> is given below:
- –secret-id: This field is a string and inputs the ARN or name of the secret that is to be accessed.
- –version-id: This field is used to specify the unique identifier of the version of the secret to be accessed. It accepts a string and is used with the “–version-stage”. If both these parameters are specified in the command, then the two parameters must refer to the same secret.
- –version-stage: This field is used to specify the version stage of the secret. The version stage accepts string values i.e., AWSPREVIOUS or AWSCURRENT.
- –cli-input-json: This option accepts a string and is used to provide instructions based on a JSON string to the service. This JSON string must be according to the format provided by the –generate-cli-skeleton. The values of the JSON string will be overwritten if other arguments are provided within the command.
- –generate-cli-skeleton: This option accepts a string value and is used to create a template or a JSON skeleton for the user. This template or skeleton will be used to provide instructions at once to the service. The JSON format is then used by the “–cli-input-json” option.
Examples
In this section of the article, we will discuss the following examples:
- Example 1: How to Get the Details of a Secret in AWS CLI?
- Example 2: How to Access a Secret’s Previous Version in AWS CLI?
- Example 3: How to Retrieve a Secret’s Current Version in AWS CLI?
- Example 4: How to Get the Key-Value Pairs of a Secret in AWS CLI?
- Example 5: How to Get Secret’s Details in the Tabular Format?
- Example 6: How to Get a Secret’s Value in a Specific Region?
- Example 7: How to Get a Binary Secret’s Value in AWS CLI?
Example 1: How to Get the Details of a Secret in AWS CLI?
The value of a secret configured in a Secrets Manager can be retrieved via a single command i.e., get-secret-value. We have already configured a secret in AWS Secrets Manager for this demo. To create or modify a secret via CLI, refer to this article: “How to Create and Modify a Secret in AWS Using CLI?”.
To acquire the value of a secret in Secrets Manager, use the below-mentioned command:
Note: Replace the value “my-first-secret” in the –secret-id with the name of your secret in AWS Secret Manager.
This command will return various secret details such as ARN, VersionID, CreatedDate, etc. The output of the command is as follows:
Example 2: How to Access a Secret’s Previous Version in AWS CLI?
With the “get-secret-value” command, users can retrieve the previous versions of a secret by specifying the version ID and the secret’s name. To access the previous version of a secret, provide the following command to the CLI:
Note: Replace the value “my-first-secret” with the name of your secret in Secrets Manager.
The output of the command is as follows:
Example 3: How to Retrieve a Secret’s Current Version in AWS CLI?
As we have navigated to a previous version of a secret by using the “get-secret-value” command, the user can also determine the details of the current version of the secret. The command to access a secret’s current version is given as follows:
Note: Replace the value “my-first-secret” in the –secret-id with your secret’s name in AWS Secret Manager.
In the output, we can see that the “VersionStages” has been shifted to the “AWSCURRENT”:
Example 4: How to Get the Key-Value Pairs of a Secret in AWS CLI?
AWS Secret Manager stores the information in the form of key-value pairs. To determine the content of these key-value pairs, the “get-secret-value” command can be used in the following way:
Note: Replace the value “my-first-secret” with the name of your secret in Secret Manager.
The output of the command is as follows:
Example 5: How to Get Secret’s Details in the Table Format?
There are various output formats in which the user can display the information of a secret. These formats include JSON, Table, YAML, and text. This functionality can be achieved with the use of a single command which is given as follows:
In the command:
- –secret-id: Replace the “my-first-secret” with your secret’s name.
- –output: The user can specify various output formats such as text, JSON, table, YAML, etc.
The output of the command is as follows:
Example 6: How to Get a Secret’s Value in a Specific Region?
Similarly, another use case of the “get-secret-value” command in AWS CLI is to access a secret in a specific region. For this purpose, use the following command:
In this command:
- –secret-id: Replace the value “my-first-secret” in the –secret-id option with the name of your secret in the AWS Secret Manager.
- –region: In this field, specify the region of your secret in the AWS Secret Manager
The output of the command is given as follows:
Example 7: How to Get a Binary Secret’s Value?
Binary secrets are those secrets that contain the data in the binary format. The details of such secrets are not visible on the Secret Manager console. To obtain the content of the binary secrets, provide the following command to AWS CLI:
In this command:
- –secret-id: In this field, replace the value “mybinarysecret” with your binary secret’s name.
- –output: This field specifies the output format i.e., text. The user can select other formats such as table, JSON, YAML, etc.
- |: It is a pipe operator that takes the output of one command as input for further processing.
- powershell -command: The binary secret contains the data in the binary format which must be decoded for the user to read and modify it. By default, the CMD in Windows does not contain the “base64” format. Therefore, this field is used which begins the processing of a PowerShell command in the command prompt.
- $input: This field represents the input from the pipe operator.
- FromBase64String(): This parameter is used to convert the input in the base64 format.
- [System.Text.Encoding]::UTF8.GetString(): This field converts the input into the UTF8 format.
Below is the output of the above command:
That’s all from this guide.
Common Exceptions in the “get-secret-value” Command And their Solutions
Commonly, two exceptions occur if a value or the length of the value provided for a parameter is incorrect. Below are the names and solutions of the two exceptions:
Exception 1: ResourceNotFound Exception
This error occurs when the name or the ARN of the secret provided in the –secret-id is incorrect.
Solution: To resolve this error, provide the correct name of the secret to the “–secret-id”.
Exception 2: Parameter Validation Failed
This error occurs when the value provided for the parameter has an invalid length:
Solution: To resolve this error, provide the correct value with the correct length to the options specified in the command.
Final Thoughts
To use the “get-secret-value” in AWS CLI, configure the AWS credentials and specify the parameters e.g., –secret-id and –version-stage to access the secret. Similarly, this command can also be used to access the binary secrets or the secrets that reside in a specific AWS region. AWS Secrets Manager prevents any possible compromise on the security of the application. This article presents a step-by-step demonstration of using the get-secret-value command in AWS CLI.
