OAuth Authorization Server for Claude Connectors
Discovery, authorize, token, refresh, and client registration on id.didi.sh, so Claude can sign a partner into MemoPop with one magic link.
- Path
- plans/OAuth-Authorization-Server-for-Claude-Connectors.md
- Authors
- Michael Staton
- Augmented with
- Claude Code on Claude Opus 5.5 (1M context)
- Tags
- Plan · Id-Didi-Sh · OAuth · Claude-Connector · Elixir
OAuth Authorization Server for Claude Connectors
This is Phase 3 of the MemoPop connector work, run in this repo. Read first:
context-v/issues/Claude-Connectors-Need-didi-sh-to-Be-an-OAuth-Server.md: what Claude requires and what MemoPop needs from the tokens.context-v/notes/What-OAuth-and-OIDC-Actually-Are-and-What-didi-sh-Still-Needs.md: the roles and the gap.- The MemoPop spec’s §Auth (in
memopop-orchestrator), which is the other half: MemoPop verifies tokens against/.well-known/jwks.json, requires audiencehttps://memopop.didi.sh, and reads the firm from the entity claim. - Current Claude docs on connector authentication (Build an MCP server for Claude and its auth pages) and the MCP authorization spec (2025-06-18 and 2025-11-25). Confirm whether Claude registers through Dynamic Client Registration, a Client ID Metadata Document, or both, and implement what Claude actually uses. Record the sources in the changelog.
What to build
- Discovery:
/.well-known/oauth-authorization-serverand/.well-known/openid-configuration. Every URL comes from configuredissuer(https://id.didi.sh), never from the request: Fly’s proxy forwards plain http, and anhttp://URL here breaks Claude. - Client registration: DCR (
POST /oauth/register, RFC 7591) and/or Client ID Metadata Documents, per what Claude uses. Redirect URIs allowed:https://claude.ai/api/mcp/auth_callbackand loopback (http://localhost:<port>/…,http://127.0.0.1:<port>/…) for Claude Code. Reject any other redirect. GET /oauth/authorize: authorization code flow with PKCE (S256 only). No session → the existing magic-link sign-in, then back here. With a session → one consent screen in the existing design system saying which app is asking (from the client’s name) and which firm the person will reach; a person in several entities picks one.resource(RFC 8707) is required and must be a registered resource;https://memopop.didi.shis the first.POST /oauth/token:authorization_code(verifies PKCE, single-use, short-lived codes) andrefresh_token(rotating; a reused refresh token revokes the family). Access tokens: EdDSA JWTs signed with the existing key (IdDidiSh.Keys),aud= the resource,sub= didi_id,entity= the chosen entity’s id and slug,scope, one-hour expiry. Store only hashes of codes and refresh tokens.- Revocation: revoking the didi.sh session revokes its refresh tokens.
Tests (ExUnit, tag each with its ID: @tag spec: "OAUTH-01")
| ID | Given / When / Then |
|---|---|
OAUTH-01 |
Discovery documents list every endpoint, and every URL is https://, even on a plain-http request |
OAUTH-02 |
Registration accepts Claude’s callback and a loopback redirect, and rejects any other redirect URI |
OAUTH-03 |
Authorize without a session sends the person through magic-link sign-in and back |
OAUTH-04 |
Authorize rejects a missing or non-S256 PKCE challenge, an unknown client, an unregistered redirect, and an unknown resource |
OAUTH-05 |
A person in two entities chooses one; the token carries that entity |
OAUTH-06 |
Token exchange with the right verifier returns an access token whose aud is the resource and which verifies against /.well-known/jwks.json; a wrong verifier is refused |
OAUTH-07 |
An authorization code works once; a second use is refused |
OAUTH-08 |
A refresh token returns a new pair; reusing the old one is refused and revokes the family |
OAUTH-09 |
Revoking the session makes its refresh tokens fail |
OAUTH-10 |
An access token for one resource is not issued with another resource’s audience |
Write them first and watch them fail, then implement. Never edit a test to pass; if one can’t pass honestly, stop and report.
Rules and done
- Work on
feature/oauth-for-connectorsfrommain(this repo’s working branch, per its CLAUDE.md). Don’t push tomainormaster, and don’t deploy; the VP Eng merges and deploys with the operator’s approval. - Invariant 4 (headless-first) is extended, deliberately and minimally. An
authorization server has to host
/oauth/authorize; Claude can’t render our login. Keep it to the sign-in hop and one consent screen, reuse the existing/accessand magic-link pages, and say so in the changelog. - The
didi_sessioncookie,/api, and the JWKS contract don’t change. The access tokens are a new artifact signed with the same key. mix testgreen (record the count before and after),mix format --check-formatted,mix compile --warnings-as-errors.- A changelog entry per this repo’s
changelog/convention, honest about what wasn’t tested (anything needing a real Claude client). - Update the issue doc’s status and add a “Resolved by” note.
- Push the branch and report: the test counts, the endpoints, and the exact token claims, so the VP Eng can check MemoPop’s verifier against them.