Serverless KMS Grants Plugin

serverless npm version

A plugin for the Serverless Framework which creates AWS KMS grants for an IAM role to give it permission to use a KMS key. The plugin creates an AWS KMS grant as part of the serverless deploy function, and revokes it as part of the serverless remove function. You can also run it from the command line.

Table of Contents

Install

  1. Add serverless-kms-grants plugin to your package.json: npm install --save-dev serverless-kms-grants

  2. Add the serverless-kms-grants plugin to the serverless.yml file:

    plugins:
        - serverless-kms-grants

  3. To verify that the plugin was added successfully, run serverless in your command line. The plugin should show up under the "Plugins" section as ServerlessKmsGrants.

Usage

Version 1.0.0

As of version 1.0.0 a list of grants can be configured. For each grant you'd like to make, configure the AWS KMS key id and role arn or role name for the plugin in serverless.yml. Using the ARN of a resource is the safest as it is guaranteed to be unique in AWS. If only a kmsKeyId is given and neither the roleName or roleArn are specified, the plugin will try to find and use the default lambda role generated by Serverless. The default serverless lambda role name follows the convention: <service>-<stage>-<region>-lambdaRole.

  • kmsKeyId: the KeyId, Alias, or Arn used to identify the KMS key (Required)
  • roleName: the name of the AWS IAM role you wish to grant access to KMS key. (Optional).
  • roleArn: the Arn of the AWS IAM role you wish to grant access to the KMS key (Optional).

Example:

custom:
  kmsGrants:
    # Grant the default serverless lambda role access to a KMS key
    - kmsKeyId: <KMS Key Identifier>
    # Grant a role with a unique name access to a KMS Key
    - kmsKeyId: <KMS Key Identifier>
      roleName: <IAM Role Name>
    # Grant a role with a specific ARN access to a KMS Key
    - kmsKeyId: <KMS Key Identifier>
      roleArn: <IAM Role Arn>

Prior to 1.0.0

Configure the AWS KMS key id and lambdaArn for the plugin in serverless.yml:

  • kmsKeyId: the KeyId, Alias, or Arn used to identify the KMS key (Required)
  • lambdaRoleName: the name of the lambda role you wish to grant access to KMS key. (Optional). If name is not specified the plugin will try with default role name.
  • lambdaRoleArn: the Arn of the lambda you wish to grant access to the KMS key (Optional). If an arn is not specified, the plugin will look for the default lambdaRole and obtain its arn. The default serverless lambda role follows the convention: <service>-<stage>-<region>-lambdaRole.
custom:
    kmsGrants:
        kmsKeyId: <KMS Key Identifier>
        lambdaRoleArn: <Lambda Arn>

For example:

custom:
    kmsGrants:
        kmsKeyId: "alias/myKey"
        lambdaRoleArn: "arn:aws:iam::000123456789:role/myservice-mystage-us-east-1-lambdaRole"

Run Locally

The plugin can be used locally via the command line to create or revoke an AWS KMS Grant (using the specification in serverless.yml above)

serverless createKmsGrant
serverless revokeKmsGrant

You can specify the stage by adding --stage <stage> to the end as follows:

serverless createKmsGrant --stage myStage
serverless revokeKmsGrant --stage myStage

Support

This is an Open Source community project. Project contributors may be able to help, depending on their time and availability. Please be specific about what you're trying to do, your system, and steps to reproduce the problem.

For bug reports or feature requests, please open an issue. You are welcome to contribute.

Official support from Trend Micro is not available. Individual contributors may be Trend Micro employees, but are not official support.

Contribute

We accept contributions from the community. To submit changes:

  1. Fork this repository.
  2. Create a new feature branch.
  3. Make your changes.
  4. Submit a pull request with an explanation of your changes or additions.

We will review and work with you to release the code.