# Authentik SSO

**URL**: https://sso.vish.gg  
**Stack**: `authentik-sso-stack` (Portainer ID: 495)  
**Host**: Calypso (DS723+)  
**Port**: 9000 (HTTP), 9443 (HTTPS)

## Overview

Authentik is the central identity provider for the homelab, providing:
- Single Sign-On (SSO) for all services
- OAuth2/OIDC provider
- SAML provider
- Forward authentication proxy
- User management

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                     Authentik Stack                         │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ authentik-db │  │authentik-    │  │ authentik-   │      │
│  │ (PostgreSQL) │  │   redis      │  │   server     │      │
│  │    :5432     │  │    :6379     │  │  :9000/9443  │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
│                                       ┌──────────────┐      │
│                                       │ authentik-   │      │
│                                       │   worker     │      │
│                                       └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
```

## Services Protected by Authentik

| Service | Domain | Protection Type |
|---------|--------|-----------------|
| Actual Budget | actual.vish.gg | Forward Auth (planned) |
| Paperless-NGX | docs.vish.gg | Forward Auth (planned) |
| Rackula | rackula.vish.gg | Forward Auth (planned) |
| Gitea | git.vish.gg | OAuth2 |
| Grafana | gf.vish.gg | OAuth2 (planned) |

## Services NOT Protected (Public/Self-Auth)

| Service | Domain | Reason |
|---------|--------|--------|
| Authentik | sso.vish.gg | Is the SSO provider |
| OpenSpeedTest | ost.vish.gg | Public utility |
| Seafile | sf.vish.gg | Has built-in auth + share links |
| ntfy | ntfy.vish.gg | Has built-in auth |

## Data Locations

| Data | Path |
|------|------|
| PostgreSQL Database | `/volume1/docker/authentik/database` |
| Media (icons, uploads) | `/volume1/docker/authentik/media` |
| Certificates | `/volume1/docker/authentik/certs` |
| Email Templates | `/volume1/docker/authentik/templates` |
| Redis Data | `/volume1/docker/authentik/redis` |

## Initial Setup

1. Deploy stack via Portainer
2. Navigate to https://sso.vish.gg/if/flow/initial-setup/
3. Create admin account (akadmin)
4. Configure providers for each service

## Backup

Critical data to backup:
- PostgreSQL database (`/volume1/docker/authentik/database`)
- Media files (`/volume1/docker/authentik/media`)

## Environment Variables

Key environment variables (stored in docker-compose):
- `AUTHENTIK_SECRET_KEY` - Encryption key (DO NOT LOSE)
- `AUTHENTIK_POSTGRESQL__PASSWORD` - Database password
- Email settings for password reset notifications

## Troubleshooting

### Check container health
```bash
docker ps | grep -i authentik
```

### View logs
```bash
docker logs Authentik-SERVER
docker logs Authentik-WORKER
```

### Database connection issues
Ensure authentik-db is healthy before server starts.