Use AWS Secrets Manager secrets in AWS Lambda functions

You can use the AWS Parameters and Secrets Lambda Extension to retrieve and cache AWS Secrets Manager secrets in Lambda functions without using an SDK. Retrieving a cached secret is faster than retrieving it from Secrets Manager. Because there is a cost for calling Secrets Manager APIs, using a cache can reduce your costs. The extension can retrieve both Secrets Manager secrets and Parameter Store parameters. For information about Parameter Store, see Parameter Store integration with Lambda extensions in the AWS Systems Manager User Guide.

A Lambda extension is a companion process that adds to the capabilities of a Lambda function. For more information, see Lambda extensions in the Lambda Developer Guide. For information about using the extension in a container image, see Working with Lambda layers and extensions in container images . Lambda logs execution information about the extension along with the function by using Amazon CloudWatch Logs. By default, the extension logs a minimal amount of information to CloudWatch. To log more details, set the environment variable PARAMETERS_SECRETS_EXTENSION_LOG_LEVEL to debug.

To provide the in-memory cache for parameters and secrets, the extension exposes a local HTTP endpoint, localhost port 2773, to the Lambda environment. You can configure the port by setting the environment variable PARAMETERS_SECRETS_EXTENSION_HTTP_PORT.

Lambda instantiates separate instances corresponding to the concurrency level that your function requires. Each instance is isolated and maintains its own local cache of your configuration data. For more information about Lambda instances and concurrency, see Managing concurrency for a Lambda function in the Lambda Developer Guide.

To add the extension for ARM, you must use the arm64 architecture for your Lambda function. For more information, see Lambda instruction set architectures in the Lambda Developer Guide. The extension supports ARM in the following Regions: Asia Pacific (Mumbai), US East (Ohio), Europe (Ireland), Europe (Frankfurt), Europe (Zurich), US East (N. Virginia), Europe (London), Europe (Spain), Asia Pacific (Tokyo), US West (Oregon), Asia Pacific (Singapore), Asia Pacific (Hyderabad), and Asia Pacific (Sydney).

The extension uses an AWS client. For information about configuring the AWS client, see Settings reference in the AWS SDK and Tools Reference Guide. If your Lambda function runs in a VPC, you need to create a VPC endpoint so that the extension can make calls to Secrets Manager. For more information, see Using an AWS Secrets Manager VPC endpoint.

Required permissions:

• The Lambda execution role must have secretsmanager:GetSecretValue permission to the secret.

• If the secret is encrypted with a customer managed key instead of the AWS managed key aws/secretsmanager, the execution role also needs kms:Decrypt permission for the KMS key.

To use the AWS Parameters and Secrets Lambda Extension

1. Add the AWS layer named AWS Parameters and Secrets Lambda Extension to your function. For instructions, see Adding layers to functions in the Lambda Developer Guide. If you use the AWS CLI to add the layer, you need the ARN of the extension. For a list of ARNs, see AWS Parameters and Secrets Lambda Extension ARNs in the AWS Systems Manager User Guide.

2. Grant permissions to the Lambda execution role to be able to access secrets:

   • secretsmanager:GetSecretValue permission for the secret. See Example: Permission to retrieve individual secret values.

   • (Optional) If the secret is encrypted with a customer managed key instead of the AWS managed key aws/secretsmanager, the execution role also needs kms:Decrypt permission for the KMS key.

   • You can use Attribute Based Access Control (ABAC) with the Lambda role to allow for more granular access to secrets in the account. For more information, see Control access to secrets using attribute-based access control (ABAC) .

3. Configure the cache with Lambda environment variables.

4. To retrieve secrets from the extension cache, you first need to add the X-AWS-Parameters-Secrets-Token to the request header. Set the token to AWS_SESSION_TOKEN, which is provided by Lambda for all running functions. Using this header indicates that the caller is within the Lambda environment.

   The following Python example shows how to add the header.

   import os
   headers = {"X-Aws-Parameters-Secrets-Token": os.environ.get('AWS_SESSION_TOKEN')}

5. To retrieve a secret within the Lambda function, use one of the following HTTP GET requests:

   • To retrieve a secret, for secretId, use the ARN or name of the secret.

     GET: /secretsmanager/get?secretId=secretId

   • To retrieve the previous secret value or a specific version by staging label, for secretId, use the ARN or name of the secret, and for versionStage, use the staging label.

     GET: /secretsmanager/get?secretId=secretId&versionStage=AWSPREVIOUS

   • To retrieve a specific secret version by ID, for secretId, use the ARN or name of the secret, and for versionId, use the version ID.

     GET: /secretsmanager/get?secretId=secretId&versionId=versionId

   Example Retrieve a secret (Python)

   The following Python example shows how to retrieve a secret and parse the result using json.loads.

   secrets_extension_endpoint = "http://localhost:" + \
       secrets_extension_http_port + \
       "/secretsmanager/get?secretId=" + \
       <secret_name>
     
     r = requests.get(secrets_extension_endpoint, headers=headers)
     
     secret = json.loads(r.text)["SecretString"] # load the Secrets Manager response into a Python dictionary, access the secret

AWS Parameters and Secrets Lambda Extension environment variables

You can configure the extension with the following environment variables.

For information about how to use environment variables, see Using Lambda environment variables in the Lambda Developer Guide.

PARAMETERS_SECRETS_EXTENSION_CACHE_ENABLED

Set to true to cache parameters and secrets. Set to false for no caching. Default is true.

PARAMETERS_SECRETS_EXTENSION_CACHE_SIZE

The maximum number of secrets and parameters to cache. Must be a value from 0 to 1000. A value of 0 means there is no caching. This variable is ignored if both SSM_PARAMETER_STORE_TTL and SECRETS_MANAGER_TTL are 0. Default is 1000.

PARAMETERS_SECRETS_EXTENSION_HTTP_PORT

The port for the local HTTP server. Default is 2773.

PARAMETERS_SECRETS_EXTENSION_LOG_LEVEL

The level of logging the extension provides: debug, info, warn, error, or none. Set to debug to see the cache configuration. Default is info.

PARAMETERS_SECRETS_EXTENSION_MAX_CONNECTIONS

Maximum number of connections for HTTP clients that the extension uses to make requests to Parameter Store or Secrets Manager. This is a per-client configuration. Default is 3.

SECRETS_MANAGER_TIMEOUT_MILLIS

Timeout for requests to Secrets Manager in milliseconds. A value of 0 means there is no timeout. Default is 0.

SECRETS_MANAGER_TTL

TTL of a secret in the cache in seconds. A value of 0 means there is no caching. The maximum is 300 seconds. This variable is ignored if PARAMETERS_SECRETS_EXTENSION_CACHE_SIZE is 0. Default is 300 seconds.

SSM_PARAMETER_STORE_TIMEOUT_MILLIS

Timeout for requests to Parameter Store in milliseconds. A value of 0 means there is no timeout. Default is 0.

SSM_PARAMETER_STORE_TTL

TTL of a parameter in the cache in seconds. A value of 0 means there is no caching. The maximum is 300 seconds. This variable is ignored if PARAMETERS_SECRETS_EXTENSION_CACHE_SIZE is 0. Default is 300 seconds.