Autenticación OAuth
Esta página contiene detalles sobre cómo usar OAuth en Immich.
¿No puedes configurar app.immich:///oauth-callback como un URI de redirección válido? Consulta URI de Redirección Móvil para una solución alternativa.
Visión General
Immich admite autenticación de terceros a través de OpenID Connect (OIDC), una capa de identidad construida sobre OAuth2. OIDC es compatible con la mayoría de los proveedores de identidad, incluyendo:
Requisitos Previos
Antes de habilitar OAuth en Immich, se necesita configurar una nueva aplicación cliente en el servidor de autenticación de terceros. Aunque los detalles de esta configuración varían dependiendo del proveedor, el enfoque general debe ser el mismo.
-
Crear una nueva Aplicación (Cliente)
- El tipo de Proveedor debe ser
OpenID ConnectoOAuth2 - El tipo de Cliente debe ser
Confidencial - El tipo de Aplicación debe ser
Web - El tipo de Concesión debe ser
Código de Autorización
- El tipo de Proveedor debe ser
-
Configurar URIs/Orígenes de Redirección
Los URIs de redirección de inicio de sesión deben incluir:
app.immich:///oauth-callback- para iniciar sesión con OAuth desde la App Móvilhttp://DOMINIO:PUERTO/auth/login- para iniciar sesión con OAuth desde el Cliente Webhttp://DOMINIO:PUERTO/user-settings- para vincular manualmente OAuth en el Cliente Web
Los URIs de redirección deben contener todos los dominios que utilizarás para acceder a Immich. Algunos ejemplos incluyen:
Móvil
app.immich:///oauth-callback(Debes incluir esto para que las apps móviles en iOS y Android funcionen correctamente)
Localhost
http://localhost:2283/auth/loginhttp://localhost:2283/user-settings
IP Local
http://192.168.0.200:2283/auth/loginhttp://192.168.0.200:2283/user-settings
Nombre del Host
https://immich.example.com/auth/loginhttps://immich.example.com/user-settings
Habilitar OAuth
Una vez que tengas configurada la nueva aplicación cliente OAuth, puedes configurar Immich desde la página de Configuración de Administración, disponible en la web (Administración -> Configuraciones).
| Configuración | Tipo | Predeterminado | Descripción |
|---|---|---|---|
| Habilitado | boolean | false | Habilitar/deshabilitar OAuth |
| URL del Emisor | URL | (requerido) | Requerido. URL de auto-descubrimiento para el cliente (del paso anterior) |
| ID del Cliente | string | (requerido) | Requerido. ID del Cliente (del paso anterior) |
| Secreto del Cliente | string | (requerido) | Requerido. Secreto del Cliente (del paso anterior) |
| Alcance | string | openid email profile | Lista completa de alcances a enviar con la solicitud (separados por espacio) |
| Algoritmo de Firma | string | RS256 | El algoritmo utilizado para firmar el token de id (ejemplos: RS256, HS256) |
| Reclamación de Etiqueta de Almacenamiento | string | preferred_username | Mapeo de reclamación para la etiqueta de almacenamiento del usuario¹ |
| Reclamación de Rol | string | immich_role | Mapeo de reclamación para el rol del usuario. (debe devolver "user" o "admin")¹ |
| Reclamación de Cuota de Almacenamiento | string | immich_quota | Mapeo de reclamación para el almacenamiento del usuario¹ |
| Cuota Predeterminada de Almacenamiento (GiB) | number | 0 | Cuota predeterminada para el usuario sin reclamación de almacenamiento (Ingresa 0 para cuota ilimitada) |
| Texto del Botón | string | Iniciar sesión con OAuth | Texto para el botón de OAuth en la web |
| Registro Automático | boolean | true | Cuando está habilitado, registrará automáticamente a un usuario la primera vez que inicie sesión |
| Inicio Automático | boolean | false | Cuando está habilitado, omitirá la página de inicio de sesión y comenzará automáticamente el proceso de inicio de sesión OAuth |
| Anulación del URI de Redirección Móvil | URL | (vacío) | URI de redirección móvil http(s) alternativa |
La reclamación sólo se utiliza al crear un usuario y no se sincroniza después de eso.
La URL del Emisor debería ser algo como lo siguiente, y devolver un documento json válido.
https://accounts.google.com/.well-known/openid-configurationhttp://localhost:9000/application/o/immich/.well-known/openid-configuration
La parte .well-known/openid-configuration de la URL es opcional y se agregará automáticamente durante el descubrimiento.
Inicio Automático
Cuando el Inicio Automático está habilitado, la página de inicio de sesión redirigirá automáticamente al usuario a la URL de autorización OAuth para iniciar sesión con OAuth. Para acceder nuevamente a la pantalla de inicio de sesión, utiliza el botón de retroceso del navegador, o ve directamente a /auth/login?autoLaunch=0.
El Inicio Automático también se puede habilitar caso por caso al navegar a /auth/login?authLaunch=1. Esto puede ser útil en situaciones donde Immich es llamado desde, por ejemplo, Nextcloud utilizando la app de Sitios Externos y la app oidc para permitir a los usuarios interactuar directamente con una instancia iniciada de Immich.
URI de Redirección Móvil
El URI de redirección para la app móvil es app.immich:///oauth-callback, que es un Esquema Personalizado. Si este esquema personalizado no es válido como URI de redirección para tu Proveedor OAuth, puedes evitar esto haciendo lo siguiente:
- Configura un endpoint http(s) para redirigir solicitudes a
app.immich:///oauth-callback - Incluye en la lista blanca el nuevo endpoint como un URI de redirección válido con tu proveedor.
- Especifica el nuevo endpoint como la
Anulación del URI de Redirección Móvil, en las configuraciones de OAuth.
Con estos pasos en marcha, deberías poder usar OAuth desde la App Móvil sin un URI de redirección con esquema personalizado.
Immich tiene una ruta (/api/oauth/mobile-redirect) que ya está configurada para redirigir solicitudes a app.immich:///oauth-callback, y puede ser utilizada para el paso 1.
Ejemplo de Configuración
Ejemplo de Authentik
Ejemplo de Authentik
Aquí tienes un ejemplo de OAuth configurado para Authentik:
Configuración de URIs de redirección autorizados (Proveedor de OAuth2/OpenID de Authentik)
Configuración de OAuth en las Configuraciones del Sistema Immich
| Configuración | Valor |
|---|---|
| URL del Emisor | https://example.immich.app/application/o/immich/.well-known/openid-configuration |
| ID del Cliente | AFCj2rM1f4rps*************lCLEum6hH9... |
| Secreto del Cliente | 0v89FXkQOWO**************mprbvXD549HH6s1iw... |
| Alcance | openid email profile |
| Algoritmo de Firma | RS256 |
| Reclamación de Etiqueta de Almacenamiento | preferred_username |
| Reclamación de Cuota de Almacenamiento | immich_quota |
| Cuota Predeterminada de Almacenamiento (GiB) | 0 (0 para cuota ilimitada) |
| Texto del Botón | Inicia sesión con Authentik (opcional) |
| Registro Automático | Habilitado (opcional) |
| Inicio Automático | Habilitado (opcional) |
| Anulación del URI de Redirección Móvil | Deshabilitada |
| URI de Redirección Móvil |
Ejemplo de Google
Ejemplo de Google
Aquí tienes un ejemplo de OAuth configurado para Google:
Configuración de URIs de redirección autorizados (Consola de Google)
Configuración de OAuth en las Configuraciones del Sistema Immich
| Configuración | Valor |
|---|---|
| URL del Emisor | https://accounts.google.com |
| ID del Cliente | 7******************vuls.apps.googleusercontent.com |
| Client Secret | G******************OO |
| Scope | openid correo electrónico perfil |
| Signing Algorithm | RS256 |
| Storage Label Claim | nombre_de_usuario_preferido |
| Storage Quota Claim | cuota_immich |
| Default Storage Quota (GiB) | 0 (0 para cuota ilimitada) |
| Button Text | Iniciar sesión con Google (opcional) |
| Auto Register | Habilitado (opcional) |
| Auto Launch | Habilitado |
| Mobile Redirect URI Override | Habilitado (requerido) |
| Mobile Redirect URI | https://example.immich.app/api/oauth/mobile-redirect |