In this post, we’ll explain how to add custom attributes in the user token AWS Cognito claims using the Pre-Token Generation lambda trigger.

· Prerequisites
· Overview
· Amazon Cognito Setup
· Getting Started
∘ User pool app clients — JSON web tokens
∘ Add a custom claim to a JWT token
· Conclusion
· References
· Additional Readings

Prerequisites

This is the list of all the prerequisites:

• An active AWS account
• Basic knowledge of Node.js
• Basic knowledge of how AWS Cognito works

Overview

Security remains a critical requirement when building an application. AWS Cognito is therefore a service that offers many advantages in the standard management of authentication and authorization for application users.

In many scenarios when using AWS Cognito, we need or want to add additional claims to a token. This becomes particularly useful when additional custom enrichment is not available within standard-created tokens.

In this story, we will use the Pre-Token Generation lambda trigger to add custom attributes to the user token.

Amazon Cognito Setup

In the previous story, we covered setting up Amazon Cognito using the AWS CloudFormation template.

AWS Cognito auth server with AWS SDK for JavaScript (v3) using Node.js, Express.js

Getting Started

User pool app clients — JSON web tokens

Amazon Cognito user pools implement ID, access, and refresh tokens as defined by the OpenID Connect (OIDC) open standard.

• The ID Token contains claims about the identity of the authenticated user such as name, email, and phone_number.
• The Access Token contains scopes, a feature of OIDC and OAuth 2.0. An access token with custom scopes, often from an M2M client-credentials grant, authorizes access to a resource server.
• The Refresh Token is an encrypted statement of initial authentication that your app can present to your user pool when your user’s tokens expire. A refresh-token request returns new, unexpired access and ID tokens.

It looks like this after a successful login:

When we decode the idToken with https://jwt.io/.

Add a custom claim to a JWT token

Amazon Cognito invokes the Pre token generation Lambda trigger before generating the token. So we can customize identity token claims with this trigger. We can use this trigger to add new claims, update claims, or suppress claims in the identity token. To use this feature, associate a Lambda function from the Amazon Cognito user pools console or update your user pool through the AWS Command Line Interface (AWS CLI).

Suppose we want to add the department and tenantId custom attributes in the ID token.

> Navigate to the Lambda console and click on the Create Function button.

1- Select an Author from scratch
2- Give the lambda function a name
3- Select Node.js runtime (You can use other runtime like Java, C#, Python, Ruby, GO)
4- Click Create function

Then, in the lambda window, click on the index.mjs tab to select it and replace the code with the following code.

const handler = async (event) => {
  event.response = {
    claimsOverrideDetails: {
      claimsToAddOrOverride: {
        tenantId: event.request.userAttributes['custom:tenantId'],
        departmentId: event.request.userAttributes['custom:department']
      }
    },
  };

  return event;
};

export { handler };

Click on “Deploy” to deploy your lambda function.

After creating the above Lambda function, Add a Trigger in the Cognito User Pool.

• claimsToAddOrOverride
  A map of one or more key-value pairs of claims to add or override. For group-related claims, use groupOverrideDetails instead.
• claimsToSuppress
  A list that contains claims that you want Amazon Cognito to suppress from the identity token.
• groupOverrideDetails
  The output object that contains the current group configuration. The object includes groupsToOverride, iamRolesToOverride, and preferredRole.

> In your User pools > User pool properties > click Add Lambda trigger

Select the Lambda function created in the previous step and Add Lambda trigger.

Let’s try

After a new connection, we can see that the two custom attributes have been added to the idToken.

Conclusion

In this story, We have seen how to add custom claims in ID Tokens using Cognito Pre Token Generator Lambda Trigger. Note that the Pre-token generation Lambda trigger does not work on access tokens.

You can reach out to me and follow me on Medium, Twitter, GitHub

References

• https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-client-apps.html
• https://docs.aws.amazon.com/fr_fr/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-access-token.html
• https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.html

Additional Readings

AWS Cognito auth server with AWS SDK for JavaScript (v3) using Node.js, Express.js

Spring boot Authentication server using AWS cognito

Multi-Tenancy architecture using AWS Cognito : Part 1

Multi-Tenancy architecture using AWS Cognito : Part 2

👉 Link to Medium blog