Document OAuth2 admin protection

docs/ADMIN.md

@@ -6,11 +6,11 @@ reverse proxy for that hostname to serve `dist/admin/index.html` as its root
 document.
 
 Protect `admin.familyfed.ie` at the web server, reverse proxy, or hosting layer
-with Pocket ID authentication. Require the Pocket ID user group
+with OAuth2/OIDC through Pocket ID. Require the Pocket ID user group
 `familyfed_admin`. The generated page has `noindex`, but a static page cannot
 enforce a secure admin login by itself.
 
-See `docs/POCKET-ID-AUTH.md` for the exact proxy/auth requirements.
+See `docs/OAUTH2-AUTH.md` for the exact proxy/auth requirements.
 
 ## Content changes
 

docs/OAUTH2-AUTH.md

@@ -0,0 +1,85 @@
+# OAuth2/OIDC auth for admin.familyfed.ie
+
+`admin.familyfed.ie` must be protected before traffic reaches the static Astro
+files. Use Pocket ID as the OIDC issuer, with an OAuth2/OIDC proxy in front of
+the generated admin page.
+
+Required policy:
+
+- Host: `admin.familyfed.ie`
+- Required Pocket ID group: `familyfed_admin`
+- Static upstream/root: `dist/admin/index.html`
+- OIDC issuer: `https://auth.bcgen.ie`
+
+## Pocket ID client
+
+Create a Pocket ID OIDC client:
+
+- Name: `FamilyFed Admin`
+- Redirect URL: `https://admin.familyfed.ie/oauth2/callback`
+- Scopes: `openid email profile groups`
+- Allowed user group: `familyfed_admin`
+
+The redirect URL must exactly match the OAuth2 proxy config. If the proxy is
+mounted on a different hostname or path, use that callback URL in both places.
+
+## OAuth2 proxy setup
+
+Run an OAuth2/OIDC proxy in front of the static admin output. The proxy should
+receive all traffic for `admin.familyfed.ie`, complete the Pocket ID login, check
+the `groups` claim, and only then forward to the static admin page.
+
+Example `oauth2-proxy` arguments:
+
+```text
+--http-address=0.0.0.0:4180
+--provider=oidc
+--oidc-issuer-url=https://auth.bcgen.ie
+--redirect-url=https://admin.familyfed.ie/oauth2/callback
+--scope=openid email profile groups
+--email-domain=*
+--allowed-group=familyfed_admin
+--oidc-groups-claim=groups
+--reverse-proxy=true
+--upstream=http://127.0.0.1:8080/
+--cookie-secure=true
+--cookie-samesite=lax
+--cookie-name=__Secure-familyfed_admin_oauth2
+--skip-provider-button=true
+--set-xauthrequest=true
+--pass-user-headers=true
+```
+
+Required secret environment values:
+
+```text
+OAUTH2_PROXY_CLIENT_ID=<pocket-id-client-id>
+OAUTH2_PROXY_CLIENT_SECRET=<pocket-id-client-secret>
+OAUTH2_PROXY_COOKIE_SECRET=<generated-cookie-secret>
+```
+
+Generate a cookie secret with:
+
+```bash
+openssl rand -base64 32
+```
+
+The upstream can be any local static file server or reverse-proxy target that
+serves `dist/admin/index.html` as the root document for the admin hostname. Do
+not expose that upstream directly to the public internet.
+
+## Deployment checks
+
+The site build verifies that `dist/admin/index.html` exists. That confirms the
+static admin page is available for the host, but it does not prove the external
+proxy has enabled Pocket ID.
+
+Verify live protection with:
+
+```bash
+curl -I https://admin.familyfed.ie/
+```
+
+Expected unauthenticated behavior is a redirect into the OAuth2/OIDC login flow
+or a `401`/`403` response from the auth proxy. Users outside
+`familyfed_admin` should never reach the static admin HTML.

docs/POCKET-ID-AUTH.md

@@ -1,75 +0,0 @@
-# Pocket ID auth for admin.familyfed.ie
-
-`admin.familyfed.ie` must be protected before traffic reaches the static Astro
-files. Pocket ID is an OIDC provider, so the auth check belongs in the reverse
-proxy or auth middleware.
-
-Required policy:
-
-- Host: `admin.familyfed.ie`
-- Required Pocket ID group: `familyfed_admin`
-- Static upstream/root: `dist/admin/index.html`
-
-## Recommended Tinyauth setup
-
-Pocket ID's proxy guide points to Tinyauth for reverse-proxy protection, and
-Tinyauth supports Pocket ID groups through the `oauth.groups` app label.
-
-Create a Pocket ID OIDC client:
-
-- Name: `FamilyFed Admin`
-- Callback URL: `https://auth.familyfed.ie/api/oauth/callback/pocketid`
-- Scopes: `openid email profile groups`
-
-Configure Tinyauth with the Pocket ID client:
-
-```yaml
-environment:
-  TINYAUTH_OAUTH_AUTOREDIRECT: pocketid
-  TINYAUTH_OAUTH_PROVIDERS_POCKETID_CLIENTID: "<pocket-id-client-id>"
-  TINYAUTH_OAUTH_PROVIDERS_POCKETID_CLIENTSECRET: "<pocket-id-client-secret>"
-  TINYAUTH_OAUTH_PROVIDERS_POCKETID_AUTHURL: "https://pocket-id.familyfed.ie/authorize"
-  TINYAUTH_OAUTH_PROVIDERS_POCKETID_TOKENURL: "https://pocket-id.familyfed.ie/api/oidc/token"
-  TINYAUTH_OAUTH_PROVIDERS_POCKETID_USERINFOURL: "https://pocket-id.familyfed.ie/api/oidc/userinfo"
-  TINYAUTH_OAUTH_PROVIDERS_POCKETID_REDIRECTURL: "https://auth.familyfed.ie/api/oauth/callback/pocketid"
-  TINYAUTH_OAUTH_PROVIDERS_POCKETID_SCOPES: "openid email profile groups"
-  TINYAUTH_OAUTH_PROVIDERS_POCKETID_NAME: "Pocket ID"
-```
-
-Add app access labels for the admin host:
-
-```yaml
-labels:
-  tinyauth.apps.familyfed-admin.config.domain: "admin.familyfed.ie"
-  tinyauth.apps.familyfed-admin.oauth.groups: "familyfed_admin"
-```
-
-Users outside `familyfed_admin` should receive the unauthorized page from the
-auth middleware and never reach the static admin HTML.
-
-## Caddy with caddy-security
-
-If the live proxy is Caddy with `caddy-security`, create a Pocket ID OIDC client
-with this callback URL:
-
-```text
-https://admin.familyfed.ie/caddy-security/oauth2/generic/authorization-code-callback
-```
-
-Configure the authorization policy to allow only users whose OIDC groups claim
-contains `familyfed_admin`, then serve or reverse-proxy the static admin output.
-Pocket ID's own guide documents the Caddy callback shape and OIDC provider
-settings; the group condition must be added in the Caddy authorization policy.
-
-## Deployment checks
-
-The site build now verifies that `dist/admin/index.html` exists. That confirms
-the static admin page is available for the host, but it does not prove the
-external proxy has enabled Pocket ID. Verify live protection with:
-
-```bash
-curl -I https://admin.familyfed.ie/
-```
-
-Expected unauthenticated behavior is a redirect to the Pocket ID/Tinyauth login
-or a `401`/`403` response from the auth middleware.