familyfedie-website/docs/OAUTH2-AUTH.md

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-proxy sidecar 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 oauth2-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:

--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:

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:

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:

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.