ATProto OAuth Integration Spec#

Relay OAuth Provider

v0.1 Draft — March 2026

Companion to: Provisioning API Spec, Mobile Architecture Spec

1. Overview#

The relay must be a compliant ATProto OAuth 2.1 authorization server so that third-party apps (Bluesky, etc.) can authenticate users and create records via XRPC. This document specifies how the relay integrates existing Rust OAuth libraries rather than building OAuth from scratch.

1.1 Why OAuth Matters#

Without a compliant OAuth provider, no third-party app can authenticate against the relay. A user who creates an identity through the mobile app or desktop PDS cannot log into Bluesky — the entire product is unusable. OAuth is on the critical path for every lifecycle phase.

1.2 ATProto OAuth Requirements#

The ATProto OAuth spec requires PDS implementations to support:

• OAuth 2.1 authorization code flow with PKCE (S256 only)
• DPoP (Demonstrating Proof-of-Possession) using ES256, with unique JTI per request and nonce support
• PAR (Pushed Authorization Requests) — mandatory for all client types
• Dynamic Client Registration (RFC 7591) — clients provide metadata URLs, not pre-registered credentials
• Server metadata at /.well-known/oauth-authorization-server
• JWKS endpoint for public key discovery
• Grant types: authorization_code and refresh_token
• Token endpoint auth: none and private_key_jwt
• Scopes: atproto and transition:generic
• CORS support for browser-based apps
• Refresh tokens are single-use (rotation on each use)
• Tokens bound to DPoP key and client_id

2. Existing Rust Ecosystem#

2.1 Recommended: atproto-oauth-axum#

Crate: atproto-oauth-axum (v0.14.0, Feb 2026) Author: Nick Gerakines Status: Actively maintained, 22 releases since June 2025, ~440 downloads/month

Provides pre-built Axum handlers for:

• Authorization endpoint
• Token endpoint
• PAR endpoint
• JWKS endpoint
• Server metadata endpoint
• Client metadata resolution
• Authorization callback handling

This is the most direct integration path if the relay uses Axum (which aligns with the Rust web server ecosystem).

2.2 Alternative: atproto-oauth-aip#

Crate: atproto-oauth-aip Status: Same author, lower-level workflow library

Use this if the relay uses a different HTTP framework (e.g., actix-web) or needs more control over the OAuth flow. Provides the OAuth logic without Axum-specific bindings.

2.3 Reference Implementation: graze-social/aip#

Repo: graze-social/aip (105 stars, v2.2.3, Jan 2026) Status: Production-ready, Docker support, multiple storage backends

A complete standalone OAuth 2.1 authorization server with native ATProto integration. Useful as:

• Reference for how a production ATProto OAuth server works
• Potential deployment as a separate sidecar service (vs. embedding in the relay)
• Storage backend patterns (SQLite, PostgreSQL)

3. Integration Architecture#

3.1 Deployment Model#

Two viable approaches:

Option A: Embedded (recommended for v1.0)

The relay process embeds atproto-oauth-axum handlers directly into its Axum router. OAuth state lives in the same database as relay state. Simplest deployment — one process, one database.

[Third-party app] → HTTPS → [Relay: Axum router]
                                ├── /oauth/* → atproto-oauth-axum handlers
                                ├── /xrpc/*  → XRPC proxy/handler
                                └── /v1/*    → Provisioning API

Option B: Sidecar

Deploy graze-social/aip as a separate service. The relay delegates OAuth to the sidecar and validates tokens on XRPC requests. More complex but isolates OAuth concerns.

Not recommended for v1.0 — adds operational complexity for a solo developer.

3.2 Storage#

OAuth state (authorization codes, tokens, sessions, client metadata cache) stored in the relay's SQLite database. Both atproto-oauth-axum and graze-social/aip support SQLite backends.

Tables needed:

• oauth_authorization_codes — short-lived, per-authorization-flow
• oauth_access_tokens — bound to DPoP key, client_id, account
• oauth_refresh_tokens — single-use, rotated on each use
• oauth_client_metadata_cache — cached client metadata from discovery URLs
• oauth_dpop_nonces — replay prevention

3.3 Account Binding#

The OAuth provider needs to map ATProto DIDs to relay accounts. During authorization:

1. User is redirected to relay's authorization endpoint
2. Relay resolves the user's DID → account_id
3. User authenticates (password, or session token if already logged in)
4. Relay issues tokens bound to the account

The relay's existing session/authentication system (provisioning API §2) handles step 3. The OAuth library handles everything else.

4. Lifecycle Phase Behavior#

4.1 Mobile-Only Phase#

The relay is a full PDS. OAuth works identically to any hosted PDS:

• Authorization, token, and XRPC endpoints all on the relay
• Relay stores repo, signs commits, serves reads
• Third-party apps see a normal PDS

No special behavior needed. This is the standard ATProto OAuth flow.

4.2 Desktop-Enrolled Phase#

The relay is still the OAuth provider and XRPC endpoint. The difference is internal:

• Write XRPC calls (createRecord, etc.) are proxied to the desktop for repo construction before the relay signs them
• Read XRPC calls can be served from relay cache
• OAuth tokens and sessions are managed entirely at the relay — the desktop is invisible to third-party apps

No OAuth changes needed for desktop enrollment. This is the key advantage of the relay-as-permanent-endpoint architecture.

4.3 Desktop Offline (During Desktop-Enrolled Phase)#

• Read XRPC calls: served from relay cache (no change to OAuth)
• Write XRPC calls: relay returns 503 to the XRPC caller
• OAuth tokens remain valid — the 503 is at the XRPC layer, not the auth layer

Third-party apps see a PDS that accepts reads but rejects writes. This is a known ATProto pattern (PDS maintenance mode).

5. Endpoints#

The relay must serve these endpoints at its base URL (the DID document's service endpoint):

These are in addition to the relay's existing endpoints:

• /v1/* — provisioning API
• /xrpc/* — ATProto XRPC

5.1 Server Metadata#

The /.well-known/oauth-authorization-server response must include:

{
  "issuer": "https://relay.example.com",
  "authorization_endpoint": "https://relay.example.com/oauth/authorize",
  "token_endpoint": "https://relay.example.com/oauth/token",
  "pushed_authorization_request_endpoint": "https://relay.example.com/oauth/par",
  "jwks_uri": "https://relay.example.com/oauth/jwks",
  "scopes_supported": ["atproto", "transition:generic"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_methods_supported": ["none", "private_key_jwt"],
  "code_challenge_methods_supported": ["S256"],
  "dpop_signing_alg_values_supported": ["ES256"]
}

6. Authorization UI#

The relay needs a minimal web UI for the OAuth authorization screen. When a third-party app redirects a user to /oauth/authorize, the relay must:

1. Show the app's name and permissions requested
2. Allow the user to approve or deny
3. Redirect back to the app with an authorization code

For v1.0, this can be a minimal server-rendered page. No SPA needed. The provisioning API's session system handles user authentication.

For BYO relay operators, the authorization UI should be customizable (branding, colors) via relay config.

7. Security Considerations#

7.1 Token Storage#

Access tokens and refresh tokens are stored server-side. The relay validates DPoP proofs on every request, preventing token theft from being useful without the DPoP private key.

7.2 Client Metadata Caching#

ATProto uses dynamic client registration — clients provide a metadata URL, not pre-registered credentials. The relay must:

• Fetch and cache client metadata on first authorization
• Re-validate periodically (TTL: 24 hours recommended)
• Reject clients with unreachable or invalid metadata

7.3 Rate Limiting#

OAuth endpoints should be rate-limited separately from XRPC and provisioning API endpoints. Recommended limits:

• Authorization: 10/min per IP
• Token: 30/min per client_id
• PAR: 30/min per client_id

7.4 BYO Relay Implications#

Self-hosted relay operators run their own OAuth provider. The BYO relay binary (Nix/Docker) must include the OAuth endpoints. The authorization UI defaults should be sensible without configuration.

8. Implementation Milestones#

v0.1 — Basic OAuth (blocks mobile-only phase)#

• Integrate atproto-oauth-axum into relay's Axum router
• SQLite-backed token storage
• Minimal authorization UI (server-rendered)
• Server metadata endpoint
• Test with Bluesky app as client

v1.0 — Production OAuth#

• PostgreSQL storage backend option
• Client metadata caching with TTL
• Rate limiting on OAuth endpoints
• Customizable authorization UI for BYO relay operators
• Token revocation endpoint
• Audit logging of authorization grants

Later#

• Scoped tokens (read-only grants for specific collections)
• Token introspection endpoint
• Admin dashboard for managing active OAuth sessions

9. Integration Checklist#

Before the relay can accept third-party app logins:

• /.well-known/oauth-authorization-server returns valid metadata
• /oauth/authorize renders authorization UI and handles consent
• /oauth/token issues DPoP-bound access + refresh tokens
• /oauth/par accepts pushed authorization requests
• /oauth/jwks returns current signing keys
• PKCE (S256) enforced on all flows
• DPoP proof validated on every token request
• Refresh token rotation (single-use) working
• Bluesky app can complete full OAuth flow
• Bluesky app can create a post via XRPC after OAuth
• Token bound to correct account/DID

10. Design Decisions#