axum-jwt-auth 0.6.0

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

# 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

## 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.