Синхронизация учётных записей пользователей в Организацию Яндекс 360 для бизнеса

Хабр, привет! Этой статьёй я продолжаю цикл материалов об управлении Организацией в Яндекс 360 для бизнеса.

В предыдущей статье мы обсудили, какими способами можно добавить домен в Организацию — это был первый шаг. Теперь можно настраивать сервисы Яндекс 360 для бизнеса. Начнём с добавления пользователей. Ведь организация без пользователей — всё равно, что лес без деревьев.

Добавить пользователей можно пятью способами:

1. Создать вручную через web-интерфейс в панели управления Организацией.

2. Загрузить список пользователей через CSV-файл со стандартными колонками, такими как Ф. И. О., email, телефоны и др.

3. Загрузить через Rest API, используя curl или удобный инструмент написания скриптов для автоматизации управления.

4. Использовать API SCIM.

5. Настроить синхронизацию с каталогом по протоколу LDAP — при этом способе так же используется API SCIM. На нём остановимся подробнее в статье.

Расскажу о принципах работы синхронизации пользователей — почему надо делать в том порядке, который указан в официальной документации. Ещё раскрою важные аспекты, которые могут быть неочевидны. Это поможет избежать большинства ошибок при планировании и настройке.

Алгоритм действий при синхронизации пользователей

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

Шаг 1. Перед синхронизацией нужно включить SSO, то есть отдать IdP на землю. Для настройки используйте нужную инструкцию из Справки:

• ADFS

• Azure AD

• Keycloack

Шаг 2. Установить и настроить утилиту синхронизации Yandex AD SCIM.

Зачем включать SSO перед настройкой синхронизации

С помощью технологии единого входа на базе SAML 2.0 вы можете организовать вход в сервисы Яндекс 360 через вашу систему управления доступом. Так сотрудникам не придётся запоминать новые логины и пароли, а вам — заводить для них отдельные учётные записи в Яндекс 360 для бизнеса.

Когда сотрудник попытается войти в один из сервисов, то Яндекс 360, как поставщик услуг, перенаправит его на указанную вами страницу входа. Пользователь сможет авторизоваться с помощью данных, которые хранятся у поставщика удостоверений. Этот подход называется федерацией удостоверений. В этом случае в Яндекс 360 не будут храниться пароли пользователей.

Когда пользователь придёт с SAML-ответом, который подписан валидным сертификатом в Яндекс 360, для него будет автоматически создана учётная запись на основе информации в SAML-ответе. Это произойдёт, если на момент попытки авторизации учетной записи ещё не было.

Обращаю ваше внимание: именно включение SSO в организации даёт возможность автоматически создать учётную запись в процессе первого входа пользователя. Более того, это действие позволяет создавать учётные записи заранее — до первой авторизации.

Итого — включили SSO, получили три способа добавления пользователей в Организацию:

1. Автоматически при успешном вводе логина по информации из SAML-ответа (фамилия, имя и email).

2. С использованием API SCIM.

3. Через утилиту синхронизации Yandex AD SCIM, которая использует API SCIM. Это тот способ добавления пользователей, ради которого мы настроили SSO.

Общая архитектура разных способов управления учётными записями

Принятие решения об использовании или неиспользовании SSO — важнейший момент планирования Identity в Организации. Сейчас нельзя сменить тип пользователей с «SSO» на «без SSO» и обратно без потерь. Если в какой-то момент, например через год, вы измените решение и захотите включить или выключить SSO, то придётся удалить всех пользователей. Но команда Яндекс 360 сейчас работает над созданием гибкости в этом компоненте, и возможность сменить тип появится в будущем.

О настройке SSO разными способами я планирую опубликовать отдельную статью, в которой поделюсь опытом. А пока: SSO включён, переходим к настройке синхронизации с вашим LDAP-каталогом, которая осуществляется с помощью утилиты Yandex AD SCIM.

Синхронизация через утилиту Yandex AD SCIM

Что умеет утилита Yandex AD SCIM

Утилита умеет подключаться к LDAP и синхронизировать объекты из каталога на земле в Организацию Яндекс 360 по протоколу SCIM. В Яндекс 360 есть API SCIM — в нём реализовано всё необходимое для работы команд и атрибутов, которые использует утилита Yandex AD SCIM.

Поддерживаются объекты трёх типов:

1. Пользователи.

2. Группы, включая членство и вложенность.

3. Контакты (в самое ближайшее время).

Сама утилита написана на старом добром .NET, поэтому её нужно установить на Windows-машину, подключённую к домену. Она может подключаться к домену Active Directory по LDAP, к лесу Active Directory по LDAP через GC и к Samba DС. Сейчас не поддерживается работа с FreeIPA, ALD Pro.

• Чтобы подключиться по LDAP, в файле конфигурации нужно указать конкретный каталог:

LDAP = LDAP://CN=Users,DC=YourCompanyName,DC=com

Тем самым вы подключаетесь по LDAP и сразу фильтруете список пользователей только определённым контейнером. В примере речь идёт о контейнере CN=Users.

• Чтобы подключиться к Глобальному каталогу, в строчке нужно явно указать протокол GC:

LDAP = GC://CN=Users,DC=YourCompanyName,DC=com

На сегодня утилита умеет подключаться к одному LDAP- или GC-каталогу. Это значит, что с её помощью можно выгрузить учётные записи из одного леса, в том числе из нескольких доменов — деревьев этого леса.

Если учётные записи надо выгружать из нескольких доменов одного леса, то обязательно использовать подключение через GC. В этом случае стоит убедиться, что нужные атрибуты копируются в GC: например, атрибут Отчество (middleName) по умолчанию этого не делает. Надо обязательно настроить копирование атрибута, чтобы он синхронизировался в Организацию Яндекс 360, в свойства пользователей. Как это провернуть, рассказано в документации Microsoft — «Включение атрибутов в глобальный каталог».

Основные аспекты управления Yandex AD SCIM

1. Настройки работы меняются через конфигурационный файл. Он называется AD_Users.config и доступен по пути %ProgramData%\Yandex\YandexADSCIM.

2. Управление запуском осуществляется через оснастку "Службы" (services.msc). Обычно в самом низу списка по алфавиту можно найти службу с лаконичным названием Yandex AD SCIM.

• Если службу остановить, то синхронизация полностью остановится

• Если службу запустить, то запускается цикл синхронизации с параметрами, указанными в конфигурационном файле

• Если служба работает в штатном режиме, то она автоматически регулярно запускает цикл синхронизации согласно значению параметра UpdateEveryMins = N в файле конфигурации

3. Во время работы служба логирует свои действия. Если хотите включить расширенные логи, то добавьте ключ в конфигурационный файл Verboselog = true. Все логи службы сохраняются в папке %ProgramData%\Yandex\YandexADSCIM.

4. Крайне рекомендую использовать тестовый режим работы в следующих случаях:

• При первичной настройке конфигурации, после установки службы

• При изменении файла конфигурации

• При внесении массовых изменений в каталоге

В тестовом режиме утилита попытается сделать всё, что должна сделать, и сообщит об этом в логах. Но на деле в Организацию Яндекс 360 никаких изменений не будет внесено.

• Ключ DryRun = true включает тестовый режим

• Ключ DryRun = false выключает тестовый режим

По умолчанию этот ключ в конфигураторе после установки утилиты имеет значение True. Поменяйте значение на False, когда всё настроите и убедитесь по логам, что служба пытается создать только нужных пользователей.

Ключевой атрибут, с которого всё начинается

Когда будете знакомиться с документацией и применять те или иные ключи в конфигураторе, то обратите внимание на первый параметр — PropertyLoginName. Значение этого атрибута определяет уникальность пользователя в Организации.

Если не задать PropertyLoginName, Yandex AD SCIM возьмёт за основу значение UserPrincipalName. Поэтому, если планируете изменение UPN, рекомендую выбрать уникальный атрибут ObjectSID, ObjectGUID или вообще сделать ход конём и выбрать сторонний атрибут — например, EmployeeID. Желательно, чтобы его значение не менялось в будущем.

Атрибут используется при синхронизации, настройке SSO и выдаче пользователю SAML-response. Если углубиться в детали, то все поля ниже являются одним и тем же в Организации Яндекс 360:

• NameID — при настройке SSO

• PropertyLoginName — в конфигурационном файле Yandex SCIM

• username — через SCIM API

Учтите, что в случае выбора атрибута, который не соответствует email пользователя, нужно внимательно отнестись и к настройкам SSO. Значение параметра PropertyLoginName должно соответствовать значению атрибута NameID в поле Incoming claim type из настроек единого входа. Если вы используете атрибут вида username, а не [e-mail], то дополнительно укажите параметр IgnoreUsernameDomain со значением true.

Подробнее читайте в пункте 2.5 шага 4 документации Yandex AD SCIM.

Переименование пользователя в Active Directory

Недавно в Яндекс 360 добавили возможность менять значение ключевого атрибута в AD у пользователя, который синхронизируется в Организацию Яндекс 360. Это актуально для заказчиков, которые настроили SSO и, возможно, но не обязательно, настроили синхронизацию по протоколу SCIM.

В каких бизнес-кейсах может потребоваться изменение ключевого атрибута:

• В качестве PropertyLoginName используется UPN, и человек меняет свою Ф. И. О. На моём личном опыте встречались случаи, когда Ф. И. О. меняли не только девушки после замужества, но и парни по личным соображениям. Так что, надо быть готовым ко всему. При этом Ф. И. О. используется при формировании UPN: в той части, которая в AD называется username, или в простонародье «слева от собачки».

• В качестве PropertyLoginName используется ObjectGUID, и компания проходит через сценарий слияния или поглощения. Как следствие, идёт миграция AD или другой подобный процесс, что приводит к смене значения атрибута.

В этом случае нужно остановить службу синхронизации и, используя SCIM API, изменить значение атрибута username в Организации Яндекс 360 на новое:

• Для подключения к SCIM API нужно использовать тот же токен, который используете для авторизации Yandex AD SCIM

• В URL нужно использовать тот же DomainID, который в приложении Yandex AD SCIM

• UID — цифровое значение User ID пользователя, которого переименовываете, оно начинается на 113000... (всего 16 цифр)

• Пример Curl-запроса:

curl --location --request PATCH  'https://{{domain_id}}.scim-api.passport.yandex.net/v2/Users/{{uid}}' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
    "Operations": [
          {                
              "value": "{{correct_username}}",
              "op": "replace",
              "path": "userName"
          }
      ],
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
      ]
}'

Далее нужно изменить значение соответствующего атрибута в AD, будь то UPN, ObjectGUID или другое. Если речь идёт о замене значения UPN, то добавьте старые и новые ProxyAddresses и включите синхронизацию alias. EnableAliases = true.

Подробнее читайте в пункте 2.7 шага 4 документации Yandex AD SCIM.

Способы фильтрации пользователей

После того как определились с SSO, ключевым атрибутом пользователя и другими атрибутами, встаёт вопрос: что именно синхронизировать? Как правило, в домене, кроме учётных записей для рядовых сотрудников, есть ещё много чего, что не нужно синхронизировать. Например, служебные учётные записи, для администраторов, уволенных сотрудников и далее по списку. Поэтому перед синхронизацией нужно озаботиться о фильтрах объектов.

В Yandex AD SCIM можно настроить один общий фильтр на все объекты при подключении к LDAP — об этом я написал в разделе «Что умеет утилита Yandex AD SCIM». Поддерживается два типа объектов — Пользователи и Группы. В скором времени будет поддерживаться третий тип объекта — Контакты. Для всех типов можно создать три независимых LDAP-фильтра. Сами фильтры подчиняются синтаксису LDAP.

Приведу два примера.

Пример 1. Фильтр для групп

Для того чтобы синхронизировались только списки рассылок, фильтр может выглядеть так:

GroupsFilter =(&(objectClass=group)(!(groupType1.2.840.113556.1.4.803=2147483648)))

Сделаю отсылку к документации Microsoft:

ADS_GROUP_TYPE_SECURITY_ENABLED (0x80000000 = 2147483648)

Пример 2. Фильтр для пользователей

Чуть более творческий пример: синхронизируем пользователей, которые являются участниками определённой группы и не заблокированы.

UsersFilter = (&(memberOf=CN=SCIMUSER,CN=USERS,DC=YourCompanyName,DC=COM)(objectCategory=person)(objectClass=user)(!userAccountControl1.2.840.113556.1.4.803=2))

Этот кейс решает две бизнес-задачи. Во-первых, так в Организации Яндекс 360 для бизнеса появятся только участники группы SCIMUSERS. Во-вторых, если учётная запись окажется заблокирована из-за увольнения сотрудника или по другим причинам , то в следующий цикл синхронизации она будет автоматически заблокирована и в Яндекс 360 для бизнеса.

Заключение

В этой статье мы рассмотрели ключевые аспекты настройки синхронизации учётных записей пользователей в Организации Яндекс 360 для бизнеса:

• Зачем нужно включать SSO

• Что умеет утилита Yandex AD SCIM и как подключить её к GC и LDAP

• Как настраивать синхронизацию через файл конфигурации

• Как поддерживается переименование пользователей

• Как запустить и остановить процесс

• Как фильтровать пользователей

Если у вас есть вопросы, задавайте в комментариях ниже — я и мои коллеги с радостью ответим. Или я сделаю отдельный материал с разбором частых вопросов.