Authentication

By default YT Zero uses no authentication — it assumes a trusted local network, and profiles are just named views. If you expose the app beyond your LAN, or want each member of the household to sign in, the primary profile can switch the login method under Settings → Authentication.

The Authentication tab (and the other admin-only settings) is visible to admins: the primary profile (the first profile created), or — with OIDC — any signed-in identity whose groups claim contains the configured admin group. See Profiles for what "primary" means and OIDC → Group-based admin below.

Methods at a glance

Method	Login	Profile switching	Best for
None	none	free	Trusted local network (default)
Shared login + profiles	one household login	free, after sign-in	A shared device, Netflix/Plex style
Login per profile	per profile	requires re-login	Separate accounts per person
OIDC	external provider	depends on mode	SSO with Pocket ID, Authentik, Keycloak, …
Proxy header	reverse proxy	requires re-login	Authelia / forward-auth setups

When any method other than None is active, the per-profile 6-digit PINs are not used — the login replaces them. The Child Lock settings PIN is separate and keeps working.

How to configure

The Authentication tab is a three-step wizard:

1. Choose a method — pick one of the cards. The currently active method is marked.
2. Configure — fill in the credentials / provider details for the selected method. Use Save to store them without switching yet.
3. Activate — apply the method. The app reloads and the new login takes effect immediately.

The wizard refuses to activate a method until its prerequisites are met (for example, a shared password or passkey must exist before activating Shared), so you cannot accidentally lock yourself out in one click. If you still do, see Recovery.

Exactly one method is active at a time, and there is no fallback between methods. Whatever you activate is the only way in — if it stops working (OIDC provider unreachable, proxy header no longer arriving, forgotten shared/per-profile credentials, a lost passkey), the app does not silently fall back to None or to any previously configured method. You are locked out until you recover. The only way back in is the environment-variable escape hatch below: set it, restart, fix the configuration in Settings → Authentication, then remove it and restart. Plan for this before exposing the app publicly.

---

None

No login. Anyone who can reach the app picks a profile, exactly as before. This is the default.

---

Shared login + profiles

One household login guards the app; once signed in, you can switch freely between all profiles (like choosing a profile on a shared streaming account).

1. Select Shared login + profiles.
2. Set a password (and optionally a username).
3. Optionally click Add passkey to register a passkey for password-less sign-in.
4. Activate.

After activation everyone signs in with the shared credentials, then uses the profile menu to switch profiles without signing in again.

---

Login per profile

Each profile has its own credentials. Switching profile means signing out and signing back in as the other profile.

1. Select Login per profile.
2. In the profile table, give each profile a username and password.
   • At minimum, the primary profile must have a username and password before you can activate.
   • Passkeys can be added by each profile from their own session after activation.
3. Activate.

In the profile menu, choosing a different profile prompts you to sign out first.

---

OIDC

Sign in through an external OpenID Connect provider such as Pocket ID, Authentik, Keycloak, or Authelia (OIDC).

1. Select OIDC and fill in:
   • Issuer URL — the provider's full issuer. Pocket ID and Keycloak usually use the root or a realm URL (https://id.example.com), while Authentik uses a per-application path with a trailing slash: https://id.example.com/application/o/<slug>/. If discovery returns 404, the issuer is wrong — copy the "OpenID Configuration Issuer" from your provider and use Test connection to verify.
   • Client ID and Client secret
   • Scopes — defaults to openid profile email
   • Redirect URI — shown read-only; copy it into your provider's allowed redirect URIs. It is <your app URL>/api/auth/oidc/callback. Set APP_URL if the app is behind a reverse proxy so this URL is correct.
2. Click Test connection to verify the issuer's discovery document is reachable.
3. Choose a mapping mode (below).
4. Activate.

Mapping modes

• Identity → one profile (mapped) — each external identity maps to exactly one profile. Profile switching is disabled (you sign out to change profile). Choose the identity claim (default preferred_username) and, in the profile table, enter the claim value that maps to each profile. Optionally enable auto-create a profile on first login to create a profile automatically for unknown identities.
• Gateway → profile picker — OIDC only guards the front door. After signing in, everyone sees the profile picker and can switch freely (similar to Shared).

Set an optional Logout URL to send users to your provider's logout endpoint when they sign out.

Group-based admin

By default only the primary profile has admin powers (the Authentication tab, global settings, and profile/channel management). With OIDC you can additionally grant those powers to identities based on a group claim from your provider:

• Groups claim — the claim in the ID token / userinfo that lists the user's groups (default groups).
• Admin group — the group name that grants admin. Leave it empty to disable group-based admin entirely (primary-only). When set, any signed-in identity whose groups claim contains this value gets primary-equivalent powers.

This works in both mapping modes. It is convenient for delegating administration without sharing the primary profile, but it also means your IdP's group membership now controls who can change the login configuration — treat the admin group as sensitive. The primary profile always keeps admin powers regardless of groups, so local recovery still works.

Troubleshooting

• unsupported operation in the logs after a successful token exchange — the provider signed the ID token with HS256 (HMAC), which isn't accepted. In Authentik this happens when the provider has no Signing Key selected; set it to an RSA/EC certificate (e.g. "authentik Self-signed Certificate") so the ID token uses RS256.
• 404 on /.well-known/openid-configuration — wrong Issuer URL; for Authentik use https://<host>/application/o/<slug>/ (trailing slash).
• "Invalid redirect URI" — add the wizard's Redirect URI verbatim to the provider, and set APP_URL to your public https:// URL so the callback isn't generated as http://.
• no profile mapped to this identity (mapped mode) — the identity claim value doesn't match any profile's mapped value; fix the claim or the mapping, or enable auto-create.

---

Proxy header

A trusted reverse proxy (e.g. Authelia with forward-auth) authenticates the user and passes their username in a request header. YT Zero matches that value to a profile.

1. Select Proxy header.
2. Set the header name your proxy sends (e.g. Remote-User, X-authentik-username). The name is configurable — nothing is hard-coded.
3. The page shows the currently received value of that header so you can confirm your proxy is sending it.
4. In the profile table, enter the header value that maps to each profile.
5. Optionally set a logout / redirect URL (e.g. your Authelia logout endpoint).
6. Activate.

Profile switching is disabled internally — the profile menu offers a sign-out that redirects to the configured logout URL.

Important: only enable this behind a proxy that always sets the header and strips any client-supplied copy. Without a trusted proxy, anyone could send the header themselves.

---

Passkeys

Passkeys (WebAuthn) are supported for the Shared and Login per profile methods, alongside or instead of passwords.

• The WebAuthn Relying Party ID and origin are derived from the request host. Behind a reverse proxy, set APP_URL (and WEBAUTHN_RP_ID if needed) so registration and login validate against the correct domain.
• Passkeys require a secure context (HTTPS, or localhost).

---

Recovery (anti-lockout)

Because there is no fallback between methods (see the note above), a broken or forgotten login means you are locked out — the app will not revert to None on its own. The single recovery path is the YTZERO_AUTH_DISABLE environment variable, which requires access to the deployment (Docker Compose file, systemd unit, shell, etc.).

Step by step:

1. Set the variable in the environment and restart the container/process:

   YTZERO_AUTH_DISABLE=1
   

   This forces the None method for as long as the variable is set, regardless of the saved setting. Nothing in the database is changed — the saved method is only overridden at runtime.

2. Sign in as the primary profile (or any profile — None has no login) and open Settings → Authentication.

3. Correct the configuration — fix the OIDC issuer, re-enter credentials, adjust the proxy header, re-add a passkey, or switch to a different method. Save/Activate as needed.

4. Remove YTZERO_AUTH_DISABLE (or set it to anything other than 1) and restart again so the saved method takes effect.

Keep the ability to edit environment variables and restart the deployment available to whoever administers YT Zero — it is the only way back in. If you run behind a reverse proxy that itself enforces auth, make sure that layer can't also permanently block the recovery login.

See YTZERO_AUTH_DISABLE in the configuration reference.