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 tangled.org/vvill.dev/caddy-atproto-auth
23```
24
25## Configuration
26
27### Global Options
28
29The `atproto` global block configures the shared storage and security settings.
30
31```caddyfile
32{
33 atproto {
34 # Path to the SQLite database.
35 # Default: "atproto.db"
36 storage_path /var/lib/caddy/atproto.db
37
38 # A random 32+ character string used to sign session cookies.
39 # REQUIRED.
40 cookie_secret "change-me-to-a-secure-random-string-at-least-32-chars"
41 }
42}
43```
44
45### Authentication Portal (`atproto_portal`)
46
47The `atproto_portal` directive configures the central authentication server. This handles the OAuth flow, serves the login page, and issues session cookies.
48
49```caddyfile
50auth.example.com {
51 atproto_portal {
52 # The public domain of the portal.
53 # REQUIRED.
54 domain auth.example.com
55
56 # The display name shown on the login page.
57 # Default: "Authentication Portal"
58 name "My Services"
59
60 # Custom UI templates (optional)
61 ui {
62 # Path to a custom HTML template for the login page.
63 login_template /path/to/login.html
64 }
65 }
66}
67```
68
69### Authentication Gate (`atproto_gate`)
70
71The `atproto_gate` directive protects your services. It verifies the session cookie and enforces access control.
72
73```caddyfile
74app.example.com {
75 atproto_gate {
76 # List of allowed identities (DIDs or Handles).
77 # REQUIRED.
78 allow @alice.bsky.social
79 allow did:plc:1234abcd...
80
81 # URL of the central Auth Portal.
82 # Requests without a valid session will be redirected here.
83 # REQUIRED (unless in Standalone Mode).
84 portal_url https://auth.example.com
85
86 # Standalone Mode Configuration (Alternative to portal_url)
87 # If set, this gate acts as its own portal.
88 # domain app.example.com
89
90 # Custom UI templates (optional)
91 ui {
92 # Path to a custom HTML template for the "Access Denied" page.
93 forbidden_template /path/to/forbidden.html
94 }
95 }
96
97 reverse_proxy localhost:8080
98}
99```
100
101## Documentation
102
103See the `docs/` folder for detailed architectural constraints and implementation details.