┌─────────────────────────────────────────────────────────────────────────────────┐ │ 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