Перейти к основному содержимому

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

Раздел описывает настройку аутентификации пользователей через Active Directory Federation Services (AD FS) по протоколу SAML 2.0 для коробочной версиии YouGile.

Интеграция позволяет использовать корпоративные доменные учетные записи и централизованно управлять доступом. В YouGile передаются:

  • уникальный идентификатор пользователя (NameID)
  • имя и фамилия
  • доменный логин / UPN
  • группа / роль

Пользователи создаются и аутентифицируются во внешнем IdP (AD FS). В YouGile не требуется ручное создание учётных записей.

Требования к окружению​

Перед началом проверьте, что выполнены условия:

  • развернут AD FS (Windows Server 2016+)
  • доступен HTTPS-эндпоинт AD FS: https://<fqdn>/adfs/ls/
  • сервер YouGile доступен по HTTPS. Инструкция по настройке HTTPS
  • сертификат AD FS валиден
  • версия YouGile поддерживает SAML-аутентификацию (поддержка осуществляется с версии 2.5)

Настройка конфигурации SAML в YouGile​

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

"saml": {
  "allowOnlySaml": true,
  "entryPoint": "https://adfs.yougile/adfs/ls/",
  "issuer": "yougile-box",
  "audience": "yougile-box",
  "idpCert": "cert",
  "wantAssertionsSigned": true,
  "wantAuthnResponseSigned": false
},

Где параметры указывают на следующие пункты:

  • allowOnlySaml в значении true разрешает только SAML-авторизацию
  • entryPoint указывает полный путь до SAML endpoint AD FS
  • issuer идентификатор SP
  • audience значение должно совпадать со значением в настройках клиента
  • idpCert публичный сертификат AD FS
  • wantAssertionsSigned требование подписи assertion
  • wantAuthnResponseSigned подпись всего ответа (опционально)

Создание Relying Party Trust в AD FS​

  1. Откройте AD FS Management
  2. Перейдите в раздел Relying Party Trusts
  3. Нажмите Add Relying Party Trust
  4. Выберите режим Claims aware
  5. Нажмите Start

Укажите следующие параметры:

  • Display name: YouGile
  • Relying Party Identifier: yougile-box
  • Relying Party Trust Identifier (Audience): yougile-box

На шаге настройки конечной точки ACS добавьте:

https://your-yourgile-domain/saml/acs

После этого завершите мастер создания доверия.

Настройка Claim Rules (передачи атрибутов)​

Далее необходимо настроить правила выдачи атрибутов (Issuance Transform Rules).

Нажмите: Edit Claim Issuance Policy - Add Rule

Выберите шаблон: Send Claims Using a Custom Rule

  • Передайте идентификатор пользователя: Rule name: 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
",
Value = c.Value,
Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format
"]
= "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
);

Данное правило передаст email пользователя как NameID, уникальный идентификатор учетной записи YouGile.

  • Передайте имя пользователя, First Name / Display Name: Rule name: name
c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"]
=> issue(
Type = "urn:oid:2.5.4.42",
Value = c.Value
);

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

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

По итогам настройки:

  • пользователь создается автоматически
  • корректно подставляется имя и фамилия
  • корректно передаётся email / NameID