serverless-app-client-credentials-to-ssm

A Serverless plugin to export Cognito app client credentials to SSM Parameter store for µservice

Background

Amazon Cognito is a powerful service for application authentication, authorization, and user management. When working with µservice applications, we can use AWS Cognito user pool authentication to implement a fine-grained service-to-service access control where each service has a dedicated resource server with pre-defined scopes for its resources(API Gateway, Lambda etc), and a dedicated app client with limited scopes it needs to access external resources.

This service-to-service interaction normally starts with a user pool sign-in with the app client credentials where a JWT token will be returned from Cognito to the initiator for external resource access. We used to copy the app client credentials from AWS console and put to the configuration for each µservice manually. With the increasing number of µservices, we need a tool to do this securely and automatically for us.

How it works

A Serverless "hook" will be triggered after the deployment to pull the app client credentials includes url, clientId, and clientSecret which will be merged as part of the application configuration(auth.cognito) stored in the configured SSM parameter.

Note:

  • Only when there are changes for any of these three fields will this plugin update the SSM parameter.
  • For security reason, SecurityString parameter with the default AWS account key is used here.

Installation

npm install serverless-app-client-credentials-to-ssm --save-dev

Configuration

plugin registration

Inside your project's serverless.yml file add following entry to the plugins section:

plugins:
  - serverless-app-client-credentials-to-ssm

plugin configuration

Then you need to add the plugin configuration to the custom section:

custom:
  serverless-app-client-credentials-to-ssm:
    userPoolId: ${ssm:/layered-apis/userPoolId}
    appClientName: ${self:custom.appClientName}
    parameterName: /config/${self:service}-${self:provider.stage}

Sample parameter

{
  "auth": {
	"cognito": {
	  "url": "https://asdfafdsa-systems-idp-nonprod.auth.ap-southeast-2.amazoncognito.com/oauth2/token",
	  "clientId": "h3p4a1sr9pu",
	  "clientSecret": "s1oglveco0hsfraoag90ebr107rmvo9g7u36h"
	}
  },
  "database": {
	...
  }
}

License

MIT

Contribute

Yes, highly appreciate for any PRs. Thank you!