diff --git a/.env.example b/.env.example index 012ee38..9470351 100644 --- a/.env.example +++ b/.env.example @@ -26,10 +26,20 @@ FAMILIAR_HTTP_TOKEN= # FAMILIAR_ALLOW_INSECURE_BIND=false # --- OAuth 2.1 resource server (only when FAMILIAR_AUTH_MODE=oauth) --------- # +# familiar only validates JWTs; the login/DCR side lives in an external IdP. # FAMILIAR_OAUTH_ISSUER=https://idp.example.com/application/o/familiar/ # FAMILIAR_OAUTH_RESOURCE=https://familiar.example.com # this server's public URL # FAMILIAR_OAUTH_AUDIENCE=https://familiar.example.com # defaults to RESOURCE # FAMILIAR_OAUTH_JWKS_URI= # optional; else discovered from issuer +# +# Using Gitea as the issuer (RS256 JWTs + JWKS + OIDC discovery — config only, +# see doc/deployment.md). Register an OAuth2 app in Gitea first; Gitea puts the +# app's CLIENT ID in the token `aud`, so set AUDIENCE to that, not the resource. +# NOTE: Gitea has no Dynamic Client Registration — works for clients with a +# pre-registered client ID/secret, but NOT the claude.ai web connector (needs DCR). +# FAMILIAR_OAUTH_ISSUER=https://gitea.example.com # no trailing /login/oauth +# FAMILIAR_OAUTH_RESOURCE=https://familiar.example.com +# FAMILIAR_OAUTH_AUDIENCE= # --- Data / writes --------------------------------------------------------- # # Host path holding the encrypted token store (token.enc + key), audit log, and diff --git a/doc/clients/claude-web.md b/doc/clients/claude-web.md index a91f1e6..1c7efb7 100644 --- a/doc/clients/claude-web.md +++ b/doc/clients/claude-web.md @@ -4,6 +4,8 @@ The claude.ai custom-connector flow speaks **OAuth 2.1 with Dynamic Client Registration (DCR)** and does **not** accept a static bearer token. familiar itself is only a **resource server** — it validates JWTs and advertises where to authenticate, but it is **not** an authorization server and does no DCR. So Claude web needs an external IdP that supports DCR (e.g. **Authentik** or **Keycloak**) sitting in front. +> **Gitea won't work here.** Gitea is a fine OAuth issuer for familiar in general (see [deployment.md → Using Gitea as the OAuth issuer](../deployment.md)), but it has **no** Dynamic Client Registration, which this connector requires. Use it only with clients that take a pre-registered client ID/secret, or put a DCR-capable IdP in front. + > **Simpler alternative:** if you don't want to run an IdP, use the **Claude Desktop** app with a bearer token instead — see [Connect Claude Desktop](claude-desktop.md). Bearer is easier for every client except the claude.ai web connector. ## 1. Set up the IdP (external) diff --git a/doc/deployment.md b/doc/deployment.md index 92369b9..dafed53 100644 --- a/doc/deployment.md +++ b/doc/deployment.md @@ -20,7 +20,26 @@ Once it's running, see [doc/clients/](clients/) for exact per-client setup. `FAMILIAR_AUTH_MODE` picks how the HTTP transport authenticates: - **`bearer`** (default) — one static token in `FAMILIAR_HTTP_TOKEN`. Simple, and every client below except Claude web supports it. Recommended. -- **`oauth`** — familiar runs as an OAuth 2.1 **resource server**: it validates incoming JWT access tokens against an external issuer's JWKS and serves `/.well-known/oauth-protected-resource/` so OAuth-only clients can discover the authorization server. familiar is **not** an authorization server and does **no** Dynamic Client Registration — you must run an external IdP that does (Authentik, Keycloak, …). Only needed for the native **Claude web** connector. See [doc/clients/claude-web.md](clients/claude-web.md). +- **`oauth`** — familiar runs as an OAuth 2.1 **resource server**: it validates incoming JWT access tokens against an external issuer's JWKS and serves `/.well-known/oauth-protected-resource/` so OAuth-only clients can discover the authorization server. familiar is **not** an authorization server and does **no** Dynamic Client Registration (DCR) — the authorization side lives in an external IdP (Authentik, Keycloak, Gitea, …). Only needed for OAuth-only clients such as the native **Claude web** connector. See [doc/clients/claude-web.md](clients/claude-web.md). + +### Using Gitea as the OAuth issuer + +Gitea can act as the IdP for `oauth` mode — no code change, config only. Gitea is already an OIDC provider: it signs access tokens as **RS256 JWTs** (default), publishes its keys at `https://gitea.example.com/login/oauth/keys`, and serves OIDC discovery at `https://gitea.example.com/.well-known/openid-configuration`, so familiar's `JWTVerifier` can validate its tokens. + +1. In Gitea, **Settings → Applications → Create OAuth2 application** (or admin-wide under **Site Administration → Applications**). Set the redirect URI(s) your MCP client needs. Note the generated **client ID** and **secret**. +2. Point familiar at Gitea: + + ```bash + FAMILIAR_AUTH_MODE=oauth + FAMILIAR_OAUTH_ISSUER=https://gitea.example.com # no trailing /login/oauth + FAMILIAR_OAUTH_RESOURCE=https://familiar.example.com # this server's public URL + FAMILIAR_OAUTH_AUDIENCE= # Gitea sets aud to the client ID, not the resource URL + # FAMILIAR_OAUTH_JWKS_URI is discovered from the issuer's OIDC metadata; leave unset. + ``` + + `FAMILIAR_OAUTH_AUDIENCE` matters: Gitea puts the OAuth **application's client ID** in the token's `aud`, which differs from familiar's default (the resource URL). If you get *invalid token / audience mismatch*, decode a real access token (`jwt.io`) and set `FAMILIAR_OAUTH_AUDIENCE` to whatever its `aud` actually is. + +> **Caveat — no DCR.** Gitea does **not** support Dynamic Client Registration. Clients that let you paste a pre-registered client ID/secret (Claude Desktop/Code, VS Code, your own scripts) work fine with Gitea. The **claude.ai web** custom connector *requires* DCR, so Gitea alone can't back it — you'd need a DCR-capable IdP (Authentik/Keycloak) or a DCR proxy in front of Gitea. See [doc/clients/claude-web.md](clients/claude-web.md). ## Environment variables