CognitoJWT is a Python library designed to decode and verify Amazon Cognito JWT (JSON Web Token) tokens. It simplifies the process of validating ID and Access tokens issued by AWS Cognito User Pools, ensuring their integrity and authenticity. The library supports both synchronous (using `requests`) and asynchronous (using `aiohttp`) modes. While the last release was in 2021 (v1.4.1), its GitHub repository is archived, indicating a maintenance-only status with no active feature development. [2, 14]
pip install cognitojwt[sync]Verified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to decode and verify a Cognito JWT token using the synchronous `cognitojwt.decode` function. It requires your AWS region, Cognito User Pool ID, and optionally your App Client ID for `aud` (audience) claim verification. For asynchronous operations, use `cognitojwt.decode_async` within an `async` context. Remember to replace placeholder values with your actual Cognito token and configuration. For production, never set `testmode=True` and ensure tokens are retrieved from a secure authentication flow. [14]
Be aware of potential lack of future updates or community support. For new projects, consider alternatives like directly using `python-jose` or more actively maintained AWS SDK integrations if deeper Cognito interaction is needed.
CognitoJWT handles JWKS fetching, but ensure your environment allows outbound network calls to the JWKS endpoint. If deploying in a private VPC without internet access, set the `AWS_COGNITO_JWKS_PATH` environment variable to a local path of the `jwks.json` file. [2, 14]
After decoding, explicitly check the `token_use` claim in the `verified_claims` dictionary to ensure it matches the expected token type (e.g., 'id' for ID tokens, 'access' for Access tokens) for your application's context. The `app_client_id` parameter can also help verify the `aud` claim.
Most JWT libraries, including those underlying cognitojwt, support a small clock tolerance (e.g., 5 minutes) when validating expiration. Ensure this is configured or understood in your environment. The `testmode=True` option in `cognitojwt.decode` should *only* be used for development and *never* in production. [14]
This is expected behavior for expired tokens. Your application should handle this by prompting the user for re-authentication or using a valid refresh token to obtain new ID and access tokens if applicable. Ensure your system clock is synchronized.
Ensure your application can successfully fetch the latest JWKS file from `https://cognito-idp.{region}.amazonaws.com/{userPoolId}/.well-known/jwks.json`. If caching JWKS, clear the cache and re-fetch. Verify that the `region` and `userpool_id` provided to `cognitojwt.decode` are correct. [4]Ensure the `app_client_id` passed to `cognitojwt.decode` or `cognitojwt.decode_async` is the correct client ID that the token was issued for. If your application supports multiple client IDs, pass a list or tuple of allowed client IDs. [14]
Verify that the `region` and `userpool_id` passed to `cognitojwt.decode` or `cognitojwt.decode_async` correctly correspond to the Cognito User Pool that issued the token. The expected issuer format is `https://cognito-idp.{region}.amazonaws.com/{userPoolId}`. [1]