{"id":6746,"library":"okta-jwt-verifier","title":"Okta JWT Verifier for Python","description":"A Python library for validating JWT access and ID tokens issued by Okta. It simplifies the process of verifying token signatures, expiration, issuer, and audience, ensuring secure API access in Python applications. The current version is 0.4.0. Release cadence is typically moderate, with updates primarily for dependency bumps, security fixes, or minor feature enhancements.","status":"active","version":"0.4.0","language":"en","source_language":"en","source_url":"https://github.com/okta/okta-jwt-verifier-python","tags":["okta","jwt","auth","security","token-validation","oidc"],"install":[{"cmd":"pip install okta-jwt-verifier","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for JWT parsing and validation.","package":"PyJWT"},{"reason":"Used for fetching JWKS (JSON Web Key Set) from the Okta issuer.","package":"requests"},{"reason":"Provides cryptographic primitives for JWT signature verification.","package":"cryptography"}],"imports":[{"symbol":"JwtVerifier","correct":"from okta_jwt_verifier import JwtVerifier"},{"symbol":"InvalidTokenException","correct":"from okta_jwt_verifier.exceptions import InvalidTokenException"}],"quickstart":{"code":"import os\nimport asyncio\nfrom okta_jwt_verifier import JwtVerifier\nfrom okta_jwt_verifier.exceptions import InvalidTokenException, MissingIssuerException, MissingAudienceException\n\n# --- Configuration (replace with your actual Okta values) ---\n# Your Okta Org URL, e.g., 'https://dev-12345678.okta.com'\nOKTA_ORG_URL = os.environ.get('OKTA_ORG_URL', 'https://dev-12345678.okta.com')\n# The audience identifier for your API, e.g., 'api://default' or a specific Client ID\nOKTA_AUDIENCE = os.environ.get('OKTA_AUDIENCE', 'api://default')\n\n# An example JWT token. FOR SUCCESSFUL VERIFICATION, replace this with a real Okta Access Token.\n# This placeholder token is designed to match the default issuer/audience but will have an invalid signature.\nEXAMPLE_JWT_TOKEN = os.environ.get('EXAMPLE_JWT_TOKEN', 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJleHAiOjQ4MjE5MzkyMDAsImF1ZCI6ImFwaTovL2RlZmFhdWx0IiwiaXNzIjoiaHR0cHM6Ly9kZXYtMTIzNDU2NzguT2t0YS5jb20ifQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c')\n\nasync def verify_token_example():\n    if 'dev-12345678.okta.com' in OKTA_ORG_URL or OKTA_AUDIENCE == 'api://default':\n        print(\"WARNING: Using placeholder values. For successful verification, set real OKTA_ORG_URL and OKTA_AUDIENCE environment variables.\")\n    if EXAMPLE_JWT_TOKEN == 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJleHAiOjQ4MjE5MzkyMDAsImF1ZCI6ImFwaTovL2RlZmFhdWx0IiwiaXNzIjoiaHR0cHM6Ly9kZXYtMTIzNDU2NzguT2t0YS5jb20ifQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c':\n        print(\"WARNING: Using a dummy JWT token. Verification will likely fail with 'Invalid signature' or similar errors. Set EXAMPLE_JWT_TOKEN environment variable.\")\n    \n    print(f\"\\nAttempting to verify token with:\\n  Issuer: {OKTA_ORG_URL}\\n  Audience: {OKTA_AUDIENCE}\")\n\n    try:\n        # Initialize the verifier with your Okta issuer and expected audience\n        jwt_verifier = JwtVerifier(\n            issuer=OKTA_ORG_URL,\n            audience=OKTA_AUDIENCE\n        )\n\n        # Use verify_access_token for access tokens or verify_id_token for ID tokens\n        verified_claims = await jwt_verifier.verify_access_token(EXAMPLE_JWT_TOKEN)\n\n        print(\"\\nJWT Token successfully verified!\")\n        print(f\"Claims: {verified_claims}\")\n\n    except (InvalidTokenException, MissingIssuerException, MissingAudienceException) as e:\n        print(f\"\\nJWT Token verification failed: {e}\")\n        print(\"Please ensure your OKTA_ORG_URL, OKTA_AUDIENCE, and EXAMPLE_JWT_TOKEN are correctly configured and valid.\")\n    except Exception as e:\n        print(f\"\\nAn unexpected error occurred during verification: {e}\")\n\nif __name__ == \"__main__\":\n    asyncio.run(verify_token_example())\n","lang":"python","description":"This quickstart demonstrates how to initialize the `JwtVerifier` and verify an Okta Access Token. Remember to replace the placeholder environment variables (or directly set the values) with your actual Okta Org URL, API Audience, and a real JWT token for successful verification. The `verify_access_token` method is asynchronous and must be awaited."},"warnings":[{"fix":"Double-check your Okta application configuration for the exact issuer URL and the audience ID your API expects. Inspect the JWT token's `iss` and `aud` claims to ensure they match.","message":"Incorrect Issuer (Okta Org URL) or Audience. The `issuer` and `audience` values passed to `JwtVerifier` *must* exactly match the `iss` and `aud` claims within the JWT token and your Okta application/API configuration. Mismatches are a frequent cause of validation failures.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your code uses `async def` for functions that call `verify_access_token` or `verify_id_token`, and execute your main asynchronous function using `asyncio.run()`.","message":"Asynchronous API usage. The primary verification methods (`verify_access_token` and `verify_id_token`) are `async` functions. They must be called with `await` within an `async` context (e.g., an `async def` function run via `asyncio.run()`). Calling them synchronously will raise a `RuntimeWarning` or `TypeError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure the application environment has outbound HTTP/HTTPS access to your Okta Org URL. If behind a proxy, configure `requests` to use the proxy (e.g., via `HTTP_PROXY`/`HTTPS_PROXY` environment variables, which `requests` generally respects).","message":"Network access required for JWKS. The verifier needs to fetch public keys (JWKS) from your Okta Org URL's `.well-known/openid-configuration/jwks` endpoint to verify token signatures. If your application environment lacks internet access, is behind a restrictive firewall, or has proxy issues, verification will fail.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use `jwt_verifier.verify_access_token()` for access tokens (used for API authorization) and `jwt_verifier.verify_id_token()` for ID tokens (used for user authentication and identity information).","message":"Token Type Mismatch. Using `verify_access_token` for an ID token or `verify_id_token` for an access token might lead to unexpected validation errors or 'invalid token' messages, as the expected claims and validation rules can differ between token types.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}