README
¶
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 diagram illustrates the process of secret's rotation.
Upon invocation, the AWS Lambda's logic executes the following steps:
- Create Secret: new version of the "Secret User" secret is generated and stored in the staging label AWSPENDING;
- Set Secret: newly generated secret's version is set in the "System delegated credentials store";
- Test Secret: newly generated secret's version is tested against the "System delegated credentials store";
- 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
SecretsmanagerClientandServiceClient; 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
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
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ExtractSecretObject ¶
func ExtractSecretObject(v *secretsmanager.GetSecretValueOutput, secret any) error
ExtractSecretObject deserializes secret value to a Go object of the secret type.
Types ¶
type Config ¶
type Config struct {
// SecretsmanagerClient the client's instance to communicate with the secretsmanager.
SecretsmanagerClient SecretsmanagerClient
// ServiceClient the client's instance to communicate with the service delegated credentials storage.
ServiceClient ServiceClient
// SecretObj defines the interface of the secret to rotate.
SecretObj any
// Debug set to `true` to activate debug level logs.
Debug bool
}
Config defines the rotation lambda's configuration.
type SecretsmanagerClient ¶
type SecretsmanagerClient interface {
GetSecretValue(
ctx context.Context, input *secretsmanager.GetSecretValueInput, optFns ...func(*secretsmanager.Options),
) (*secretsmanager.GetSecretValueOutput, error)
PutSecretValue(
ctx context.Context, input *secretsmanager.PutSecretValueInput, optFns ...func(*secretsmanager.Options),
) (*secretsmanager.PutSecretValueOutput, error)
DescribeSecret(
ctx context.Context, input *secretsmanager.DescribeSecretInput, optFns ...func(*secretsmanager.Options),
) (
*secretsmanager.DescribeSecretOutput, error,
)
UpdateSecretVersionStage(
ctx context.Context, input *secretsmanager.UpdateSecretVersionStageInput,
optFns ...func(*secretsmanager.Options),
) (*secretsmanager.UpdateSecretVersionStageOutput, error)
}
SecretsmanagerClient client to communicate with the secretsmanager.
type ServiceClient ¶
type ServiceClient interface {
// Create generates the secret and mutates the `secret` value.
Create(ctx context.Context, secret any) error
// Set sets newly generated credentials in the system delegated credentials storage.
Set(ctx context.Context, secretCurrent, secretPending, secretPrevious any) error
// Test tries to connect to the system delegated credentials storage using newly generated secret.
Test(ctx context.Context, secret any) error
}
ServiceClient defines the interface to communicate with the service (e.g. database) to rotate the access credentials.
Source Files
Directories