Caddy module to require at-proto authentication and restrict routes to DIDs
1# caddy-atproto-auth
2
3A native Caddy module that provides Identity-Aware Proxy (IAP) capabilities using the **atproto** (Bluesky) OAuth 2.1 ecosystem.
4
5Turn any atproto identity into a "Web Passport" for your self-hosted services. The module acts as an OAuth Confidential Client, managing the DPoP cryptographic handshake, session persistence, and DID-based authorization without requiring external authentication sidecars like Authelia.
6
7## Features
8
9- **Zero-Dependency**: Plugs directly into Caddy, no external databases (uses embedded SQLite).
10- **Stateless Verification**: Uses signed, domain-scoped cookies for lightning-fast request verification at the edge without database lookups.
11- **Two Deployment Modes**:
12 - *Standalone*: Add to any individual app's Caddyfile route directly.
13 - *Centralized Hub*: Act as an Identity Provider (`auth.example.com`) granting SSO access to many subdomains (`app.example.com`).
14- **Full Customization**: Fully override the login and forbidden pages with your own HTML templates.
15
16## Usage
17
18Build a custom Caddy binary with `xcaddy`:
19
20```bash
21xcaddy build \
22 --with github.com/vvill/caddy-atproto-auth
23```
24
25### Example: Centralized Auth Hub
26
27```caddyfile
28{
29 atproto {
30 storage_path /var/lib/caddy/atproto.db
31 cookie_secret "your-very-long-random-secret-key"
32 }
33}
34
35# The Portal (Login page and OAuth endpoints)
36auth.example.com {
37 atproto_portal {
38 name "My HomeLab"
39 domain auth.example.com
40 }
41}
42
43# A protected application
44app.example.com {
45 atproto_gate {
46 allow @alice.bsky.social
47 allow did:plc:1234...
48 portal_url https://auth.example.com
49 }
50
51 reverse_proxy localhost:8080
52}
53```
54
55## Documentation
56
57See the `docs/` folder for detailed architectural constraints and configuration options.