homelab-optimized/docs/infrastructure/USER_ACCESS_GUIDE.md

User Access Guide

Overview

This guide covers user management for the homelab, including Homarr dashboard access and Authentik SSO.

Authentik SSO

Users

Username	Name	Email	Groups
akadmin	authentik Default Admin	admin@example.com	authentik Admins
aquabroom	Crista	partner@example.com	Viewers
openhands	openhands	your-email@example.com	-

Groups

Group	Purpose	Members
authentik Admins	Full admin access	akadmin
Viewers	Read-only access	aquabroom (Crista)

Sites Protected by Authentik Forward Auth

These sites share the same SSO cookie (vish.gg domain). Once logged in, users can access ALL of them:

Site	Service	Notes
dash.vish.gg	Homarr Dashboard	Main homelab dashboard
actual.vish.gg	Actual Budget	Budgeting app
docs.vish.gg	Documentation	Docs server
npm.vish.gg	Nginx Proxy Manager	⚠️ Admin access
paperless.vish.gg	Paperless-NGX	Document management

Sites with OAuth SSO

These apps have their own user management after Authentik login:

Site	Service	User Management
git.vish.gg	Gitea	Gitea user permissions
gf.vish.gg	Grafana	Grafana org/role permissions
sf.vish.gg	Seafile	Seafile user permissions
mm.crista.love	Mattermost	Mattermost team permissions

Homarr Dashboard

Access URL

• External: https://dash.vish.gg
• Internal: http://atlantis.vish.local:7575

User Management

Homarr has its own user system in addition to Authentik:

1. Go to https://dash.vish.gg
2. Login via Authentik
3. Click Manage → Users
4. Create/manage users and permissions

Permissions

Permission	Can Do
Admin	Edit boards, manage users, full access
User	View boards, use apps
View Only	View boards only

Creating a New User

Step 1: Create Authentik Account

1. Go to https://sso.vish.gg/if/admin/
2. Directory → Users → Create
3. Fill in username, email, name
4. Set password or send invite

Step 2: Add to Group

1. Directory → Groups → Viewers
2. Users tab → Add existing user
3. Select the user → Add

Step 3: Create Homarr Account (Optional)

1. Go to https://dash.vish.gg
2. Manage → Users → Create User
3. Set permissions (uncheck Admin for read-only)

Restricting Access

Option 1: Remove Forward Auth from Sensitive Sites

Edit NPM proxy host and remove the Authentik advanced config for sites you want to restrict.

Option 2: Add Authentik Policy Bindings

1. Go to Authentik Admin → Applications
2. Select the application
3. Policy / Group / User Bindings tab
4. Add a policy to restrict by group

Option 3: App-Level Permissions

Configure permissions within each app (Grafana roles, Gitea teams, etc.)

Access Policy

Philosophy: Trusted users (like partners) get full access to view everything, but only admins get superuser/admin privileges.

Current Setup

User	Authentik Superuser	Access Level
akadmin	✅ Yes	Full admin everywhere
aquabroom (Crista)	❌ No	View all sites, no admin powers

What This Means

Crista can:

• ✅ Access all *.vish.gg sites after SSO login
• ✅ View Homarr dashboard
• ✅ Use Actual Budget, Paperless, etc.
• ✅ View NPM settings
• ❌ Cannot access Authentik admin panel
• ❌ Cannot modify Authentik users/groups
• ❌ App-specific admin depends on each app's settings

App-Specific Permissions

Some apps have their own user management after Authentik login:

• Homarr: Set user as non-admin when creating account
• Grafana: Assign Viewer role (not Admin/Editor)
• Gitea: Add to teams with read permissions
• Paperless: Create user without admin flag

Quick Reference

Authentik Admin

• URL: https://sso.vish.gg/if/admin/
• Login: Your admin account

Homarr Admin

• URL: https://dash.vish.gg/manage
• Login: Via Authentik SSO

API Tokens

• Authentik: Directory → Tokens & App passwords
• Homarr: Manage → Settings → API