OAuth 驗證

此頁面包含有關在 Immich 中使用 OAuth 的詳細資訊。

提示

無法將 app.immich:///oauth-callback 設置為有效的重定向 URI？請參閱移動端重定向 URI 尋找替代方案。

概述

Immich 支援透過 OpenID Connect (OIDC) 的第三方認證，這是一個構建在 OAuth2 基礎上的身份層。OIDC 被大多數身份提供商支援，包括：

基本條件

在 Immich 中啟用 OAuth 之前，需要在第三方認證伺服器中配置一個新的客戶端應用程式。雖然具體的配置方式因提供商而異，但通常的操作步驟應該相似。

建立一個新的 (客戶端) 應用程式
1. 提供商 類型應設置為 OpenID Connect 或 OAuth2
2. 客戶端類型 應設置為 Confidential
3. 應用程式 類型應設置為 Web
4. 授權類型應設置為 Authorization Code
配置重定向 URI/來源

登入重定向 URI 應包括：
- app.immich:///oauth-callback - 用於從移動應用程式使用 OAuth 登入
- http://DOMAIN:PORT/auth/login - 用於從網頁客戶端使用 OAuth 登入
- http://DOMAIN:PORT/user-settings - 用於在網頁客戶端手動連結 OAuth
重定向 URI 應包含所有您將用於訪問 Immich 的域。例如：

移動端
- app.immich:///oauth-callback (必須包括此項以確保 iOS 和 Android 移動應用程式正常運作)
本地主機
- http://localhost:2283/auth/login
- http://localhost:2283/user-settings
本地 IP
- http://192.168.0.200:2283/auth/login
- http://192.168.0.200:2283/user-settings
主機名稱
- https://immich.example.com/auth/login
- https://immich.example.com/user-settings

啟用 OAuth

一旦配置好新的 OAuth 客戶端應用程式，可以使用網頁中的管理設定頁面 (Administration -> Settings) 配置 Immich。

設定	類型	預設值	描述
已啟用	布林值	false	啟用/禁用 OAuth
發行者 URL	URL	(必填)	必填。用於客戶端自我發現的 URL (來自前一步)
客戶端 ID	字串	(必填)	必填。客戶端 ID (來自前一步)
客戶端密鑰	字串	(必填)	必填。客戶端密鑰 (來自前一步)
範圍	字串	openid email profile	發送請求時的完整範圍列表 (以空格分隔)
簽名算法	字串	RS256	用於簽署 id token 的算法 (例如: RS256, HS256)
存儲標籤聲明	字串	preferred_username	對應於用戶存儲標籤的聲明¹
角色聲明	字串	immich_role	對應於用戶角色的聲明。(應返回 "user" 或 "admin")¹
存儲配額聲明	字串	immich_quota	對應於用戶存儲的聲明¹
默認存儲配額 (GiB)	數值	0	無存儲配額聲明的用戶的默認配額 (輸入 0 表示無限制配額)
按鈕文字	字串	用 OAuth 登入	網頁上的 OAuth 按鈕文字
自動註冊	布林值	true	當為 true 時，用戶首次登入時將自動註冊
自動啟動	布林值	false	當為 true 時，將跳過登入頁面並自動開始 OAuth 登入流程
移動端重定向 URI 覆蓋	URL	(空)	http(s) 替代的移動端重定向 URI

聲明選項 [1]

聲明僅在用戶創建時使用，之後不會進行同步。

信息

發行者 URL 應類似於以下示例，並返回有效的 json 文件。

https://accounts.google.com/.well-known/openid-configuration
http://localhost:9000/application/o/immich/.well-known/openid-configuration

URL 中的 .well-known/openid-configuration 部分是可選的，並且在發現過程中將自動添加。

自動啟動

當啟用自動啟動時，登入頁面將自動將用戶重定向到 OAuth 授權 URL，以通過 OAuth 登入。若要再次訪問登入頁面，請使用瀏覽器的返回按鈕或直接導航到 /auth/login?autoLaunch=0。自動啟動也可以通過請求的方式啟用，訪問 /auth/login?authLaunch=1，這在如 Nextcloud 使用 External sites 應用及 oidc 應用直接與已登入的 Immich 實例互動的情況下非常有用。

移動端重定向 URI

移動應用程式的重定向 URI 為 app.immich:///oauth-callback，這是一個自定義方案。如果此自定義方案對於您的 OAuth 供應商來說是一個無效的重定向 URI，您可以按照以下步驟解決：

配置一個 http(s) 端點來將請求轉發到 app.immich:///oauth-callback
在您的供應商中將新端點列入白名單作為有效的重定向 URI。
在 OAuth 設定中將新端點指定為 移動端重定向 URI 覆蓋。

完成這些步驟後，您應該可以在移動應用程式中使用無需自定義方案的重定向 URI 的 OAuth。

信息

Immich 提供了一個路由 (/api/oauth/mobile-redirect) 已經配置為轉發請求到 app.immich:///oauth-callback，可用於步驟 1。

示例配置

Authentik 示例

以下是一個為 Authentik 配置 OAuth 的示例：

授權重定向 URI 的配置 (Authentik OAuth2/OpenID Provider)

在 Immich 系統設定中的 OAuth 配置

設定	值
發行者 URL	`https://example.immich.app/application/o/immich/.well-known/openid-configuration`
客戶端 ID	AFCj2rM1f4rps***...
客戶端密鑰	0v89FXkQOWO***...
範圍	openid email profile
簽名算法	RS256
存儲標籤聲明	preferred_username
存儲配額聲明	immich_quota
默認存儲配額 (GiB)	0 (0 表示無限制配額)
按鈕文字	用 Authentik 登入 (可選)
自動註冊	啟用 (可選)
自動啟動	啟用 (可選)
移動端重定向 URI 覆蓋	禁用
移動端重定向 URI

Google 示例

以下是一個為 Google 配置 OAuth 的示例：

授權重定向 URI 的配置 (Google Console)

在 Immich 系統設定中的 OAuth 配置

設定	值
發行者 URL	`https://accounts.google.com`
客戶端 ID	7***...vuls.apps.googleusercontent.com
客戶端密鑰	G******************OO
範圍	openid email profile
簽名算法	RS256
保存標籤聲明	preferred_username
保存配額聲明	immich_quota
預設存儲配額（GiB）	0 （0 表示無限配額）
按鈕文字	使用 Google 登錄（可選）
自動註冊	啟用（可選）
自動啟動	啟用
手機重定向 URI 覆蓋	啟用（必選）
手機重定向 URI	`https://example.immich.app/api/oauth/mobile-redirect`

概述​

基本條件​

啟用 OAuth​

自動啟動​

移動端重定向 URI​

示例配置​

Authentik 示例​

Google 示例​

概述