Understanding ID Token vs. Access Token in AWS Amplify

In a recent StackOverflow answer, I addressed an issue related to the use of ID Token vs. Access Token in the Amplify JavaScript library. I think it's worth writing this up to provide further information and resources for people who might stumble upon this problem.

ID Token vs. Access Token

The Amplify JavaScript library sends the JWT Access Token by default in GraphQL requests. However, the AWS console for AppSync, which powers Amplify's API module, actually sends the ID Token instead of the Access Token. This discrepancy can cause confusion among developers. The main reason to send the ID Token is that it contains user attribute information such as email, that we might need on the backend for authorization checks.

To override the default behavior and send the ID Token in the Authorization header for GraphQL requests, you can configure Amplify as follows:

Amplify.configure({  API: {    graphql_headers: async () => {      const session = await Auth.currentSession();      return {        Authorization: session.getIdToken().getJwtToken(),      };    },  },});

However, there are security risks when using the ID Token in such a way. If not absolutely necessary, we should opt for another option.

Add Claims to Access Token

Alternatively, we can modify the Access Token in a way that it contains the information actually need, without exposing the ID Token. AWS Cognito supports Lambda triggers that execute code before or after certain events. In this case, the Pre Token Generation Lambda Trigger allows us to hook into the token generation and add custom claims and groups to the Access Token, before it is being generated.

import type { PreTokenGenerationTriggerHandler } from 'aws-lambda';export const handler: PreTokenGenerationTriggerHandler = async (event, context) => {  const { email } = event.request.userAttributes;  event.response = {    claimsOverrideDetails: {      claimsToAddOrOverride: {        email: email,      },      // claimsToSuppress: ['some_attribute'],    },  };  return event;};

The event payload contains request.userAttributes object with properties such as first name, last name, email and so on. We have to modify the event and return it with the claims we would like to add, change or even suppress. In this case we add the email to claimsToAddOrOverride and return the event.

Further Reading

Here are some links that might help you to dig deeper:

• Pre Token Generation Lambda Trigger

• Add Cognito Lambda Triggers to Amplify

• Multi-tenant AWS Amplify

• Amplify GitHub Issue

• OpenID Standard Claims

I hope you found this post helpful. If you have any questions or comments, feel free to leave them below. If you'd like to connect with me, you can find me on LinkedIn or GitHub. Thanks for reading!