Caddy module to require at-proto authentication and restrict routes to DIDs
docs: Add main README.md
author
Will Garrison
date
(Mar 4, 2026, 5:27 PM -0800)
commit
10b2f92e
10b2f92e6929233ae2f1d18f2dc92e4d486eaec4
parent
310f115f
310f115fe9a3c8a33aab371e4f7aa0ef392b6748
+57
+57
README.md
+57
README.md
···
1
+
# caddy-atproto-auth
2
+
3
+
A native Caddy module that provides Identity-Aware Proxy (IAP) capabilities using the **atproto** (Bluesky) OAuth 2.1 ecosystem.
4
+
5
+
Turn 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
+
18
+
Build a custom Caddy binary with `xcaddy`:
19
+
20
+
```bash
21
+
xcaddy 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)
36
+
auth.example.com {
37
+
atproto_portal {
38
+
name "My HomeLab"
39
+
domain auth.example.com
40
+
}
41
+
}
42
+
43
+
# A protected application
44
+
app.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
+
57
+
See the `docs/` folder for detailed architectural constraints and configuration options.