service
1e1a528a5e
Add comprehensive documentation for VPS setup and configuration including: - Project instructions - VPS1 starting point configuration - VPS1 current state documentation - VPS1 todo list Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
296 lines
28 KiB
Plaintext
296 lines
28 KiB
Plaintext
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ SSO INTEGRATION ARCHITECTURE │
|
|
│ Gitea + Immich with Netbird Zitadel │
|
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
|
|
┌──────────────────┐
|
|
│ │
|
|
│ User Browser │
|
|
│ │
|
|
└────────┬─────────┘
|
|
│
|
|
│ 1. User clicks "Login with SSO"
|
|
│
|
|
▼
|
|
┌──────────────────────────────────────┐
|
|
│ │
|
|
│ Choose Application: │
|
|
│ │
|
|
│ ┌─────────────────┐ ┌─────────────┴────────────────┐
|
|
│ │ │ │ │
|
|
│ │ Gitea │ │ Immich │
|
|
│ │ │ │ │
|
|
│ │ git.phiiiil.de │ │ immich.phiiiil.de │
|
|
│ │ │ │ │
|
|
│ └────────┬────────┘ └────────────┬─────────────────┘
|
|
│ │ │
|
|
│ └────────────┬───────────┘
|
|
│ │
|
|
└─────────────────────────┼─────────────────────┐
|
|
│ │
|
|
│ 2. Redirect to │
|
|
│ Zitadel with │
|
|
│ Client ID │
|
|
│ │
|
|
▼ │
|
|
┌──────────────────────────────────┐ │
|
|
│ │ │
|
|
│ Netbird Zitadel │ │
|
|
│ (Identity Provider) │ │
|
|
│ │ │
|
|
│ nb.phiiiil.de │ │
|
|
│ │ │
|
|
│ ┌────────────────────────┐ │ │
|
|
│ │ │ │ │
|
|
│ │ • Authentication │ │ │
|
|
│ │ • User Management │ │ │
|
|
│ │ • Token Issuance │ │ │
|
|
│ │ • OAuth2/OIDC │ │ │
|
|
│ │ │ │ │
|
|
│ └────────────────────────┘ │ │
|
|
│ │ │
|
|
└────────────┬─────────────────────┘ │
|
|
│ │
|
|
│ 3. Authenticate │
|
|
│ & Get Code │
|
|
│ │
|
|
│ 4. Return with Code │
|
|
│ │
|
|
│ │
|
|
└────────────────────────┘
|
|
│
|
|
│
|
|
┌──────────────┴──────────────┐
|
|
│ │
|
|
│ 5. Exchange Code for Token │
|
|
│ │
|
|
▼ ▼
|
|
┌─────────────────┐ ┌────────────────────┐
|
|
│ │ │ │
|
|
│ Gitea │ │ Immich │
|
|
│ │ │ │
|
|
│ Validates │ │ Validates │
|
|
│ Token │ │ Token │
|
|
│ │ │ │
|
|
│ Creates/Links │ │ Creates/Links │
|
|
│ User Account │ │ User Account │
|
|
│ │ │ │
|
|
└────────┬────────┘ └─────────┬──────────┘
|
|
│ │
|
|
│ 6. Session Established │
|
|
│ │
|
|
└────────────┬───────────────┘
|
|
│
|
|
▼
|
|
┌──────────────────┐
|
|
│ │
|
|
│ User Logged In │
|
|
│ │
|
|
│ • Gitea: Git │
|
|
│ repos, SSH │
|
|
│ │
|
|
│ • Immich: │
|
|
│ Photos, ML │
|
|
│ │
|
|
└──────────────────┘
|
|
|
|
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ CONFIGURATION SUMMARY │
|
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌──────────────────────────────────────────────────────────────────────────────────┐
|
|
│ ZITADEL CONFIGURATION (https://nb.phiiiil.de/ui) │
|
|
├──────────────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ Project: Gitea Project: Immich │
|
|
│ ┌─────────────────────────┐ ┌─────────────────────────┐ │
|
|
│ │ Application: gitea │ │ Application: immich │ │
|
|
│ │ Type: Web Application │ │ Type: Web Application │ │
|
|
│ │ Auth Method: PKCE │ │ Auth Method: PKCE │ │
|
|
│ │ │ │ │ │
|
|
│ │ Redirect URIs: │ │ Redirect URIs: │ │
|
|
│ │ • https://git.phiiiil.de│ │ • https://immich.phiiiil│ │
|
|
│ │ /user/oauth2/zitadel/ │ │ .de/auth/login │ │
|
|
│ │ callback │ │ │ │
|
|
│ │ │ │ Scopes: │ │
|
|
│ │ Scopes: │ │ • openid │ │
|
|
│ │ • openid │ │ • profile │ │
|
|
│ │ • profile │ │ • email │ │
|
|
│ │ • email │ │ │ │
|
|
│ │ │ │ │ │
|
|
│ │ Output: │ │ Output: │ │
|
|
│ │ • Client ID │ │ • Client ID │ │
|
|
│ │ • Client Secret │ │ • Client Secret │ │
|
|
│ └─────────────────────────┘ └─────────────────────────┘ │
|
|
│ │
|
|
└──────────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌──────────────────────────────────────────────────────────────────────────────────┐
|
|
│ GITEA CONFIGURATION (https://git.phiiiil.de) │
|
|
├──────────────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ Admin Panel → Authentication Sources → Add OAuth2: │
|
|
│ ┌────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ Authentication Name: Netbird Zitadel │ │
|
|
│ │ OAuth2 Provider: OpenID Connect │ │
|
|
│ │ Client ID: [from Zitadel] │ │
|
|
│ │ Client Secret: [from Zitadel] │ │
|
|
│ │ Discovery Endpoint: https://nb.phiiiil.de/ │ │
|
|
│ │ .well-known/openid-configuration │ │
|
|
│ │ Auto-discover Email: ✅ Enabled │ │
|
|
│ │ Scopes: openid profile email │ │
|
|
│ │ Email Auth Field: Email │ │
|
|
│ │ Update Avatar: ✅ Enabled │ │
|
|
│ └────────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ Features: │
|
|
│ ✅ OAuth2 already enabled in docker-compose.yml │
|
|
│ ✅ Auto-user creation available │
|
|
│ ✅ Existing admin account: phil / j8bKvIl3AtIp5aTG │
|
|
│ ✅ SSH on port 2222 continues to work │
|
|
│ │
|
|
└──────────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌──────────────────────────────────────────────────────────────────────────────────┐
|
|
│ IMMICH CONFIGURATION (https://immich.phiiiil.de) │
|
|
├──────────────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ Admin Panel → Settings → Authentication → OAuth: │
|
|
│ ┌────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ Button Text: Login with Netbird │ │
|
|
│ │ Client ID: [from Zitadel] │ │
|
|
│ │ Client Secret: [from Zitadel] │ │
|
|
│ │ Issuer URL: https://nb.phiiiil.de │ │
|
|
│ │ Authorization Endpoint: https://nb.phiiiil.de/oauth/v2/authorize │ │
|
|
│ │ Token Endpoint: https://nb.phiiiil.de/oauth/v2/token │ │
|
|
│ │ User Info Endpoint: https://nb.phiiiil.de/oidc/v1/userinfo │ │
|
|
│ │ Scope: openid profile email │ │
|
|
│ │ Auto Registering: ✅ Enabled │ │
|
|
│ │ Auto Linking: ✅ Enabled │ │
|
|
│ │ Storage Label Claim: email │ │
|
|
│ └────────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ Alternative: Via .env file │
|
|
│ ┌────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ IMMICH_OAUTH_ENABLED=true │ │
|
|
│ │ IMMICH_OAUTH_ISSUER_URL=https://nb.phiiiil.de │ │
|
|
│ │ IMMICH_OAUTH_CLIENT_ID=[from Zitadel] │ │
|
|
│ │ IMMICH_OAUTH_CLIENT_SECRET=[from Zitadel] │ │
|
|
│ │ IMMICH_OAUTH_AUTO_REGISTER=true │ │
|
|
│ └────────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ Features: │
|
|
│ ✅ OAuth2/OIDC supported │
|
|
│ ✅ Auto-user registration available │
|
|
│ ✅ 37GB of photos must remain accessible │
|
|
│ │
|
|
└──────────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌──────────────────────────────────────────────────────────────────────────────────┐
|
|
│ OAUTH2 / OIDC ENDPOINTS │
|
|
├──────────────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ Discovery (Config): │
|
|
│ • https://nb.phiiiil.de/.well-known/openid-configuration │
|
|
│ │
|
|
│ Authorization: │
|
|
│ • https://nb.phiiiil.de/oauth/v2/authorize │
|
|
│ │
|
|
│ Token Exchange: │
|
|
│ • https://nb.phiiiil.de/oauth/v2/token │
|
|
│ │
|
|
│ User Info: │
|
|
│ • https://nb.phiiiil.de/oidc/v1/userinfo │
|
|
│ │
|
|
│ JWKS (Public Keys): │
|
|
│ • https://nb.phiiiil.de/oauth/v2/keys │
|
|
│ │
|
|
│ End Session (Logout): │
|
|
│ • https://nb.phiiiil.de/oidc/v1/end_session │
|
|
│ │
|
|
└──────────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌──────────────────────────────────────────────────────────────────────────────────┐
|
|
│ SECURITY CONSIDERATIONS │
|
|
├──────────────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ✅ All communication over HTTPS (Caddy + Let's Encrypt) │
|
|
│ ✅ PKCE (Proof Key for Code Exchange) enabled │
|
|
│ ✅ No passwords sent over network │
|
|
│ ✅ Token-based authentication │
|
|
│ ✅ Centralized user management │
|
|
│ ✅ Single sign-on across services │
|
|
│ ✅ Token expiration and refresh handling │
|
|
│ │
|
|
│ Recommendations: │
|
|
│ • Use strong password for Netbird admin │
|
|
│ • Enable 2FA in Netbird/Zitadel if available │
|
|
│ • Store Client Secrets securely (password manager) │
|
|
│ • Review token expiration settings │
|
|
│ • Monitor OAuth logs for suspicious activity │
|
|
│ │
|
|
└──────────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌──────────────────────────────────────────────────────────────────────────────────┐
|
|
│ IMPLEMENTATION FLOW │
|
|
├──────────────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ 1. BACKUP Run /home/phil/docker/backup/backup.sh │
|
|
│ │
|
|
│ 2. ZITADEL CONFIG Access https://nb.phiiiil.de/ui │
|
|
│ • Create Gitea project │
|
|
│ • Create Gitea application │
|
|
│ • Save Client ID + Secret │
|
|
│ • Create Immich project │
|
|
│ • Create Immich application │
|
|
│ • Save Client ID + Secret │
|
|
│ │
|
|
│ 3. GITEA CONFIG Access https://git.phiiiil.de │
|
|
│ • Login as admin (phil) │
|
|
│ • Add OAuth2 authentication source │
|
|
│ • Enable auto-user creation │
|
|
│ • Test SSO login │
|
|
│ │
|
|
│ 4. IMMICH CONFIG Access https://immich.phiiiil.de │
|
|
│ • Login as admin │
|
|
│ • Configure OAuth2 in settings │
|
|
│ • Enable auto-registration │
|
|
│ • Test SSO login │
|
|
│ │
|
|
│ 5. TESTING Test full authentication flow │
|
|
│ • Verify login works for both │
|
|
│ • Verify user creation │
|
|
│ • Verify logout works │
|
|
│ • Check cross-service SSO │
|
|
│ │
|
|
│ 6. DOCUMENTATION Update all documentation files │
|
|
│ │
|
|
└──────────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌──────────────────────────────────────────────────────────────────────────────────┐
|
|
│ ROLLBACK PROCEDURES │
|
|
├──────────────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ Gitea: │
|
|
│ • Login with local admin account │
|
|
│ • Remove OAuth2 authentication source via admin panel │
|
|
│ • Users revert to password authentication │
|
|
│ │
|
|
│ Immich: │
|
|
│ • Login with local admin account │
|
|
│ • Disable OAuth2 in settings │
|
|
│ • Restart immich-server container │
|
|
│ │
|
|
│ Complete Restore: │
|
|
│ • Restore databases from /mnt/backup/latest/ │
|
|
│ • Gitea: gunzip < gitea-db.sql.gz | docker exec -i gitea-db psql -U gitea │
|
|
│ • Immich: gunzip < immich-db.sql.gz | docker exec -i immich_postgres psql │
|
|
│ │
|
|
└──────────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
|
|
Generated: 2026-01-25
|
|
Document: sso-integration-plan.md
|