Introduction

When a custom Cognito user-pool attribute does not appear in the ID token, the issue is usually not that the attribute failed to save. More often, the app client is not allowed to read it, the token is being inspected before the new claim takes effect, or the claim needs to be added or reshaped through a Pre Token Generation trigger.

Understand what goes into an ID token

A Cognito ID token is a JWT containing claims about the authenticated user. It is not simply a dump of every attribute stored on the user profile. Cognito decides which claims to include based on token rules, app client settings, and any token customization you apply.

That means a custom attribute such as custom:membershipLevel can exist on the user and still not be present in the ID token you are decoding.

Check app client read permissions first

One of the most common causes is that the app client is not configured with read access to the attribute. In Cognito user pools, app clients can be restricted to specific readable and writable attributes.

If the app client cannot read custom:membershipLevel, you should not expect it to appear in the token claims.

So the first practical check is:

• confirm the attribute exists on the user
• confirm the app client has read permission for that attribute
• sign in again and inspect a freshly issued token

This is often enough to explain the missing claim.

Verify the attribute is actually set on the user

If you are debugging through code or the AWS CLI, check the user profile directly:

aws cognito-idp admin-get-user \
  --user-pool-id us-east-1_example \
  --username [email protected]

Look for the custom attribute in the returned user attributes. If it is missing there, the token cannot include it.

If it is present there but missing in the token, the problem is token generation or app client configuration rather than user storage.

Use a Pre Token Generation trigger when you need explicit control

If you want to add, override, or reshape claims in the token, Cognito provides the Pre Token Generation Lambda trigger.

A simplified Python example looks like this:

1def lambda_handler(event, context):
2    user_attributes = event["request"]["userAttributes"]
3    membership = user_attributes.get("custom:membershipLevel", "basic")
4
5    event["response"]["claimsOverrideDetails"] = {
6        "claimsToAddOrOverride": {
7            "membershipLevel": membership
8        }
9    }
10
11    return event

This is useful when:

• you want a friendlier claim name
• you need to derive a claim from several attributes
• you need claim control beyond default attribute behavior

Re-authenticate after changes

A very practical trap is looking at an old token. If you update a custom attribute after the user already signed in, the current token does not automatically rewrite itself.

You usually need a fresh authentication flow or token refresh cycle before the new claim appears.

So if you changed the attribute and immediately decoded an older cached token, you may be debugging the wrong thing.

Common Pitfalls

The biggest pitfall is assuming every user attribute automatically appears in every ID token. Cognito token claims are constrained by configuration and token-generation logic.

Another issue is ignoring the app client's readable attribute settings. A correctly stored custom attribute may still be invisible to a particular app client.

It is also easy to inspect stale tokens and conclude the claim is missing permanently when the real issue is just token age.

Finally, do not overload tokens with unnecessary profile data. Even if you can add many claims, tokens should stay intentional and reasonably small.

Summary

• A missing custom attribute in a Cognito ID token does not automatically mean the attribute failed to save.
• Check the user profile and the app client's readable attribute settings first.
• Re-authenticate or refresh tokens after making attribute changes.
• Use a Pre Token Generation trigger when you need explicit claim customization.
• Treat token contents as a designed claim set, not as a full user-record dump.