obs-game-stream-plugin/docs/authentik-setup.md

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.