Initial commit: VPS setup documentation
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>
This commit is contained in:
295
docs/sso-integration-diagram.txt
Normal file
295
docs/sso-integration-diagram.txt
Normal file
@@ -0,0 +1,295 @@
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ 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
|
||||
Reference in New Issue
Block a user