AWS Lambda to rotate Secret in AWS Secretsmanager

AWS Lambda function to rotate secret's version, e.g. database access credentials, stored in AWS Secretsmanager.

• How it works
  • The Lambda Module
    • Plugins
    • List of Plugins
    • Plugin Codebase Structure
• Contribution
• Development
  • Requirements
  • Commands

How it works

[C4 Container] Architecture Diagram.

The diagram illustrates the process of secret's rotation.

Upon invocation, the AWS Lambda's logic executes the following steps:

1. Create Secret: new version of the "Secret User" secret is generated and stored in the staging label AWSPENDING;
2. Set Secret: newly generated secret's version is set in the "System delegated credentials store";
3. Test Secret: newly generated secret's version is tested against the "System delegated credentials store";
4. Finish Secret: newly generated secret's version is moved from the stage AWSPENDING to AWSCURRENT.

Note that the secret is expected to be JSON-encoded.

The Lambda Module

The AWS Lambda's logic defined in the Go module is encapsulated in two interfaces:

• SecretsmanagerClient: defines communication with the secrets vault, i.e. AWS Secretsmanager;
• ServiceClient: defines communication with the system which credentials are stored in the vault. The interface's methods define the logic to perform the rotation steps 1-3. The client uses the secret "Secret Admin" to pass authentication and authorization in order to reset the credentials "Secret User".

The AWS Lambda handler is defined as the function Start configured with the object of the type Config. The config includes the following attributes:

• Clients, i.e. instances of SecretsmanagerClient and ServiceClient;
• SecretObj: the type defining the structure of the secret "Secret User";
• Debug: flag to activate debug level logs.

Plugins

The lambda module defines the interfaces and abstract methods only. The implementation for specific "System delegated credentials store" is done as a plugin which defines the signatures of ServiceClient according to the system's specs. Every plugin is distributed as a separate Go module.

List of Plugins

• neon: plugin to change user's password in the Neon SaaS Postgres service.
• confluent: plugin to rotate Confluent Cloud API keys.

Plugin Codebase Structure

Every plugin is stored in the directory plugin.

It is recommended to use the template to develop and distribute plugin's codebase:

.
|-- README.md
|-- go.mod                <- Definition of Go module: github.com/kislerdm/aws-lambda-secret-rotation/plugin/{{.PluginName}}
|-- go.sum
|-- models.go             <- Types defining structure of "Secret User" and "Secret Admin"         
|-- serviceclient.go      <- Implementation of `ServiceClient` interface
|-- serviceclient_test.go
|-- .release_notes        <- release notes following https://keepachangelog.com/en/1.0.0/
|   |-- v0.0.1.md
|   |-- ...   
|   `-- vx.y.z.md
|-- cmd
|   `-- lambda
|       `-- main.go       <- AWS Lambda handler's definition
`-- example               <- (optional) terraform example to provision resources to rotate "Secret User" secret

Contribution

The codebase is distributed under the MIT license. Please feel free to open an issue ticket, or PR to contribute.

Development

Requirements

• go ~> 1.19
• gnuMake

Commands

Run to see available commands:

make help

Run to test the lambda module:

make tests

Run to test a plugin module:

make test-plugin PLUGIN=##name-of-the-plugin##

For example, to run unit tests for the Neon plugin:

make test-plugin PLUGIN=neon

Run to build lambda binary for selected plugin:

make build PLUGIN=##name-of-the-plugin##

For example, to run unit tests for the Neon plugin:

make build PLUGIN=neon