# 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.