ID Token vs Access Token: Authorization Decision Guidelines

A common point of confusion when using Cognito is understanding the roles of ID Tokens and Access Tokens—two critical components of the OAuth 2.0 authorization framework (RFC 6749) and OpenID Connect (OIDC) standards.

I often hear customers say "Let’s use a token to secure this API call. Should I use the ID token or the access token? The ID token looks nicer to me. After all, if I know who the user is, I can make better authorization decisions, right?". In the case of ID and access tokens, they have clear and well-defined purposes, so you should use them based on that. Using the wrong token can introduce potential vulnerabilities in your solution. The intention of this article is to provide a decision guide that is clear and straightforward.

Note: All code snippets are for testing/demonstration purposes only. Please use with caution.

This simple mental model provides robust guidance for token usage. Let's dive deeper into why this distinction is important:

Client-Side Authorization involves the application itself making decisions about what the user is allowed to do based on the information contained in the ID Token. This typically happens in scenarios where the application needs to display different UI elements (e.g., Showing or hiding certain menu options based on the user’s role or attributes, displaying user-specific information like name or email) or enable/disable features based on the user's identity and attributes (e.g., premium users vs. free users). Since the ID Token is meant to be consumed by the client application, it is appropriate for the client to use it to make UI-related authorization decisions. The sensitive information (PII) in the ID Token should not be sent to downstream services or resource servers.

This code demonstrates how to use AWS Amplify to retrieve and leverage ID tokens to implement role-based access control in a React dashboard based on Cognito user groups and custom attributes.

In nutshell, ID Tokens:

Purpose: Designed for client-side authentication and conveying user identity information e.g. show the user's name, email address, avatar, and such at the top right of the page
Contains: Personally Identifiable Information (PII) such as email addresses, names, and other sensitive user data.
Usage: Should only be consumed by the client application that requested the authentication.
Not Recommended for Authorization at the resource service: Using ID tokens for authorization at resource servers is a security anti-pattern. Because the ID token often contains unencrypted personally identifiable information (PII), it should not be sent to resource servers. Avoid sharing data—especially PII—with systems that don't require it to perform their function

When a backend API, microservice, or any resource server (e.g., AWS API Gateway, an application backend) needs to determine whether a user has permission to access a resource, it should rely on the Access Tokens. Access Tokens are designed for authorization and contain claims specifically meant for access control, such as scopes, roles, or permissions. They are short-lived and contain only the information necessary for access control, reducing security risks. The backend service can validate the token’s signature, issuer, and claims before granting. More information on JWT verification can be found here.

Resource Server common authorization scenarios:

- Determining if a user can access specific API endpoints
- Checking if a user can perform CRUD operations
- Validating if a user has the right scope to access a resource

Why Access Token is Appropriate Here:

- Contains only necessary authorization claims.
- Can include custom scopes for fine-grained control. For further reading on this topic, please refer to this auth0 blog
- Shorter lifetime for better security.
- Doesn't expose unnecessary PII.
- Optimized for resource server validation.

Sometimes, your resource server needs additional information to make authorization decisions that isn't included in the standard access token. You can use Cognito's Pre-Token Generation Lambda to add custom claims to your access token. Here's how it works:

Standard Access Token might only have basic claims:

Using Pre-Token Generation Lambda trigger to enrich it:

Resulting "enriched" Access Token:

Key Benefits:

- Add authorization-specific data without exposing unnecessary PII.
- Keep control over what information is included.
- Some claims can be encrypted if necessary for additional data protection - see https://datatracker.ietf.org/doc/draft-ietf-oauth-selective-disclosure-jwt/
- Add only the claims needed for authorization decisions

This approach allows you to have all necessary authorization data in the access token while maintaining security and privacy best practices.

Now, when you absolutely must include PII (Personally Identifiable Information) in an Access Token for authorization purposes, you should encrypt this sensitive data. Here's how this concept works:

Example of sensitive PII that might be needed:

Use Pre-Token Lambda Trigger for encryption:

Resulting Access Token (With Encrypted PII):

Best Practices:

- Only encrypt data that absolutely needs to be in the token
- Use appropriate KMS key policies
- Implement proper logging and monitoring
- Consider data residency requirements
- Implement proper error handling
- Use the minimum required IAM permissions
- Consider implementing rate limiting
- Regular security audits of the encryption/decryption process

In the context of Amazon Cognito and modern authentication flows, it's crucial to use tokens for their intended purposes. ID tokens should be used for client-side authentication and authorization (which are UX features in the client), while access tokens should be used for authorization at resource servers. This separation of concerns enhances security, protects user privacy, and allows for more efficient and effective authorization mechanisms.