initial commit

docs/authentik-setup.md

@@ -0,0 +1,87 @@
+# Authentik setup
+
+Creates a Forward Auth Proxy Provider that NPM will consult before allowing
+any request to `https://stream.hetherman.cloud`.
+
+Prerequisites: you already run Authentik at `https://auth.hetherman.cloud` and
+have admin access.
+
+## 1. Create a group
+
+1. Authentik admin -> **Directory -> Groups -> Create**
+2. Name: `stream-viewers`
+3. Save.
+4. Add each friend's user account to this group. **Do not** add yourself /
+   your admin account - your access comes from your existing admin group.
+
+## 2. Create a Proxy Provider
+
+1. **Applications -> Providers -> Create**
+2. Select **Proxy Provider** and click Next.
+3. Fill in:
+   - **Name**: `game-stream-forward-auth`
+   - **Authorization flow**: `default-provider-authorization-implicit-consent`
+     (skips the "Authorize application" prompt so friends get a one-click login)
+   - **Type**: **Forward auth (single application)**
+   - **External host**: `https://stream.hetherman.cloud`
+   - **Token validity**: default (24 hours) is fine
+4. Save.
+
+## 3. Create an Application
+
+1. **Applications -> Applications -> Create**
+2. Fill in:
+   - **Name**: `Game Stream`
+   - **Slug**: `game-stream`
+   - **Provider**: `game-stream-forward-auth` (the provider from step 2)
+   - **Launch URL**: `https://stream.hetherman.cloud`
+3. Save.
+
+## 4. Bind the group policy
+
+Restrict who can authenticate to this application:
+
+1. Open the `Game Stream` application you just created.
+2. Go to the **Policy / Group / User Bindings** tab -> **Create binding**
+3. **Group**: `stream-viewers`
+4. Leave the rest as default; Save.
+
+After this step, only members of `stream-viewers` (and Authentik superusers)
+can authenticate to the game stream.
+
+## 5. Ensure the outpost serves this application
+
+Authentik runs an "outpost" that exposes `/outpost.goauthentik.io/auth/nginx`
+for the nginx `auth_request` forward-auth pattern.
+
+1. **Applications -> Outposts**
+2. Edit the default `authentik Embedded Outpost` (or create one if there is
+   not one already).
+3. Under **Applications**, make sure `Game Stream` is checked.
+4. Save. The outpost reloads automatically.
+
+Verify the outpost endpoint is reachable:
+
+```
+curl -I https://auth.hetherman.cloud/outpost.goauthentik.io/ping
+```
+
+A 200 or 204 means the outpost is up.
+
+## 6. Verify end-to-end
+
+After finishing `docs/npm-setup.md`:
+
+1. Open `https://stream.hetherman.cloud` in a private/incognito browser.
+2. You should be redirected to Authentik to log in.
+3. Log in as a member of `stream-viewers`. You should be redirected back to
+   the stream page.
+4. Log out, clear cookies, try logging in as a non-member. You should be
+   denied with a "You do not have access" message.
+
+## Revoking access
+
+Remove the friend's user from the `stream-viewers` group. Their Authentik
+session remains valid until it expires, but the next `auth_request` forward
+auth check (evaluated on every HTTP request NPM sees) will fail the group
+policy and they will be locked out within seconds.