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

SAML ADFS

к сведению

Time поддерживает стандарт SAML (Security Assertion Markup Language) для различных провайдеров авторизации.

Ниже приведены шаги по настройке SAML 2.0 с помощью Microsoft ADFS для Time и Microsoft Windows Server.

Требования​

  • Инсталляция Active Directory, в которой все пользователи имеют следующие атрибуты:

    • электронная почта (email)
    • имя учётной записи (username)
    • имя пользователя (first name)
    • фамилия пользователя (last name)

  • Microsoft Server версии не ниже 2016. Скриншоты, используемые в этом руководстве, сделаны в Microsoft Server 2016R2, но для других версий действия должны быть аналогичными.

  • SSL-сертификат для подписи вашей страницы входа в ADFS.

  • ADFS установлена на вашем Microsoft Server. Вы можете найти подробное руководство по развертыванию и настройке ADFS в этой статье.

Подготовка​

Перед началом настройки необходимо сгенерировать сертификат и приватный ключ.

Создайте скрипт (например, с именем gen-cert.sh):

#!/bin/bash

umask 077

CERT_NAME_PUBLIC="saml-public"
CERT_NAME_PRIVATE="saml-private"

openssl req \
    -x509 \
    -days 3650 \
    -nodes \
    -newkey rsa:4096 \
    -keyout "${CERT_NAME_PRIVATE}.key" \
    -out "${CERT_NAME_PUBLIC}.crt" \
    -subj "/C=${CRT_C:-"RU"}/L=${CRT_L:-"Moscow"}/O=${CRT_O:-"OnPremise"}/OU=${CRT_OU:-"Time"}/CN=${CRT_CN:-"time.example.ru"}" \
    -addext "basicConstraints=critical,CA:true,pathlen:0" \
    -addext "subjectAltName=${CRT_SAN:-"IP.1:192.168.0.1,IP.2:127.0.0.1"}"

и сделайте его исполняемым:

chmod +x gen-cert.sh

Скрипт поддерживает параметры:

  • CRT_C (Country) — двухбуквенный код страны (по умолчанию RU)
  • CRT_L (Location) — локация (по умолчанию Moscow)
  • CRT_O (Organization) — название организации (по умолчанию OnPremise)
  • CRT_OU (Organizational Unit) — организационная единица (по умолчанию Time)
  • CRT_CN (Common Name) — общее название объекта (по умолчанию time.example.ru)
  • CRT_SAN (Subject Alternative Name) — альтернативное имя субъекта является расширением к X.509, которое позволяет связывать различные значения с сертификатом безопасности (по умолчанию IP.1:192.168.0.1,IP.2:127.0.0.1)

Пример генерации ключевой пары:

CRT_C="RU" CRT_L="Moscow" CRT_O="MyOrg" CRT_OU="SomeUnit" CRT_CN="time.my-domain.com" CRT_SAN="IP.1:172.16.0.1"  ./gen-cert.sh

В результате будет сгенерирован сертификат (saml-public.crt) и приватный ключ (saml-private.crt).

Настройка ADFS​

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

  1. Откройте ADFS console, и выберите Service, затем выберите Endpoints. В столбце Type найдите SAML 2.0/WS-Federation и запишите значение столбца URL Path.

    • Если вы выбрали значения по умолчанию для установки, это будет /adfs/ls.

  2. Откройте оснастку управления ADFS, затем выберите AD FS → Relying Party Trusts → Add Relying Party Trust на правой боковой панели. Вы также можете щелкнуть правой кнопкой мыши на пункте Relying Party Trusts, затем выбрать Add Relying Party Trust в контекстном меню.

    Add Relying Party Trust

  3. На экране приветствия мастера настройки выберите Claims aware, затем выберите Start.

    Claims aware

  4. На экране Select Data Source screen выберите Enter data about the relying party manually.

    Enter data

  5. На экране Specify Display Name введите отображаемое имя (например, Time). Опционально можно добавить примечание.

    Specify Display Name

  6. На экране Configure Certificate оставьте параметры сертификата в значениях по умолчанию.

    Configure Certificate

  7. Рекомендуется настроить шифрование для вашего SAML-соединения. Для этого выберите Browse, затем загрузите публичный сертификат поставщика услуг, который был сгенерирован на этапе Подготовка.

    Configure Encryption

  8. На экране Configure URL выберите Enable Support for the SAML 2.0 WebSSO protocol, затем введите SAML 2.0 SSO service URL в следующем формате: https://<time-url>/login/sso/saml, где <time-url> — должен соответствовать вашему URL-адресу Time.

    Configure URL

  9. На экране Configure Identifiers введите Relying party trust identifier — это необходимо для идентификации запрашиваемых клеймов (claims).

    • Формат Relying party trust identifier должен быть https://<time-url>/login/sso/saml, где <time-url> соответствует вашему URL-адресу Time. Эта опция должна совпадать со строкой Service Provider Identifier.

    Configure Identifiers

    • Для получения дополнительной информации об "Relying party trust identifier" и о том, как применяется сопоставление префиксов, смотрите в этой документации.
к сведению

Необходимо использовать именно HTTPS, потому что SAML не будет работать на HTTP.

Нажмите Add, затем Next.

  1. На экране Choose Access Control Policy выберите политику контроля доступа, подходящую для вашего окружения. В этом руководстве предполагается, что значения по умолчанию Permit everyone и флажок I do not want to configure [...] снят.

    Choose Access Control Policy

  2. На экране Ready to Add Trust проверьте свои настройки.

    Ready to Add Trust

  3. На экране Finish выберите Configure claims issuance policy for this application для этого приложения, затем нажмите Close.

    Finish

Создание claims rules​

  1. На вкладке Issuance Transform Rules редактора Claim Rules выберите Add Rule….

    Add Rule

  2. На экране Choose Rule Type выберите в раскрывающемся меню пункт Send LDAP Attributes as Claims, затем нажмите Next.

    Choose Rule Type

  3. На экране Configure Claim Rule введите Claim Rule Name по вашему выбору, выберите Active Directory as the Attribute Store, затем добавьте следующие сопоставления (mappings):

    LDAP AttributeOutgoing Claim Type
    E-Mail-AddressesEmail
    E-Mail-AddressesName ID
    Given-NameFirstName
    SurnameLastName (опционально)
    SAM-Account-NameUsername (опционально)
    objectGUIDobjectGUID

    Configure Claim Rule

    Продолжение таблицы сопоставления полей:

    Configure Claim Rule

    Нажмите Finish для того, чтобы добавить правило.

    примечание

    Записи в столбце Outgoing Claim Type могут быть изменены. Записи могут содержать тире, но без пробелов. Они используются для сопоставления соответствующих полей в настройках Time.

  4. Выберите Add Rule, чтобы создать еще одно новое правило.

  5. На экране Choose Rule Type выберите вариант Transform an Incoming Claim, затем нажмите Next.

    Choose Rule Type

  6. На экране Configure Claim Rule введите Claim Rule Name по вашему выбору, затем:

    • Выберите Name ID для Incoming claim type
    • Выберите Unspecified для Incoming name ID format
    • Выберите E-Mail Address для Outgoing claim type
    • Выберите Pass through all claim values, затем нажмите OK.

    Configure Claim Rule

  7. Нажмите Finish, чтобы создать claim rule, затем нажмите OK, чтобы завершить создание правил.

  8. Откройте Windows PowerShell от имени администратора, затем выполните следующую команду:

    Set-ADFSRelyingPartyTrust -TargetName <display-name> -SamlResponseSignature "MessageAndAssertion"

    где <display-name> — это имя, указанное вами на шаге 5 при добавлении доверительной стороны (relying party trust). В нашем примере <display-name> было бы Time. Это действие добавляет подпись к сообщениям SAML, что делает проверку успешной.

Экспорт сертификата Identity Provider​

Теперь экспортируйте сертификат провайдера удостоверений (Identity Provider), который позже будет загружен в Time для завершения настройки SAML.

  1. Откройте оснастку управления ADFS, выберите AD FS → Service → Certificates, затем дважды щелкните сертификат в разделе Token-signing. Вы также можете выбрать View Certificate в контекстном меню, открываемом кликом правой кнопки мыши.

    Certificate

  2. На экране Certificate откройте вкладку Details, выберите Copy to File, затем нажмите OK.

    Copy to File

  3. На экране Certificate Export Wizard нажмите Next.

    Next

  4. Выберите Base-64 encoded X.509 (.CER), затем снова нажмите Next.

    Base-64 encoded X.509

  5. На экране Certificate Export Wizard нажмите Browse, чтобы указать расположение, в которое вы хотите экспортировать сертификат поставщика удостоверений (Identity Provider Certificate), затем укажите имя файла.

    Browse

  6. Выберите Save. На экране Certificate Export Wizard убедитесь, что путь к файлу указан правильно, затем нажмите Next.

  7. В Completing the Certificate Export Wizard выберите Finish, затем нажмите OK, чтобы подтвердить успешность экспорта.

    Finish

Настройка SAML Sign-On для Time​

  1. Создайте URL-адрес метаданных, добавив FederationMetadata/2007-06/FederationMetadata.xml к корневому URL-адресу сервера ADFS, например: https://<adfs.domain.com>/federationmetadata/2007-06/FederationMetadata.xml.

  2. Далее настройте параметры сервера Time через ENV-переменные (предпочтительно) или файл config.json:

    • TIME_SAMLSETTINGS_ENABLE=true — включение авторизации через SAML.
    • TIME_SAMLSETTINGS_ENCRYPT=true — включение шифрования запросов.
    • TIME_SAMLSETTINGS_SERVICEPROVIDERIDENTIFIER=https://${TIME_DOMAIN}/login/sso/saml — уникальный идентификатор поставщика услуг.
    • TIME_SAMLSETTINGS_ASSERTIONCONSUMERSERVICEURL=https://${TIME_DOMAIN}/login/sso/saml — адрес для входа через поставщика услуг.
    • TIME_SAMLSETTINGS_IDPURL=https://<adfs.domain.com>/adfs/ls/ — URL-адрес, на который мессенджер отправляет SAML-запрос для входа.
    • TIME_SAMLSETTINGS_IDPDESCRIPTORURL=http://<adfs.domain.com>/adfs/services/trust — URL-адрес издателя поставщика учетных записей для запросов SAML.
    • TIME_SAMLSETTINGS_IDPMETADATAURL=https://<adfs.domain.com>/federationmetadata/2007-06/FederationMetadata.xml — URL, по которому мессенджер отправляет запрос на получение метаданных (см. документацию вашего провайдера аторизации).
    • TIME_SAMLSETTINGS_SIGNATUREALGORITHM=RSAwithSHA256 — алгоритм для подписи запроса SAML (см. Admin Guide).
    • TIME_SAMLSETTINGS_CANONICALALGORITHM=Canonical1.1 — алгоритм канонизации для XML (см. Admin Guide).
    • TIME_SAMLSETTINGS_IDPCERTIFICATEFILE=/time/certs/saml-idp.crt — путь к публичному сертификату проверки подлинности, выданный поставщиком удостоверений.
    • TIME_SAMLSETTINGS_PUBLICCERTIFICATEFILE=/time/certs/saml-public.crt — путь к файлу сертификата, используемого для подписи запроса SAML к поставщику удостоверений (файл, который был сгенерирован на этапе Подготовка).
    • TIME_SAMLSETTINGS_PRIVATEKEYFILE=/time/certs/saml-private.key — путь к файлу закрытого ключа, используемый для расшифровки утверждений SAML от поставщика удостоверений (файл, который был сгенерирован на этапе Подготовка).
    • TIME_SAMLSETTINGS_IDPCERTIFICATECONTENT= — содержимое публичного сертификата проверки подлинности, выданный поставщиком удостоверений.
    • TIME_SAMLSETTINGS_PUBLICCERTIFICATECONTENT= — содержимое файла сертификата, используемого для подписи запроса SAML к поставщику удостоверений (файл, который был сгенерирован на этапе Подготовка).
    • TIME_SAMLSETTINGS_PRIVATEKEYCONTENT= — содержимое файла закрытого ключа, используемый для расшифровки утверждений SAML от поставщика удостоверений (файл, который был сгенерирован на этапе Подготовка).
    • TIME_SAMLSETTINGS_IDATTRIBUTE=objectGUID — атрибут, который будет использоваться для сопоставления пользователей из SAML.
    • TIME_SAMLSETTINGS_FIRSTNAMEATTRIBUTE=FirstName — атрибут имени пользователя
    • TIME_SAMLSETTINGS_LASTNAMEATTRIBUTE=LastName — атрибут фамилии пользователя
    • TIME_SAMLSETTINGS_EMAILATTRIBUTE=Email — атрибут имейла пользователя
    • TIME_SAMLSETTINGS_USERNAMEATTRIBUTE=Username — атрибут юзернейма пользователя
    • TIME_SAMLSETTINGS_NICKNAMEATTRIBUTE=Username - атрибут псевдонима пользователя
    • TIME_TEAMSETTINGS_TEAMMATENAMEDISPLAY=full_name — cпособ отображения имён пользователей в интерфейсе Time (в данном случае — будет отображаться имя и фамилия пользователя).
    • TIME_SAMLSETTINGS_LOGINBUTTONTEXT='SAML (ADFS)' — текст на кнопке для входа через SAML.
    • TIME_SAMLSETTINGS_AUTOJOINTEAMATTRIBUTE='groups=<time_ad_group>:<time_team_id>' — параметр сопоставления группы пользователей в AD (<time_ad_group>), пользователи которой будут автоматически добавляться в указанную Team ID в Time (<time_team_id>)

    где:

    • ${TIME_DOMAIN} — домен, на котором работает Time.
    • <adfs.domain.com> — домен, на котором работает ADFS.

  3. Затем перезапустите сервер Time (все инстансы).

  4. Войдите в Time как системный администратор, перейдите в System Console → Authentication → SAML, и проверьте что все указанные выше параметры добавились в соответствующие поля. Для дополнительных настроек также используйте ENV-переменные или config.json (см. Admin Guide).

Готово! Если вы хотите убедиться, что SAML SSO успешно включен, переключите свою учетную запись системного администратора с электронной почты на аутентификацию на основе SAML с помощью изображения вашего профиля, выбрав Profile → Security → Sign-in Method → Switch to SAML SSO, а затем войдите в систему через SAML под своей учетной записью провайдера авторизации.

FAQ​

Авторизация через ADFS не проходит, в логах Time ошибка вида: "User.IsValid: Invalid user, password and auth data cannot both be set​

Полный текст ошибки:

User.IsValid: Invalid user, password and auth data cannot both be set., 
user_id=9i9uoi5jrpbj5fudhahpjkh68e
Ответ

Повторите попытку авторизации. Скорее всего пользователь, под которым происходит авторизация — уже есть в Time, и попытка конвертации локального пользователя в пользователя ADFS прошла не сразу.

После авторизации через ADFS у пользователя нет команд для присоединения, сообщение вида: No teams are available to join. Please create a new team or ask your administrator for an invite.​

No teams are available to join

Ответ

По умолчанию новые пользователи не добавляются в Team, для этого необходимо сделать что-то одно из перечисленного:

  • присылать инвайт-ссылку — после логина по ссылке пользователь будет добавлен в указанную Team
  • после успешной авторизации добавить пользователя в Team вручную
  • настроить автоматическое добавление в команду с помощью параметра AutoJoinTeamAttribute — см. Admin Guide

Как привязать аутентификацию к атрибуту Id вместо Email?​

Ответ

В качестве альтернативного варианта вы можете использовать атрибут Id вместо Email для привязки пользователя. Рекомендуется выбирать уникальный идентификатор, который не будет меняться со временем.