jwt-verify 0.1.2

# JWT Verify Examples

Examples demonstrating **JWT verification** for **AWS Cognito** and **OIDC-compatible** identity providers.

## Quick Start

1. Copy the example environment file:

   ```bash
   cp .env.example .env
   ```

2. Edit `.env` with your configuration:

   ```bash
   # For Cognito
   AWS_REGION=us-east-1
   COGNITO_USER_POOL_ID=us-east-1_example
   COGNITO_CLIENT_ID=your-client-id
   COGNITO_ID_TOKEN=your-id-token
   COGNITO_ACCESS_TOKEN=your-access-token
   ```

3. Run the examples:

   ```bash
   # Basic examples (CLI)
   cargo run --example cognito_basic
   cargo run --example oidc_basic

   # Axum web server examples
   cargo run --example cognito_axum
   cargo run --example oidc_axum
   ```

## Examples Overview

### Basic Examples (CLI)

#### `cognito_basic.rs`

Demonstrates AWS Cognito JWT verification:

- ✅ 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, malformed tokens)
- ✅ JWK prefetching (hydration)

#### `oidc_basic.rs`

Demonstrates OIDC JWT verification:

- ✅ Single provider with single client ID
- ✅ Multiple providers with different client IDs
- ✅ Single provider with multiple client IDs
- ✅ Negative test cases
- ✅ JWK prefetching (hydration)

### Axum Integration Examples (Web Server)

#### `cognito_axum.rs`

Full-featured Axum web server with Cognito JWT authentication:

- ✅ Self-contained example with Bearer token extraction
- ✅ Converts `JwtError` to `PublicJwtError` for security
- ✅ Public endpoints (no authentication)
- ✅ Protected endpoints requiring ID tokens
- ✅ Protected endpoints requiring access tokens
- ✅ Role-based access control (admin scope check)
- ✅ Flexible endpoint accepting both token types
- ✅ Proper error handling with HTTP status codes
- ✅ JWK prefetching on startup

**Endpoints:**

- `GET /` - Public endpoint
- `GET /health` - Health check
- `GET /protected/id-token` - Requires ID token
- `GET /protected/access-token` - Requires access token
- `GET /admin` - Requires access token with 'admin' scope
- `GET /user-info` - Accepts either ID or access token

**Usage:**

```bash
# Start the server
cargo run --example cognito_axum

# Test endpoints
curl http://localhost:3000/
curl -H "Authorization: Bearer <ID_TOKEN>" http://localhost:3000/protected/id-token
curl -H "Authorization: Bearer <ACCESS_TOKEN>" http://localhost:3000/protected/access-token
```

#### `oidc_axum.rs`

Full-featured Axum web server with OIDC JWT authentication:

- ✅ Self-contained example with Bearer token extraction
- ✅ Converts `JwtError` to `PublicJwtError` for security
- ✅ Same features as `cognito_axum.rs` but for OIDC providers
- ✅ Works with any OIDC-compatible identity provider
- ✅ Can be used with Cognito as an OIDC provider

**Endpoints:**

- Same as `cognito_axum.rs`

**Usage:**

```bash
# Start the server
cargo run --example oidc_axum

# Test endpoints
curl http://localhost:3000/
curl -H "Authorization: Bearer <ID_TOKEN>" http://localhost:3000/protected/id-token
curl -H "Authorization: Bearer <ACCESS_TOKEN>" http://localhost:3000/protected/access-token
```

## Configuration Reference

### AWS Cognito

| Variable               | Description                  | Example                 |
| ---------------------- | ---------------------------- | ----------------------- |
| `AWS_REGION`           | AWS region of your user pool | `us-east-1`             |
| `COGNITO_USER_POOL_ID` | Cognito user pool ID         | `us-east-1_example`     |
| `COGNITO_CLIENT_ID`    | Client ID (web app)          | `your-client-id`        |
| `COGNITO_CLIENT_ID_2`  | Client ID (mobile app)       | `your-mobile-client-id` |
| `COGNITO_ID_TOKEN`     | ID token for testing         | `eyJraWQ...`            |
| `COGNITO_ACCESS_TOKEN` | Access token for testing     | `eyJraWQ...`            |

**Multiple user pools:**

```bash
# Second user pool
AWS_REGION_2=us-west-2
COGNITO_USER_POOL_ID_2=us-west-2_example2
COGNITO_CLIENT_ID_2=client2
```

### OIDC Providers

| Variable            | Description              | Example                                              |
| ------------------- | ------------------------ | ---------------------------------------------------- |
| `OIDC_ISSUER`       | Provider issuer URL      | `https://accounts.example.com`                       |
| `OIDC_JWKS_URL`     | JWKS URL (optional)      | `https://accounts.example.com/.well-known/jwks.json` |
| `OIDC_CLIENT_ID`    | Client ID                | `your-client-id`                                     |
| `OIDC_ID_TOKEN`     | ID token for testing     | `eyJraWQ...`                                         |
| `OIDC_ACCESS_TOKEN` | Access token for testing | `eyJraWQ...`                                         |

**Multiple providers:**

```bash
# Second provider
OIDC_ISSUER_2=https://auth.example2.com
OIDC_JWKS_URL_2=https://auth.example2.com/.well-known/jwks.json
OIDC_CLIENT_ID_2=client2
```

### Using Cognito as OIDC Provider

AWS Cognito can be used with the OIDC verifier:

```bash
OIDC_ISSUER=https://cognito-idp.us-east-1.amazonaws.com/us-east-1_example
OIDC_JWKS_URL=https://cognito-idp.us-east-1.amazonaws.com/us-east-1_example/.well-known/jwks.json
OIDC_CLIENT_ID=your-client-id
```

## Getting Test Tokens

### AWS Cognito

Using AWS CLI:

```bash
aws cognito-idp admin-initiate-auth \
  --user-pool-id us-east-1_example \
  --client-id your-client-id \
  --auth-flow ADMIN_USER_PASSWORD_AUTH \
  --auth-parameters USERNAME=user@example.com,PASSWORD=YourPassword123
```

Or use AWS Amplify in your application and extract tokens from the authentication response.

### OIDC Providers

Most OIDC providers offer:

- Developer consoles with token generation tools
- OAuth 2.0 authorization code flow
- Test clients for development

Check your provider's documentation for specific instructions.