feat(secretsmanager): hosted rotation (#10790)

Add support for secret rotation using a hosted rotation Lambda function. This should eventually replace the `SecretRotation` class which uses a serverless application (old way of doing this, currently used in `aws-rds`). Note: the `HostedRotationLambda` CF property doesn't support excluding characters yet so we'll have to wait until we can use it in `aws-rds`. See https://docs.aws.amazon.com/secretsmanager/latest/userguide/integrating_cloudformation.html See https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-secretsmanager-rotationschedule-hostedrotationlambda.html ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
aws · Oct 13, 2020 · 2cb8e22 · 2cb8e22
1 parent 1fbb8bc
commit 2cb8e22
Show file tree

Hide file tree

Showing 6 changed files with 691 additions and 10 deletions.
diff --git a/packages/@aws-cdk/aws-secretsmanager/README.md b/packages/@aws-cdk/aws-secretsmanager/README.md
@@ -69,7 +69,9 @@ then `Secret.grantRead` and `Secret.grantWrite` will also grant the role the
 relevant encrypt and decrypt permissions to the KMS key through the
 SecretsManager service principal.
 
-### Rotating a Secret with a custom Lambda function
+### Rotating a Secret
+
+#### Using a Custom Lambda Function
 
 A rotation schedule can be added to a Secret using a custom Lambda function:
 
@@ -85,6 +87,31 @@ secret.addRotationSchedule('RotationSchedule', {
 
 See [Overview of the Lambda Rotation Function](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets-lambda-function-overview.html) on how to implement a Lambda Rotation Function.
 
+#### Using a Hosted Lambda Function
+
+Use the `hostedRotation` prop to rotate a secret with a hosted Lambda function:
+
+```ts
+const secret = new secretsmanager.Secret(this, 'Secret');
+
+secret.addRotationSchedule('RotationSchedule', {
+ hostedRotation: secretsmanager.HostedRotation.mysqlSingleUser(),
+});
+```
+
+Hosted rotation is available for secrets representing credentials for MySQL, PostgreSQL, Oracle,
+MariaDB, SQLServer, Redshift and MongoDB (both for the single and multi user schemes).
+
+When deployed in a VPC, the hosted rotation implements `ec2.IConnectable`:
+
+```ts
+const myHostedRotation = secretsmanager.HostedRotation.mysqlSingleUser({ vpc: myVpc });
+secret.addRotationSchedule('RotationSchedule', { hostedRotation: myHostedRotation });
+dbConnections.allowDefaultPortFrom(hostedRotation);
+```
+
+See also [Automating secret creation in AWS CloudFormation](https://docs.aws.amazon.com/secretsmanager/latest/userguide/integrating_cloudformation.html).
+
 ### Rotating database credentials
 
 Define a `SecretRotation` to rotate database credentials:

diff --git a/packages/@aws-cdk/aws-secretsmanager/lib/rotation-schedule.ts b/packages/@aws-cdk/aws-secretsmanager/lib/rotation-schedule.ts
@@ -1,5 +1,6 @@
+import * as ec2 from '@aws-cdk/aws-ec2';
 import * as lambda from '@aws-cdk/aws-lambda';
-import { Duration, Resource } from '@aws-cdk/core';
+import { Duration, Resource, Stack } from '@aws-cdk/core';
 import { Construct } from 'constructs';
 import { ISecret } from './secret';
 import { CfnRotationSchedule } from './secretsmanager.generated';
@@ -9,9 +10,18 @@ import { CfnRotationSchedule } from './secretsmanager.generated';
  */
 export interface RotationScheduleOptions {
  /**
- * The Lambda function that can rotate the secret.
+ * A Lambda function that can rotate the secret.
+ *
+ * @default - either `rotationLambda` or `hostedRotation` must be specified
  */
- readonly rotationLambda: lambda.IFunction;
+ readonly rotationLambda?: lambda.IFunction;
+
+ /**
+ * Hosted rotation
+ *
+ * @default - either `rotationLambda` or `hostedRotation` must be specified
+ */
+ readonly hostedRotation?: HostedRotation;
 
  /**
  * Specifies the number of days after the previous rotation before
@@ -28,6 +38,23 @@ export interface RotationScheduleOptions {
 export interface RotationScheduleProps extends RotationScheduleOptions {
  /**
  * The secret to rotate.
+ *
+ * If hosted rotation is used, this must be a JSON string with the following format:
+ *
+ * ```
+ * {
+ * "engine": <required: database engine>,
+ * "host": <required: instance host name>,
+ * "username": <required: username>,
+ * "password": <required: password>,
+ * "dbname": <optional: database name>,
+ * "port": <optional: if not specified, default port will be used>,
+ * "masterarn": <required for multi user rotation: the arn of the master secret which will be used to create users/change passwords>
+ * }
+ * ```
+ *
+ * This is typically the case for a secret referenced from an `AWS::SecretsManager::SecretTargetAttachment`
+ * or an `ISecret` returned by the `attach()` method of `Secret`.
  */
  readonly secret: ISecret;
 }
@@ -39,12 +66,254 @@ export class RotationSchedule extends Resource {
  constructor(scope: Construct, id: string, props: RotationScheduleProps) {
  super(scope, id);
 
+ if ((!props.rotationLambda && !props.hostedRotation) || (props.rotationLambda && props.hostedRotation)) {
+ throw new Error('One of `rotationLambda` or `hostedRotation` must be specified.');
+ }
+
  new CfnRotationSchedule(this, 'Resource', {
  secretId: props.secret.secretArn,
- rotationLambdaArn: props.rotationLambda.functionArn,
+ rotationLambdaArn: props.rotationLambda?.functionArn,
+ hostedRotationLambda: props.hostedRotation?.bind(props.secret, this),
  rotationRules: {
  automaticallyAfterDays: props.automaticallyAfter && props.automaticallyAfter.toDays() || 30,
  },
  });
+
+ // Prevent secrets deletions when rotation is in place
+ props.secret.denyAccountRootDelete();
+ }
+}
+
+/**
+ * Single user hosted rotation options
+ */
+export interface SingleUserHostedRotationOptions {
+ /**
+ * A name for the Lambda created to rotate the secret
+ *
+ * @default - a CloudFormation generated name
+ */
+ readonly functionName?: string;
+
+ /**
+ * A list of security groups for the Lambda created to rotate the secret
+ *
+ * @default - a new security group is created
+ */
+ readonly securityGroups?: ec2.ISecurityGroup[];
+
+ /**
+ * The VPC where the Lambda rotation function will run.
+ *
+ * @default - the Lambda is not deployed in a VPC
+ */
+ readonly vpc?: ec2.IVpc;
+
+ /**
+ * The type of subnets in the VPC where the Lambda rotation function will run.
+ *
+ * @default - the Vpc default strategy if not specified.
+ */
+ readonly vpcSubnets?: ec2.SubnetSelection;
+}
+
+/**
+ * Multi user hosted rotation options
+ */
+export interface MultiUserHostedRotationOptions extends SingleUserHostedRotationOptions {
+ /**
+ * The master secret for a multi user rotation scheme
+ */
+ readonly masterSecret: ISecret;
+}
+
+/**
+ * A hosted rotation
+ */
+export class HostedRotation implements ec2.IConnectable {
+ /** MySQL Single User */
+ public static mysqlSingleUser(options: SingleUserHostedRotationOptions = {}) {
+ return new HostedRotation(HostedRotationType.MYSQL_SINGLE_USER, options);
+ }
+
+ /** MySQL Multi User */
+ public static mysqlMultiUser(options: MultiUserHostedRotationOptions) {
+ return new HostedRotation(HostedRotationType.MYSQL_MULTI_USER, options, options.masterSecret);
+ }
+
+ /** PostgreSQL Single User */
+ public static postgreSqlSingleUser(options: SingleUserHostedRotationOptions = {}) {
+ return new HostedRotation(HostedRotationType.POSTGRESQL_SINGLE_USER, options);
+ }
+
+ /** PostgreSQL Multi User */
+ public static postgreSqlMultiUser(options: MultiUserHostedRotationOptions) {
+ return new HostedRotation(HostedRotationType.POSTGRESQL_MULTI_USER, options, options.masterSecret);
+ }
+
+ /** Oracle Single User */
+ public static oracleSingleUser(options: SingleUserHostedRotationOptions = {}) {
+ return new HostedRotation(HostedRotationType.ORACLE_SINGLE_USER, options);
+ }
+
+ /** Oracle Multi User */
+ public static oracleMultiUser(options: MultiUserHostedRotationOptions) {
+ return new HostedRotation(HostedRotationType.ORACLE_MULTI_USER, options, options.masterSecret);
+ }
+
+ /** MariaDB Single User */
+ public static mariaDbSingleUser(options: SingleUserHostedRotationOptions = {}) {
+ return new HostedRotation(HostedRotationType.MARIADB_SINGLE_USER, options);
  }
+
+ /** MariaDB Multi User */
+ public static mariaDbMultiUser(options: MultiUserHostedRotationOptions) {
+ return new HostedRotation(HostedRotationType.MARIADB_MULTI_USER, options, options.masterSecret);
+ }
+
+ /** SQL Server Single User */
+ public static sqlServerSingleUser(options: SingleUserHostedRotationOptions = {}) {
+ return new HostedRotation(HostedRotationType.SQLSERVER_SINGLE_USER, options);
+ }
+
+ /** SQL Server Multi User */
+ public static sqlServerMultiUser(options: MultiUserHostedRotationOptions) {
+ return new HostedRotation(HostedRotationType.SQLSERVER_MULTI_USER, options, options.masterSecret);
+ }
+
+ /** Redshift Single User */
+ public static redshiftSingleUser(options: SingleUserHostedRotationOptions = {}) {
+ return new HostedRotation(HostedRotationType.REDSHIFT_SINGLE_USER, options);
+ }
+
+ /** Redshift Multi User */
+ public static redshiftMultiUser(options: MultiUserHostedRotationOptions) {
+ return new HostedRotation(HostedRotationType.REDSHIFT_MULTI_USER, options, options.masterSecret);
+ }
+
+ /** MongoDB Single User */
+ public static mongoDbSingleUser(options: SingleUserHostedRotationOptions = {}) {
+ return new HostedRotation(HostedRotationType.MONGODB_SINGLE_USER, options);
+ }
+
+ /** MongoDB Multi User */
+ public static mongoDbMultiUser(options: MultiUserHostedRotationOptions) {
+ return new HostedRotation(HostedRotationType.MONGODB_MULTI_USER, options, options.masterSecret);
+ }
+
+ private _connections?: ec2.Connections;
+
+ private constructor(
+ private readonly type: HostedRotationType,
+ private readonly props: SingleUserHostedRotationOptions | MultiUserHostedRotationOptions,
+ private readonly masterSecret?: ISecret,
+ ) {
+ if (type.isMultiUser && !masterSecret) {
+ throw new Error('The `masterSecret` must be specified when using the multi user scheme.');
+ }
+ }
+
+ /**
+ * Binds this hosted rotation to a secret
+ */
+ public bind(secret: ISecret, scope: Construct): CfnRotationSchedule.HostedRotationLambdaProperty {
+ // https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-secretsmanager-rotationschedule-hostedrotationlambda.html
+ Stack.of(scope).addTransform('AWS::SecretsManager-2020-07-23');
+
+ if (!this.props.vpc && this.props.securityGroups) {
+ throw new Error('`vpc` must be specified when specifying `securityGroups`.');
+ }
+
+ if (this.props.vpc) {
+ this._connections = new ec2.Connections({
+ securityGroups: this.props.securityGroups || [new ec2.SecurityGroup(scope, 'SecurityGroup', {
+ vpc: this.props.vpc,
+ })],
+ });
+ }
+
+ // Prevent master secret deletion when rotation is in place
+ if (this.masterSecret) {
+ this.masterSecret.denyAccountRootDelete();
+ }
+
+ return {
+ rotationType: this.type.name,
+ kmsKeyArn: secret.encryptionKey?.keyArn,
+ masterSecretArn: this.masterSecret?.secretArn,
+ masterSecretKmsKeyArn: this.masterSecret?.encryptionKey?.keyArn,
+ rotationLambdaName: this.props.functionName,
+ vpcSecurityGroupIds: this._connections?.securityGroups?.map(s => s.securityGroupId).join(','),
+ vpcSubnetIds: this.props.vpc?.selectSubnets(this.props.vpcSubnets).subnetIds.join(','),
+ };
+ }
+
+ /**
+ * Security group connections for this hosted rotation
+ */
+ public get connections() {
+ if (!this.props.vpc) {
+ throw new Error('Cannot use connections for a hosted rotation that is not deployed in a VPC');
+ }
+
+ // If we are in a vpc and bind() has been called _connections should be defined
+ if (!this._connections) {
+ throw new Error('Cannot use connections for a hosted rotation that has not been bound to a secret');
+ }
+
+ return this._connections;
+ }
+}
+
+/**
+ * Hosted rotation type
+ */
+export class HostedRotationType {
+ /** MySQL Single User */
+ public static readonly MYSQL_SINGLE_USER = new HostedRotationType('MySQLSingleUser');
+
+ /** MySQL Multi User */
+ public static readonly MYSQL_MULTI_USER = new HostedRotationType('MySQLMultiUser', true);
+
+ /** PostgreSQL Single User */
+ public static readonly POSTGRESQL_SINGLE_USER = new HostedRotationType('PostgreSQLSingleUser');
+
+ /** PostgreSQL Multi User */
+ public static readonly POSTGRESQL_MULTI_USER = new HostedRotationType('PostgreSQLMultiUser', true);
+
+ /** Oracle Single User */
+ public static readonly ORACLE_SINGLE_USER = new HostedRotationType('OracleSingleUser');
+
+ /** Oracle Multi User */
+ public static readonly ORACLE_MULTI_USER = new HostedRotationType('OracleMultiUser', true);
+
+ /** MariaDB Single User */
+ public static readonly MARIADB_SINGLE_USER = new HostedRotationType('MariaDBSingleUser');
+
+ /** MariaDB Multi User */
+ public static readonly MARIADB_MULTI_USER = new HostedRotationType('MariaDBMultiUser', true);
+
+ /** SQL Server Single User */
+ public static readonly SQLSERVER_SINGLE_USER = new HostedRotationType('SQLServerSingleUser')
+
+ /** SQL Server Multi User */
+ public static readonly SQLSERVER_MULTI_USER = new HostedRotationType('SQLServerMultiUser', true);
+
+ /** Redshift Single User */
+ public static readonly REDSHIFT_SINGLE_USER = new HostedRotationType('RedshiftSingleUser')
+
+ /** Redshift Multi User */
+ public static readonly REDSHIFT_MULTI_USER = new HostedRotationType('RedshiftMultiUser', true);
+
+ /** MongoDB Single User */
+ public static readonly MONGODB_SINGLE_USER = new HostedRotationType('MongoDBSingleUser');
+
+ /** MongoDB Multi User */
+ public static readonly MONGODB_MULTI_USER = new HostedRotationType('MongoDBMultiUser', true);
+
+ /**
+ * @param name The type of rotation
+ * @param isMultiUser Whether the rotation uses the mutli user scheme
+ */
+ private constructor(public readonly name: string, public readonly isMultiUser?: boolean) {}
 }
diff --git a/packages/@aws-cdk/aws-secretsmanager/lib/secret-rotation.ts b/packages/@aws-cdk/aws-secretsmanager/lib/secret-rotation.ts
@@ -136,6 +136,7 @@ export class SecretRotationApplication {
 export interface SecretRotationProps {
  /**
  * The secret to rotate. It must be a JSON string with the following format:
+ *
  * ```
  * {
  * "engine": <required: database engine>,
@@ -148,8 +149,8 @@ export interface SecretRotationProps {
  * }
  * ```
  *
- * This is typically the case for a secret referenced from an
- * AWS::SecretsManager::SecretTargetAttachment or an `ISecret` returned by the `attach()` method of `Secret`.
+ * This is typically the case for a secret referenced from an `AWS::SecretsManager::SecretTargetAttachment`
+ * or an `ISecret` returned by the `attach()` method of `Secret`.
  *
  * @see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-secretsmanager-secrettargetattachment.html
  */
@@ -270,8 +271,7 @@ export class SecretRotation extends CoreConstruct {
  automaticallyAfter: props.automaticallyAfter,
  });
 
- // Prevent secrets deletions when rotation is in place
- props.secret.denyAccountRootDelete();
+ // Prevent master secret deletion when rotation is in place
  if (props.masterSecret) {
  props.masterSecret.denyAccountRootDelete();
  }