Sanitized mirror from private repository - 2026-03-27 11:53:55 UTC
This commit is contained in:
Gitea Mirror Bot
147
docs/infrastructure/USER_ACCESS_GUIDE.md
Normal file
147
docs/infrastructure/USER_ACCESS_GUIDE.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user