Skip to content

Latest commit

 

History

History
125 lines (100 loc) · 7.3 KB

README.md

File metadata and controls

125 lines (100 loc) · 7.3 KB
Raw

vault-lambda-extension

This repository contains the source code for Hashicorp's Vault AWS Lambda extension. The extension utilizes the AWS Lambda Extensions API to read secrets from your Vault deployment and write the result to disk before the Lambda function itself starts to execute. To use it, include the following ARN as a layer in your Lambda function:

arn:aws:lambda:us-east-1:634166935893:layer:vault-lambda-extension:6

Where region may be any of ap-northeast-1, ap-northeast-2, ap-south-1, ap-southeast-1, ap-southeast-2, ca-central-1, eu-central-1, eu-north-1, eu-west-1, eu-west-2, eu-west-3, sa-east-1, us-east-1, us-east-2, us-west-1, us-west-2.

The extension authenticates with Vault using AWS IAM auth, and writes the result as JSON to disk. It also writes a vault token to /tmp/vault/token. All configuration is supplied via environment variables.

Getting Started

Quick Start

The quick-start directory has an end to end example, for which you will need an AWS account and some command line tools. Follow the readme in that directory if you'd like to try out the extension from scratch. Please note it will create real infrastructure with an associated cost as per AWS' pricing.

Adding the extension to your existing Lambda and Vault infrastructure

Requirements:

  • ARN of the role your Lambda runs as
  • An instance of Vault accessible from AWS Lambda
  • An authenticated vault client
  • A secret in Vault that you want your Lambda to access, and a policy giving read access to it

First, set up AWS IAM auth on Vault, and attach a policy to your ARN:

vault auth enable aws
vault write -force auth/aws/config/client
vault write auth/aws/role/vault-lambda-role \
    auth_type=iam \
    bound_iam_principal_arn="${YOUR_ARN}" \
    policies="${YOUR_POLICY}" \
    ttl=1h

Add the extension to your Lambda layers using the console or cli:

arn:aws:lambda:<your-region>:634166935893:layer:vault-lambda-extension:6

Configure the extension using Lambda environment variables:

VAULT_ADDR=http://vault.example.com:8200    # Your Vault address
VAULT_AUTH_PROVIDER=aws                     # The AWS IAM auth mount point, i.e. the path segment after auth/ from above
VAULT_AUTH_ROLE=vault-lambda-role           # The Vault role to authenticate as. Must be configured for the ARN of your Lambda's role
VAULT_SECRET_PATH=secret/lambda-app/token   # The path to a secret in Vault. Can be static or dynamic.
                                            # Unless VAULT_SECRET_FILE is specified, JSON response will be written to /tmp/vault/secret.json

If everything is correctly set up, your Lambda function can then read secret material from /tmp/vault/secret.json. The exact contents of the JSON object will depend on the secret read, but its schema is the Secret struct from the Vault API module.

Configuration

The extension is configured via Lambda environment variables. Most of the Vault CLI client's environment variables are available, as well as some additional variables to configure auth, which secret(s) to read and where to write secrets. At least one valid secret to read must be specified.

Environment variable Description Required Example value
VAULT_ADDR Vault address to connect to Yes https://x.x.x.x:8200
VAULT_AUTH_PROVIDER Name of the configured AWS IAM auth route on Vault Yes aws
VAULT_AUTH_ROLE Vault role to authenticate as Yes lambda-app
VAULT_SECRET_PATH Secret path to read, written to /tmp/vault/secret.json unless VAULT_SECRET_FILE is specified No database/creds/lambda-app
VAULT_SECRET_FILE Path to write the JSON response for VAULT_SECRET_PATH No /tmp/db.json
VAULT_SECRET_PATH_FOO Additional secret path to read, where FOO can be any name, as long as a matching VAULT_SECRET_FILE_FOO is specified No secret/lambda-app/token
VAULT_SECRET_FILE_FOO Must exist for any correspondingly named VAULT_SECRET_PATH_FOO. Name has no further effect beyond matching to the correct path variable No /tmp/token

The remaining environment variables are not required, and function exactly as described in the Vault Commands (CLI) documentation. However, note that VAULT_CLIENT_TIMEOUT cannot extend the timeout beyond the 10s timeout imposed by the Extensions API.

Environment variable Description Required Example value
VAULT_CACERT Path to a PEM-encoded CA certificate file on the local disk No /tmp/ca.crt
VAULT_CAPATH Path to a directory of PEM-encoded CA certificate files on the local disk No /tmp/certs
VAULT_CLIENT_CERT Path to a PEM-encoded client certificate on the local disk No /tmp/client.crt
VAULT_CLIENT_KEY Path to an unencrypted, PEM-encoded private key on disk which corresponds to the matching client certificate No /tmp/client.key
VAULT_CLIENT_TIMEOUT Timeout for Vault requests. Default value is 60s. Any value over 10s will exceed the Extensions API timeout and therefore have no effect No 5s
VAULT_MAX_RETRIES Maximum number of retries on 5xx error codes. Defaults to 2 No 2
VAULT_SKIP_VERIFY Do not verify Vault's presented certificate before communicating with it. Setting this variable is not recommended and voids Vault's security model No true
VAULT_TLS_SERVER_NAME Name to use as the SNI host when connecting via TLS No vault.example.com
VAULT_RATE_LIMIT Only applies to a single invocation of the extension. See Vault Commands (CLI) documentation for details No 10
VAULT_NAMESPACE The namespace to use for the command No education
VAULT_SRV_LOOKUP The Vault client will lookup DNS SRV records for the host. See Vault Commands (CLI) documentation for details No true
VAULT_MFA MFA credentials. See Vault Commands (CLI) documentation for details No true

Limitations

For this early release, the extension does not support automatic secret renewal. This means once a secret is written to disk, it will not be refreshed once it expires. This may cause problems if you use provisioned concurrency or if your Lambda is invoked often enough that execution contexts live beyond the lifetime of the secret.