Autenticação OAuth

Esta página contém detalhes sobre como usar OAuth no Immich.

dica

Não conseguiu definir app.immich:///oauth-callback como um URI de redirecionamento válido? Veja URI de Redirecionamento Móvel para uma solução alternativa.

Visão Geral

O Immich suporta autenticação de terceiros via OpenID Connect (OIDC), uma camada de identidade construída sobre o OAuth2. O OIDC é compatível com a maioria dos provedores de identidade, incluindo:

Pré-requisitos

Antes de habilitar o OAuth no Immich, um novo aplicativo cliente precisa ser configurado no servidor de autenticação de terceiros. Embora os detalhes desta configuração variem de provedor para provedor, a abordagem geral deve ser a mesma.

Crie um novo Aplicativo (Cliente)
1. O tipo de Provedor deve ser OpenID Connect ou OAuth2
2. O tipo de Cliente deve ser Confidential
3. O tipo de Aplicativo deve ser Web
4. O tipo de Concessão deve ser Authorization Code
Configure URIs/Origens de Redirecionamento

Os URIs de Redirecionamento para Login devem incluir:
- app.immich:///oauth-callback - para fazer login com OAuth no Aplicativo Mobile
- http://DOMAIN:PORT/auth/login - para fazer login com OAuth no Cliente Web
- http://DOMAIN:PORT/user-settings - para vincular OAuth manualmente no Cliente Web
Os URIs de Redirecionamento devem conter todos os domínios que você usará para acessar o Immich. Alguns exemplos incluem:

Mobile
- app.immich:///oauth-callback (Você DEVE incluir isso para que os aplicativos móveis iOS e Android funcionem corretamente)
Localhost
- http://localhost:2283/auth/login
- http://localhost:2283/user-settings
IP Local
- http://192.168.0.200:2283/auth/login
- http://192.168.0.200:2283/user-settings
Nome do Host
- https://immich.example.com/auth/login
- https://immich.example.com/user-settings

Habilitar OAuth

Depois que você tiver configurado um novo aplicativo cliente OAuth, o Immich pode ser configurado usando a página de Configurações de Administração, disponível na web (Administração -> Configurações).

Configuração	Tipo	Padrão	Descrição
Habilitado	boolean	false	Habilitar/desabilitar OAuth
URL do Provedor	URL	(obrigatório)	Obrigatório. URL de auto-descoberta para o cliente (do passo anterior)
ID do Cliente	string	(obrigatório)	Obrigatório. ID do Cliente (do passo anterior)
Segredo do Cliente	string	(obrigatório)	Obrigatório. Segredo do Cliente (do passo anterior)
Escopo	string	openid email profile	Lista completa de escopos a serem enviadas com a solicitação (delimitados por espaço)
Algoritmo de Assinatura	string	RS256	O algoritmo usado para assinar o token de id (exemplos: RS256, HS256)
Reivindicação do Rótulo de Armazenamento	string	preferred_username	Mapeamento de reivindicação para o rótulo de armazenamento do usuário¹
Reivindicação da Função	string	immich_role	Mapeamento de reivindicação para a função do usuário. (deve retornar "user" ou "admin")¹
Reivindicação de Cota de Armazenamento	string	immich_quota	Mapeamento de reivindicação para o armazenamento do usuário¹
Cota de Armazenamento Padrão (GiB)	number	0	Cota padrão para usuário sem reivindicação de cota de armazenamento (Insira 0 para cota ilimitada)
Texto do Botão	string	Entrar com OAuth	Texto para o botão OAuth na web
Registro Automático	boolean	true	Quando ativado, registrará automaticamente um usuário na primeira vez que ele entrar
Lançamento Automático	boolean	false	Quando ativado, pulará a página de login e iniciará automaticamente o processo de login OAuth
Substituir URI de Redirecionamento Móvel	URL	(vazio)	Alternativa http(s) para URI de redirecionamento móvel

Opções de Reivindicação [1]

Reivindicação é usada apenas na criação de usuário e não sincronizada após isso.

informação

O URL do Provedor deve se parecer com o seguinte e retornar um documento json válido.

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

A parte .well-known/openid-configuration do URL é opcional e será adicionada automaticamente durante a descoberta.

Lançamento Automático

Quando o Lançamento Automático está habilitado, a página de login redirecionará automaticamente o usuário para o URL de autorização OAuth, para entrar com OAuth. Para acessar a tela de login novamente, use o botão 'voltar' do navegador ou navegue diretamente para /auth/login?autoLaunch=0. O Lançamento Automático também pode ser habilitado com base em cada solicitação ao navegar para /auth/login?authLaunch=1, isso pode ser útil em situações onde o Immich é chamado por exemplo, pelo Nextcloud usando o aplicativo Sites Externos e o aplicativo oidc para permitir que os usuários interajam diretamente com uma instância logada do Immich.

URI de Redirecionamento Móvel

O URI de redirecionamento para o aplicativo móvel é app.immich:///oauth-callback, que é um Esquema Personalizado. Se este esquema personalizado for um URI de redirecionamento inválido para seu Provedor OAuth, você pode contornar isso fazendo o seguinte:

Configure um endpoint http(s) para encaminhar solicitações para app.immich:///oauth-callback
Liste o novo endpoint como um URI de redirecionamento válido no seu provedor.
Especifique o novo endpoint como a opção Substituir URI de Redirecionamento Móvel, nas configurações OAuth.

Com essas etapas em vigor, você deve conseguir usar OAuth no Aplicativo Móvel sem um URI de redirecionamento personalizado.

informação

O Immich possui uma rota (/api/oauth/mobile-redirect) que já está configurada para encaminhar solicitações para app.immich:///oauth-callback, e pode ser usado para o passo 1.

Exemplo de Configuração

Exemplo de Authentik

Aqui está um exemplo do OAuth configurado para Authentik:

Configuração de URIs de Redirecionamento Autorizados (Provedor Authentik OAuth2/OpenID)

URIs de Redirecionamento Autorizados Authentik

Configuração de OAuth nas Configurações do Sistema Immich

Configuração	Valor
URL do Provedor	`https://example.immich.app/application/o/immich/.well-known/openid-configuration`
ID do Cliente	AFCj2rM1f4rps*************lCLEum6hH9...
Segredo do Cliente	0v89FXkQOWO**************mprbvXD549HH6s1iw...
Escopo	openid email profile
Algoritmo de Assinatura	RS256
Reivindicação do Rótulo	preferred_username
Reivindicação de Cota	immich_quota
Cota Padrão (GiB)	0 (0 para cota ilimitada)
Texto do Botão	Entrar com Authentik (opcional)
Registro Automático	Habilitado (opcional)
Lançamento Automático	Habilitado (opcional)
Substituir URI de Redirecionamento Móvel	Desativado
URI de Redirecionamento Móvel

Exemplo do Google

Aqui está um exemplo do OAuth configurado para Google:

Configuração de URIs de Redirecionamento Autorizados (Console do Google)

URIs de Redirecionamento Autorizados Google

Configuração de OAuth nas Configurações do Sistema Immich

Configuração	Valor
URL do Provedor	`https://accounts.google.com`
ID do Cliente	7******************vuls.apps.googleusercontent.com
Client Secret	G******************OO
Escopo	openid email profile
Algoritmo de Assinatura	RS256
Claim para Rótulo de Armazenamento	preferred_username
Claim da Cota de Armazenamento	immich_quota
Cota Padrão de Armazenamento (GiB)	0 (0 para cota ilimitada)
Texto do Botão	Entrar com Google (opcional)
Registro Automático	Habilitado (opcional)
Lançamento Automático	Habilitado
Redirecionamento para Mobile	Habilitado (necessário)
URI de Redirecionamento para Mobile	`https://example.immich.app/api/oauth/mobile-redirect`

Visão Geral​

Pré-requisitos​

Habilitar OAuth​

Lançamento Automático​

URI de Redirecionamento Móvel​

Exemplo de Configuração​

Exemplo de Authentik​

Exemplo do Google​