Интеграция SAML + AD FS

Пошаговая инструкция по интеграции YouGile с Active Directory Federation Services по протоколу SAML 2.0.

Требования

• Windows Server 2016+ с ролью AD DS (контроллер домена)
• Развёрнутый AD FS с HTTPS-доступом
• YouGile версии 2.5+ с HTTPS. Инструкция по настройке HTTPS
• Заполненный атрибут Email у пользователей в Active Directory

1. Проверка работоспособности AD FS

1.1 Включите страницу тестирования

Set-AdfsProperties -EnableIdpInitiatedSignOnPage $true

1.2 Проверьте в браузере

• Страница входа: https://adfs.example.com/adfs/ls/IdpInitiatedSignOn.aspx — должна отобразиться форма входа, после авторизации — сообщение "You are signed in"
• Метаданные: https://adfs.example.com/FederationMetadata/2007-06/FederationMetadata.xml — должен открыться XML-файл

2. Подготовка пользователей в Active Directory

Убедитесь, что у пользователей заполнен атрибут Email:

# Проверка
Get-ADUser -Identity username -Properties EmailAddress

# Установка email
Set-ADUser -Identity username -EmailAddress "username@example.com"

3. Создание Relying Party Trust

3.1 Создание через мастер

1. Откройте AD FS Management
2. Перейдите в Relying Party Trusts
3. Нажмите Add Relying Party Trust
4. Выберите Claims aware => Start
5. Выберите Enter data about the relying party manually
6. Display name: YouGile
7. На шаге Configure URL выберите Enable support for the SAML 2.0 WebSSO protocol и укажите ACS URL:

https://your-yourgile-domain/data/saml/auth-response

8. На шаге Configure Identifiers добавьте:

yougile-box

9. Завершите мастер

3.2 Отключение шифрования

YouGile не поддерживает зашифрованные SAML-ответы. Отключите шифрование (при необходимости, замените YouGile на ваш Display name из шага 6 пункта 3.1):

Set-AdfsRelyingPartyTrust -TargetName "YouGile" -EncryptClaims $false

4. Настройка Claim Rules

Настройте правила выдачи атрибутов через PowerShell (порядок правил важен). Для настройки правил передачи просто скопируйте инструкции ниже и вставьте в PowerShell (при необходимости, замените YouGile на ваш Display name из шага 6 пункта 3.1):

$rules = @'
@RuleTemplate = "LdapClaims"
@RuleName = "LDAP Attributes"
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
=> issue(store = "Active Directory", types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/displayname"), query = ";mail,displayName;{0}", param = c.Value);

@RuleName = "Transform Email to NameID"
c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"]
=> issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress");

@RuleName = "Display Name"
c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/displayname"]
=> issue(Type = "urn:oid:2.5.4.42", Value = c.Value);
'@

Set-AdfsRelyingPartyTrust -TargetName "YouGile" -IssuanceTransformRules $rules

Важно:

• Правило LDAP Attributes должно идти первым. Оно извлекает email и Display Name из Active Directory. Последующие правила преобразуют эти данные. Если порядок нарушен, AD FS вернёт ошибку InvalidNameIDPolicy.

После настройки перезапустите службу:

Restart-Service adfssrv

5. Экспорт сертификата AD FS

Для настройки YouGile понадобится публичный сертификат Token-Signing:

$cert = Get-AdfsCertificate -CertificateType Token-Signing
$b64 = [Convert]::ToBase64String($cert.Certificate.RawData)
$b64 | Out-File C:\adfs-cert.txt

Откройте файл и скопируйте содержимое (одна строка Base64 без заголовков).

Либо скопируйте сертификат напрямую в буфер обмена на Windows-сервере:

$cert = Get-AdfsCertificate -CertificateType Token-Signing
[Convert]::ToBase64String($cert.Certificate.RawData) | Set-Clipboard

И вставьте в conf.json вручную — это самый надёжный способ.

6. Настройка YouGile

Откройте conf.json на сервере YouGile и добавьте секцию saml:

"saml": {
  "allowOnlySaml": true,
  "entryPoint": "https://adfs.example.com/adfs/ls/",
  "issuer": "yougile-box",
  "audience": "yougile-box",
  "idpCert": "MIIE2DCCAsCgAwIBAgIQ...вставьте_полный_сертификат_в_одну_строку...",
  "wantAssertionsSigned": true,
  "wantAuthnResponseSigned": false
}

Параметры:

Параметр	Описание
allowOnlySaml	true — только SAML-авторизация
entryPoint	URL SAML-endpoint AD FS
issuer	Идентификатор SP (должен совпадать с Relying Party Identifier)
audience	Должен совпадать с issuer
idpCert	Публичный сертификат Token-Signing AD FS (Base64, одна строка)
wantAssertionsSigned	Требовать подпись assertion
wantAuthnResponseSigned	Подпись всего ответа (опционально)

Перезапустите YouGile после сохранения.

7. Проверка интеграции

1. Откройте веб-интерфейс YouGile
2. Нажмите Войти через SAML
3. Вы будете перенаправлены на страницу входа AD FS
4. Введите доменные учётные данные
5. После успешной аутентификации — возврат в YouGile

Решение типичных проблем

Ошибка	Причина	Решение
Get-_InternalDomainJoinInformation not recognized	Повреждённый модуль AD FS	Переустановить роль AD FS
Federation service name does not match	Wildcard указан как Federation Service Name	Указать конкретное имя (например adfs.example.com)
MSIS3200: No AssertionConsumerService	ACS URL в AD FS не совпадает с запросом YouGile	Исправить Endpoint в Relying Party Trust на фактический URL из логов
InvalidNameIDPolicy	Нет правила извлечения email или неправильный порядок правил	Добавить LDAP Attributes правило первым, заполнить email у пользователей AD
No decryption key for encrypted SAML response	AD FS шифрует ответ	Set-AdfsRelyingPartyTrust -TargetName "YouGile" -EncryptClaims $false