Аутентификация OAuth

На этой странице содержится информация о использовании OAuth в Immich.

совет

Не можете установить app.immich:///oauth-callback как допустимый URI перенаправления? См. Mobile Redirect URI для альтернативного решения.

Обзор

Immich поддерживает аутентификацию через сторонние сервисы с использованием OpenID Connect (OIDC), слоя идентификации, построенного поверх OAuth2. OIDC поддерживается большинством провайдеров идентификации, включая:

Предварительные условия

Прежде чем включить OAuth в Immich, необходимо настроить новое клиентское приложение на сервере сторонней аутентификации. Хотя детали настройки могут различаться в зависимости от провайдера, общий подход должен быть одинаковым.

Создайте новое (Client) приложение
1. Тип Provider должен быть OpenID Connect или OAuth2
2. Тип Client должен быть Confidential
3. Тип Application должен быть Web
4. Тип Grant должен быть Authorization Code
Настройте Redirect URIs/Origins

Sign-in redirect URIs должны включать:
- 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 через страницу настроек Администрирования, доступную в вебе (Администрирование -> Настройки).

Настройка	Тип	Значение по умолчанию	Описание
Включено	boolean	false	Включить/выключить OAuth
URL издателя	URL	(required)	Обязательно. URL для автоматического обнаружения клиента (из предыдущего шага)
ID клиента	string	(required)	Обязательно. ID клиента (из предыдущего шага)
Секрет клиента	string	(required)	Обязательно. Секрет клиента (из предыдущего шага)
Scope	string	openid email profile	Полный список доступов для отправки с запросом (разделенный пробелами)
Алгоритм подписи	string	RS256	Алгоритм, используемый для подписи токена id (например: RS256, HS256)
Требование для метки хранилища	string	preferred_username	Сопоставление с требованием для метки хранилища пользователя¹
Требование для роли	string	immich_role	Сопоставление с требованием для роли пользователя. (должно возвращать "user" или "admin")¹
Требование для квоты хранилища	string	immich_quota	Сопоставление с требованием для хранилища пользователя¹
Квота хранилища по умолчанию (ГиБ)	number	0	Квота по умолчанию для пользователя без требования квоты (Введите 0 для безлимитной квоты)
Текст кнопки	string	Login with OAuth	Текст кнопки OAuth на вебе
Автоматическая регистрация	boolean	true	При включении автоматически регистрирует пользователя при первом входе
Авто запуск	boolean	false	При включении автоматически пропускает страницу входа и начинает процесс входа через OAuth
Переопределение Mobile Redirect URI	URL	(empty)	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 является необязательной и будет автоматически добавлена при обнаружении.

Авто запуск

Когда функция авто запуска включена, страница входа автоматически перенаправляет пользователя на URL авторизации OAuth для входа через OAuth. Чтобы снова получить доступ к экрану входа, используйте кнопку "Назад" в браузере или перейдите непосредственно на /auth/login?autoLaunch=0. Авто запуск может быть включен также на основе запроса, перейдя на /auth/login?authLaunch=1, это может быть полезно в ситуациях, когда Immich вызывается, например, из Nextcloud с использованием приложения External sites и приложения oidc, чтобы предоставить пользователям возможность взаимодействовать с авторизованной инстанцией Immich.

Mobile Redirect URI

URI перенаправления для мобильного приложения — app.immich:///oauth-callback, который представляет собой Custom Scheme. Если пользовательская схема является недопустимым URI перенаправления для вашего провайдера OAuth, вы можете обойти это, выполнив следующее:

Настройте http(s)-endpoint для пересылки запросов на app.immich:///oauth-callback
Внесите новый endpoint в белый список как допустимый URI перенаправления с вашим провайдером.
Укажите новый endpoint как Переопределение Mobile Redirect URI в настройках OAuth.

С этими шагами вы сможете использовать OAuth из мобильного приложения без URI перенаправления с пользовательской схемой.

информация

Immich имеет маршрут (/api/oauth/mobile-redirect), который уже настроен для пересылки запросов на app.immich:///oauth-callback и может быть использован для шага 1.

Пример настройки

Пример для Authentik

Вот пример настройки OAuth для Authentik:

Настройка авторизованных URI перенаправления (Authentik OAuth2/OpenID Provider)

URI перенаправления, авторизованные Authentik

Настройка OAuth в Immich System Settings

Настройка	Значение
URL издателя	`https://example.immich.app/application/o/immich/.well-known/openid-configuration`
ID клиента	AFCj2rM1f4rps***********lCLEum6hH9...
Секрет клиента	0v89FXkQOWO***************************mprbvXD549HH6s1iw...
Scope	openid email profile
Алгоритм подписи	RS256
Требование для метки хранилища	preferred_username
Требование для квоты хранилища	immich_quota
Квота хранилища по умолчанию (ГиБ)	0 (0 для неограниченной квоты)
Текст кнопки	Войти с Authentik (опционально)
Автоматическая регистрация	Включено (опционально)
Авто запуск	Включено (опционально)
Переопределение Mobile Redirect URI	Отключено
Mobile Redirect URI

Пример для Google

Вот пример настройки OAuth для Google:

Настройка авторизованных URI перенаправления (Google Console)

URI перенаправления, авторизованные Google

Настройка OAuth в Immich System Settings

Настройка	Значение
URL издателя	`https://accounts.google.com`
ID клиента	7******************************vuls.apps.googleusercontent.com
Client Secret	G********************OO
Scope	openid email profile
Signing Algorithm	RS256
Storage Label Claim	preferred_username
Storage Quota Claim	immich_quota
Default Storage Quota (GiB)	0 (0 для неограниченной квоты)
Button Text	Войти с помощью Google (необязательно)
Auto Register	Включено (необязательно)
Auto Launch	Включено
Mobile Redirect URI Override	Включено (обязательно)
Mobile Redirect URI	`https://example.immich.app/api/oauth/mobile-redirect`

Обзор​

Предварительные условия​

Включение OAuth​

Авто запуск​

Mobile Redirect URI​

Пример настройки​

Пример для Authentik​

Пример для Google​