{"id":8020,"library":"cognitojwt","title":"CognitoJWT","description":"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]","status":"maintenance","version":"1.4.1","language":"en","source_language":"en","source_url":"http://github.com/borisrozumnuk/cognitojwt","tags":["aws","cognito","jwt","authentication","security"],"install":[{"cmd":"pip install cognitojwt[sync]","lang":"bash","label":"Synchronous mode"},{"cmd":"pip install cognitojwt[async]","lang":"bash","label":"Asynchronous mode"}],"dependencies":[{"reason":"Required for synchronous operations if installed with the `[sync]` extra.","package":"requests","optional":true},{"reason":"Required for asynchronous operations if installed with the `[async]` extra.","package":"aiohttp","optional":true}],"imports":[{"symbol":"cognitojwt","correct":"import cognitojwt"}],"quickstart":{"code":"import cognitojwt\nimport os\n\n# Replace with your actual Cognito details or load from environment variables\nid_token = os.environ.get('COGNITO_ID_TOKEN', 'YOUR_COGNITO_ID_TOKEN_HERE') # Example token, should come from authentication flow\nregion = os.environ.get('AWS_REGION', 'us-east-1')\nuserpool_id = os.environ.get('COGNITO_USERPOOL_ID', 'us-east-1_XXXXXXXXX')\napp_client_id = os.environ.get('COGNITO_APP_CLIENT_ID', 'YOUR_APP_CLIENT_ID') # Optional, but highly recommended for 'aud' claim verification\n\ntry:\n    # Synchronous mode example\n    verified_claims: dict = cognitojwt.decode(\n        id_token,\n        region,\n        userpool_id,\n        app_client_id=app_client_id, # Optional: verifies the 'aud' claim matches your app client ID\n        testmode=False # Set to True to disable token expiration check for testing only\n    )\n    print(\"Token successfully verified (sync mode):\")\n    print(verified_claims)\n\n    # Asynchronous mode example (requires an async context, e.g., FastAPI, Sanic, or standalone with asyncio.run)\n    # import asyncio\n    # async def main():\n    #     verified_claims_async: dict = await cognitojwt.decode_async(\n    #         id_token,\n    #         region,\n    #         userpool_id,\n    #         app_client_id=app_client_id,\n    #         testmode=False\n    #     )\n    #     print(\"Token successfully verified (async mode):\")\n    #     print(verified_claims_async)\n    # asyncio.run(main())\n\nexcept cognitojwt.exceptions.CognitoJWTException as e:\n    print(f\"Token verification failed: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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]"},"warnings":[{"fix":"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.","message":"The cognitojwt GitHub repository is archived, meaning it is no longer under active development for new features. While functional, consider this when starting new projects or evaluating long-term maintenance. [2]","severity":"gotcha","affected_versions":"All versions"},{"fix":"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]","message":"Do not hardcode Cognito public keys. AWS frequently rotates its signing keys. Always fetch the JSON Web Key Set (JWKS) from the provided Cognito endpoint to ensure signature verification uses the correct, up-to-date keys. [1]","severity":"breaking","affected_versions":"All versions"},{"fix":"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.","message":"Ensure proper validation of the `token_use` claim. Cognito issues both ID tokens (for user identity) and Access tokens (for API authorization), and mixing them up can lead to security vulnerabilities or validation failures. [1, 4]","severity":"gotcha","affected_versions":"All versions"},{"fix":"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]","message":"Be mindful of clock skew between your server and the Cognito service. A slight time difference can cause valid tokens to fail expiration checks. [1]","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"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.","cause":"The JWT token's 'exp' (expiration) claim indicates it has passed its valid timestamp.","error":"Token verification failed: Token is expired"},{"fix":"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]","cause":"The token's signature cannot be verified using the public keys obtained from the Cognito JWKS endpoint, likely due to stale or incorrect JWKS keys, or a tampered token.","error":"Token verification failed: Invalid signature"},{"fix":"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]","cause":"The 'aud' (audience) claim in the token's payload does not match the `app_client_id` provided during verification.","error":"Token verification failed: Invalid 'aud' claim"},{"fix":"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]","cause":"The 'iss' (issuer) claim in the token's payload does not match the expected Cognito User Pool issuer URL.","error":"Token verification failed: Invalid 'iss' claim"}]}