Подробный гайд: Конфигурация SAML 2.0 вместо OIDC Этот гайд предназначен для администраторов и разработчиков, которые планируют перейти с OpenID Connect (OIDC) на SAML 2.0 или настроить SAML как основной метод SSO в корпоративной среде.

---

1. Краткое сравнение: почему SAML вместо OIDC?

Параметр	SAML 2.0	OIDC (OAuth 2.0 + JWT)
Формат данных	XML	JSON (JWT)
Протокол	SOAP/HTTP-Redirect & HTTP-POST	REST/HTTP + JSON
Основное использование	Enterprise, legacy-приложения, гос. сектор, AD/ADFS	Современные веб/мобильные приложения, API, SPA
Механизм SSO	Redirect/POST с SAMLResponse	Authorization Code Flow + ID Token
Атрибуты	Rich XML <AttributeStatement>	Claims в JWT (sub, email, groups и т.д.)
Сложность настройки	Выше (ручной маппинг, сертификаты, bindings)	Ниже (стандартизированный Discovery, библиотеки)

Когда выбирать SAML:

• Приложение поддерживает только SAML (например, старые ERP, CRM, гос. порталы)
• Корпоративные политики/комплаенс требуют SAML
• Требуется детальная передача ролей/атрибутов в формате, ожидаемом legacy-системой
• Интеграция с ADFS, некоторыми IdP, где OIDC ограничен или отключён

---

2. Архитектура и ключевые понятия SAML

Термин	Описание
IdP (Identity Provider)	Сервер, который аутентифицирует пользователя и выпускает Assertion (Keycloak, Azure AD, Okta, ADFS, OneLogin)
SP (Service Provider)	Приложение/сервис, запрашивающий аутентификацию
Entity ID / Issuer	Уникальный идентификатор IdP или SP (обычно URL или URN)
ACS URL (Assertion Consumer Service)	Эндпоинт SP, куда IdP отправляет SAMLResponse
SSO URL	Эндпоинт IdP, куда SP отправляет AuthnRequest
NameID	Основной идентификатор пользователя в assertion (email, persistent, transient)
Binding	Способ передачи: HTTP-Redirect (запрос) и HTTP-POST (ответ, рекомендуемый)
Metadata XML	Файл с настройками, сертификатами и эндпоинтами IdP/SP

---

3. Подготовка к миграции с OIDC на SAML

1. Соберите параметры приложения (SP):

• ACS URL (куда принимать SAMLResponse)
• Entity ID (Identifier приложения)
• Требуемые атрибуты (email, name, groups, role и т.д.)
• Формат NameID (обычно emailAddress или persistent)
• Требуется ли подпись assertion/response, шифрование, SLO

2. Убедитесь в наличии:

• Доступа к админ-панели IdP
• X.509 сертификата IdP (для валидации подписи)
• NTP-синхронизации на всех серверах (критично для NotBefore/NotOnOrAfter)
• Staging-окружения для тестов

План миграции:

• Настроить SAML параллельно с OIDC
• Протестировать на тестовых пользователях
• Переключить переключатель аутентификации в приложении
• Отключить OIDC после подтверждения стабильности

---

4. Пошаговая конфигурация

Шаг 1: Настройка на стороне IdP

1. Создайте новое приложение/интеграцию типа SAML 2.0.

2. Укажите:

• Entity ID / Audience URI = app.example.com/saml
• ACS URL / Reply URL = app.example.com/saml/acs
• SSO URL / Sign-on URL = app.example.com/login (опционально, для SP-initiated)

3. Сертификаты:

• Включите подпись assertion (обязательно)
• При необходимости включите шифрование assertion (укажите SP-сертификат)
• Скачайте/экспортируйте IdP X.509 сертификат (в формате PEM или DER)

4. Маппинг атрибутов (Claims / Mappers):

| Атрибут в SP | Формат в SAML | Пример маппинга | |--------------|---------------|-----------------| | NameID | urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress | user.email | | Email | schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress | user.email | | Groups/Roles | Кастомный namespace | user.groups | 5. Включите Single Logout (SLO) если требуется (укажите SLO URL IdP и SP).
6. Экспортируйте Metadata XML IdP (содержит Entity ID, SSO URL, сертификаты, bindings).

Шаг 2: Настройка на стороне SP (Приложения)

1. В панели администрирования приложения выберите Authentication: SAML 2.0.

2. Введите или импортируйте:

- IdP Metadata URL/XML или вручную:

• SSO URL (IdP endpoint, HTTP-POST)
• Entity ID / Issuer
• X.509 Certificate (IdP)

- SP параметры:

• Entity ID
• ACS URL

3. Настройте NameID Format согласно IdP.
4. Укажите Attribute Mapping (как входящие SAML-атрибуты маппятся на внутренние поля пользователя/роли).

5. Включите валидацию:

• AudienceRestriction
• Signature Validation (Assertion и/или Response)
• Clock Skew (обычно ±5 минут)

6. Сохраните и перезапустите сервис (если требуется).

Шаг 3: Обмен метаданными и сертификатами

• IdP → SP: Передайте IdP Metadata XML или загрузите его по URL в SP.
• SP → IdP: Если IdP поддерживает автоматический обмен, загрузите SP Metadata или укажите ACS/Entity ID вручную.
• Сертификаты: Убедитесь, что в SP импортирован актуальный IdP-сертификат. При ротации сертификатов загрузите новый заранее и включите режим dual-cert если поддерживается.

Шаг 4: Тестирование

1. Откройте приложение → нажмите "Войти через SSO" → должен произойти редирект на IdP.
2. Пройдите аутентификацию → редирект обратно на ACS URL.

3. Проверьте:

• Создание сессии в приложении
• Корректность маппинга атрибутов
• Отсутствие ошибок валидации подписи/аудитории

4. Используйте SAML Tracer (расширение браузера) или saml-decoder для инспекции SAMLResponse.
5. Протестируйте SLO (выход из приложения → выход из IdP).

---

5. Примеры настройки популярных IdP

Keycloak

Clients → Create → Client Protocol: saml
• Valid Redirect URIs: https://app.example.com/saml/acs
• Client Signature Required: ON
• Sign Documents: ON
• Keys → Import/Export → загрузить сертификат IdP
• Mappers → Add:
  - Name ID Mapper: Format = emailAddress, Value = user.email
  - User Property/Attribute: map groups, roles, etc.

Azure AD (Entra ID)

Enterprise Apps → New App → Non-gallery → SAML

• Basic SAML Configuration:

  Identifier: https://app.example.com/saml
  Reply URL (ACS): https://app.example.com/saml/acs

• Attributes & Claims:

  NameID: user.mail (format: emailAddress)
  Add custom claims для групп/ролей

• Download: Federation Metadata XML, Certificate (Base64)

Okta

Applications → Create App → SAML 2.0
• General Settings: ACS URL, Audience URI  
• Attribute Statements: email, groups, etc.  
• Sign On → View Setup Instructions → Metadata URL, Certificate  
• Assign users/groups

ADFS (Windows Server)

AD FS Management → Add Relying Party Trust
• Import metadata or manual → Identifier = Entity ID
• Endpoint: SAML POST binding → ACS URL
• Issuance Transform Rules: 
  - Send LDAP Attributes as Claims (mail → Email, Token-Groups → Groups)
  - Transform Incoming Claims → NameID
• Certificates → Verify signing cert

---

6. Безопасность и лучшие практики (2024–2026)

Практика	Описание
Подпись assertion	Обязательно. Используйте RSA-SHA256 или ECDSA. Откажитесь от SHA-1
Шифрование	Включайте, если assertion содержит чувствительные данные (PII, роли)
Binding	Используйте HTTP-POST для SAMLResponse. HTTP-Redirect только для запросов
Валидация Audience	SP должен строго проверять <AudienceRestriction>
Clock Sync	Разница часов >5 мин ломает валидацию NotBefore/NotOnOrAfter
Ротация сертификатов	Планируйте заранее. Поддерживайте 2 сертификата в метаданных, если возможно
Отключите слабый crypto	Запретите MD5, SHA-1, RSA < 2048 бит
Логи и мониторинг	Логируйте успешные/ошибочные assertion, но не храните полные XML в открытом виде

---

7. Устранение неполадок (Troubleshooting)

Ошибка	Возможная причина	Решение
Invalid Audience	Mismatch Entity ID в SP и IdP	Проверьте Identifier/Audience URI, убедитесь в точном совпадении (включая http:///https://)
Signature validation failed	Неверный/истёкший сертификат, рассинхрон часов, слабый алгоритм	Обновите сертификат IdP в SP, проверьте NTP, включите SHA-256
NameID missing	Не настроен маппинг NameID в IdP	Добавьте NameID Mapper с форматом emailAddress или persistent
Атрибуты не приходят	Неверный namespace, фильтр claims, SP не ожидает формат	Проверьте SAML Tracer, сравните с документацией SP, настройте AttributeStatement
Циклические редиректы	SP не принимает assertion, ACS URL неверен, конфликт методов аутентификации	Проверьте ACS URL, отключите OIDC/LDAP на время теста, включите debug-логи
Request expired	Большая задержка между IdP и SP, рассинхрон часов	Настройте NTP, увеличьте ClockSkew (временно, для диагностики)

Полезные инструменты:

• SAML Chrome Tracer - chrome.google.com/webstore/detail/saml-chrome-tracer/
• SAML Decoder - www.samldecoder.com/ (base64 → XML)
• openssl x509 -in cert.pem -text -noout (проверка сертификата)
• Логи IdP/SP с уровнем DEBUG для SAML-обмена

---

8. Чек-лист миграции с OIDC на SAML

• [ ] Собраны ACS URL, Entity ID, требуемые атрибуты приложения
• [ ] Создано SAML-приложение в IdP, настроены Endpoint'ы
• [ ] Сконфигурирован NameID и маппинг атрибутов
• [ ] Экспортирован IdP Metadata / X.509 сертификат
• [ ] Настроен SP: импорт метаданных, валидация подписи, audience, clock skew
• [ ] Протестировано в staging: SSO, атрибуты, роли, сессия
• [ ] Проверено SLO (если требуется)
• [ ] Настроены логи и мониторинг ошибок SAML
• [ ] Выполнена ротация сертификатов (план на 6–12 мес.)
• [ ] Отключён OIDC в production после подтверждения стабильности SAML

---

Заключение

Переход с OIDC на SAML требует более детальной ручной настройки, но обеспечивает совместимость с enterprise-экосистемами, legacy-приложениями и строгими политиками безопасности. Ключ к успеху: точное совпадение Entity ID/ACS, корректный маппинг NameID и атрибутов, строгая валидация подписи и синхронизация времени.