Understanding ID Token vs. Access Token in AWS Amplify

It has been pointed out to me that the suggested way to change the Access Token via Pre Token Generation does not work at the moment. The article has been changed accordingly.

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.

Add Claims to ID Token

We can modify the ID Token in a way that it contains the information actually need. 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 ID Token, before it is being generated.

Unfortunately, this solution does not currently work for the Access Token. This means that we expose the ID token and should be careful about this.

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!

Comments

[Abrom]

Hi @chris- great article. However, it might need to be updated. At the moment the pre token generation Lambda trigger does not allow modification to the access token, it only allows modifying the ID token. It should be noted that groups are already included in the access token by default. So this could be used to help with RBAC/ABAC.

Cheers!

[Chris Cook]

Thank you for pointing this out. I wasn't aware that the token generation doesn't run for access token.

[Abrom]

Hi Chris! I hope all is well on your end. I was randomly checking out articles and came across my comment on your post about access token customization. Great news! You can in fact now customize an access token with Amazon Cognito as part of advanced security features. Here's the documentation on this.

[Chris Cook]

Hi Abrom! Thank you for sharing this new feature, that's very good to know!

[Jason Wadsworth]

The pre-token generation trigger only allows claims overrides on the identity token at this point in time. The ability to modify the access token is one of the more requested changes.

[Chris Cook]

Thank you for pointing this out. I will update the article and submit a feature request to the AWS Team :)