Настройка ONLYOFFICE SP и AD FS IdP

Введение

Технология единого входа (англ. Single Sign-On или SSO) — технология, которая позволяет пользователям осуществлять вход в систему только один раз, а затем получать доступ ко множеству приложений/сервисов без повторной аутентификации.

Если на веб-портале существует несколько обширных независимых разделов (форум, чат, блоги и так далее), пройдя процедуру аутентификации в одном из сервисов, пользователь автоматически получает доступ ко всем остальным, что избавляет его от многократного ввода данных своей учетной записи.

SSO — это всегда совместная работа двух приложений: поставщика учетных записей и поставщика сервиса (англ. Identity Provider и Service Provider, далее по тексту сокращенно «IdP» и «SP»). ONLYOFFICE SSO реализует только SP. В качестве IdP может выступать множество различных провайдеров, но в этой статье мы рассмотрим реализацию Active Directory Federation Services (AD FS).

примечание

Если вы хотите использовать SSO при подключении десктопных редакторов ONLYOFFICE к ONLYOFFICE Workspace, отключите Приватные комнаты в Панели управления.

Системные требования

Системные требования включают в себя следующее программное обеспечение, которое было протестировано и корректно работает с ONLYOFFICE SSO:

• Windows Server 2008 R2, Windows Server 2016;
• AD FS версии 3.0 или более поздней версии.

Подготовка ONLYOFFICE Workspace для настройки SSO

1. Установите ONLYOFFICE Workspace для Docker или любую более позднюю версию с поддержкой SSO (AD FS поддерживается, начиная с версии 9.5 Сервера совместной работы).
2. Привяжите доменное имя, например, myportal-address.com.
3. На портале перейдите в Панель управления > HTTPS, создайте и примените сертификат letsencrypt для шифрования трафика (для включения HTTPS на портале).

Подготовка AD FS для настройки SSO

1. Установите последнюю версию AD DS (Active Directory Domain Service) со всеми официальными обновлениями и исправлениями.

2. Установите последнюю версию AD FS со всеми официальными обновлениями и исправлениями.

   Для развертывания AD FS с нуля можно воспользоваться следующей инструкцией.

3. Проверьте, что ссылка на файл метаданных AD FS доступна публично. Для этого:

   1. В консоли Диспетчер сервера откройте Tools (Инструменты) > AD FS Management (Управление AD FS),

   2. Перейдите в AD FS \ Service \ Endpoints (AD FS \ Служба \ Конечные точки),

   3. Найдите в таблице строку с типом Federation Metadata (Метаданные федерации). Ссылка на файл метаданных IdP формируется по следующей схеме:

      https://{ad-fs-domain}/{path-to-FederationMetadata.xml}

      

      Можно также воспользоваться следующей командой PowerShell:

      PS C:\Users\Administrator> (Get-ADFSEndpoint | Where {$_.Protocol -eq "FederationMetadata" -or $_.Protocol -eq "Federation Metadata"}).FullUrl.ToString()

      В результате вы должны получить ссылку следующего вида:

      https://onlyofficevm.northeurope.cloudapp.azure.com/FederationMetadata/2007-06/FederationMetadata.xml

   4. Для проверки, что AD FS стартовал корректно, откройте ссылку в браузере. Должен отобразиться или скачаться XML-файл. Скопируйте ссылку на XML-файл метаданных: она потребуется на следующем шаге.

Настройка ONLYOFFICE SP

1. Убедитесь, что вы зашли в качестве администратора в Панель управления ONLYOFFICE, и щелкните вкладку SSO в разделе НАСТРОЙКИ ПОРТАЛА на левой боковой панели.

   примечание

   Вы можете зарегистрировать только одного корпоративного поставщика учетных записей для вашей организации на портале ONLYOFFICE.

   

2. Включите SSO, используя переключатель Включить аутентификацию с помощью технологии единого входа. Ссылку, скопированную из AD FS, вставьте в поле URL-адрес XML-файла метаданных IdP.

   

   Нажмите кнопку со стрелкой вверх, чтобы загрузить метаданные IdP. Форма Настройки поставщика сервиса ONLYOFFICE будет автоматически заполнена данными из AD FS IdP.

3. В поле Пользовательская надпись для кнопки входа вы можете ввести любой текст вместо стандартного (Single Sign-on). Этот текст будет отображаться на кнопке для входа с помощью сервиса Single Sign-on на странице аутентификации ONLYOFFICE.

   

4. В селекторе Формат NameID выберите следующее значение: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.

   

5. В разделе Открытые сертификаты поставщика учетных записей \ Дополнительные параметры уберите галочку Проверять подпись ответов выхода, так как AD FS не требует этого по умолчанию.

   

6. Добавьте сертификаты в раздел Сертификаты поставщика сервиса. Можно сгенерировать самоподписанные сертификаты или добавить любые другие.

   примечание

   В окне Новый сертификат переключите селектор Использовать для на signing and encrypt, так как AD FS IdP автоматически настроен на проверку цифровой подписи и шифрование данных.

   

   Должно получиться примерно так:

   

7. В разделе Сертификаты поставщика сервиса \ Дополнительные параметры уберите галочку Подписывать ответы выхода, так как AD FS не требует этого по умолчанию.

   

   примечание

   Форму Сопоставление атрибутов настраивать не нужно. В разделе Дополнительные параметры можно включить настройку Скрыть страницу аутентификации, чтобы скрыть страницу аутентификации по умолчанию и автоматически перенаправлять на сервис SSO.

   Важно

   Если вам необходимо восстановить страницу аутентификации по умолчанию (чтобы иметь доступ к порталу, если ваш сервер IdP выйдет из строя), можно добавить ключ /Auth.aspx?skipssoredirect=true после доменного имени портала в адресной строке браузера.

8. Нажмите Сохранить. Должен открыться раздел Метаданные поставщика сервиса ONLYOFFICE.

   

   Проверьте, что настройки доступны публично, нажав СКАЧАТЬ XML-ФАЙЛ МЕТАДАННЫХ ПОСТАВЩИКА СЕРВИСА. Должно отобразиться содержимое XML-файла.

9. Скопируйте ссылку на файл метаданных ONLYOFFICE SP из поля Идентификатор сущности поставщика сервиса (ссылка на XML-файл метаданных) и перейдите на машину, где установлен AD FS.

   

Настройка AD FS IdP

1. Включите строгую проверку подлинности для приложений .NET.

   Приложения .NET Framework 3.5/4.0/4.5.x можно переключить на протокол по умолчанию TLS 1.2, включив раздел реестра SchUseStrongCrypto. Этот раздел реестра принудительно заставит приложения .NET использовать TLS 1.2.

   примечание

   Для AD FS на Windows Server 2016 и Windows Server 2012 R2 используйте ключ .NET Framework 4.0/4.5.x: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft.NETFramework\v4.0.30319

   Для .NET Framework 3.5 используйте следующий раздел реестра:

   [HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\v2.0.50727] "SchUseStrongCrypto"=dword:00000001

   Для .NET Framework 4.0/4.5.x используйте следующий раздел реестра:

   HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319 "SchUseStrongCrypto"=dword:00000001

   

   Можно также воспользоваться следующей командой PowerShell:

   New-ItemProperty -path 'HKLM:\SOFTWARE\Microsoft\.NetFramework\v4.0.30319' -name 'SchUseStrongCrypto' -value '1' -PropertyType 'DWord' -Force | Out-Null

   Для получения дополнительной информации обратитесь к этой статье.

2. В консоли Диспетчер сервера откройте Tools (Инструменты) > AD FS Management (Управление AD FS),

   

3. В панели управления AD FS выберите Trust Relationships > Relying Party Trusts (Отношения доверия > Отношения доверия проверяющей стороны). Выберите команду Add Relying Party Trust... (Добавить отношение доверия проверяющей стороны...) справа. Откроется Мастер добавления отношений доверия проверяющей стороны,

   

4. В окне мастера выберите переключатель Import data about the relying party published online or on a local network (Импорт данных о проверяющей стороне, опубликованных в Интернете или локальной сети), вставьте скопированную ранее ссылку на файл метаданных ONLYOFFICE SP в поле Federation metadata address (host name or URL) (Адрес метаданных федерации (имя узла или URL-адрес)) и нажмите кнопку Next (Далее),

   

5. В поле Display name (Отображаемое имя) укажите любое имя и нажмите кнопку Next (Далее),

   

6. Выберите опцию I do not want to configure multi-factor authentication settings for this relying party trust at this time (Сейчас не настраивать параметры для этого отношения доверия с проверяющей стороной) и нажмите кнопку Next (Далее),

   

7. Выберите опцию Permit all users to access this relying party (Разрешить доступ к этой проверяющей стороне всем пользователям) и нажмите кнопку Next (Далее),

   

8. Проверьте полученные настройки и нажмите кнопку Next (Далее),

   

9. Оставьте опцию, выбранную по умолчанию, без изменений и нажмите кнопку Close (Закрыть),

   

10. Откроется новое окно. На вкладке Issuance Transform Rules (Правила преобразования выдачи) нажмите кнопку Add Rule... (Добавить правило...),

    

11. Выберите опцию Send LDAP Attributes as Claims (Отправка атрибутов LDAP как утверждений) из списка Claim rule template (Шаблон правила утверждения) и нажмите кнопку Next (Далее),

    

12. Напишите любое имя в поле Claim rule name (Имя правила утверждения). Выберите опцию Active Directory из списка Attribute store (Хранилище атрибутов) и заполните форму Mapping of LDAP attributes to outgoing claim types (Сопоставление атрибутов LDAP типам исходящих утверждений) согласно приведенной ниже таблице. Когда все будет готово, нажмите Finish (Завершить).

    LDAP Attribute (Атрибут LDAP)	Outgoing Claim Type (Тип исходящего утверждения)
    Given-Name	givenName
    Surname	sn
    E-Mail-Addresses	mail
    Telephone-Number	mobile
    Title	title
    physicalDeliveryOfficeName	l

    

13. В окне Edit Claim Rules (Изменить правила утверждений) снова нажмите кнопку Add Rule... (Добавить правило...), выберите опцию Transform an Incoming Claim (Преобразование входящего утверждения) из списка Claim rule template (Шаблон правила утверждения) и нажмите кнопку Next (Далее),

    

14. Напишите любое имя в поле Claim rule name (Имя правила утверждения) и выберите следующие параметры из списков:

    • Incoming claim type (Тип входящего утверждения): mail,
    • Outgoing claim type (Тип исходящего утверждения): Name ID,
    • Outgoing name ID format (Формат ИД исходящего имени): Email

    

    Когда все будет готово, нажмите кнопку Finish (Завершить).

    Должно получиться примерно так:

    

    Если не будет работать выход (logout) из AD FS, рекомендуется добавить Custom Claim Rule (настраиваемое правило утверждения), заменив {portal-domain} на домен своего SP, а {ad-fs-domain} на домен IdP:

    c:[Type == "mail"]
     => 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", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/namequalifier"] = "http://{ad-fs-domain}/adfs/services/trust", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/spnamequalifier"] = "https://{portal-domain}/sso/metadata");

    

15. Нажмите OK.

16. Для работы SSO из интранета включите опцию Forms Authentication (Проверка подлинности с помощью форм) в окне Edit Global Authentication Policy (Изменить глобальную политику проверки подлинности), вызываемом через контекстное меню AD FS / Authentication Policies (AD FS / Политики проверки подлинности),

    

17. Откройте свойства созданной проверяющей стороны и перейдите на вкладку Advanced (Дополнительные параметры),

    

    Выберите опцию SHA-1 в списке Secure hash algorithm (Алгоритм SHA).

    

Проверка работы ONLYOFFICE SP и AD FS IdP

Вход в ONLYOFFICE на стороне SP

1. Перейдите на страницу аутентификации ONLYOFFICE (например, https://myportal-address.com/auth.aspx).

2. Нажмите на кнопку Single sign-on (название кнопки может отличаться, если вы указали свой вариант при настройке ONLYOFFICE SP). Если этой кнопки нет, значит, SSO не включен.

   

3. Если все настроено верно в SP и IdP, вы будете перенаправлены на форму входа в AD FS IdP:

   

4. Введите логин и пароль учетной записи в AD FS IdP и нажмите кнопку Sign in.

5. Если учетные данные указаны правильно, вы будете перенаправлены на главную страницу портала. Учетная запись пользователя будет создана автоматически, если ее еще нет, или обновлена, если данные были изменены в IdP.

Профили пользователей, добавленных с помощью SSO-аутентификации

Возможность редактирования профилей пользователей, созданных с помощью SSO-аутентификации, ограничена. Поля профиля пользователя, полученные из IdP, заблокированы для редактирования (а именно: Имя, Фамилия, Email, Должность и Местоположение). Эти поля можно отредактировать только из вашей учетной записи в IdP.

На следующем изображении показано меню «Действия» для пользователя SSO:

На следующем изображении показан профиль пользователя SSO, открытый на редактирование:

Пользователи, созданные с помощью SSO-аутентификации, отмечены в списке пользователей значком SSO для администраторов портала: