exanubes
Q&A

Setup Cognito User Pool with custom emailing service

In this article we will go over creating a user pool, along with a user pool client to use for connecting to Cognito from our application. Instead of using the built-in AWS SES service for sending emails to the user, we will create a lambda that will use SendGrid for sending customer emails. However, because data is encrypted we will have to create a Customer Managed Key in KMS to use for encryption which the lambda will later use for decryption. Once we’re done with the infrastructure, we will use AWS SDK v3 to create an API for users to register, verify and sign in. Then we will use the JWT Access Token from Cognito for authorizing users to use protected API endpoints.

Here’s a github repo if you’re here for the code .

Creating a user pool

// stacks/cognito.stack.ts
export class CognitoStack extends Stack {
	private createUserPool(cmk: Key): UserPool {
		const userPool = new UserPool(this, 'exanubes-user-pool', {
			userPoolName: 'exanubes_user_pool',
			selfSignUpEnabled: true,
			signInAliases: {
				username: true,
				email: true
			},
			removalPolicy: RemovalPolicy.DESTROY,

			standardAttributes: {
				email: { required: true, mutable: false }
			},
			autoVerify: { email: true },
			customSenderKmsKey: cmk
		});
	}
}

When creating a userpool we need decide a couple of things, like for example if we want users to be able to signup on their own. Without this option enabled, only an administrator will be able to create users and send invitations to them. We can also set what users will be able to sign in with, here we’re gonna allow username and email.

There’s a list of standard attributes available, however, we can also define custom attributes with customAttributes property. The most important prop here though, would be the customSenderKmsKey. This is the key that we want Cognito to use for encrypting the verification codes and temporary passwords so that we can decrypt them using that same key and make them available to users while at the same time not being tied to using SES.

Creating a CMK

// stacks/cognito.stack.ts
private createCustomManagedKey(): Key {
    return new Key(this, 'KMS-Symmetric-Key', {
      keySpec: KeySpec.SYMMETRIC_DEFAULT,
      alias: keyAlias,
      enableKeyRotation: false,
    });
}

In order to complete the creation of a user pool, we’re gonna need a symmetric key. This means that we’re using a single key for encryption and decryption. Important to note that we’re passing keyAlias variable not a string as we’re gonna need that alias later.

Adding a client

// stacks/cognito.stack.ts
userPool.addClient('exanubes-user-pool-client', {
	userPoolClientName: 'exanubes-cognito-app',
	authFlows: {
		userPassword: true
	},
	accessTokenValidity: Duration.days(1),
	idTokenValidity: Duration.days(1),
	refreshTokenValidity: Duration.days(30),
	preventUserExistenceErrors: true
});

A user pool in and of itself does not provide any access for our application. For that we need to create a client. This is useful as we can create different clients depending on the application we want to connect with and configure them differently. Aside from deciding token validity and different authentication flows. We can also setup 0Auth or decide what attributes a client can read or write. The preventUserExistenceErrors obfuscates the error when a user does not exist to avoid giving that information to the end user.

Creating a custom mailer resource

// stacks/cognito.stack.ts
  private createCustomEmailer(cmk: Key): Function {
    return new Function(this, "custom-emailer-lambda", {
      code: Code.fromAsset(
        join(__dirname, "..", "lambdas/custom-email-sender")
      ),
      runtime: Runtime.NODEJS_14_X,
      handler: "index.handler",
      environment: {
        KEY_ID: cmk.keyArn,
        KEY_ALIAS: `arn:aws:kms:${region}:${accountId}:alias/${keyAlias}`,
        SENDGRID_API_KEY: String(process.env.SENDGRID_API_KEY),
      },
    });
  }

Run-of-the-mill lambda function setup. One thing to note are the environment variables. Considering that our lambda is supposed to decrypt sensitive data sent from cognito, it need the CMK ARN and the CMK alias ARN. In the documentation they claim that the key alias should suffice, however, it’s been throwing errors for me when following their instructions. In this example I’ll be using sendgrid so that’s the key I’m passing here, change it to your own liking.

Creating custom mailer lambda

Setup

// lambdas/custom-email-sender/logger.ts
const b64 = require('base64-js');
const encryptionSdk = require('@aws-crypto/client-node');
const emailClient = require('@sendgrid/mail');

const { encrypt, decrypt } = encryptionSdk.buildClient(
	encryptionSdk.CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT
);
const generatorKeyId = String(process.env.KEY_ALIAS);
const keyIds = [String(process.env.KEY_ID)];
const keyring = new encryptionSdk.KmsKeyringNode({ generatorKeyId, keyIds });
const sendgridApiKey = String(process.env.SENDGRID_API_KEY);
emailClient.setApiKey(sendgridApiKey);

Starting off with setting up all the keys and clients. We’re using the @aws-crypto module to get our encryption and decryption methods as well as a keyring which we create by pointing to the CMK environment variables created in the previous step. This keyring will be used for decryption/encryption operations. Last but not least, we also have to setup the SendGrid client.

Implementation

// lambdas/custom-email-sender/logger.ts
exports.handler = async (event: CognitoTriggerEvent) => {
	//Decrypt the secret code using encryption SDK.
	let plainTextCode;
	if (event.request.code) {
		const { plaintext } = await decrypt(keyring, b64.toByteArray(event.request.code));
		plainTextCode = plaintext.toString?.();
	}
	//PlainTextCode now has the decrypted secret.
	const user = event.request.userAttributes;
	const email = {
		to: `${event.userName} <${user.email}>`,
		from: 'Exanubes.com <newsletter@exanubes.com>',
		subject: `[${event.triggerSource}] Welcome to Exanubes.com`,
		text: `Welcome to exanubes.com,\njoin us by going to http://localhost:3001/verify?code=${plainTextCode}&username=${event.userName}`
	};

	switch (event.triggerSource) {
		case TriggerSource.SignUp:
			try {
				await emailClient.send(email);
			} catch (error) {
				console.log(error);
			}
			break;
		case TriggerSource.ResendCode:
		case TriggerSource.ForgotPassword:
		case TriggerSource.UpdateUserAttribute:
		case TriggerSource.VerifyUserAttribute:
		case TriggerSource.AdminCreateUser:
		case TriggerSource.AccountTakeOverNotification:
			return;
		default:
			const x: never = event.triggerSource;
			console.log('Unhandled case for trigger source: ', event.triggerSource);
			return x;
	}
};

The meat of the implementation is at the very beginning where we actually have to use the CMK to decrypt data from the request. For that we’re using the aforementioned decrypt method and keyring. Because plaintext comes back as Buffer we also had to convert it to a string. Rest of the code is pretty straight-forward were we create an email and send it to the user. In this minimalistic example I’m only sending an email on signup in order to handle user verification, however, as you can see there’s a lot of different trigger sources that can be used for sending user emails. I’ve left out types out of the article for brevity, you can see them on github .

Configuring permissions

// stacks/cognito.stack.ts
  private setPermissions(key: Key, lambda: Function): void {
    // Allow Cognito Service to use key for encryption
    key.addToResourcePolicy(
      new PolicyStatement({
        actions: ["kms:Encrypt"],
        effect: Effect.ALLOW,
        principals: [new ServicePrincipal("cognito-idp.amazonaws.com")],
        resources: ["*"],
      })
    );

    // Allow custom emailer lambda to use key
    lambda.role!.attachInlinePolicy(
      new Policy(this, "userpool-policy", {
        statements: [
          new PolicyStatement({
            actions: ["kms:Decrypt", "kms:DescribeKey"],
            effect: Effect.ALLOW,
            resources: [key.keyArn],
          }),
        ],
      })

    );

    // Allow cognito to use lambda
    lambda.addPermission("exanubes-cognito-custom-mailer-permission", {
      principal: new ServicePrincipal("cognito-idp.amazonaws.com"),
      action: "lambda:InvokeFunction",
    });
  }

As for everything in AWS, we still have to explicitly state what service can use which resources and vice versa. First we allow Cognito to use the CMK for encryption. Then We allow our lambda to access the key and use it for decryption. This permission is special though as it is attached inline, this is due to a circular dependency error that occurs when we try to add it in the conventional way – this approach is recommended by the aws-cdk team. Last but not least, we have to allow Cognito to invoke our lambda.

Putting it all together

// stacks/cognito.stack.ts
  constructor(scope: Construct, id: string, props: Props) {
    super(scope, id, props);

    const cmk = this.createCustomManagedKey();
    const userPool = this.createUserPool(cmk);
    const customEmailer = this.createCustomEmailer(cmk);

    this.setPermissions(cmk, customEmailer);

    userPool.addTrigger(UserPoolOperation.CUSTOM_EMAIL_SENDER, customEmailer);
  }

Thus far we have created a user pool and added a connection client to use in our application. We’ve also created a Customer Managed Key [CMK] for encrypting and decrypting sensitive data sent from cognito to our lambda which will be used as the custom mailer function instead of SES. With all the permissions configured, all that was left was adding a trigger to the user pool to point it to our lambda.

Now, we’re going to use the AWS SDK v3 to create a backend API for registering, verifying and signing users in. Then we’ll create a passport.js jwt strategy to authorize Cognito Access Tokens to use protected API routes.

Setup SDK Client

// auth/auth.service.ts
class AuthService {
	private readonly client: CognitoIdentityProviderClient;
	constructor(private readonly awsConfigService: AwsConfigService) {
		this.client = new CognitoIdentityProviderClient({
			region: awsConfigService.region,
			credentials: {
				accessKeyId: awsConfigService.accessKeyId,
				secretAccessKey: awsConfigService.secretAccessKey
			}
		});
	}
}

For this part we’re gonna use the @aws-sdk/client-cognito-identity-provider library from aws. V3 is pretty straight forward as the API is very standardized throughout the different services. First off we need to create a client instance, for that we need a couple of things. accessKeyId and secretAccessKey can be generated in IAM service, region should be the same as the region where the user pool is going to be.

All data is fed to awsConfigService through environment variables in .env file

Create Signup, Verify and Signin methods

// auth/auth.service.ts
  async signup({ password, username, email }: SignUpDto) {
    const input: SignUpCommandInput = {
      Password: password,
      Username: username,
      ClientId: this.awsConfigService.userPoolClientId,
      UserAttributes: [{ Name: 'email', Value: email }],
    };
    const command = new SignUpCommand(input);
    return this.client.send(command);
  }

// auth/auth.service.ts
  async verifySignup(code: string, username: string) {
    const input: ConfirmSignUpCommandInput = {
      ClientId: this.awsConfigService.userPoolClientId,
      Username: username,
      ConfirmationCode: code,
    };
    const command = new ConfirmSignUpCommand(input);
    return this.client.send(command);
  }

// auth/auth.service.ts
  async login({ username, password }: LoginDto) {
    const input: InitiateAuthCommandInput = {
      ClientId: this.awsConfigService.userPoolClientId,
      AuthFlow: AuthFlowType.USER_PASSWORD_AUTH,
      AuthParameters: {
        USERNAME: username,
        PASSWORD: password,
      },
    };
    const command = new InitiateAuthCommand(input);
    const response = await this.client.send(command);
    return response.AuthenticationResult;
  }

As I mentioned before, the API is very standardized so it’s quite simple to use. The crux of it is to find the right command. After that it’s just about getting the right props for the input and sending the command.

In this case we have a simple implementation where we’re gonna collect user data via the frontend application, however, the ClientId is referring to the client we’ve added to the user pool . You can either look for it in Cognito user pool section in AWS Console, or you can add a CloudFormation output to the Cognito stack.

// stacks/cognito.stack.ts
new CfnOutput(this, 'exanubes-user-pool-client-id', {
	value: client.userPoolClientId
});

Implement passport strategy for Cognito tokens

// auth/auth.service.ts
export class JwtStrategy extends PassportStrategy(Strategy) {
	constructor(private readonly awsConfigService: AwsConfigService) {
		super({
			jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
			ignoreExpiration: false,
			secretOrKeyProvider: async (request, jwtToken, done) => {
				const jwtHeader: { kid: string } = jwt_decode(jwtToken, {
					header: true
				});
				const res = await fetch(awsConfigService.issuerAddress);
				const data = await res.json();
				const jwk = data.keys.find((key) => key.kid === jwtHeader.kid);

				if (!jwk) {
					throw new Error('Something went wrong');
				}
				done(null, jwkToPem(jwk));
			},
			algorithms: ['RS256']
		});
	}
	async validate(payload) {
		return payload;
	}
}

Probably the most important part of the server implementation. After we log a user in and send him the Access Token generated by Cognito, we need to have a way of validating the token in order to either authorize or deny access to the user. As with any jwt, in order to validate it we have to know what secret was used to encode it. The thing is, we don’t know ‘cause AWS did it for us. Luckily, we can get access to the secrets by calling the issuer address which is the cognito identity provider or cognito-idp. In response we get an array of JSON Web Keys(JWK), one of them is ours. In order to determine which one it is, we use the key id (kid) from the JWT Token and look for a JWK with the same kid. Once we have the right JWK we convert it to PEM and that’s the secret for verifying JWT.

Should you want more granular authorization based on token payload, it can be done in the validate function. In this small example we just allow all valid tokens.

Implementation details not regarding AWS have been omitted for brevity. If you're interested in the full implementation with NestJS, go to the github repository for this article.

Summary

In this article we’ve gone over several important points for working with AWS Cognito. First of all as it turns out there’s a distinction between a Cognito User Pool and a Client. Former is the brains of the operation and the latter is the entrypoint and configuration of what the connected application can do via the client. We’ve also used the KMS service to generate an encryption key which allowed us to replace the SES service and use our own 3rd party mailing service via a Lambda function. After setting up all the permissions between Cognito, KMS and Lambda we’ve moved on to the backend service where we used the AWS SDK v3 to create all the relevant endpoints for creating and signing users in. Last but not least, we’ve setup a Passport strategy for authorizing Cognito Access Tokens and allowing or denying access to users on protected API endpoints.