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

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

You have two options:

### Option A: Create accounts manually (recommended for small groups)

1. **Directory -> Users -> Create**
   - Set username, name, email
   - Set a temporary password
   - Enable "User must change password on next login"
2. **Directory -> Groups -> stream-viewers -> Users tab -> Add** the new user.
3. Send your friend the URL (`https://stream.hetherman.cloud`) and their
   temporary credentials. They set their own password on first login.

### Option B: Self-service enrollment via invite link

This requires a working enrollment flow with an Invitation stage. The key
requirement is that the **User Write stage** in the enrollment flow must have
`stream-viewers` set in the **Groups** field - this is what auto-adds new
users to the group. The invitation form itself has no group field.

1. **Flows & Stages -> Stages** - find or create a User Write stage and set
   **Groups** to `stream-viewers`.
2. **Flows & Stages -> Flows** - create an enrollment flow with these stages
   in order: Invitation stage -> prompt (email/password) -> User Write -> Login.
3. **Flows & Stages -> Invitations -> Create**:
   - **Flow**: your enrollment flow
   - **Single use**: on (one invite per person)
   - Set an expiry date
4. Copy the invite link (shown after saving) and send it to your friend. They
   click it, fill in username/password, and are redirected to the stream.

> **Important:** if friends completed enrollment but were not added to
> `stream-viewers` (because the User Write stage was not configured), add them
> manually: **Directory -> Groups -> stream-viewers -> Users tab -> Add**.

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