2022/01/28 - AWS Secrets Manager - 3 updated api methods
Changes Feature are ready to release on Jan 28th
{'RotationRules': {'Duration': 'string', 'ScheduleExpression': 'string'}}
Retrieves the details of a secret. It does not include the encrypted secret value. Secrets Manager only returns fields that have a value in the response.
Required permissions: secretsmanager:DescribeSecret. For more information, see IAM policy actions for Secrets Manager and Authentication and access control in Secrets Manager.
See also: AWS API Documentation
Request Syntax
client.describe_secret(
SecretId='string'
)
string
[REQUIRED]
The ARN or name of the secret.
For an ARN, we recommend that you specify a complete ARN rather than a partial ARN.
dict
Response Syntax
{
'ARN': 'string',
'Name': 'string',
'Description': 'string',
'KmsKeyId': 'string',
'RotationEnabled': True|False,
'RotationLambdaARN': 'string',
'RotationRules': {
'AutomaticallyAfterDays': 123,
'Duration': 'string',
'ScheduleExpression': 'string'
},
'LastRotatedDate': datetime(2015, 1, 1),
'LastChangedDate': datetime(2015, 1, 1),
'LastAccessedDate': datetime(2015, 1, 1),
'DeletedDate': datetime(2015, 1, 1),
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'VersionIdsToStages': {
'string': [
'string',
]
},
'OwningService': 'string',
'CreatedDate': datetime(2015, 1, 1),
'PrimaryRegion': 'string',
'ReplicationStatus': [
{
'Region': 'string',
'KmsKeyId': 'string',
'Status': 'InSync'|'Failed'|'InProgress',
'StatusMessage': 'string',
'LastAccessedDate': datetime(2015, 1, 1)
},
]
}
Response Structure
(dict) --
ARN (string) --
The ARN of the secret.
Name (string) --
The name of the secret.
Description (string) --
The description of the secret.
KmsKeyId (string) --
The ARN of the KMS key that Secrets Manager uses to encrypt the secret value. If the secret is encrypted with the Amazon Web Services managed key aws/secretsmanager, this field is omitted.
RotationEnabled (boolean) --
Specifies whether automatic rotation is turned on for this secret.
To turn on rotation, use RotateSecret. To turn off rotation, use CancelRotateSecret.
RotationLambdaARN (string) --
The ARN of the Lambda function that Secrets Manager invokes to rotate the secret.
RotationRules (dict) --
The rotation schedule and Lambda function for this secret. If the secret previously had rotation turned on, but it is now turned off, this field shows the previous rotation schedule and rotation function. If the secret never had rotation turned on, this field is omitted.
AutomaticallyAfterDays (integer) --
The number of days between automatic scheduled rotations of the secret. You can use this value to check that your secret meets your compliance guidelines for how often secrets must be rotated.
In DescribeSecret and ListSecrets, this value is calculated from the rotation schedule after every successful rotation. In RotateSecret, you can set the rotation schedule in RotationRules with AutomaticallyAfterDays or ScheduleExpression, but not both.
Duration (string) --
The length of the rotation window in hours, for example 3h for a three hour window. Secrets Manager rotates your secret at any time during this window. The window must not go into the next UTC day. If you don't specify this value, the window automatically ends at the end of the UTC day. The window begins according to the ScheduleExpression. For more information, including examples, see Schedule expressions in Secrets Manager rotation.
ScheduleExpression (string) --
A cron() or rate() expression that defines the schedule for rotating your secret. Secrets Manager rotation schedules use UTC time zone.
Secrets Manager rate() expressions represent the interval in days that you want to rotate your secret, for example rate(10 days). If you use a rate() expression, the rotation window opens at midnight, and Secrets Manager rotates your secret any time that day after midnight. You can set a Duration to shorten the rotation window.
You can use a cron() expression to create rotation schedules that are more detailed than a rotation interval. For more information, including examples, see Schedule expressions in Secrets Manager rotation. If you use a cron() expression, Secrets Manager rotates your secret any time during that day after the window opens. For example, cron(0 8 1 * ? *) represents a rotation window that occurs on the first day of every month beginning at 8:00 AM UTC. Secrets Manager rotates the secret any time that day after 8:00 AM. You can set a Duration to shorten the rotation window.
LastRotatedDate (datetime) --
The last date and time that Secrets Manager rotated the secret. If the secret isn't configured for rotation, Secrets Manager returns null.
LastChangedDate (datetime) --
The last date and time that this secret was modified in any way.
LastAccessedDate (datetime) --
The last date that the secret value was retrieved. This value does not include the time. This field is omitted if the secret has never been retrieved.
DeletedDate (datetime) --
The date the secret is scheduled for deletion. If it is not scheduled for deletion, this field is omitted. When you delete a secret, Secrets Manager requires a recovery window of at least 7 days before deleting the secret. Some time after the deleted date, Secrets Manager deletes the secret, including all of its versions.
If a secret is scheduled for deletion, then its details, including the encrypted secret value, is not accessible. To cancel a scheduled deletion and restore access to the secret, use RestoreSecret.
Tags (list) --
The list of tags attached to the secret. To add tags to a secret, use TagResource. To remove tags, use UntagResource.
(dict) --
A structure that contains information about a tag.
Key (string) --
The key identifier, or name, of the tag.
Value (string) --
The string value associated with the key of the tag.
VersionIdsToStages (dict) --
A list of the versions of the secret that have staging labels attached. Versions that don't have staging labels are considered deprecated and Secrets Manager can delete them.
Secrets Manager uses staging labels to indicate the status of a secret version during rotation. The three staging labels for rotation are:
AWSCURRENT, which indicates the current version of the secret.
AWSPENDING, which indicates the version of the secret that contains new secret information that will become the next current version when rotation finishes. During rotation, Secrets Manager creates an AWSPENDING version ID before creating the new secret version. To check if a secret version exists, call GetSecretValue.
AWSPREVIOUS, which indicates the previous current version of the secret. You can use this as the last known good version.
For more information about rotation and staging labels, see How rotation works.
(string) --
(list) --
(string) --
OwningService (string) --
The name of the service that created this secret.
CreatedDate (datetime) --
The date the secret was created.
PrimaryRegion (string) --
The Region the secret is in. If a secret is replicated to other Regions, the replicas are listed in ReplicationStatus.
ReplicationStatus (list) --
A list of the replicas of this secret and their status:
Failed, which indicates that the replica was not created.
InProgress, which indicates that Secrets Manager is in the process of creating the replica.
InSync, which indicates that the replica was created.
(dict) --
A replication object consisting of a RegionReplicationStatus object and includes a Region, KMSKeyId, status, and status message.
Region (string) --
The Region where replication occurs.
KmsKeyId (string) --
Can be an ARN, Key ID, or Alias.
Status (string) --
The status can be InProgress, Failed, or InSync.
StatusMessage (string) --
Status message such as "Secret with this name already exists in this region".
LastAccessedDate (datetime) --
The date that you last accessed the secret in the Region.
{'SecretList': {'RotationRules': {'Duration': 'string',
'ScheduleExpression': 'string'}}}
Lists the secrets that are stored by Secrets Manager in the Amazon Web Services account.
To list the versions of a secret, use ListSecretVersionIds.
To get the secret value from SecretString or SecretBinary, call GetSecretValue.
For information about finding secrets in the console, see Enhanced search capabilities for secrets in Secrets Manager.
Required permissions: secretsmanager:ListSecrets. For more information, see IAM policy actions for Secrets Manager and Authentication and access control in Secrets Manager.
See also: AWS API Documentation
Request Syntax
client.list_secrets(
MaxResults=123,
NextToken='string',
Filters=[
{
'Key': 'description'|'name'|'tag-key'|'tag-value'|'primary-region'|'all',
'Values': [
'string',
]
},
],
SortOrder='asc'|'desc'
)
integer
The number of results to include in the response.
If there are more results available, in the response, Secrets Manager includes NextToken. To get the next results, call ListSecrets again with the value from NextToken.
string
A token that indicates where the output should continue from, if a previous call did not show all results. To get the next results, call ListSecrets again with this value.
list
The filters to apply to the list of secrets.
(dict) --
Allows you to add filters when you use the search function in Secrets Manager. For more information, see Find secrets in Secrets Manager.
Key (string) --
The following are keys you can use:
description: Prefix match, not case-sensitive.
name: Prefix match, case-sensitive.
tag-key: Prefix match, case-sensitive.
tag-value: Prefix match, case-sensitive.
primary-region: Prefix match, case-sensitive.
all: Breaks the filter value string into words and then searches all attributes for matches. Not case-sensitive.
Values (list) --
The keyword to filter for.
You can prefix your search value with an exclamation mark ( !) in order to perform negation filters.
(string) --
string
Lists secrets in the requested order.
dict
Response Syntax
{
'SecretList': [
{
'ARN': 'string',
'Name': 'string',
'Description': 'string',
'KmsKeyId': 'string',
'RotationEnabled': True|False,
'RotationLambdaARN': 'string',
'RotationRules': {
'AutomaticallyAfterDays': 123,
'Duration': 'string',
'ScheduleExpression': 'string'
},
'LastRotatedDate': datetime(2015, 1, 1),
'LastChangedDate': datetime(2015, 1, 1),
'LastAccessedDate': datetime(2015, 1, 1),
'DeletedDate': datetime(2015, 1, 1),
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'SecretVersionsToStages': {
'string': [
'string',
]
},
'OwningService': 'string',
'CreatedDate': datetime(2015, 1, 1),
'PrimaryRegion': 'string'
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
SecretList (list) --
A list of the secrets in the account.
(dict) --
A structure that contains the details about a secret. It does not include the encrypted SecretString and SecretBinary values. To get those values, use GetSecretValue .
ARN (string) --
The Amazon Resource Name (ARN) of the secret.
Name (string) --
The friendly name of the secret. You can use forward slashes in the name to represent a path hierarchy. For example, /prod/databases/dbserver1 could represent the secret for a server named dbserver1 in the folder databases in the folder prod.
Description (string) --
The user-provided description of the secret.
KmsKeyId (string) --
The ARN of the KMS key that Secrets Manager uses to encrypt the secret value. If the secret is encrypted with the Amazon Web Services managed key aws/secretsmanager, this field is omitted.
RotationEnabled (boolean) --
Indicates whether automatic, scheduled rotation is enabled for this secret.
RotationLambdaARN (string) --
The ARN of an Amazon Web Services Lambda function invoked by Secrets Manager to rotate and expire the secret either automatically per the schedule or manually by a call to RotateSecret.
RotationRules (dict) --
A structure that defines the rotation configuration for the secret.
AutomaticallyAfterDays (integer) --
The number of days between automatic scheduled rotations of the secret. You can use this value to check that your secret meets your compliance guidelines for how often secrets must be rotated.
In DescribeSecret and ListSecrets, this value is calculated from the rotation schedule after every successful rotation. In RotateSecret, you can set the rotation schedule in RotationRules with AutomaticallyAfterDays or ScheduleExpression, but not both.
Duration (string) --
The length of the rotation window in hours, for example 3h for a three hour window. Secrets Manager rotates your secret at any time during this window. The window must not go into the next UTC day. If you don't specify this value, the window automatically ends at the end of the UTC day. The window begins according to the ScheduleExpression. For more information, including examples, see Schedule expressions in Secrets Manager rotation.
ScheduleExpression (string) --
A cron() or rate() expression that defines the schedule for rotating your secret. Secrets Manager rotation schedules use UTC time zone.
Secrets Manager rate() expressions represent the interval in days that you want to rotate your secret, for example rate(10 days). If you use a rate() expression, the rotation window opens at midnight, and Secrets Manager rotates your secret any time that day after midnight. You can set a Duration to shorten the rotation window.
You can use a cron() expression to create rotation schedules that are more detailed than a rotation interval. For more information, including examples, see Schedule expressions in Secrets Manager rotation. If you use a cron() expression, Secrets Manager rotates your secret any time during that day after the window opens. For example, cron(0 8 1 * ? *) represents a rotation window that occurs on the first day of every month beginning at 8:00 AM UTC. Secrets Manager rotates the secret any time that day after 8:00 AM. You can set a Duration to shorten the rotation window.
LastRotatedDate (datetime) --
The most recent date and time that the Secrets Manager rotation process was successfully completed. This value is null if the secret hasn't ever rotated.
LastChangedDate (datetime) --
The last date and time that this secret was modified in any way.
LastAccessedDate (datetime) --
The last date that this secret was accessed. This value is truncated to midnight of the date and therefore shows only the date, not the time.
DeletedDate (datetime) --
The date and time the deletion of the secret occurred. Not present on active secrets. The secret can be recovered until the number of days in the recovery window has passed, as specified in the RecoveryWindowInDays parameter of the DeleteSecret operation.
Tags (list) --
The list of user-defined tags associated with the secret. To add tags to a secret, use TagResource. To remove tags, use UntagResource.
(dict) --
A structure that contains information about a tag.
Key (string) --
The key identifier, or name, of the tag.
Value (string) --
The string value associated with the key of the tag.
SecretVersionsToStages (dict) --
A list of all of the currently assigned SecretVersionStage staging labels and the SecretVersionId attached to each one. Staging labels are used to keep track of the different versions during the rotation process.
(string) --
(list) --
(string) --
OwningService (string) --
Returns the name of the service that created the secret.
CreatedDate (datetime) --
The date and time when a secret was created.
PrimaryRegion (string) --
The Region where Secrets Manager originated the secret.
NextToken (string) --
Secrets Manager includes this value if there's more output available than what is included in the current response. This can occur even when the response includes no values at all, such as when you ask for a filtered view of a long list. To get the next results, call ListSecrets again with this value.
{'RotateImmediately': 'boolean',
'RotationRules': {'Duration': 'string', 'ScheduleExpression': 'string'}}
Configures and starts the asynchronous process of rotating the secret.
If you include the configuration parameters, the operation sets the values for the secret and then immediately starts a rotation. If you don't include the configuration parameters, the operation starts a rotation with the values already stored in the secret. For more information about rotation, see Rotate secrets.
To configure rotation, you include the ARN of an Amazon Web Services Lambda function and the schedule for the rotation. The Lambda rotation function creates a new version of the secret and creates or updates the credentials on the database or service to match. After testing the new credentials, the function marks the new secret version with the staging label AWSCURRENT. Then anyone who retrieves the secret gets the new version. For more information, see How rotation works.
When rotation is successful, the AWSPENDING staging label might be attached to the same version as the AWSCURRENT version, or it might not be attached to any version.
If the AWSPENDING staging label is present but not attached to the same version as AWSCURRENT, then any later invocation of RotateSecret assumes that a previous rotation request is still in progress and returns an error.
Required permissions: secretsmanager:RotateSecret. For more information, see IAM policy actions for Secrets Manager and Authentication and access control in Secrets Manager. You also need lambda:InvokeFunction permissions on the rotation function. For more information, see Permissions for rotation.
See also: AWS API Documentation
Request Syntax
client.rotate_secret(
SecretId='string',
ClientRequestToken='string',
RotationLambdaARN='string',
RotationRules={
'AutomaticallyAfterDays': 123,
'Duration': 'string',
'ScheduleExpression': 'string'
},
RotateImmediately=True|False
)
string
[REQUIRED]
The ARN or name of the secret to rotate.
For an ARN, we recommend that you specify a complete ARN rather than a partial ARN.
string
A unique identifier for the new version of the secret that helps ensure idempotency. Secrets Manager uses this value to prevent the accidental creation of duplicate versions if there are failures and retries during rotation. This value becomes the VersionId of the new version.
If you use the Amazon Web Services CLI or one of the Amazon Web Services SDK to call this operation, then you can leave this parameter empty. The CLI or SDK generates a random UUID for you and includes that in the request for this parameter. If you don't use the SDK and instead generate a raw HTTP request to the Secrets Manager service endpoint, then you must generate a ClientRequestToken yourself for new versions and include that value in the request.
You only need to specify this value if you implement your own retry logic and you want to ensure that Secrets Manager doesn't attempt to create a secret version twice. We recommend that you generate a UUID-type value to ensure uniqueness within the specified secret.
This field is autopopulated if not provided.
string
The ARN of the Lambda rotation function that can rotate the secret.
dict
A structure that defines the rotation configuration for this secret.
AutomaticallyAfterDays (integer) --
The number of days between automatic scheduled rotations of the secret. You can use this value to check that your secret meets your compliance guidelines for how often secrets must be rotated.
In DescribeSecret and ListSecrets, this value is calculated from the rotation schedule after every successful rotation. In RotateSecret, you can set the rotation schedule in RotationRules with AutomaticallyAfterDays or ScheduleExpression, but not both.
Duration (string) --
The length of the rotation window in hours, for example 3h for a three hour window. Secrets Manager rotates your secret at any time during this window. The window must not go into the next UTC day. If you don't specify this value, the window automatically ends at the end of the UTC day. The window begins according to the ScheduleExpression. For more information, including examples, see Schedule expressions in Secrets Manager rotation.
ScheduleExpression (string) --
A cron() or rate() expression that defines the schedule for rotating your secret. Secrets Manager rotation schedules use UTC time zone.
Secrets Manager rate() expressions represent the interval in days that you want to rotate your secret, for example rate(10 days). If you use a rate() expression, the rotation window opens at midnight, and Secrets Manager rotates your secret any time that day after midnight. You can set a Duration to shorten the rotation window.
You can use a cron() expression to create rotation schedules that are more detailed than a rotation interval. For more information, including examples, see Schedule expressions in Secrets Manager rotation. If you use a cron() expression, Secrets Manager rotates your secret any time during that day after the window opens. For example, cron(0 8 1 * ? *) represents a rotation window that occurs on the first day of every month beginning at 8:00 AM UTC. Secrets Manager rotates the secret any time that day after 8:00 AM. You can set a Duration to shorten the rotation window.
boolean
Specifies whether to rotate the secret immediately or wait until the next scheduled rotation window. The rotation schedule is defined in RotateSecretRequest$RotationRules.
If you don't immediately rotate the secret, Secrets Manager tests the rotation configuration by running the testSecret step of the Lambda rotation function. The test creates an AWSPENDING version of the secret and then removes it.
If you don't specify this value, then by default, Secrets Manager rotates the secret immediately.
dict
Response Syntax
{
'ARN': 'string',
'Name': 'string',
'VersionId': 'string'
}
Response Structure
(dict) --
ARN (string) --
The ARN of the secret.
Name (string) --
The name of the secret.
VersionId (string) --
The ID of the new version of the secret.