JWT Verify

Rust library for verifying JWTs signed by Amazon Cognito, and any OIDC-compatible IDP.

Inspired by awslabs/aws-jwt-verify.

Features

• Comprehensive validation of JWT tokens (ID tokens and Access tokens)
• Support for both AWS Cognito and generic OIDC providers
• Efficient JWK key management with automatic caching
• Multiple user pools/providers with automatic issuer matching
• Multiple client IDs per pool/provider
• Configurable clock skew and cache duration
• JWK prefetching (hydration) for cold start optimization
• Detailed error handling and reporting
• Thread-safe for use in async contexts
• Integration with popular Rust web frameworks (Axum)

Installation

Add this to your Cargo.toml:

[dependencies]
jwt-verify = "0.1.0"

Quick Start

Verifying AWS Cognito Tokens

use jwt_verify::{CognitoJwtVerifier, JwtError, JwtVerifier};

#[tokio::main]
async fn main() -> Result<(), JwtError> {
    // Create a verifier with a single user pool
    let verifier = CognitoJwtVerifier::new_single_pool(
        "us-east-1",              // AWS region
        "us-east-1_example",      // Cognito user pool ID
        &["client1".to_string()], // Allowed client IDs
    )?;

    // Verify an ID token
    let id_token = "your_jwt_id_token_here";
    let claims = verifier.verify_id_token(id_token).await?;

    println!("Subject: {}", claims.get_sub());
    println!("Email: {}", claims.get_email().unwrap_or("N/A"));

    // Verify an access token
    let access_token = "your_jwt_access_token_here";
    let access_claims = verifier.verify_access_token(access_token).await?;

    println!("Scopes: {:?}", access_claims.get_scopes());
    println!("Has 'read' scope: {}", access_claims.has_scope("read"));

    Ok(())
}

Verifying OIDC Tokens

use jwt_verify::{JwtError, JwtVerifier, OidcJwtVerifier, OidcProviderConfig};

#[tokio::main]
async fn main() -> Result<(), JwtError> {
    // Create a configuration for an OIDC provider
    let config = OidcProviderConfig::new(
        "https://accounts.example.com",                              // Issuer URL
        Some("https://accounts.example.com/.well-known/jwks.json"),  // JWKS URL
        &["client1".to_string()],                                    // Allowed client IDs
        None,                                                        // Optional additional config
    )?;

    // Create an OIDC verifier
    let verifier = OidcJwtVerifier::new(vec![config])?;

    // Verify an ID token
    let id_token = "your_jwt_id_token_here";
    let claims = verifier.verify_id_token(id_token).await?;

    println!("Subject: {}", claims.get_sub());

    Ok(())
}

Advanced Usage

Single Pool with Multiple Client IDs

A common use case is having one user pool with multiple client IDs (e.g., web app, mobile app):

use jwt_verify::{CognitoJwtVerifier, JwtError, VerifierConfig};
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), JwtError> {
    // Single user pool with multiple client IDs
    let config = VerifierConfig::new(
        "us-east-1",
        "us-east-1_example",
        &["web-client-id".to_string(), "mobile-client-id".to_string()],
        None,
    )?
    .with_clock_skew(Duration::from_secs(120))           // 2 minutes clock skew
    .with_cache_duration(Duration::from_secs(3600 * 12)); // 12 hours cache

    let verifier = CognitoJwtVerifier::new(vec![config])?;

    // Tokens from either client ID will be accepted
    let token = "your_jwt_token_here";
    let claims = verifier.verify_id_token(token).await?;

    Ok(())
}

Multiple User Pools

The verifier automatically selects the correct user pool based on the token's issuer claim:

use jwt_verify::{CognitoJwtVerifier, JwtError, VerifierConfig};

#[tokio::main]
async fn main() -> Result<(), JwtError> {
    // Create configurations for multiple user pools
    let config1 = VerifierConfig::new(
        "us-east-1",
        "us-east-1_pool1",
        &["client1".to_string()],
        None,
    )?;

    let config2 = VerifierConfig::new(
        "us-west-2",
        "us-west-2_pool2",
        &["client2".to_string()],
        None,
    )?;

    // Create a verifier with multiple user pools
    let verifier = CognitoJwtVerifier::new(vec![config1, config2])?;

    // The verifier automatically matches the token to the correct pool
    let token = "your_jwt_token_here";
    let claims = verifier.verify_id_token(token).await?;

    Ok(())
}

JWK Prefetching (Hydration)

Prefetch JWKs to avoid cold start latency:

use jwt_verify::{CognitoJwtVerifier, JwtError, JwtVerifier};

#[tokio::main]
async fn main() -> Result<(), JwtError> {
    let verifier = CognitoJwtVerifier::new_single_pool(
        "us-east-1",
        "us-east-1_example",
        &["client1".to_string()],
    )?;

    // Prefetch JWKs to warm up the cache
    let hydration_results = verifier.hydrate().await;
    for (pool_id, result) in hydration_results {
        match result {
            Ok(_) => println!("✅ Prefetched JWKs for pool {}", pool_id),
            Err(e) => println!("❌ Failed to prefetch for pool {}: {}", pool_id, e),
        }
    }

    // Now token verification will be faster
    let token = "your_jwt_token_here";
    let claims = verifier.verify_id_token(token).await?;

    Ok(())
}

Multiple OIDC Providers

use jwt_verify::{JwtError, OidcJwtVerifier, OidcProviderConfig};

#[tokio::main]
async fn main() -> Result<(), JwtError> {
    let provider1 = OidcProviderConfig::new(
        "https://accounts.example.com",
        Some("https://accounts.example.com/.well-known/jwks.json"),
        &["client1".to_string()],
        None,
    )?;

    let provider2 = OidcProviderConfig::new(
        "https://auth.example2.com",
        Some("https://auth.example2.com/.well-known/jwks.json"),
        &["client2".to_string()],
        None,
    )?;

    // Create a verifier with multiple providers
    let verifier = OidcJwtVerifier::new(vec![provider1, provider2])?;

    // The verifier automatically matches the token to the correct provider
    let token = "your_jwt_token_here";
    let claims = verifier.verify_id_token(token).await?;

    Ok(())
}

Examples

The library includes comprehensive examples demonstrating various use cases:

• cognito_basic.rs: AWS Cognito JWT verification including:
  • Single user pool with single client ID
  • Multiple user pools with different client IDs
  • Single user pool with multiple client IDs (web/mobile apps)
  • Negative test cases (wrong token types, expired tokens, etc.)
• oidc_basic.rs: OIDC JWT verification including:
  • Single provider with single client ID
  • Multiple providers with different client IDs
  • Single provider with multiple client IDs
  • Negative test cases

Running Examples

1. Set up configuration using a .env file:

   cd examples
   cp .env.example .env
   # Edit .env with your actual configuration
   

2. Run the examples:

   cargo run --example cognito_basic
   cargo run --example oidc_basic
   

Example Configuration

The examples support various configurations through environment variables:

# Single user pool with multiple client IDs
AWS_REGION=us-east-1
COGNITO_USER_POOL_ID=us-east-1_example
COGNITO_CLIENT_ID=web-app-client-id
COGNITO_CLIENT_ID_2=mobile-app-client-id

# Your test tokens
COGNITO_ID_TOKEN=your-id-token
COGNITO_ACCESS_TOKEN=your-access-token

See examples/README.md for detailed configuration instructions and more examples.

Common Use Cases

ID Token vs Access Token

• ID Tokens: Used for authentication - contains user identity information (email, name, etc.)
• Access Tokens: Used for authorization - contains scopes and permissions

// Verify ID token for authentication
let id_claims = verifier.verify_id_token(id_token).await?;
println!("User: {}", id_claims.get_email().unwrap_or("N/A"));

// Verify access token for authorization
let access_claims = verifier.verify_access_token(access_token).await?;
if access_claims.has_scope("admin") {
    // Allow admin operations
}

Error Handling

The library provides detailed error information for debugging:

match verifier.verify_id_token(token).await {
    Ok(claims) => {
        // Token is valid
        println!("User: {}", claims.get_sub());
    }
    Err(e) => {
        // Handle specific error cases
        eprintln!("Token verification failed: {}", e);
        // Don't expose detailed errors to clients in production
    }
}

Best Practices

1. Reuse verifier instances: Create a single verifier instance and reuse it for all verifications (thread-safe)
2. Set appropriate clock skew: Use 1-2 minutes to account for time differences between systems
3. Configure cache duration: Match your IdP's key rotation policy (default: 12 hours)
4. Prefetch JWKs: Use hydrate() to warm up the cache and avoid cold start latency
5. Use correct token types: ID tokens for authentication, access tokens for authorization
6. Validate scopes: Always check scopes in access tokens for authorization decisions
7. Handle errors gracefully: Don't expose detailed error information to clients in production
8. Multiple client IDs: Use a single pool/provider config with multiple client IDs for different apps (web, mobile)

License

This project is licensed under the MIT License.