Authentik Groups Configuration¶

Complete reference for all Authentik groups in the homelab infrastructure.

This document defines the correct group hierarchy, inheritance, and per-app access configuration.

Quick Reference: Fix Common Mistakes¶

CRITICAL: How Parent Groups Work¶

In Authentik, "Parent group" means the current group inherits FROM the parent.

tier-family
  └── Parent: tier-friends
      └── Means: tier-family GETS everything tier-friends has, PLUS its own additions

Common Mistake: Setting tier-guests.parent = tier-owner gives guests ALL owner permissions!

The Golden Rules¶

NEVER set tier-owner as a parent - Owner is the top tier, nothing should inherit from it
tier-guests has NO parent - It's intentionally isolated with no permissions
Only tier-family has a parent (tier-friends) - This is the only inheritance relationship between tiers
Service groups have NO parents - They are standalone, assigned via tier memberships

Complete Group Hierarchy¶

AUTHENTIK GROUPS
================

TIER GROUPS (Assign users to ONE of these)
──────────────────────────────────────────
┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│  tier-owner ──────────────────────────────────────────────────────────────┐ │
│    │ (Jake)                                                               │ │
│    │ Parent: NONE                                                         │ │
│    │ Direct memberships: ALL service groups                               │ │
│    │                                                                      │ │
│    └───────────────────────────────────────────────────────────────────┐  │ │
│                                                                        │  │ │
│  tier-family ────────────────────────────────────────────────────────┐ │  │ │
│    │ (Mom, trusted family)                                           │ │  │ │
│    │ Parent: tier-friends                                            │ │  │ │
│    │ Gets: everything tier-friends has + additional admin groups     │ │  │ │
│    │                                                                 │ │  │ │
│    └───────────────────────────────────────────────────────────────┐ │ │  │ │
│                                                                    │ │ │  │ │
│  tier-friends ───────────────────────────────────────────────────┐ │ │ │  │ │
│    │ (Bob, friends)                                              │ │ │ │  │ │
│    │ Parent: NONE                                                │ │ │ │  │ │
│    │ Direct memberships: base media/social service groups        │ │ │ │  │ │
│    │                                                             │ │ │ │  │ │
│    └───────────────────────────────────────────────────────────┐ │ │ │ │  │ │
│                                                                │ │ │ │ │  │ │
│  tier-guests ────────────────────────────────────────────────┐ │ │ │ │ │  │ │
│      (Temporary/untrusted accounts)                          │ │ │ │ │ │  │ │
│      Parent: NONE                                            │ │ │ │ │ │  │ │
│      Direct memberships: NONE                                │ │ │ │ │ │  │ │
│                                                              │ │ │ │ │ │  │ │
│      CAN ACCESS: Nothing (login to Authentik only)          ─┘ │ │ │ │ │  │ │
│                                                                 │ │ │ │ │  │ │
│      + tier-friends access ─────────────────────────────────────┘ │ │ │ │  │ │
│                                                                   │ │ │ │  │ │
│      + tier-family additions ─────────────────────────────────────┘ │ │ │  │ │
│                                                                     │ │ │  │ │
│      + tier-owner additions (everything) ───────────────────────────┘ │ │  │ │
│                                                                       │ │  │ │
└───────────────────────────────────────────────────────────────────────┴─┴──┴─┘

SERVICE GROUPS (Apps check these - users get them via tier inheritance)
───────────────────────────────────────────────────────────────────────

DASHBOARD
├── home-portal-admins    # Can manage dashboard widgets/layouts
├── home-portal-users     # Can view dashboard

MEDIA STREAMING
├── jellyfin-access       # Can stream media
├── immich-access         # Can view/upload photos

MEDIA REQUESTS
├── jellyseerr-access     # Can request media
├── jellyseerr-admin      # Can approve/manage requests
├── overseerr-access      # Can request media (legacy)

MEDIA MANAGEMENT (arr-stack)
├── arr-users             # Can access request apps (Jellyseerr/Overseerr)
├── arr-admins            # Can access management apps (Sonarr/Radarr/etc)

CUSTOM APPS
├── money-tracker-access  # Personal finance app
├── trip-planner-access   # Travel planning app
├── tcg-access            # Trading card game
├── subtitleai-access     # Subtitle generator
├── rms-access            # Recipe management
├── pelican-access        # Game server panel
├── pelican-admin         # Game server admin
├── romm-access           # ROM management
├── otterwiki-access      # Documentation wiki

INFRASTRUCTURE (owner-only)
├── proxmox-access        # Proxmox hypervisor
├── kubernetes-access     # K8s dashboard
├── authentik-admins      # Authentik admin panel
├── supabase-access       # Supabase Studio

Tier Group Definitions¶

tier-owner¶

Purpose: Full access to everything (you)

Setting	Value
Parent group	NONE (CRITICAL!)
Is superuser	No (use group memberships instead)

Direct group memberships (add tier-owner to these groups):

ALL service groups:
- home-portal-admins
- home-portal-users
- jellyfin-access
- immich-access
- jellyseerr-access
- jellyseerr-admin
- overseerr-access
- arr-users
- arr-admins
- money-tracker-access
- trip-planner-access
- tcg-access
- subtitleai-access
- rms-access
- pelican-access
- pelican-admin
- romm-access
- otterwiki-access
- proxmox-access
- kubernetes-access
- authentik-admins
- supabase-access

Users in this group: jake (your main account)

tier-family¶

Purpose: Extended access for trusted family members

Setting	Value
Parent group	`tier-friends`
Is superuser	No

Inherits from tier-friends: - home-portal-users - jellyfin-access - immich-access (read-only) - jellyseerr-access - overseerr-access - arr-users

Additional direct memberships (add tier-family to these):

- home-portal-admins      # Can customize dashboard
- jellyseerr-admin        # Can approve media requests
- immich-access           # Full photo access (upload)

Users in this group: (add trusted family members)

tier-friends¶

Purpose: Base external access for friends

Setting	Value
Parent group	NONE
Is superuser	No

Direct group memberships (add tier-friends to these):

- home-portal-users       # View dashboard
- jellyfin-access         # Stream media
- jellyseerr-access       # Request media
- overseerr-access        # Request media (legacy)
- arr-users               # Access request interfaces

Users in this group: (add friends)

tier-guests¶

Purpose: Temporary or untrusted accounts (no app access)

Setting	Value
Parent group	NONE (CRITICAL!)
Is superuser	No (CRITICAL!)

Direct group memberships: NONE

Users in this group: (temporary accounts, test accounts)

What guests CAN do: Log into Authentik (that's it - they see no apps)

Service Group Definitions¶

Dashboard Groups¶

Group	Purpose	Who gets it
`home-portal-admins`	Manage dashboard widgets, layouts, services	tier-owner, tier-family
`home-portal-users`	View dashboard, rearrange personal layout	tier-owner, tier-family, tier-friends

Media Streaming Groups¶

Group	Purpose	Who gets it
`jellyfin-access`	Stream media via Jellyfin	tier-owner, tier-family, tier-friends
`immich-access`	View/upload photos in Immich	tier-owner, tier-family

Jellyfin Plugin Config: - Roles: tier-owner, tier-family, tier-friends (OR jellyfin-access) - Admin Roles: tier-owner - Role Claim: groups

Immich OAuth Config: - Claim: groups - Admin claim value: tier-owner or immich-admin

Media Request Groups¶

Group	Purpose	Who gets it
`jellyseerr-access`	Request movies/TV shows	tier-owner, tier-family, tier-friends
`jellyseerr-admin`	Approve/manage requests	tier-owner, tier-family
`overseerr-access`	Legacy request interface	tier-owner, tier-family, tier-friends
`arr-users`	Forward auth for request apps	tier-owner, tier-family, tier-friends

Media Management Groups (arr-stack)¶

Group	Purpose	Who gets it
`arr-admins`	Access Sonarr, Radarr, Lidarr, Prowlarr, Bazarr, SABnzbd, Deluge	tier-owner ONLY

Forward auth bindings: - Jellyseerr/Overseerr: arr-users - Sonarr/Radarr/Lidarr/Prowlarr/Bazarr/SABnzbd/Deluge: arr-admins

Custom App Groups¶

Group	App	Who gets it	Auth Type
`money-tracker-access`	Money Tracker	tier-owner	NextAuth OIDC
`trip-planner-access`	Trip Planner	tier-owner	NextAuth OIDC
`tcg-access`	Trading Card Game	tier-owner, (tier-friends?)	NextAuth OIDC
`subtitleai-access`	SubtitleAI	tier-owner	NextAuth OIDC
`rms-access`	Recipe Management	tier-owner, tier-family	NextAuth OIDC
`pelican-access`	Game Server Panel	tier-owner, tier-friends	Forward auth or OIDC
`pelican-admin`	Game Server Admin	tier-owner	Panel role
`romm-access`	ROM Management	tier-owner	Forward auth
`otterwiki-access`	Documentation	tier-owner	Forward auth

Infrastructure Groups¶

Group	Purpose	Who gets it
`proxmox-access`	Proxmox hypervisor access	tier-owner ONLY
`kubernetes-access`	Kubernetes dashboard	tier-owner ONLY
`authentik-admins`	Authentik admin panel	tier-owner ONLY
`supabase-access`	Supabase Studio	tier-owner ONLY

Per-App Configuration Reference¶

Jellyfin (Native OIDC)¶

Provider: jellyfin (OAuth2/OpenID Provider)

Setting	Value
Redirect URI	`https://jellyfin.bogocat.com/sso/OID/redirect/authentik`
Scopes	`openid profile email groups`

Application bindings: tier-owner, tier-family, tier-friends

Plugin config (in Jellyfin): | Setting | Value | |---------|-------| | Roles | tier-owner, tier-family, tier-friends | | Admin Roles | tier-owner | | Role Claim | groups |

Immich (Native OIDC)¶

Provider: immich-oauth (OAuth2/OpenID Provider)

Setting	Value
Redirect URIs	`app.immich:///oauth-callback`, `https://photos.bogocat.com/auth/login`
Scopes	`openid profile email`

Application bindings: tier-owner, tier-family

arr-stack Apps (Forward Auth)¶

Each app uses a proxy provider + application binding.

App	Provider	Hostname	Binding Group
Jellyseerr	`jellyseerr-proxy`	jellyseerr.bogocat.com	`arr-users`
Overseerr	`overseerr-proxy`	overseerr.bogocat.com	`arr-users`
Sonarr	`sonarr-proxy`	sonarr.bogocat.com	`arr-admins`
Radarr	`radarr-proxy`	radarr.bogocat.com	`arr-admins`
Lidarr	`lidarr-proxy`	lidarr.bogocat.com	`arr-admins`
Prowlarr	`prowlarr-proxy`	prowlarr.bogocat.com	`arr-admins`
Bazarr	`bazarr-proxy`	bazarr.bogocat.com	`arr-admins`
SABnzbd	`sabnzbd-proxy`	sabnzbd.bogocat.com	`arr-admins`
Deluge	`deluge-proxy`	deluge.bogocat.com	`arr-admins`

All providers must be assigned to: authentik Embedded Outpost

Home Portal (NextAuth OIDC)¶

Provider: home-portal (OAuth2/OpenID Provider)

Setting	Value
Redirect URIs	`http://localhost:3000/api/auth/callback/authentik`, `https://portal.bogocat.com/api/auth/callback/authentik`
Scopes	`openid profile email groups`

Application bindings: home-portal-users (minimum access)

In-app group checks: - home-portal-admins → Can manage widgets/services - home-portal-users → Can view and rearrange

Money Tracker (NextAuth OIDC)¶

Provider: money-tracker (OAuth2/OpenID Provider)

Setting	Value
Redirect URIs	`http://localhost:3000/api/auth/callback/authentik`, `https://money.bogocat.com/api/auth/callback/authentik`
Scopes	`openid profile email groups`

Application bindings: money-tracker-access

Trip Planner (NextAuth OIDC)¶

Provider: trip-planner (OAuth2/OpenID Provider)

Setting	Value
Redirect URIs	`http://localhost:3000/api/auth/callback/authentik`, `https://travel.bogocat.com/api/auth/callback/authentik`
Scopes	`openid profile email groups`

Application bindings: trip-planner-access

Access Matrix Summary¶

App/Service	tier-guests	tier-friends	tier-family	tier-owner
Dashboard
Home Portal (view)	-	Yes	Yes	Yes
Home Portal (admin)	-	-	Yes	Yes
Media Streaming
Jellyfin	-	Yes	Yes	Yes
Jellyfin (admin)	-	-	-	Yes
Immich	-	-	Yes	Yes
Media Requests
Jellyseerr (request)	-	Yes	Yes	Yes
Jellyseerr (approve)	-	-	Yes	Yes
Media Management
Sonarr, Radarr, etc.	-	-	-	Yes
Custom Apps
Money Tracker	-	-	-	Yes
Trip Planner	-	-	-	Yes
TCG	-	(opt)	(opt)	Yes
SubtitleAI	-	-	-	Yes
RMS	-	-	Yes	Yes
Gaming
Pelican (use)	-	Yes	Yes	Yes
Pelican (admin)	-	-	-	Yes
RoMM	-	-	-	Yes
Infrastructure
OtterWiki	-	-	-	Yes
Proxmox	-	-	-	Yes
Kubernetes	-	-	-	Yes
Supabase	-	-	-	Yes
Authentik Admin	-	-	-	Yes

Setup/Verification Checklist¶

Verify Tier Groups¶

For each tier group, check:

[ ] tier-owner
    [ ] Parent group: EMPTY (not set)
    [ ] Is superuser: NO
    [ ] Groups tab: Contains ALL service groups

[ ] tier-family
    [ ] Parent group: tier-friends
    [ ] Is superuser: NO
    [ ] Groups tab: Contains home-portal-admins, jellyseerr-admin, immich-access

[ ] tier-friends
    [ ] Parent group: EMPTY (not set)
    [ ] Is superuser: NO
    [ ] Groups tab: Contains home-portal-users, jellyfin-access, jellyseerr-access, arr-users

[ ] tier-guests
    [ ] Parent group: EMPTY (not set)
    [ ] Is superuser: NO
    [ ] Groups tab: EMPTY (no memberships)

Verify Service Groups¶

For each service group:

[ ] All groups exist in Directory → Groups
[ ] No service group has a parent set
[ ] Is superuser: NO for all groups

Verify User Assignments¶

[ ] Your account (jake) is ONLY in tier-owner
[ ] Family members are ONLY in tier-family
[ ] Friends are ONLY in tier-friends
[ ] No user is directly in multiple tiers (tiers are mutually exclusive)
[ ] Guest/test accounts are ONLY in tier-guests

Verify Application Bindings¶

For each application:

[ ] Check Applications → [App] → Policy / Group / User Bindings
[ ] Verify correct group(s) are bound
[ ] NO individual user bindings (use groups only)

Troubleshooting¶

Guest has superuser access¶

Symptom: User in tier-guests can access everything

Cause: tier-guests has tier-owner (or another tier) as parent

Fix: 1. Directory → Groups → tier-guests → Edit 2. Clear the "Parent group" field 3. Save

User in tier-friends has admin access¶

Symptom: Friends can access Sonarr, Radarr, etc.

Cause: tier-friends has incorrect group memberships or parent

Fix: 1. Directory → Groups → tier-friends → Groups tab 2. Remove any admin groups (arr-admins, proxmox-access, etc.) 3. Verify parent is NOT set

Groups not appearing in JWT¶

Symptom: session.user.groups is empty or missing

Fix: 1. Verify "Groups Claim" scope mapping exists (Customization → Property Mappings) 2. Verify scope is added to the provider (Providers → [provider] → Advanced → Scopes) 3. Verify app requests groups scope in authorization

User can't access app they should have access to¶

Checklist: 1. Is user in the correct tier group? 2. Is the tier group a member of the required service group? 3. Is the application bound to the service group? 4. Is the application assigned to the outpost (for forward auth)?

Creating New Groups¶

When adding a new app:

Create service group: Directory → Groups → Create
Name: {app-name}-access
Parent: NONE
Is superuser: NO
Add to tier memberships:
For owner-only: Add only to tier-owner
For family+: Add to tier-owner AND tier-family
For friends+: Add to tier-owner, tier-family, AND tier-friends
Create application binding:
Applications → [App] → Policy / Group / User Bindings
Create Binding → Group → Select the new service group
Document in this file

Files Reference¶

File	Purpose
`/root/tower-fleet/docs/reference/authentik-groups-configuration.md`	This document
`/root/tower-fleet/docs/infrastructure/jellyfin-sso.md`	Jellyfin OIDC setup
`/root/tower-fleet/docs/infrastructure/arr-stack-sso.md`	Forward auth setup
`/root/tower-fleet/docs/design/home-portal-rbac-design.md`	Detailed RBAC design

Changelog¶

Date	Change
2025-12-11	Initial comprehensive documentation