A library for ATProtocol identities.
smokesignal.events
1# atproto-oauth-axum
2
3Axum web framework integration for AT Protocol OAuth.
4
5## Overview
6
7Production-ready OAuth handlers for authorization flows, callbacks, JWKS endpoints, and metadata with secure state management.
8
9## Features
10
11- **OAuth endpoint handlers**: Complete Axum handlers for authorization flows, callbacks, and metadata endpoints
12- **JWKS endpoint**: JSON Web Key Set endpoint for public key distribution to authorization servers
13- **Client metadata**: RFC 7591 compliant OAuth client metadata endpoint for dynamic registration
14- **Callback processing**: OAuth authorization callback handler with state validation and token exchange
15- **State management**: Secure OAuth state and request management with Axum extractors
16- **Error handling**: Comprehensive error handling with proper HTTP status codes
17
18## CLI Tools
19
20The following command-line tool is available when built with the `clap` feature:
21
22- **`atproto-oauth-tool`**: Complete OAuth login workflow tool for AT Protocol services with local callback server
23
24## Usage
25
26### Basic Server Setup
27
28```rust
29use atproto_oauth_axum::{
30 handle_complete::handle_oauth_callback,
31 handle_jwks::handle_oauth_jwks,
32 handler_metadata::handle_oauth_metadata,
33 state::OAuthClientConfig,
34};
35use axum::{routing::get, Router};
36
37let oauth_config = OAuthClientConfig {
38 client_uri: "https://your-app.com".to_string(),
39 client_id: "https://your-app.com/oauth/client-metadata.json".to_string(),
40 redirect_uris: "https://your-app.com/oauth/callback".to_string(),
41 jwks_uri: "https://your-app.com/.well-known/jwks.json".to_string(),
42 signing_keys: vec![identify_key("did:key:zQ3sh...")?],
43};
44
45let app = Router::new()
46 .route("/oauth/client-metadata.json", get(handle_oauth_metadata))
47 .route("/.well-known/jwks.json", get(handle_oauth_jwks))
48 .route("/oauth/callback", get(handle_oauth_callback))
49 .with_state(oauth_config);
50```
51
52### OAuth Handlers
53
54The library provides ready-to-use handlers for:
55
56- **Client Metadata**: Generates RFC 7591 compliant metadata
57- **JWKS Endpoint**: Serves JSON Web Key Sets for signature verification
58- **Callback Processing**: Handles OAuth authorization callbacks with token exchange
59
60## Command Line Examples
61
62```bash
63# Start OAuth login flow for a handle
64cargo run --bin atproto-oauth-tool login did:key:zQ3sh... alice.bsky.social
65
66# Start OAuth login flow for a DID
67cargo run --bin atproto-oauth-tool login did:key:zQ3sh... did:plc:user123
68```
69
70The tool provides a complete OAuth client implementation with:
71- Subject resolution and DID document retrieval
72- PDS and authorization server discovery
73- PKCE and DPoP parameter generation
74- Local web server for callback handling
75- Complete token exchange flow
76
77## License
78
79MIT License