OAuth认证

本页面包含有关在Immich中使用OAuth的详细信息。

提示

无法将app.immich:///oauth-callback设置为有效的重定向URI？请参阅移动端重定向URI以获取备用解决方案。

概述

Immich支持通过OpenID Connect (OIDC)进行第三方身份验证，该身份层构建在OAuth2之上。OIDC被大多数身份提供者支持，包括：

• Authentik
• Authelia
• Okta
• Google

前置条件

在Immich中启用OAuth之前，需要在第三方认证服务器中配置一个新的客户端应用程序。虽然该设置的具体细节因提供者而异，但通常的操作方法应该相同。

1. 创建一个新的（客户端）应用程序

   1. 提供者类型应为OpenID Connect或OAuth2
   2. 客户端类型应为Confidential
   3. 应用程序类型应为Web
   4. 授权类型应为Authorization Code

2. 配置重定向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客户端应用后，可以使用管理设置页面中的设置选项在Immich中配置（网页管理 -> 设置）。

设置	类型	默认值	描述
启用	布尔值	false	启用/禁用OAuth
提供者URL	URL	（必需）	必需。客户端的自发现URL（见上一步）
客户端ID	字符串	（必需）	必需。客户端ID（见上一步）
客户端秘密	字符串	（必需）	必需。客户端秘密（见上一步）
授权范围	字符串	openid email profile	随请求发送的完整作用域列表（用空格分隔）
签名算法	字符串	RS256	用于签署ID令牌的算法（例如：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调用Immich时很有用，例如使用外部站点应用和oidc应用，以便用户能够直接与已登录的Immich实例交互。

移动端重定向URI

移动应用的重定向URI是app.immich:///oauth-callback，这是一个自定义方案。如果此自定义方案对您的OAuth提供者无效，您可以通过以下方法解决：

1. 配置一个HTTP(s)端点，将请求转发到app.immich:///oauth-callback
2. 将新端点列白为提供者中的有效重定向URI。
3. 在OAuth设置中，将新端点指定为移动端重定向URI覆盖。

通过这些步骤，您应该可以无须自定义方案重定向URI地在移动应用中使用OAuth。

信息

Immich配置了一个路由（/api/oauth/mobile-redirect），可将请求转发至app.immich:///oauth-callback，并可用于第1步。

示例配置

Authentik示例

Authentik示例

以下是为Authentik配置的OAuth示例：

已授权的重定向URI配置（Authentik OAuth2/OpenID提供者）

Immich系统设置中的OAuth配置

设置	值
提供者URL	https://example.immich.app/application/o/immich/.well-known/openid-configuration
客户端ID	AFCj2rM1f4rps***lCLEum6hH9...
客户端秘密	0v89FXkQOWO***mprbvXD549HH6s1iw...
授权范围	openid email profile
签名算法	RS256
存储标签声明	preferred_username
存储配额声明	immich_quota
默认存储配额（GiB）	0（0表示无限制配额）
按钮文本	使用Authentik登录（可选）
自动注册	启用（可选）
自动启动	启用（可选）
移动端重定向URI覆盖	禁用
移动端重定向URI

Google示例

Google示例

以下是为Google配置的OAuth示例：

已授权的重定向URI配置（Google控制台）

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