feat(secretsmanager): add grantUpdate method

packages/@aws-cdk/aws-secretsmanager/README.md

@@ -44,14 +44,15 @@ A secret can set `RemovalPolicy`. If it set to `RETAIN`, that removing a secret
 ### Grant permission to use the secret to a role
 
 You must grant permission to a resource for that resource to be allowed to 
-use a secret. This can be achieved with the `Secret.grantRead` and/or 
-`Secret.grantWrite` method, depending on your need:
+use a secret. This can be achieved with the `Secret.grantRead`, `Secret.grantWrite`, and/or `Secret.grantUpdate`
+ method, depending on your need:
 
 ```ts
 const role = new iam.Role(stack, 'SomeRole', { assumedBy: new iam.AccountRootPrincipal() });
 const secret = new secretsmanager.Secret(stack, 'Secret');
 secret.grantRead(role);
 secret.grantWrite(role);
+secret.grantUpdate(role);
 ```
 
 If, as in the following example, your secret was created with a KMS key:
@@ -60,8 +61,9 @@ const key = new kms.Key(stack, 'KMS');
 const secret = new secretsmanager.Secret(stack, 'Secret', { encryptionKey: key });
 secret.grantRead(role);
 secret.grantWrite(role);
+secret.grantUpdate(role);
 ```
-then `Secret.grantRead` and `Secret.grantWrite` will also grant the role the
+then `Secret.grantRead`, `Secret.grantWrite`, and `Secret.grantUpdate` will also grant the role the
 relevant encrypt and decrypt permissions to the KMS key through the
 SecretsManager service principal.
 

packages/@aws-cdk/aws-secretsmanager/lib/secret.ts

@@ -48,6 +48,12 @@ export interface ISecret extends IResource {
    */
   grantWrite(grantee: iam.IGrantable): iam.Grant;
 
+  /**
+   * Grants updating the secret value to some role.
+   *
+   * @param grantee       the prinicpal being granted permission.
+   */
+  grantUpdate(grantee: iam.IGrantable): iam.Grant;
   /**
    * Adds a rotation schedule to the secret.
    */
@@ -181,6 +187,25 @@ abstract class SecretBase extends Resource implements ISecret {
     return result;
   }
 
+  public grantUpdate(grantee: iam.IGrantable): iam.Grant {
+    // See https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_identity-based-policies.html
+    const result = iam.Grant.addToPrincipal({
+      grantee,
+      actions: ['secretsmanager:UpdateSecret'],
+      resourceArns: [this.secretArn],
+      scope: this,
+    });
+
+    if (this.encryptionKey) {
+      // See https://docs.aws.amazon.com/kms/latest/developerguide/services-secrets-manager.html
+      this.encryptionKey.grantEncrypt(
+        new kms.ViaServicePrincipal(`secretsmanager.${Stack.of(this).region}.amazonaws.com`, grantee.grantPrincipal),
+      );
+    }
+
+    return result;
+  }
+
   public get secretValue() {
     return this.secretValueFromJson('');
   }

packages/@aws-cdk/aws-secretsmanager/test/test.secret.ts

@@ -420,6 +420,96 @@ export = {
     test.done();
   },
 
+  'grantUpdate'(test: Test) {
+    // GIVEN
+    const stack = new cdk.Stack();
+    const secret = new secretsmanager.Secret(stack, 'Secret', {});
+    const role = new iam.Role(stack, 'Role', { assumedBy: new iam.AccountRootPrincipal() });
+
+    // WHEN
+    secret.grantUpdate(role);
+
+    // THEN
+    expect(stack).to(haveResource('AWS::IAM::Policy', {
+      PolicyDocument: {
+        Version: '2012-10-17',
+        Statement: [{
+          Action: 'secretsmanager:UpdateSecret',
+          Effect: 'Allow',
+          Resource: { Ref: 'SecretA720EF05' },
+        }],
+      },
+    }));
+    test.done();
+  },
+
+  'grantUpdate with kms'(test: Test) {
+    // GIVEN
+    const stack = new cdk.Stack();
+    const key = new kms.Key(stack, 'KMS');
+    const secret = new secretsmanager.Secret(stack, 'Secret', { encryptionKey: key });
+    const role = new iam.Role(stack, 'Role', { assumedBy: new iam.AccountRootPrincipal() });
+
+    // WHEN
+    secret.grantUpdate(role);
+
+    // THEN
+    const expectStack = expect(stack);
+    expectStack.to(haveResource('AWS::IAM::Policy', {
+      PolicyDocument: {
+        Version: '2012-10-17',
+        Statement: [{
+          Action: 'secretsmanager:UpdateSecret',
+          Effect: 'Allow',
+          Resource: { Ref: 'SecretA720EF05' },
+        }],
+      },
+    }));
+    expectStack.to(haveResourceLike('AWS::KMS::Key', {
+      KeyPolicy: {
+        Statement: [
+          {},
+          {},
+          {},
+          {
+            Action: [
+              'kms:Encrypt',
+              'kms:ReEncrypt*',
+              'kms:GenerateDataKey*',
+            ],
+            Condition: {
+              StringEquals: {
+                'kms:ViaService': {
+                  'Fn::Join': [
+                    '',
+                    [
+                      'secretsmanager.',
+                      {
+                        Ref: 'AWS::Region',
+                      },
+                      '.amazonaws.com',
+                    ],
+                  ],
+                },
+              },
+            },
+            Effect: 'Allow',
+            Principal: {
+              AWS: {
+                'Fn::GetAtt': [
+                  'Role1ABCC5F0',
+                  'Arn',
+                ],
+              },
+            },
+            Resource: '*',
+          },
+        ],
+      },
+    }));
+    test.done();
+  },
+
   'secretValue'(test: Test) {
     // GIVEN
     const stack = new cdk.Stack();