SAML SSO

SnapOtter поддерживает SAML 2.0 для единого входа. Пользователи могут входить через внешнего поставщика удостоверений (Okta, Azure AD / Entra ID, Google Workspace или любой стандартный IdP SAML 2.0) вместо локальной аутентификации по имени пользователя и паролю.

Корпоративная функция

SAML SSO требует лицензии team или enterprise с функцией saml_sso. Если SAML_ENABLED=true задан без действительной лицензии, маршруты SAML молча пропускаются и записывается предупреждение.

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

• Работающий экземпляр SnapOtter, доступный по публичному URL
• EXTERNAL_URL установлен в этот публичный URL (например, https://photos.example.com)
• Лицензионный ключ team или enterprise с функцией saml_sso
• Доступ администратора к вашему поставщику удостоверений SAML

Быстрый старт

Добавьте эти переменные окружения в ваш docker-compose.yml:

services:
  snapotter:
    image: snapotter/snapotter:latest
    environment:
      EXTERNAL_URL: "https://photos.example.com"
      SNAPOTTER_LICENSE_KEY: "your-license-key"
      SAML_ENABLED: "true"
      SAML_IDP_SSO_URL: "https://idp.example.com/sso/saml"
      SAML_IDP_CERTIFICATE: |
        MIICpDCCAYwCCQDU+pQ4pHgSpDANBgkqhkiG9w0BAQsFADAUMRIw
        ...your IdP's signing certificate in PEM format...
        EAYHKoZIzj0CAQYFK4EEACIDYgAE

Перезапустите контейнер. На странице входа появляется кнопка «Sign in with SAML» (или метка, заданная в SAML_PROVIDER_NAME).

Справочник конфигурации

Переменная	По умолчанию	Описание
SAML_ENABLED	false	Включить вход через SAML.
SAML_IDP_SSO_URL		URL конечной точки SSO у IdP. Обязательно, когда SAML включён.
SAML_IDP_CERTIFICATE		Сертификат подписи X.509 у IdP в формате PEM (сам текст сертификата, а не путь к файлу). Обязательно, когда SAML включён.
EXTERNAL_URL		Публичный URL, по которому доступен SnapOtter. Обязательно, когда SAML включён.
SAML_ENTITY_ID	${EXTERNAL_URL}/api/auth/saml/metadata	SP Entity ID / Audience URI, отправляемый IdP.
SAML_CALLBACK_URL	${EXTERNAL_URL}/api/auth/saml/callback	URL Assertion Consumer Service (ACS).
SAML_AUTO_CREATE_USERS	true	Автоматически создавать локальную учётную запись пользователя при первом входе через SAML.
SAML_AUTO_LINK_USERS	false	Связать удостоверение SAML с существующим локальным пользователем, если адрес электронной почты совпадает.
SAML_DEFAULT_ROLE	user	Роль, назначаемая автоматически создаваемым пользователям SAML. Одна из admin, editor или user.
SAML_PROVIDER_NAME		Отображаемая метка для кнопки входа SAML на фронтенде (например, «Okta», «Azure AD»). Если пусто, на кнопке написано «SAML».
SAML_USERNAME_ATTRIBUTE		Атрибут утверждения SAML, используемый как имя пользователя. Если пусто, используется локальная часть email, затем NameID.
SAML_EMAIL_ATTRIBUTE	email	Атрибут утверждения SAML, используемый как адрес электронной почты пользователя.

Сервер отказывается запускаться, если SAML_ENABLED=true и отсутствует любая из трёх обязательных переменных (SAML_IDP_SSO_URL, SAML_IDP_CERTIFICATE, EXTERNAL_URL).

Замечания по безопасности

И wantAuthnResponseSigned, и wantAssertionsSigned жёстко заданы как true. SnapOtter отклоняет неподписанные или неправильно подписанные ответы SAML. Утверждения от доверенного IdP считаются подтверждёнными по электронной почте.

Поддерживается только вход, инициированный SP. SnapOtter не поддерживает вход, инициированный IdP (незапрошенный), или единый выход (SLO). Выход из SnapOtter не выполняет выход пользователя из IdP.

Метаданные и URL SP

Вашему IdP нужны три значения от SnapOtter:

Поле	Значение
ACS URL (Assertion Consumer Service)	${EXTERNAL_URL}/api/auth/saml/callback
Entity ID / Audience URI	${EXTERNAL_URL}/api/auth/saml/metadata
SP Metadata (XML)	GET ${EXTERNAL_URL}/api/auth/saml/metadata

Например, если EXTERNAL_URL равен https://photos.example.com:

• ACS URL: https://photos.example.com/api/auth/saml/callback
• Entity ID: https://photos.example.com/api/auth/saml/metadata
• Конечная точка метаданных: https://photos.example.com/api/auth/saml/metadata (возвращает XML)

Некоторые IdP могут импортировать URL метаданных SP напрямую, что автоматически заполняет ACS URL и Entity ID.

Настройка провайдера

Okta

1. В административной консоли Okta перейдите в Applications > Create App Integration.
2. Выберите SAML 2.0 и нажмите Next.
3. Задайте имя (например, «SnapOtter») и нажмите Next.
4. Настройте параметры SAML:
   • Single sign-on URL: Ваш ACS URL (например, https://photos.example.com/api/auth/saml/callback)
   • Audience URI (SP Entity ID): Ваш Entity ID (например, https://photos.example.com/api/auth/saml/metadata)
   • Name ID format: EmailAddress
   • Application username: Email
5. В разделе Attribute Statements добавьте email, сопоставленный с user.email.
6. Нажмите Next, затем Finish.
7. Перейдите на вкладку Sign On, нажмите View SAML setup instructions и скопируйте:
   • Identity Provider Single Sign-On URL в SAML_IDP_SSO_URL
   • X.509 Certificate в SAML_IDP_CERTIFICATE

Azure AD / Entra ID

1. В портале Azure перейдите в Microsoft Entra ID > Enterprise applications > New application.
2. Нажмите Create your own application, назовите его «SnapOtter» и выберите Integrate any other application you don't find in the gallery.
3. Перейдите в Single sign-on > SAML и нажмите Edit в разделе Basic SAML Configuration:
   • Identifier (Entity ID): Ваш Entity ID (например, https://photos.example.com/api/auth/saml/metadata)
   • Reply URL (ACS URL): Ваш ACS URL (например, https://photos.example.com/api/auth/saml/callback)
4. В разделе SAML Certificates скачайте Certificate (Base64).
5. В разделе Set up SnapOtter скопируйте Login URL.
6. Задайте SAML_IDP_SSO_URL равным Login URL, а SAML_IDP_CERTIFICATE равным содержимому скачанного сертификата.
7. Назначьте пользователей или группы приложению в разделе Users and groups.

Google Workspace

1. В консоли администратора Google перейдите в Apps > Web and mobile apps > Add app > Add custom SAML app.
2. Назовите приложение «SnapOtter» и нажмите Continue.
3. На странице Google Identity Provider details скопируйте SSO URL и скачайте Certificate. Нажмите Continue.
4. Настройте параметры поставщика услуг:
   • ACS URL: Ваш ACS URL (например, https://photos.example.com/api/auth/saml/callback)
   • Entity ID: Ваш Entity ID (например, https://photos.example.com/api/auth/saml/metadata)
   • Name ID format: EMAIL
   • Name ID: Basic Information > Primary email
5. Нажмите Continue, затем Finish.
6. Включите приложение (ON) для ваших организационных подразделений.
7. Задайте SAML_IDP_SSO_URL равным SSO URL из шага 3, а SAML_IDP_CERTIFICATE равным содержимому скачанного сертификата.

Универсальный IdP SAML 2.0

Для любого поставщика удостоверений, совместимого с SAML 2.0:

1. Создайте новое приложение SAML / поставщика услуг в вашем IdP.
2. Задайте ACS URL равным ${EXTERNAL_URL}/api/auth/saml/callback.
3. Задайте Entity ID / Audience равным ${EXTERNAL_URL}/api/auth/saml/metadata.
4. Настройте IdP на отправку электронной почты пользователя в атрибуте с именем email (или задайте SAML_EMAIL_ATTRIBUTE в соответствии с именем атрибута вашего IdP).
5. Скопируйте IdP SSO URL и сертификат подписи в SAML_IDP_SSO_URL и SAML_IDP_CERTIFICATE.

Провижининг пользователей

Автоматическое создание

Когда SAML_AUTO_CREATE_USERS равен true (по умолчанию), локальная учётная запись пользователя создаётся при первом входе кого-либо через SAML. Роль устанавливается в SAML_DEFAULT_ROLE.

Имя пользователя выводится в следующем порядке:

1. Значение атрибута утверждения, указанного в SAML_USERNAME_ATTRIBUTE (если задано и присутствует)
2. Локальная часть адреса электронной почты (всё до @)
3. SAML NameID

Если возникает конфликт имён пользователей, добавляется числовой суффикс (например, jane становится jane_2).

Автоматическое связывание

Когда SAML_AUTO_LINK_USERS равен true, SnapOtter связывает удостоверение SAML с существующей локальной учётной записью, если адреса электронной почты совпадают. Это полезно, когда у вас есть заранее созданные учётные записи пользователей и вы хотите, чтобы они начали использовать SSO без потери своих данных.

WARNING

Включайте автоматическое связывание, только если вы доверяете своему IdP SAML в проверке адресов электронной почты. Непроверенный адрес электронной почты от неправильно настроенного IdP может позволить кому-либо захватить учётную запись другого пользователя.

Сопоставление атрибутов

Поле SnapOtter	Источник	Конфигурация
Email	Атрибут утверждения	SAML_EMAIL_ATTRIBUTE (по умолчанию: email)
Username	Атрибут утверждения, email или NameID	SAML_USERNAME_ATTRIBUTE (см. порядок вывода выше)
External ID	NameID	Всегда SAML NameID, не настраивается

Принудительное применение SSO

Если вы хотите обязать всех пользователей входить через SAML (или OIDC) и заблокировать локальный вход по паролю, включите принудительное применение SSO:

1. Убедитесь, что корпоративная функция sso_enforcement лицензирована (доступна в планах team и enterprise).
2. В Admin Settings > Security включите SSO Enforcement.
3. Задайте break-glass username: это единственная локальная учётная запись, которая всё ещё может входить с паролем для экстренного доступа, если IdP недоступен.

Когда принудительное применение SSO активно, любая попытка локального входа (кроме break-glass пользователя) возвращает ошибку 403 с сообщением «Local password login is disabled. Please use SSO.»

TIP

Всегда настраивайте break-glass username перед включением принудительного применения SSO. Без него вы можете быть заблокированы в SnapOtter, если ваш IdP выйдет из строя.

Использование SAML вместе с OIDC

SAML и OIDC можно включить одновременно. Когда оба активны, страница входа показывает отдельные кнопки для каждого провайдера (с метками из SAML_PROVIDER_NAME и OIDC_PROVIDER_NAME). Пользователи могут входить любым методом.

Оба провайдера независимо используют одни и те же настройки автоматического создания, автоматического связывания и принудительного применения SSO: у каждого есть собственные переменные *_AUTO_CREATE_USERS, *_AUTO_LINK_USERS и *_DEFAULT_ROLE.

Устранение неполадок

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

Подпись ответа SAML или подпись утверждения не удалось проверить. Проверьте:

• Сертификат в SAML_IDP_CERTIFICATE совпадает с текущим сертификатом подписи в вашем IdP (сертификаты ротируются, поэтому проверьте срок действия)
• Сертификат в формате PEM (начинается с -----BEGIN CERTIFICATE-----)
• Сертификат представляет собой полный текст, а не путь к файлу
• ACS URL и Entity ID, настроенные в вашем IdP, точно совпадают со значениями SnapOtter (схема, хост, порт, путь)

Отсутствующие атрибуты

Если имена пользователей или адреса электронной почты пусты после входа, ваш IdP может не отправлять ожидаемые атрибуты. Проверьте:

• Ваш IdP настроен на передачу атрибута email (или того, что задано в SAML_EMAIL_ATTRIBUTE)
• Если используется SAML_USERNAME_ATTRIBUTE, убедитесь, что этот атрибут включён в утверждение
• Некоторые IdP требуют явной настройки сопоставления атрибутов перед передачей клеймов

Расхождение часов

Утверждения SAML включают временные условия (NotBefore, NotOnOrAfter). Если часы вашего сервера и часы IdP не синхронизированы, проверка утверждения завершается неудачей. Запустите NTP на обеих машинах, чтобы синхронизировать часы.

«SAML is enabled via env but saml_sso enterprise feature is not licensed»

Это предупреждение появляется в логах сервера, когда SAML_ENABLED=true, но лицензия не включает функцию saml_sso. Проверьте ваш лицензионный ключ и план. Функция saml_sso доступна в планах team и enterprise.

Вход перенаправляет обратно с ошибкой

Если нажатие кнопки входа SAML перенаправляет обратно на страницу входа с ошибкой, проверьте логи сервера для деталей. Частые причины:

• IdP SSO URL недоступен с сервера
• IdP отклонил запрос аутентификации (проверьте журналы аудита IdP)
• IdP вернул неподписанный ответ (SnapOtter требует, чтобы и ответ, и утверждение были подписаны)