Утилита YandexADSCIM

Чтобы подключить синхронизацию пользователей из Active Directory, ALD Pro или Samba DC на Windows, Linux или других *nix-платформах, установите утилиту YandexADSCIM по инструкции ниже и запустите ее от имени пользователя с правами чтения из каталога LDAP.

# Разрешить исходящий HTTPS к SCIM API Яндекс
Allow outbound: TCP 443 to scim-api.passport.yandex.net

# Разрешить исходящий HTTPS для работы утилиты
Allow outbound: TCP 443 to 77.88.21.80

# Разрешить исходящий HTTPS для загрузки образа утилиты
Allow outbound: TCP 443 to registry.yandexcloud.net

# Разрешить исходящий LDAP/LDAPS к вашим серверам
Allow outbound: TCP 389,636 to your-ad-servers.example.com

# Проверка доступа к SCIM API Яндекс
telnet scim-api.passport.yandex.net 443
# Или
curl -I https://scim-api.passport.yandex.net/

# Проверка доступа для работы утилиты
telnet 77.88.21.80 443
# Или
curl -I https://77.88.21.80/

# Проверка доступа к вашим серверам
telnet dc.example.com 389

Шаг 1. Получите Docker-образ утилиты

# Загрузка образа из внешнего реестра
docker pull registry.yandexcloud.net/cn1v24roe2k2kcqihnke/adscim:latest

# Проверка загруженного образа
docker images | grep adscim

# Загрузка образа из архива
docker load -i adscim2402.tar

# Проверка загруженного образа
docker images | grep adscim

Шаг 2. Подготовьте окружение

1. Для установки утилиты понадобятся:

   • Docker и Docker Compose;
   • OAuth-токен для доступа к scim-api.passport.yandex.net;
   • Учетные данные для подключения. Где взять учетные данные и токен

2. Создайте рабочую директорию для утилиты:

   mkdir -p adscim/config
   cd adscim
   

Шаг 3. Настройте конфигурационный файл

Создайте конфигурационный файл config/application.json:

{
    "adscim": {
        "source": {
            "type": "active-directory", // Тип каталога: active-directory, generic-ldap
            "ldap": {
                "urls": [ // Адреса LDAP-серверов
                    "ldap://dc.example.com:389" // Формат: протокол://хост:порт
                ],
                "paths": [ // Базовые DN для поиска пользователей
                    "OU=Users,DC=example,DC=com" // Организационные подразделения
                ],
                "username": "sync_user@example.com", // Учетная запись для подключения
                "password": { // Пароль (рекомендуется использовать файлы)
                    "value": "<пароль_от_вашего_сервера>" // Прямое значение пароля
                }
            }
        },
        "destination": {
            "scim": {
                "bearerToken": { // OAuth-токен для доступа к SCIM API
                    "value": "<токен_SCIM>"
                },
                "domainId": "<идентификатор_домена>" // ID домена в Яндекс 360
            }
        },
        "sync": {
            "dryRun": true, // Тестовый режим (без изменений в Яндекс 360)
            "intervalMinutes": 60 // Интервал синхронизации в минутах
        }
    }
}

где

• "dryRun": true — тестовый режим для проверки подключения к вашему серверу и SCIM API без внесения изменений на стороне Яндекс 360;

• dc.example.com:389 — адрес вашего сервера (AD или другого);

• DC – domainComponent, собственный домен и доменная зона;

• OU – OrganizationUnit, компания, департамент или отдел, из которого вы хотите получить пользователей;

• OU=Users,DC=example,DC=com — путь к пользователям в каталоге LDAP;

• sync_user@example.com — пользователь для подключения к единому входу (SSO);

• <пароль_от_вашего_сервера> — пароль для подключения к единому входу (SSO);

• <токен_SCIM> — OAuth-токен для Яндекс 360;

• <идентификатор_домена> — ваш Domain ID в Яндекс 360. Где его взять

Ключевые параметры конфигурации

Базовые настройки подключения

• urls — адреса серверов LDAP в формате ldap://хост:порт или ldaps://хост:порт для защищенного соединения;
• paths — организационные подразделения для поиска пользователей, например OU=Users,DC=example,DC=com;
• username/password — учетные данные и пароль для подключения к LDAP-серверу.

Параметры синхронизации

• dryRun — режим пробного запуска без внесения изменений в каталог Яндекс 360 — обязателен во время настройки синхронизации;
• intervalMinutes — интервал времени между автоматическими запусками синхронизации в минутах;
• allowUsersDeletion — разрешение на блокировку пользователей в Яндекс 360 при их отсутствии в LDAP-каталоге — обязательно при синхронизации из нескольких лесов Active Directory.

{
    "logging": { // Настройки логирования
        "level": { // Уровни детализации логов
            "ru.yandex.ya360.backend.b2b_platform.adscim": "INFO" // DEBUG, INFO, WARN, ERROR
        }
    },
    "adscim": {
        "source": {
            "type": "active-directory",
            "ldap": {
                "urls": [
                    "ldap://dc.example.com:389"
                ],
                "paths": [
                    "OU=Users,DC=example,DC=com"
                ],
                "username": "sync_user@example.com",
                "password": {
                    "value": "<пароль_от_вашего_сервера>"
                },
                "connectionTimeout": 5000, // Тайм-аут подключения (мс)
                "readTimeout": 10000, // Тайм-аут чтения данных (мс)
                "pageSize": 100, // Размер страницы для постраничного поиска
                "contactFetchProxyAddresses": true, // Загружать прокси-адреса контактов
                "connectionPool": { // Настройки пула подключений
                    "initialConnections": 1, // Начальное количество соединений
                    "maxConnections": 10, // Максимальное количество соединений
                    "healthCheckIntervalMs": 60000 // Интервал проверки здоровья (мс)
                },
                "filters": { // LDAP-фильтры для поиска объектов
                    "users": "(&(objectCategory=person)(objectClass=user))", // Фильтр для пользователей Active Directory
                    "groups": "(objectClass=group)", // Фильтр для групп
                    "contacts": "(objectClass=contact)" // Фильтр для контактов
                },
                "attributes": { // Сопоставление LDAP-атрибутов
                    "user": {
                        "loginName": ["userPrincipalName"], // Логин пользователя
                        "firstName": ["givenName"], // Имя
                        "lastName": ["surName", "sn"], // Фамилия
                        "middleName": ["middleName"], // Отчество
                        "displayName": ["displayName"], // Отображаемое имя
                        "title": ["title"], // Должность
                        "workMail": ["mail"], // Основная электронная почта
                        "mobilePhone": ["mobile"], // Мобильный телефон
                        "workPhone": ["telephoneNumber"], // Рабочий телефон
                        "ipPhone": ["ipPhone"], // IP-телефон
                        "required": ["userPrincipalName", "mail"] // Обязательные атрибуты
                    },
                    "group": { // Атрибуты групп
                        "name": ["name", "cn"], // Название группы
                        "description": ["description"], // Описание группы
                        "mail": ["mail"], // Электронная почта группы
                        "displayFlag": [] // Флаг отображения группы
                    },
                    "sharedContact": { // Атрибуты контактов
                        "firstName": ["givenName"], // Имя контакта
                        "lastName": ["surName", "sn"], // Фамилия контакта
                        "middleName": ["middleName"], // Отчество контакта
                        "title": ["title"], // Должность контакта
                        "department": ["department"], // Подразделение контакта
                        "company": ["company"], // Организация контакта
                        "workMail": ["mail"], // Основная электронная почта контакта
                        "workPhone": ["telephoneNumber"], // Рабочий телефон контакта
                        "otherWorkPhone": ["otherTelephone"], // Дополнительный рабочий телефон
                        "mobilePhone": ["mobile"], // Мобильный телефон контакта
                        "otherMobilePhone": ["otherMobile"], // Дополнительный мобильный телефон
                        "ipPhone": ["ipPhone"], // IP-телефон контакта
                        "otherIpPhone": ["otherIpPhone"], // Дополнительный IP-телефон
                        "address1": ["streetAddress"], // Адрес (улица и дом)
                        "address2": ["l"], // Адрес (город)
                        "address3": ["st"], // Адрес (регион)
                        "address4": ["postalCode"] // Почтовый индекс
                    }
                }
            }
        },
        "destination": {
            "scim": {
                "bearerToken": {
                    "value": "<токен_SCIM>" // OAuth-токен для доступа к SCIM API
                },
                "domainId": "<идентификатор_домена>" // ID домена в Яндекс 360
            }
        },
        "sync": {
            "enableGroups": false, // Включить синхронизацию групп
            "enableContacts": false, // Включить синхронизацию контактов
            "intervalMinutes": 60, // Интервал синхронизации
            "dryRun": true, // Тестовый режим (без изменений в Яндекс 360)
            "allowUsersDeletion": true, // Разрешить блокировку пользователей
            "allowGroupsDeletion": true, // Разрешить блокировку групп
            "allowContactsDeletion": true, // Разрешить блокировку контактов
            "ignoreUsernameDomain": false, // Игнорировать домен в логине
            "ignoreUserEmailChange": false, // Игнорировать изменение электронной почты
            "initialDelaySeconds": 10, // Задержка перед стартом
            "aliases": { // Настройки алиасов электронной почты
                "enabled": false, // Включить обработку алиасов
                "domains": [], // Разрешенные домены
                "changeDomains": {} // Замена доменов
            }
        }
    }
}

logging:
  level:
    ru.yandex.ya360.backend.b2b_platform.adscim: INFO # Уровень детализации логов: DEBUG, INFO, WARN, ERROR
adscim:
  source:
    type: generic-ldap # Тип каталога: generic-ldap для FreeIPA и совместимых систем
    ldap:
      urls:
        - ldap://ald-server.example.com:389 # Адрес вашего сервера
      paths:
        - cn=users,cn=accounts,dc=example,dc=com # Базовый DN для поиска в формате FreeIPA
      username: uid=svc_sync,cn=users,cn=accounts,dc=example,dc=com # Учетная запись в формате Distinguished Name
      password:
        value: <пароль_от_вашего_сервера> # Пароль для подключения
      filters:
        users: "(objectClass=posixAccount)" # Фильтр для поиска пользователей
        groups: "(objectClass=posixGroup)"  # Фильтр для поиска групп
      attributes:
        user:
          loginName:
            - uid         # Логин пользователя
          firstName:
            - givenName   # Имя пользователя
          lastName:
            - sn          # Фамилия пользователя
          workMail:
            - mail        # Основной адрес электронной почты
  destination:
    scim:
      bearerToken:
        value: <токен_SCIM> # OAuth-токен для доступа к SCIM API Яндекс 360
      domainId: <идентификатор_домена> # ID домена в Яндекс 360
  sync:
    dryRun: true # Тестовый режим (без изменений в Яндекс 360)
    ignoreUsernameDomain: true # Игнорировать домен в логине (в FreeIPA обычно отсутствует)

Шаг 4. Запустите утилиту

1. Создайте docker-compose.yml:

   services:
       adscim:
           image: registry.yandexcloud.net/cn1v24roe2k2kcqihnke/adscim:latest
           container_name: adscim
           restart: unless-stopped
           ports:
               - "127.0.0.1:3402:3402"
           volumes:
               - ./config/application.json:/app/config/application.json:ro
               - logs:/app/logs
           environment:
               - JAVA_OPTS=-Xmx1024m -Xms512m
           healthcheck:
               test: [ "CMD", "curl", "-f", "http://localhost:3402/actuator/health" ]
               interval: 30s
               timeout: 10s
               retries: 3
               start_period: 60s
   
   volumes:
       logs:
   

2. Запустите сервис:

   docker-compose up -d
   

3. Проверьте статус:

   docker-compose ps
   docker-compose logs -f
   
   Основные команды управления

   # Управление сервисом
   docker-compose up -d           # запуск
   docker-compose down            # остановка
   docker-compose restart         # перезапуск
   docker-compose ps              # статус
   docker-compose logs -f         # просмотр логов
   
   # Остановка с очисткой
   docker-compose down -v         # остановка с удалением volumes
   

   В колонке STATUS должен быть статус Up (healthy).

Шаг 5. Включите синхронизацию

Если система в тестовом режиме работает корректно:

1. Измените в конфигурационном файле параметр "dryRun" на false;

2. Перезапустите сервис:

   docker-compose restart
   

Хранение секретов

Чтобы хранить секреты, вынесите их из конфигурационного файла в отдельные.

1. Создайте файлы с секретами в отдельной директории рядом с файлом docker-compose.yml:

   # Создание директории для секретов
   mkdir -p secrets
   
   # Создание файлов с секретами (без лишних пробелов и переводов строк)
   echo "<пароль_от_вашего_сервера>" > secrets/ldap_password.txt
   echo "<токен_SCIM>" > secrets/scim_bearer_token.txt
   
   # Установка прав доступа к файлам (600 — чтение только владельцем)
   chmod 600 secrets/ldap_password.txt secrets/scim_bearer_token.txt
   

2. Обновите конфигурационный файл config/application.json:

   {
       "adscim": {
           "source": {
               "type": "active-directory",
               "ldap": {
                   "urls": ["ldap://dc.example.com:389"],
                   "paths": ["OU=Users,DC=example,DC=com"],
                   "username": "sync_user@example.com",
                   "password": {
                       "file": "/run/secrets/ldap_password"
                   }
               }
           },
           "destination": {
               "scim": {
                   "bearerToken": {
                       "file": "/run/secrets/scim_bearer_token"
                   },
                   "domainId": "<идентификатор_домена>"
               }
           },
           "sync": {
               "dryRun": true,
               "intervalMinutes": 60
           }
       }
   }
   

3. Добавьте в файл docker-compose.yml путь к файлам с секретами:

   services:
       adscim:
           image: registry.yandexcloud.net/cn1v24roe2k2kcqihnke/adscim:latest
           container_name: adscim
           restart: unless-stopped
           ports:
               - "127.0.0.1:3402:3402"
           secrets:
               - ldap_password
               - scim_bearer_token
           volumes:
               - ./config/application.json:/app/config/application.json:ro
               - logs:/app/logs
           environment:
               - JAVA_OPTS=-Xmx1024m -Xms512m
           healthcheck:
               test: [ "CMD", "curl", "-f", "http://localhost:3402/actuator/health" ]
               interval: 30s
               timeout: 10s
               retries: 3
               start_period: 60s
   
   secrets:
       ldap_password:
           file: ./secrets/ldap_password.txt
       scim_bearer_token:
           file: ./secrets/scim_bearer_token.txt
   
   volumes:
       logs:
   

4. После внесения изменений перезапустите сервис:

   docker-compose down
   docker-compose up -d
   

Возможные ситуации при работе

Типичные сценарии синхронизации

Диагностика и устранение неполадок

Проверка подключения

# Проверка LDAP подключения
ldapsearch -H ldap://dc.example.com:389 -x -b "OU=Users,DC=example,DC=com" -D "sync_user@example.com" -W

# Проверка SCIM API
curl -H "Authorization: Bearer <токен_SCIM>" "https://scim-api.passport.yandex.net/v2/Users?domainId=<идентификатор_домена>"

Ответ при успешном подключении к LDAP:

• Список пользователей из указанного организационного подразделения (OU);
• Данные атрибутов для каждого пользователя (имя, электронная почта, должность и т.д.).
• Нет сообщений об ошибках Invalid credentials или Connection failed.

Ответ при успешном подключении к SCIM API:

• HTTP-статус 200 OK;
• JSON-файл с информацией о пользователях, уже существующих в каталоге Яндекс 360;
• Корректная структура данных SCIM без ошибок авторизации;
• Нет сообщений об ошибках Authentication failed или Invalid token.

Анализ логов и решение проблем

Проверьте логи приложения для выявления причин ошибок:

docker-compose logs -f

Мониторинг работы сервиса

Для проверки состояния утилиты используйте следующие команды:

# Проверка состояния через Health Check
curl http://localhost:3402/actuator/health

# Проверка статуса контейнера
docker-compose ps

Если утилита работает корректно:

1. Health Check должен вернуть HTTP-статус 200 OK с JSON-файлом:

   {"status":"UP"}
   

2. Статус контейнера в ответе docker-compose ps должен содержать:

   • UP — контейнер запущен;
   • (healthy) — Health Check проходит успешно;
   • Время работы контейнера — например, Up 5 minutes.

Если утилита работает некорректно:

• Статус контейнера имеет значение DOWN — проверьте логи для диагностики неполадок;

• Статус контейнера имеет значение EXIT или RESTARTING — проверьте конфигурацию и доступность зависимостей;

• Отсутствие статуса (healthy) — проблемы с внутренней работой утилиты.