# 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