How to Parse AWS Auth Cognito Token
How do you parse an AWS Auth Cognito token? You parse an AWS Auth Cognito token by decoding the JSON Web Token (JWT) returned after authentication, extracting claims such as user ID, groups, and expiration, and verifying its integrity using Amazon Cognito’s public keys, typically as part of a secure authorization flow in your backend or API.
For enterprise leaders, correctly parsing and validating Cognito tokens is fundamental to managing identity, enforcing access controls, and securing APIs in a scalable, compliant, and cloud-native architecture.
Step 1: Understand the Cognito Token Structure
When a user signs in through Amazon Cognito User Pools, they receive one or more tokens:
- ID Token: Contains user identity information (e.g., email, name)
- Access Token: Grants access to authorized resources (e.g., APIs)
- Refresh Token: Used to obtain new tokens without re-authenticating
These are JWTs (JSON Web Tokens), which are Base64-encoded and digitally signed.
Token Format:
php-template
<Header>.<Payload>.<Signature>
Each token includes claims, such as:
- sub – Unique user identifier
- email – User’s email address
- exp – Expiration timestamp
- aud – Client ID
- cognito:groups – User groups (for RBAC)
Executive Insight: Proper token parsing ensures secure identity enforcement across your cloud services and APIs.
Step 2: Decode the Token Payload
To parse the token, you decode the JWT payload (middle section) without verifying the signature, useful for internal processing, debugging, or non-sensitive tasks.
Example in Python:
import base64
import json
def decode_jwt(token):
payload = token.split(‘.’)[1]
padded = payload + ‘=’ * (-len(payload) % 4) # Pad for Base64 decoding
decoded = base64.urlsafe_b64decode(padded)
return json.loads(decoded)
token = “eyJraWQiOiJrM… (truncated)”
claims = decode_jwt(token)
print(claims)
Example in Node.js:
const jwt = require(‘jsonwebtoken’);
const token = “eyJraWQiOiJk…”; // JWT string
const decoded = jwt.decode(token);
console.log(decoded);
Note: Decoding ≠ verification. Always verify signatures in production flows.
Step 3: Verify the Token’s Authenticity
To ensure the token is valid and hasn’t been tampered with, verify the JWT signature using Cognito’s public keys.
1. Retrieve Public Keys from Cognito:
https://cognito-idp.{region}.amazonaws.com/{userPoolId}/.well-known/jwks.json
Example:
https://cognito-idp.us-east-1.amazonaws.com/us-east-1_AbCdEfGhI/.well-known/jwks.json
2. Use a JWT library that supports JWK verification:
Python (using python-jose):
from jose import jwt
import requests
region = “us-east-1”
user_pool_id = “us-east-1_XXXXXX”
client_id = “your-client-id”
jwks_url =
f”https://cognito-idp.{region}.amazonaws.com/{user_pool_id}/.well-known/jwks.json”
keys = requests.get(jwks_url).json()[“keys”]
token = “eyJraW…”
claims = jwt.decode(
token,
keys,
algorithms=[“RS256”],
audience=client_id
)
print(claims)
✅ Best Practice: Always validate the aud, exp, and iss claims to ensure the token was issued by your Cognito user pool and hasn’t expired.
Step 4: Use the Parsed Token for Authorization
Once validated, use the token’s claims to authorize access to backend resources:
- Map cognito:groups to roles in your app
- Use sub as a unique user key for data access
- Implement RBAC and ABAC policies in your logic or API Gateway
API Gateway Integration:
If you’re using API Gateway + Cognito Authorizer, the validated claims are automatically passed to your Lambda as part of the event.requestContext.authorizer.claims object.
Step 5: Handle Expiration and Refresh Tokens
Tokens expire, typically:
- ID & Access Tokens: 1 hour
- Refresh Token: 30 days (configurable)
Use the Refresh Token in client apps to get a new Access/ID token without re-authenticating:
POST /oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token
&client_id=YOUR_APP_CLIENT_ID
&refresh_token=YOUR_REFRESH_TOKEN
Enterprise Insight: Proper token lifecycle management reduces friction for users while maintaining security across sessions.
Final Thoughts
Parsing AWS Cognito tokens is essential for building secure, scalable authentication flows in cloud-native applications. Done properly, it enables fine-grained access control, personalized user experiences, and regulatory compliance.
For executives, integrating token-based auth into backend systems strengthens your organization’s security posture and simplifies identity management across apps and APIs.
