# User Access Matrix

*Managing access to homelab services*

---

## Overview

This document outlines user access levels and permissions across homelab services. Access is managed through Authentik SSO with role-based access control.

---

## User Roles

### Role Definitions

| Role | Description | Access Level |
|------|-------------|--------------|
| **Admin** | Full system access | All services, all actions |
| **Family** | Regular user | Most services, limited config |
| **Guest** | Limited access | Read-only on shared services |
| **Service** | Machine account | API-only, no UI |

---

## Service Access Matrix

### Authentication Services

| Service | Admin | Family | Guest | Service |
|---------|-------|--------|-------|---------|
| Authentik | ✅ Full | ❌ None | ❌ None | ❌ None |
| Vaultwarden | ✅ Full | ✅ Personal | ❌ None | ❌ None |

### Media Services

| Service | Admin | Family | Guest | Service |
|---------|-------|--------|-------|---------|
| Plex | ✅ Full | ✅ Stream | ✅ Stream (limited) | ❌ None |
| Jellyfin | ✅ Full | ✅ Stream | ✅ Stream | ❌ None |
| Sonarr | ✅ Full | ✅ Use | ❌ None | ✅ API |
| Radarr | ✅ Full | ✅ Use | ❌ None | ✅ API |
| Jellyseerr | ✅ Full | ✅ Request | ❌ None | ✅ API |

### Infrastructure

| Service | Admin | Family | Guest | Service |
|---------|-------|--------|-------|---------|
| Portainer | ✅ Full | ❌ None | ❌ None | ❌ None |
| Prometheus | ✅ Full | ⚠️ Read | ❌ None | ❌ None |
| Grafana | ✅ Full | ⚠️ View | ❌ None | ✅ API |
| Nginx Proxy Manager | ✅ Full | ❌ None | ❌ None | ❌ None |

### Home Automation

| Service | Admin | Family | Guest | Service |
|---------|-------|--------|-------|---------|
| Home Assistant | ✅ Full | ✅ User | ⚠️ Limited | ✅ API |
| Pi-hole | ✅ Full | ⚠️ DNS Only | ❌ None | ❌ None |
| AdGuard | ✅ Full | ⚠️ DNS Only | ❌ None | ❌ None |

### Communication

| Service | Admin | Family | Guest | Service |
|---------|-------|--------|-------|---------|
| Matrix | ✅ Full | ✅ User | ❌ None | ✅ Bot |
| Mastodon | ✅ Full | ✅ User | ❌ None | ✅ Bot |
| Mattermost | ✅ Full | ✅ User | ❌ None | ✅ Bot |

### Productivity

| Service | Admin | Family | Guest | Service |
|---------|-------|--------|-------|---------|
| Paperless | ✅ Full | ✅ Upload | ❌ None | ✅ API |
| Seafile | ✅ Full | ✅ User | ⚠️ Limited | ✅ API |
| Wallabag | ✅ Full | ✅ User | ❌ None | ❌ None |

### Development

| Service | Admin | Family | Guest | Service |
|---------|-------|--------|-------|---------|
| Gitea | ✅ Full | ✅ User | ⚠️ Public | ✅ Bot |
| OpenHands | ✅ Full | ❌ None | ❌ None | ❌ None |

---

## Access Methods

### VPN Required

These services are only accessible via VPN:

- Prometheus (192.168.0.210:9090)
- Grafana (192.168.0.210:3000)
- Home Assistant (192.168.0.20:8123)
- Authentik (192.168.0.11:9000)
- Vaultwarden (192.168.0.10:8080)

### Public Access (via NPM)

- Plex: plex.vish.gg
- Jellyfin: jellyfin.vish.gg
- Matrix: matrix.vish.gg
- Mastodon: social.vish.gg

---

## Authentik Configuration

### Providers

| Service | Protocol | Client ID | Auth Flow |
|---------|----------|-----------|-----------|
| Grafana | OIDC | grafana | Default |
| Portainer | OIDC | portainer | Default |
| Jellyseerr | OIDC | jellyseerr | Default |
| Gitea | OAuth2 | gitea | Default |
| Paperless | OIDC | paperless | Default |

### Flows

1. **Default Flow** - Password + TOTP
2. **Password Only** - Simplified (internal)
3. **Out-of-band** - Recovery only

---

## Adding New Users

### 1. Create User in Authentik

```
Authentik Admin → Users → Create
- Username: <name>
- Email: <email>
- Name: <full name>
- Groups: <appropriate>
```

### 2. Assign Groups

```
Authentik Admin → Groups
- Admin: Full access
- Family: Standard access
- Guest: Limited access
```

### 3. Configure Service Access

For each service:
1. Add user to service (if supported)
2. Or add to group with access
3. Test login

---

## Revoking Access

### Process

1. **Disable user** in Authentik (do not delete)
2. **Remove from groups**
3. **Remove from service-specific access**
4. **Change shared passwords** if needed
5. **Document** in access log

### Emergency Revocation

```bash
# Lock account immediately
ak admin user set-password --username <user> --password-insecure <random>

# Or via Authentik UI
# Users → <user> → Disable
```

---

## Password Policy

| Setting | Value |
|---------|-------|
| Min Length | 12 characters |
| Require Numbers | Yes |
| Require Symbols | Yes |
| Require Uppercase | Yes |
| Expiry | 90 days |
| History | 5 passwords |

---

## Two-Factor Authentication

### Required For

- Admin accounts
- Vaultwarden
- SSH access

### Supported Methods

| Method | Services |
|--------|----------|
| TOTP | All SSO apps |
| WebAuthn | Authentik |
| Backup Codes | Recovery only |

---

## SSH Access

### Key-Based Only

```bash
# Add to ~/.ssh/authorized_keys
ssh-ed25519 AAAA... user@host
```

### Access Matrix

| Host | Admin | User | Notes |
|------|-------|------|-------|
| Atlantis | ✅ Key | ❌ | admin@atlantis.vish.local |
| Calypso | ✅ Key | ❌ | admin@calypso.vish.local |
| Concord NUC | ✅ Key | ❌ | homelab@concordnuc.vish.local |
| Homelab VM | ✅ Key | ❌ | homelab@192.168.0.210 |
| RPi5 | ✅ Key | ❌ | pi@rpi5-vish.local |

---

## Service Accounts

### Creating Service Accounts

1. Create user in Authentik
2. Set username: `svc-<service>`
3. Generate long random password
4. Store in Vaultwarden
5. Use for API access only

### Service Account Usage

| Service | Account | Use Case |
|---------|---------|----------|
| Prometheus | svc-prometheus | Scraping metrics |
| Backup | svc-backup | Backup automation |
| Monitoring | svc-alert | Alert delivery |
|arrstack | svc-arr | API automation |

---

## Audit Log

### What's Logged

- Login attempts (success/failure)
- Password changes
- Group membership changes
- Service access (where supported)

### Accessing Logs

```bash
# Authentik
Authentik Admin → Events

# System SSH
sudo lastlog
sudo grep "Failed password" /var/log/auth.log
```

---

## Password Managers

### Vaultwarden Organization

- **Homelab Admin**: Full access to all items
- **Family**: Personal vaults only
- **Shared**: Service credentials

### Shared Credentials

| Service | Credential Location |
|---------|---------------------|
| NPM | Vaultwarden → Shared → Infrastructure |
| Database | Vaultwarden → Shared → Databases |
| API Keys | Vaultwarden → Shared → APIs |

---

## Links

- [Authentik Setup](../services/authentik-sso.md)
- [Authentik Infrastructure](../infrastructure/authentik-sso.md)
- [VPN Setup](../services/individual/wg-easy.md)