AWS secretsmanager documentation change
Summary
Added documentation for cross-account secret retrieval using role chaining and pre-fetching secrets at startup. Updated configuration options and examples.
Security assessment
The changes document security features like cross-account access via IAM role chaining (requiring sts:AssumeRole permissions) and pre-fetch configuration. No evidence of addressing a specific vulnerability; these are feature enhancements explaining secure implementation patterns.
Diff
diff --git a/secretsmanager/latest/userguide/secrets-manager-agent.md b/secretsmanager/latest/userguide/secrets-manager-agent.md index 98c73fe78..01898d8c6 100644 --- a//secretsmanager/latest/userguide/secrets-manager-agent.md +++ b//secretsmanager/latest/userguide/secrets-manager-agent.md @@ -7 +7 @@ -How the Secrets Manager Agent worksUnderstanding Secrets Manager Agent cachingBuild the Secrets Manager AgentInstall the Secrets Manager AgentRetrieve secrets with the Secrets Manager AgentUnderstanding the refreshNow parameterConfiguration optionsOptional featuresLoggingSecurity considerations +How the Secrets Manager Agent worksUnderstanding Secrets Manager Agent cachingBuild the Secrets Manager AgentInstall the Secrets Manager AgentRetrieve secrets with the Secrets Manager AgentUnderstanding the refreshNow parameterRetrieve secrets across accounts with role chainingPre-fetch secrets at startupConfiguration optionsOptional featuresLoggingSecurity considerations @@ -27,0 +28,2 @@ The Secrets Manager Agent retrieves and caches secrets in memory, allowing your +The Secrets Manager Agent is open source. The source code, installation instructions, and latest release information are available on [GitHub](https://github.com/aws/aws-secretsmanager-agent). + @@ -60,0 +63,4 @@ The Secrets Manager Agent returns secret values in the same format as the respon + * Retrieve secrets across accounts with role chaining + + * Pre-fetch secrets at startup + @@ -444,4 +450,3 @@ The following curl example shows how to get a secret from the Secrets Manager Ag - curl -v -H \\ - "X-Aws-Parameters-Secrets-Token: $(</var/run/awssmatoken)" \\ - 'http://localhost:2773/secretsmanager/get?secretId=YOUR_SECRET_ID' \\ - echo + curl -v -H \ + "X-Aws-Parameters-Secrets-Token: $(</var/run/awssmatoken)" \ + 'http://localhost:2773/secretsmanager/get?secretId=YOUR_SECRET_ID' @@ -535,4 +540,3 @@ The following curl example shows how to force the Secrets Manager Agent to refre - curl -v -H \\ - "X-Aws-Parameters-Secrets-Token: $(</var/run/awssmatoken)" \\ - 'http://localhost:2773/secretsmanager/get?secretId=YOUR_SECRET_ID&refreshNow=true' \\ - echo + curl -v -H \ + "X-Aws-Parameters-Secrets-Token: $(</var/run/awssmatoken)" \ + 'http://localhost:2773/secretsmanager/get?secretId=YOUR_SECRET_ID&refreshNow=true' @@ -579,0 +584,158 @@ The following Python example shows how to get a secret from the Secrets Manager +## Retrieve secrets across accounts with role chaining + +Role chaining enables the Secrets Manager Agent to retrieve secrets from other AWS accounts by assuming IAM roles using AWS STS `AssumeRole`. The Secrets Manager Agent creates and caches a separate caching client for each unique role ARN. Each role client maintains its own independent cache, so the same secret fetched with different roles has separate cache entries. + +### Required permissions + +To use role chaining, you need the following: + + * The Secrets Manager Agent's environment credentials must have `sts:AssumeRole` permission on the target role ARN. + + * The target role must have `secretsmanager:GetSecretValue` and `secretsmanager:DescribeSecret` permissions for the secrets you want to access. + + * The target role's trust policy must allow the Secrets Manager Agent's identity to assume it. + + + + +### Retrieve cross-account secrets + +Include the `roleArn` query parameter in your request to the Secrets Manager Agent to specify which role to assume for the secret retrieval. + +curl + + +###### Example – Cross-account secret using curl + + + curl -v -H \ + "X-Aws-Parameters-Secrets-Token: $(</var/run/awssmatoken)" \ + 'http://localhost:2773/secretsmanager/get?secretId=YOUR_SECRET_ID&roleArn=arn:aws:iam::ACCOUNT_ID:role/ROLE_NAME' + +Python + + +###### Example – Cross-account secret using Python + + + import requests + + def get_secret_cross_account(): + secret_id = "YOUR_SECRET_ID" + role_arn = "arn:aws:iam::ACCOUNT_ID:role/ROLE_NAME" + url = f"http://localhost:2773/secretsmanager/get?secretId={secret_id}&roleArn={role_arn}" + + with open('/var/run/awssmatoken') as fp: + token = fp.read() + + headers = { + "X-Aws-Parameters-Secrets-Token": token.strip() + } + + try: + response = requests.get(url, headers=headers) + + if response.status_code == 200: + return response.text + else: + raise Exception(f"Status code {response.status_code} - {response.text}") + + except Exception as e: + raise Exception(f"Error: {e}") + +### Role chaining configuration and limits + +Configure role chaining with the `max_roles` option in your TOML configuration file. This sets the maximum number of simultaneous assumed roles, in the range 1 to 20. The default is 20. + +###### Important + +Assumed roles are not evicted from the Secrets Manager Agent's role cache. Once the maximum number of roles has been reached, requests with new role ARNs are rejected with a `400` error until the Secrets Manager Agent is restarted. + +###### Error responses for role chaining + +**`400`** + + +The `roleArn` format is invalid or the maximum number of assumed roles has been reached. + +**`403`** + + +The AWS STS `AssumeRole` call failed. Verify that the target role's trust policy allows the Secrets Manager Agent's identity to assume it. + +## Pre-fetch secrets at startup + +By default, the Secrets Manager Agent fetches secrets on demand when your application requests them. With pre-fetching, the Secrets Manager Agent loads specified secrets into the cache when it starts up, so your application can access them immediately without waiting for the first API call. Pre-fetching runs as a background task—the Secrets Manager Agent begins accepting requests immediately and does not block on pre-fetch completion. + +You can specify secrets to pre-fetch in two ways: + + * **Explicit secrets** – List specific secret IDs or ARNs. + + * **Tag-based discovery** – Discover secrets by tag key. The Secrets Manager Agent fetches all secrets that have the specified tag. + + + + +### Required permissions + +In addition to the standard permissions for retrieving secrets, pre-fetching requires the following: + + * `secretsmanager:BatchGetSecretValue` – Required for all pre-fetch operations. + + * `secretsmanager:ListSecrets` – Required only when using tag-based discovery. + + + + +### Configure pre-fetching + +Add a `[prefetch]` section to your TOML configuration file. The following options are available: + +**`cache_buffer_ratio`** + + +The maximum fraction of the cache to fill per client during pre-fetch, in the range 0.1 to 1.0. The default is 0.8. When the buffer limit is reached, the Secrets Manager Agent stops pre-fetching remaining secrets—it does not evict existing cache entries. Secrets not loaded during pre-fetch are still available on demand. + +**`max_jitter_seconds`** + + +A random delay in seconds before pre-fetching begins, in the range 0 to 10. The default is 0. Use this to prevent synchronized fleet-wide API calls when multiple agents start at the same time. + +###### Example Pre-fetch configuration with explicit secrets + + + [prefetch] + cache_buffer_ratio = 0.6 + max_jitter_seconds = 5 + secrets = [ + { secret_id = "arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret-AbCdEf" }, + { secret_id = "MyOtherSecret" }, + ] + +###### Example Pre-fetch configuration with tag-based discovery + + + [prefetch] + cache_buffer_ratio = 0.8 + filter_tags = [ + { key = "Environment" }, + { key = "Team" }, + ] + +You can also combine explicit secrets and tag-based discovery in the same configuration. For cross-account pre-fetching, add the `role_arn` field. For more information, see Retrieve secrets across accounts with role chaining. + +###### Example Pre-fetch configuration with cross-account access + + + [prefetch] + cache_buffer_ratio = 0.6 + max_jitter_seconds = 5 + secrets = [ + { secret_id = "arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret-AbCdEf" }, + { secret_id = "cross-account-secret", role_arn = "arn:aws:iam::987654321098:role/SecretAccessRole" }, + ] + filter_tags = [ + { key = "Environment" }, + { key = "Team", role_arn = "arn:aws:iam::987654321098:role/SecretAccessRole" }, + ] + @@ -635,0 +798,5 @@ The maximum number of connections from HTTP clients that the Secrets Manager Age +**`max_roles`** + + +The maximum number of simultaneous IAM roles for cross-account access, in the range 1 to 20. The default is 20. For more information, see Retrieve secrets across accounts with role chaining. +