axum-jwt-auth 0.6.1

A simple JWT authentication middleware for Axum
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

# axum-jwt-auth

[![Rust](https://github.com/cmackenzie1/axum-jwt-auth/actions/workflows/rust.yml/badge.svg)](https://github.com/cmackenzie1/axum-jwt-auth/actions/workflows/rust.yml)
[![Crates.io Version](https://img.shields.io/crates/v/axum-jwt-auth)](https://crates.io/crates/axum-jwt-auth)
[![docs.rs](https://img.shields.io/docsrs/axum-jwt-auth)](https://docs.rs/axum-jwt-auth)

JWT authentication middleware for Axum. Supports local keys and remote JWKS with automatic caching and refresh.

## Installation

```bash
cargo add axum-jwt-auth
```

## Quick Start

```rust
use axum::{routing::get, Router};
use axum_jwt_auth::{Claims, JwtDecoderState, LocalDecoder};
use jsonwebtoken::{DecodingKey, Algorithm, Validation};
use serde::{Deserialize, Serialize};
use std::sync::Arc;

#[derive(Serialize, Deserialize)]
struct MyClaims {
    sub: String,
    exp: usize,
}

async fn protected(user: Claims<MyClaims>) -> String {
    format!("Hello, {}!", user.claims.sub)
}

#[tokio::main]
async fn main() {
    let keys = vec![DecodingKey::from_secret(b"secret")];
    let decoder = LocalDecoder::builder()
        .keys(keys)
        .validation(Validation::new(Algorithm::HS256))
        .build()
        .unwrap();

    let state = JwtDecoderState {
        decoder: Arc::new(decoder),
    };

    let app = Router::new()
        .route("/protected", get(protected))
        .with_state(state);

    // Server will expect: Authorization: Bearer <jwt>
}
```

## Features

- **Local validation**: Validate JWTs with local RSA/HMAC keys
- **Remote JWKS**: Automatic fetching, caching, and refresh of remote JWKS endpoints
- **Flexible token extraction**: Bearer tokens (default), custom headers or cookies
- **Type-safe claims**: Strongly-typed claims via generic extractors
- **Axum integration**: Drop-in extractor for route handlers

## Remote JWKS

Validate JWTs using remote JWKS endpoints with automatic caching and refresh:

```rust
use axum_jwt_auth::{Claims, JwtDecoderState, RemoteJwksDecoder};
use jsonwebtoken::{Algorithm, Validation};
use std::sync::Arc;

#[tokio::main]
async fn main() {
    let mut validation = Validation::new(Algorithm::RS256);
    validation.set_audience(&["your-audience"]);
    validation.set_issuer(&["your-issuer"]);

    let decoder = RemoteJwksDecoder::builder()
        .jwks_url("https://your-auth-provider.com/.well-known/jwks.json".to_string())
        .validation(validation)
        .build()
        .unwrap();
    let decoder = Arc::new(decoder);

    // Initialize: fetch keys immediately and start background refresh task
    let shutdown_token = decoder.initialize().await.expect("Failed to initialize JWKS decoder");

    let state = JwtDecoderState { decoder };
    let app = Router::new()
        .route("/protected", get(protected))
        .with_state(state);

    // Later, during application shutdown:
    shutdown_token.cancel();
}
```

The remote decoder:
- Fetches JWKS on initialization
- Automatically refreshes keys in the background (default: every hour)
- Caches keys for fast lookup by `kid` (key ID)
- Includes retry logic with configurable attempts and backoff
- Supports graceful shutdown via `CancellationToken`

## Custom Token Extractors

Extract tokens from custom headers or cookies:

```rust
use axum_jwt_auth::{define_header_extractor, define_cookie_extractor};

define_header_extractor!(XAuthToken, "x-auth-token");
define_cookie_extractor!(AuthCookie, "auth_token");

async fn header_auth(user: Claims<MyClaims, HeaderTokenExtractor<XAuthToken>>) { }
async fn cookie_auth(user: Claims<MyClaims, CookieTokenExtractor<AuthCookie>>) { }
```

## Examples

See the [examples](./examples/) directory for complete working examples:

- [**local**](./examples/local/) - Local RSA key validation
- [**remote**](./examples/remote/) - Remote JWKS with caching and retry logic
- [**cloudflare**](./examples/cloudflare/) - Cloudflare Access JWT validation

## License

MIT - see [LICENSE](LICENSE) for details.