Immich 的 OAuth 身份验证

本页介绍如何在Immich中使用OAuth。

提示

如果无法把app.immich:///oauth-callback设置为有效重定向URI，参见“移动端重定向URI”中的替代方案。

概览

Immich通过OpenID Connect（OIDC）支持第三方身份验证。OIDC是在OAuth2之上构建的身份层，大多数身份提供商都支持它，包括：

• Authentik
• Authelia
• Okta
• Google
• Keycloak

前置条件

在Immich中启用OAuth前，需要先在第三方身份验证服务器中配置一个客户端应用。不同提供商的具体操作不同，但总体方法相同。

1. 创建新的客户端应用

   1. Provider类型应为OpenID Connect或OAuth2。
   2. Client类型应为Confidential。
   3. Application类型应为Web。
   4. Grant类型应为Authorization Code。

2. 配置重定向URI与来源

   登录重定向URI应包含：

   • app.immich:///oauth-callback：移动应用中的OAuth登录。
   • http://DOMAIN:PORT/auth/login：Web客户端中的OAuth登录。
   • http://DOMAIN:PORT/user-settings：在Web客户端中手动关联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

3. 配置后端通道注销URL

   如果身份验证服务器支持，可以指定Backchannel logout URL，格式为http://DOMAIN:PORT/api/oauth/backchannel-logout。

启用 OAuth

配置好OAuth客户端应用后，在Immich Web端的Administration -> Settings页面中配置OAuth。

Claim Options [1]

这些claim只在创建用户时使用，之后不会同步。

信息

Issuer 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部分可以省略，发现过程会自动添加。

自动启动登录

启用Auto Launch后，登录页会自动跳转到OAuth授权URL。要重新打开登录界面，可使用浏览器的后退按钮，或直接访问/auth/login?autoLaunch=0。也可以通过/auth/login?autoLaunch=1按请求启用Auto Launch。例如，Nextcloud通过External sites与oidc应用调用Immich时，这可以让用户直接使用已登录的Immich实例。

移动端重定向 URI

移动应用的重定向URI为app.immich:///oauth-callback，使用自定义scheme。如果OAuth提供商不接受这种URI，可以按以下步骤处理：

1. 配置一个HTTP(S)端点，把请求转发到app.immich:///oauth-callback。
2. 在身份提供商中，将新端点加入有效重定向URI白名单。
3. 在Immich的OAuth设置中，把新端点填入Mobile Redirect URI Override。

完成后，移动应用就可以使用OAuth，而无需让身份提供商接受自定义scheme的重定向URI。

信息

Immich已经提供/api/oauth/mobile-redirect路由，会转发到app.immich:///oauth-callback，可用于第一步。

配置示例

Authelia 示例

以下示例展示如何配置Authelia OAuth：

示例假定用户schema中存在immichquota属性，用来设置Immich存储配额。与配额相关的配置是可选的。

authentication_backend:
  ldap:
    # The LDAP server configuration goes here.
    # See: https://www.authelia.com/c/ldap
    attributes:
      extra:
        immichquota: # The attribute name from LDAP
          name: 'immich_quota'
          multi_valued: false
          value_type: 'integer'
identity_providers:
  oidc:
    ## The other portions of the mandatory OpenID Connect 1.0 configuration go here.
    ## See: https://www.authelia.com/c/oidc
    claims_policies:
      immich_policy:
        custom_claims:
          immich_quota:
            attribute: 'immich_quota'
    scopes:
      immich_scope:
        claims:
          - 'immich_quota'

    clients:
      - client_id: 'immich'
        client_name: 'Immich'
        # https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret
        client_secret: '$pbkdf2-sha512$310000$c8p78n7pUMln0jzvd4aK4Q$JNRBzwAo0ek5qKn50cFzzvE9RXV88h1wJn5KGiHrD0YKtZaR/nCb2CJPOsKaPK0hjf.9yHxzQGZziziccp6Yng'
        public: false
        require_pkce: true
        pkce_challenge_method: 'S256'
        redirect_uris:
          - 'https://example.immich.app/auth/login'
          - 'https://example.immich.app/user-settings'
          - 'app.immich:///oauth-callback'
        scopes:
          - 'openid'
          - 'profile'
          - 'email'
          - 'immich_scope'
        claims_policy: 'immich_policy'
        response_types:
          - 'code'
        grant_types:
          - 'authorization_code'
        id_token_signed_response_alg: 'RS256'
        userinfo_signed_response_alg: 'RS256'
        token_endpoint_auth_method: 'client_secret_post'

Immich系统设置中的OAuth配置

Authentik 示例

以下示例展示如何配置Authentik OAuth：

Authentik OAuth2/OpenID Provider中的授权重定向URI配置

Immich系统设置中的OAuth配置

Google 示例

以下示例展示如何配置Google OAuth：

Google控制台中的授权重定向URI配置

Immich系统设置中的OAuth配置

Keycloak 示例

以下示例展示如何配置Keycloak OAuth：

在Keycloak Realm中创建immich客户端。

Immich系统设置中的OAuth配置

Role Claim可通过Client Role管理。记得创建claim名称为immich_role的映射器。