Синхронизация данных

Синхронизация данных о сотрудниках с сервисами Контура
Примеры сценариев
Требования
Спецификация SCIM
Настройка cинхронизатора

Синхронизация данных о сотрудниках с сервисами Контура

В базовой реализации SSO сервисы Контура узнают об изменениях в учетной записи сотрудника во время входа в сервис. Из-за этого другие сотрудники не видят актуальной информации о пользователе сервиса.

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

Синхронизация происходит на основе списка групп, по которому вычитываются сотрудники из хранилища клиента. Данные в Контуре обновляются в соответствии с этим списком групп. При включении группы в синхронизацию оттуда будут вычитаны все сотрудники.

Примеры сценариев

Увольнение сотрудников, появление новых, изменения в орг. структуре и другие.

Требования

Есть два способа подключения:

On-premise синхронизатор — программное обеспечение, которое нужно подключить к своему Active Directory, используется протокол LDAP, LDAPS.
Облачный синхронизатор — программное обеспечение, запущенное на серверах Контура, подключается к облачному хранилищу клиента. Сейчас поддерживается синхронизация через GraphAPI.

В качестве протокола синхронизации реализовано собственное решение SCIM.

Спецификация SCIM

Создание или обновление пользователя

POST <address>/scim/users

Заголовки запроса

Content-Type	application/json
X-Kontur-Apikey	API-ключ, полученный через Кабинет Интегратора

Параметры запроса

providerId

Идентификатор интеграции, выдаваемый после подключения

Тело запроса

Requisites

KeyValueCollection — набор данных о пользователе из системы клиента согласно Claim Mapping

Ответ запроса

Метод должен всегда возвращать ответ в формате JSON.

Requisites

KeyValueCollection — набор данных о пользователе из системы Контура согласно Claim Mapping

POST /scim/users?providerId=best_company

HEADERS
Content-type: application/json
X-Kontur-Apikey: abcd-efgh-1234-5678

BODY
{
    "Requisites": {
        "given_name": "Maxim",
        "family_name": "Ivanov"
        "sub": "1234567890"
    }
}
 
RESPONSE
200 OK
Content-type: application/json
{
    "Requisites": {      
        "first_name": "Maxim",
        "second_name": "Ivanov"  
    }
}

Удаление пользователя

DELETE <address>/scim/users/{userId}

Заголовки запроса

X-Kontur-Apikey

API-ключ, полученный через Кабинет Интегратора.

Параметры пути

userId

Идентификатор пользователя в системе клиента.

Параметры запроса

providerId

Идентификатор интеграции, выдаваемый после подключения.

DELETE /scim/users/id_number_24?providerId=best_company

HEADERS
X-Kontur-Apikey: abcd-efgh-1234-5678

RESPONSE
200 OK

Получение пользователей

GET <address>/scim/users

Заголовки запроса

X-Kontur-Apikey

API-ключ, полученный через Кабинет Интегратора.

Параметры запроса

providerId	Идентификатор интеграции, выдаваемый после подключения.
take	Кол-во записей, которые нужно вернуть.
skip	Кол-во записей, которые нужно пропустить с начала.

Ответ запроса

Метод должен всегда возвращать ответ в формате JSON.

Count	Кол-во записей в ответе.
Users	Список из набора данных о пользователе из системы Контура согласно Claim Mapping.

GET /scim/users?providerId=best_company&take=1&skip=0

HEADERS
X-Kontur-Apikey: abcd-efgh-1234-5678

RESPONSE
200 OK
{
    "Requisites": {    
        "first_name": "Maxim",  
        "second_name": "Ivanov"  
  }
}

Настройка cинхронизатора

Облачная версия

Настройки для синхронизации сотрудников включаются на стороне Контура. Для синхронизации через GraphAPI от клиента требуется получить следующие данные:

Атрибут для связывания с сотрудником из внешнего хранилища, на основе которого будет происходить создание или обновление пользователя. Например, oid.
Атрибут для удаления сотрудников. Например, email.
Сlient_ID приложения.
Client_Secret приложения.
Tenant ID.
Список групп для синхронизации.
Атрибуты учетных записей, которые будут передаваться при синхронизации. Например, id; mail; displayName.

On-premise версия

Адреса SCIM сервера:

Для боевой среды: https://api.kontur.host/external-authentication/v1.0
Для тестовой среды: https://api.testkontur.ru/external-authentication/v1.0

Настройки синхронизатора хранятся в файле appsettings.json в папке с программой. Ниже представлен пример настроек.

{
  // Логирование происходит в файл, поэтому можно настроить 
  // количество и размер лог-файлов.
  "FileLogSettings": { 
    "MaxFiles": 100,
    "MaxSize" : 1000000000
  },
  "SynchronizationSettings": {
    "DemoEnabled": true, // демо режим, если true, то не будут отправляться запросы в Контур, а просто запишутся в файл
    "ApiKey": "", // апи ключ для взаимодействия с апи
    "ScimUrl": "", // url scim api
    "SynchronizationPeriodSeconds": 300,
    "UsersBoundAttribute": "", //атрибут, по которому проводится сопоставление списков пользователей
    "RemoveByRequisite": "", //атрибут, по которому будет блокироваться пользователь в системе Контура
    "AllowedClaims": [], //Список, разрешённых к получению атрибутов пользователя из системы Контура
    "GetUsersPageSize": 1000, // Количество запрашиваемых пользователей из системы Контура
    "DomainConfigurations": [ 
      {
        "LdapLogin": "", // Необязательное поле, если у запускающего пользователя есть права на чтение AD
        "LdapPassword": "", // Необязательное поле, если у запускающего пользователя есть права на чтение AD
        "Domain": "", // название домена
        "RequisitesToLoad": [ "sn", "displayname", "givenname", "sAMAccountName", "mail" ], // данные, которые буду выбраны из пользователя
        "UsersFilter": "(&(objectClass=user)(objectCategory=person)(!userAccountControl:1.2.840.113556.1.4.803:=2))", // по какому фильтру будут получены пользователи
        "GroupFilter": "(&(objectClass=group)(Name=GroupName))", // по какому фильтру будут получены группы. Если нужно получить всех пользователей, можно не указывать настройки GroupFilter и SortGroupsByRequisiteм
        "OrganizationUnitFilter": [],
        "PageSize": 1000, // Количество запрашиваемых пользователей из системы Клиента
        "SortUsersByRequisite": "mail", // реквизит, по которому будут сортироваться пользователи при поиске      
        "SortGroupsByRequisite": "Name", // реквизит, по которому будут сортироваться группы при поиске
        "EnableNestedGroups": true // Нужно ли при фильтрации по группам, учитывать вложенность одних групп в другие
      }
    ]
  }
}