Add OAuth 2.1 implementation for ATProto SDK

[zzstoatzz]

overview

this PR adds OAuth 2.1 support to the atproto Python SDK, implementing the ATProto OAuth specification. this enables secure, password-free authentication for ATProto applications.

---

architecture & design decisions

new package: atproto_oauth

created a standalone package following the SDK's existing modular structure:

packages/atproto_oauth/
├── client.py          # main OAuth client
├── dpop.py            # DPoP proof generation (ES256)
├── pkce.py            # PKCE challenge/verifier (S256)
├── metadata.py        # server discovery
├── security.py        # SSRF protection, URL validation
├── models.py          # dataclasses for state/sessions
├── stores/            # pluggable storage backends
│   ├── base.py        # abstract interfaces
│   └── memory.py      # in-memory implementation
└── README.md          # comprehensive usage guide

why separate package? keeps OAuth concerns isolated, allows applications to use only what they need, and follows the pattern of atproto_identity, atproto_crypto, etc.

OAuth 2.1 compliance details

authorization code flow with PKCE

spec reference: RFC 7636, ATProto OAuth §3.2

• only S256 challenge method (SHA256)
• verifier: 128 bytes (within spec's 43-128 range)
• challenge generated on authorization start, verified on token exchange

implementation: packages/atproto_oauth/pkce.py:25-43

def generate_pair(cls, verifier_length: int = 128) -> tuple[str, str]:
    verifier = cls.generate_verifier(verifier_length)
    challenge = base64.urlsafe_b64encode(
        hashlib.sha256(verifier.encode()).digest()
    ).decode().rstrip('=')
    return verifier, challenge

DPoP (demonstrating proof-of-possession)

spec reference: RFC 9449, ATProto OAuth §4.2

• ES256 algorithm (ECDSA with P-256 curve)
• unique jti per request (16-byte token)
• includes ath claim (access token hash) when presenting tokens
• automatic nonce rotation on server challenge

implementation: packages/atproto_oauth/dpop.py:94-143

nuance: DPoP nonces are tracked separately for auth server vs PDS, as they can issue different nonces. the client automatically handles nonce rotation when receiving use_dpop_nonce errors.

# packages/atproto_oauth/client.py:332-337
if DPoPManager.is_dpop_nonce_error(response):
    new_nonce = DPoPManager.extract_nonce_from_response(response)
    if new_nonce:
        session.dpop_pds_nonce = new_nonce
        # retry with new nonce...

pushed authorization requests (PAR)

spec reference: RFC 9126, ATProto OAuth §3.1.1

• all authorization parameters sent to PAR endpoint first
• returns request_uri used in actual authorization
• prevents parameter injection and ensures server validates everything upfront

implementation: packages/atproto_oauth/client.py:204-241

nuance: PAR endpoint validation is mandatory - we check require_pushed_authorization_requests: true in server metadata (security.py:171-173).

ATProto-specific implementation

DID-based identity resolution

spec reference: ATProto OAuth §2.2

the OAuth flow begins with a handle or DID, not a static service URL:

1. resolve handle → DID (via atproto_identity)
2. resolve DID document → extract PDS URL
3. discover auth server from PDS

implementation: packages/atproto_oauth/client.py:76-95

# resolve handle to DID
resolved_did = await self._id_resolver.handle.resolve(handle_or_did)

# get PDS from DID document
atproto_data = await self._id_resolver.did.resolve_atproto_data(did)
pds_url = atproto_data.pds

authorization server discovery

spec reference: ATProto OAuth §2.3

• fetch /.well-known/oauth-protected-resource from PDS
• extract authorization_servers array
• fetch /.well-known/oauth-authorization-server from auth server

implementation: packages/atproto_oauth/metadata.py:10-131

nuance: we validate the auth server URL matches the issuer field in metadata to prevent issuer confusion attacks (security.py:117-132).

client identification

spec reference: ATProto OAuth §2.4

• client_id must be HTTPS URL (or localhost for dev)
• points to client metadata JSON document
• server must support client_id_metadata_document_supported: true

implementation: client metadata hosting is left to applications (varies by deployment). the SDK validates server support (security.py:179-181).

security features

SSRF protection

spec reference: ATProto OAuth Security Considerations

all URLs validated before fetching:

• blocks private IP ranges (10.x, 172.16-31.x, 192.168.x)
• blocks cloud metadata endpoints (169.254.169.254, metadata.google.internal)
• enforces HTTPS except localhost

implementation: packages/atproto_oauth/security.py:22-62

state parameter for CSRF protection

• cryptographically random state tokens (22-byte urlsafe)
• stored with TTL (10 minutes)
• single-use (deleted after consumption)

implementation: packages/atproto_oauth/client.py:159-167

storage abstraction

pluggable stores

two abstract base classes for different storage needs:

StateStore - temporary OAuth state during authorization flow:

• short-lived (10 minute TTL)
• high write throughput during auth flows
• requires atomic operations

SessionStore - long-lived OAuth sessions:

• multi-week lifespan
• requires encryption for token storage
• may need locking for token refresh

implementation: packages/atproto_oauth/stores/base.py

built-in memory stores provided for development. production use requires implementing persistent stores.

---

production case study: plyr.fm

plyr.fm uses this OAuth implementation in production with custom storage backends.

postgres state store

implements StateStore with postgres for multi-instance deployments:

key decisions:

• serializes DPoP private keys to PEM for database storage
• lazy cleanup pattern: expired states cleaned on save/get operations
• follows same TTL as memory store (10 minutes)

implementation: plyr.fm/backend/src/backend/_internal/oauth_stores/postgres.py

encrypted session storage

instead of using SessionStore directly, plyr.fm stores OAuth sessions in postgres with encryption:

approach:

• Fernet symmetric encryption for OAuth tokens at rest
• serializes entire OAuthSession to JSON, then encrypts
• stores in UserSession table with 2-week expiration
• decryption failure = invalid session (handles key rotation gracefully)

why not use SessionStore? needed tighter integration with app's session model (user profiles, artist status, etc.) and wanted control over encryption strategy.

implementation: plyr.fm/backend/src/backend/_internal/auth.py:63-133

# encrypt OAuth session before storage
encrypted_data = _encrypt_data(json.dumps(oauth_session))

user_session = UserSession(
    session_id=session_id,
    did=did,
    handle=handle,
    oauth_session_data=encrypted_data,
    expires_at=datetime.now(UTC) + timedelta(days=14),
)

token refresh pattern

plyr.fm doesn't currently implement automatic token refresh, relying on the 2-week session expiration. when needed, refresh would follow this pattern:

# deserialize stored session
oauth_session = OAuthSession(**stored_data)

# refresh tokens
refreshed_session = await oauth_client.refresh_session(oauth_session)

# re-encrypt and store
await update_session_tokens(session_id, refreshed_session)

---

testing

unit tests: 15 tests covering PKCE and DPoP functionality

uv run pytest tests/test_oauth_*.py -v

flask demo: working example application

uv run python examples/oauth_flask_demo/app.py

---

what's next (not in this PR)

this PR provides the core OAuth client. future enhancements could include:

• integration with atproto_client.Client - add login_oauth() methods
• additional store implementations - SQLite, Redis, etc.
• automatic token refresh - background refresh before expiration
• more comprehensive integration tests - currently only unit tests

feedback very welcome on the current implementation before exploring these additions.