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, що використовується як ім'я користувача. Якщо порожнє, повертається до локальної частини електронної пошти, потім до 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 (небажаний), чи Single Logout (SLO). Вихід зі SnapOtter не виводить користувача з IdP.

Метадані SP та URL

Вашому 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)
Ім'я користувача	Атрибут твердження, 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 вимагає, щоб і відповідь, і твердження були підписані)