A library for ATProtocol identities.
smokesignal.events
1# atproto-oauth-aip
2
3OAuth AIP (Identity Provider) implementation for AT Protocol.
4
5## Overview
6
7Complete OAuth 2.0 authorization code flow with PAR, PKCE, token exchange, and AT Protocol session management for identity providers.
8
9## Features
10
11- **OAuth 2.0 authorization code flow**: Complete implementation with PKCE support for secure authentication
12- **Pushed Authorization Requests (PAR)**: Enhanced security through server-side request storage
13- **Token exchange**: Secure OAuth token issuance and refresh capabilities
14- **AT Protocol session management**: Convert OAuth tokens to AT Protocol sessions with DID resolution
15- **Resource validation**: OAuth protected resource and authorization server configuration validation
16- **Structured error handling**: Comprehensive error types following AT Protocol conventions
17
18## CLI Tools
19
20This crate does not provide standalone CLI tools. It serves as a library for OAuth AIP implementations.
21
22
23## Usage
24
25### Basic OAuth Flow
26
27```rust
28use atproto_oauth_aip::{OAuthClient, oauth_init, oauth_complete, session_exchange};
29use atproto_oauth::storage::MemoryStorage;
30
31#[tokio::main]
32async fn main() -> Result<(), Box<dyn std::error::Error>> {
33 // Initialize OAuth client
34 let client = OAuthClient::new(
35 "https://your-app.com/client-id".to_string(),
36 Some("your-client-secret".to_string()),
37 "https://your-app.com/callback".to_string(),
38 );
39
40 // Initialize storage (use persistent storage in production)
41 let storage = MemoryStorage::new();
42
43 // Start OAuth flow
44 let (authorization_url, state) = oauth_init(
45 &client,
46 "user@example.com", // User identifier
47 &storage,
48 ).await?;
49
50 // Redirect user to authorization_url
51 println!("Please visit: {}", authorization_url);
52
53 // After user authorizes and is redirected back with code and state...
54 let authorization_code = "received-auth-code";
55 let returned_state = "returned-state";
56
57 // Complete OAuth flow
58 let access_token = oauth_complete(
59 &client,
60 authorization_code,
61 returned_state,
62 &storage,
63 ).await?;
64
65 // Exchange for AT Protocol session
66 let session = session_exchange(
67 &client,
68 &access_token,
69 &storage,
70 ).await?;
71
72 println!("Authenticated as: {} ({})", session.handle, session.did);
73 println!("PDS Endpoint: {}", session.pds_endpoint);
74
75 Ok(())
76}
77```
78
79### Fetching OAuth Metadata
80
81```rust
82use atproto_oauth_aip::resources::{oauth_protected_resource, oauth_authorization_server};
83
84// Get OAuth protected resource configuration
85let protected_resource = oauth_protected_resource("https://bsky.social").await?;
86
87// Get OAuth authorization server metadata
88let auth_server = oauth_authorization_server(&protected_resource).await?;
89```
90
91## API Documentation
92
93### Core Types
94
95- `OAuthClient`: OAuth client credentials and configuration
96- `ATProtocolSession`: Authenticated session containing DID, handle, and PDS endpoint
97
98### Main Functions
99
100- `oauth_init()`: Initiates OAuth flow using PAR
101- `oauth_complete()`: Exchanges authorization code for access token
102- `session_exchange()`: Converts OAuth access token to AT Protocol session
103
104### Resource Functions
105
106- `oauth_protected_resource()`: Fetch OAuth protected resource metadata
107- `oauth_authorization_server()`: Fetch OAuth authorization server metadata
108
109## Error Handling
110
111The crate uses typed errors following the AT Protocol error format:
112
113```rust
114use atproto_oauth_aip::OAuthWorkflowError;
115
116match result {
117 Err(OAuthWorkflowError::InvalidAuthorizationRequest(e)) => {
118 // Handle PAR errors
119 }
120 Err(OAuthWorkflowError::TokenExchangeFailed(e)) => {
121 // Handle token exchange errors
122 }
123 // ... other error types
124}
125```
126
127## Storage Requirements
128
129This crate requires an implementation of the `OAuthStorage` trait from `atproto-oauth`. For production use, implement persistent storage rather than using `MemoryStorage`.
130
131## Security Considerations
132
133- Always use HTTPS URLs for OAuth endpoints
134- Implement proper state validation to prevent CSRF attacks
135- Store client secrets securely
136- Use persistent storage with appropriate security measures
137- Validate DPoP keys when required by the authorization server
138
139## Dependencies
140
141This crate depends on:
142- `atproto-oauth`: Core OAuth implementation
143- `atproto-identity`: AT Protocol identity resolution
144- `atproto-record`: Record handling
145- `reqwest`: HTTP client
146- `serde`: Serialization
147- `tokio`: Async runtime
148
149## License
150
151MIT License