Okta JWT Verifier for Python

Warnings

• gotcha 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.
  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.
• gotcha 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`.
  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()`.
• gotcha 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.
  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).
• gotcha 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.
  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).

Install

• pip install okta-jwt-verifier Install stable version

Imports

• JwtVerifier

  from okta_jwt_verifier import JwtVerifier

• InvalidTokenException

  from okta_jwt_verifier.exceptions import InvalidTokenException

Quickstart

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.

import os
import asyncio
from okta_jwt_verifier import JwtVerifier
from okta_jwt_verifier.exceptions import InvalidTokenException, MissingIssuerException, MissingAudienceException

# --- Configuration (replace with your actual Okta values) ---
# Your Okta Org URL, e.g., 'https://dev-12345678.okta.com'
OKTA_ORG_URL = os.environ.get('OKTA_ORG_URL', 'https://dev-12345678.okta.com')
# The audience identifier for your API, e.g., 'api://default' or a specific Client ID
OKTA_AUDIENCE = os.environ.get('OKTA_AUDIENCE', 'api://default')

# An example JWT token. FOR SUCCESSFUL VERIFICATION, replace this with a real Okta Access Token.
# This placeholder token is designed to match the default issuer/audience but will have an invalid signature.
EXAMPLE_JWT_TOKEN = os.environ.get('EXAMPLE_JWT_TOKEN', 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJleHAiOjQ4MjE5MzkyMDAsImF1ZCI6ImFwaTovL2RlZmFhdWx0IiwiaXNzIjoiaHR0cHM6Ly9kZXYtMTIzNDU2NzguT2t0YS5jb20ifQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c')

async def verify_token_example():
    if 'dev-12345678.okta.com' in OKTA_ORG_URL or OKTA_AUDIENCE == 'api://default':
        print("WARNING: Using placeholder values. For successful verification, set real OKTA_ORG_URL and OKTA_AUDIENCE environment variables.")
    if EXAMPLE_JWT_TOKEN == 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJleHAiOjQ4MjE5MzkyMDAsImF1ZCI6ImFwaTovL2RlZmFhdWx0IiwiaXNzIjoiaHR0cHM6Ly9kZXYtMTIzNDU2NzguT2t0YS5jb20ifQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c':
        print("WARNING: Using a dummy JWT token. Verification will likely fail with 'Invalid signature' or similar errors. Set EXAMPLE_JWT_TOKEN environment variable.")
    
    print(f"\nAttempting to verify token with:\n  Issuer: {OKTA_ORG_URL}\n  Audience: {OKTA_AUDIENCE}")

    try:
        # Initialize the verifier with your Okta issuer and expected audience
        jwt_verifier = JwtVerifier(
            issuer=OKTA_ORG_URL,
            audience=OKTA_AUDIENCE
        )

        # Use verify_access_token for access tokens or verify_id_token for ID tokens
        verified_claims = await jwt_verifier.verify_access_token(EXAMPLE_JWT_TOKEN)

        print("\nJWT Token successfully verified!")
        print(f"Claims: {verified_claims}")

    except (InvalidTokenException, MissingIssuerException, MissingAudienceException) as e:
        print(f"\nJWT Token verification failed: {e}")
        print("Please ensure your OKTA_ORG_URL, OKTA_AUDIENCE, and EXAMPLE_JWT_TOKEN are correctly configured and valid.")
    except Exception as e:
        print(f"\nAn unexpected error occurred during verification: {e}")

if __name__ == "__main__":
    asyncio.run(verify_token_example())