Top.Mail.Ru
Перейти к основному содержимому

Инструкция по API MultiDirectory

Объединённая инструкция по использованию API MultiDirectory.
Основана на старой документации и дополнена новыми возможностями (beta).

Общие сведения об API​

Ознакомиться с более подробным API MULTIDIRECTORY вы можете по ссылкам ниже:

Для взаимодействия используются HTTP-методы:

  • GET — для получения информации
  • POST — для создания сущности
  • PUT — для изменения сущности
  • DELETE — для удаления
  • PATCH — для частичного изменения сущности
Примечание!

Для подключения к API вашей MULTIDIRECTORY укажите ссылку в таком виде:

  • https://адрес_MultiDirectory/api/docs
  • https://адрес_MultiDirectory/api/redoc

Аутентификация​

Токен аутентификации​

POST /api/auth/token/get

Примечание

Логин передается в форматах:

  • DN
  • UPN
  • sAMAccountName

Пример запроса для получения токена аутентификации:

{
  "username": "<string>",
  "password": "<string>"
}

Пример ответа.

{
  "access_token": "123",
  "refresh_token": "456",
  "type": "bearer"
}
Время жизни токенов:
  • access_token – 20 минут
  • refresh_token – 14 суток

Новая версия

  • POST /auth/ – вход (username, password), возвращает cookie + сессию
  • DELETE /auth/ – выход
  • GET /auth/me – данные текущего пользователя
  • PATCH /auth/user/password – сброс пароля
  • GET /auth/setup – проверка необходимости первичной настройки
  • POST /auth/setup – выполнение первичной настройки (структура + политики)

LDAP API​

Основные операции доступны в обоих API.

Создание объекта​

POST /entry/add

Пример запроса для создания объектов:

{
  "entry": "ou=your_ou,ou=users,dc=your.domain,dc=ru",
  "attributes": [
    {
      "type": "objectClass",
      "vals": [ "top", "container", "organizationUnit" ]
    }
  ],
  "password": "you_password"
}
описание

entry - Distinguished Name (DN) создаваемой записи. attributes - массив объектов, каждый описывает атрибут LDAP-записи

  • type: название атрибута LDAP-записи
  • vals: массив значений для атрибута ["top", "container", "organizationUnit"] задают иерархию и возможности записи.

password - пароль для записи, если она представляет пользователя с доступом.

Обновление объекта​

Пример запроса для обновления:

PATCH /entry/update

{
  "object": "cn=your.object,ou=users,dc=your_domain,dc=ru",
  "changes": [
    {
      "operation": 0,
      "modification": {
        "type": "office",
        "vals": [ "TEST" ]
      }
    },
    {
      "operation": 1,
      "modification": {
        "type": "memberOf",
        "vals": [ "cn=old.group,ou=groups,dc=your_domain,dc=ru" ]
      }
    },
    {
      "operation": 2,
      "modification": {
        "type": "description",
        "vals": [ "Updated description" ]
      }
    }
  ]
}
описание

object — DN объекта, над которым выполняются изменения (например, пользователь).

Первый блок (operation: 0) добавляет новый атрибут office со значением "TEST".

Второй блок (operation: 1) удаляет у объекта членство в группе cn=old.group,ou=groups,dc=your_domain,dc=ru через атрибут memberOf.

Третий блок (operation: 2) заменяет существующее значение атрибута description на "Updated description".

Удаление объекта​

Пример запроса для удаления объекта:

DELETE /entry/delete

{
  "entry": "cn=your.object,ou=users,dc=your_domain,dc=ru"
}
Описание
  • entry — DN объекта, который нужно удалить (например, пользователь или группа).

Поиск объектов​

Пример запроса для поиска объекта:

POST /entry/search

{
  "base_object": "ou=users,dc=your_domain,dc=ru",
  "scope": 1,
  "deref_aliases": 0,
  "size_limit": 10,
  "time_limit": 0,
  "types_only": false,
  "filter": "(objectClass=user)",
  "attributes": [
    "cn",
    "mail",
    "sAMAccountName",
    "memberOf"
  ],
  "page_number": 1
}
Описание

base_object — DN с которого начинается поиск (например, ou=users,dc=your_domain,dc=ru).

scope:

  • 0 = base (только объект),

  • 1 = one (один уровень),

  • 2 = sub (включая все вложенные).

filter — LDAP-фильтр (например, (objectClass=user) или (cn=john*)).

attributes — список атрибутов, которые хотим получить.

page_number — для постраничного вывода.

Bulk-операции​

Bulk-операции — это методы API, которые позволяют выполнять однотипное действие сразу над несколькими объектами в каталоге за один запрос.

Пример запроса для массового обновление объектов:

  • PATCH /entry/update_many
{
  "objects": [
    "cn=user1,ou=users,dc=your_domain,dc=ru",
    "cn=user2,ou=users,dc=your_domain,dc=ru"
  ],
  "changes": [
    {
      "operation": 2,
      "modification": {
        "type": "description",
        "vals": [ "Updated in bulk" ]
      }
    }
  ]
}
описание

objects — список DN объектов, к которым применяются изменения.

operation: 2 (replace) — замена значения атрибута.

type — имя атрибута (например, description).

vals — новое значение.

Пример запроса для массового удлаения объектов:

  • POST /entry/delete_many – массовое удаление объектов
{
  "entries": [
    "cn=olduser1,ou=users,dc=your_domain,dc=ru",
    "cn=olduser2,ou=users,dc=your_domain,dc=ru",
    "cn=oldgroup,ou=groups,dc=your_domain,dc=ru"
  ]
}
описание

entries — список DN объектов, которые нужно удалить.

Kerberos API​

Настройка каталога для KDC/kadmin​

Пример запроса для настройки KDC/kadmin:

  • POST /kerberos/setup/tree
{
  "trusted_domain": "string",
  "trusted_kdc_addr": "string",
  "service_princ_password": "string"
}
описание

trusted_domain — домен, которому будет доверять Kerberos (например, YOUR.DOMAIN.RU).

trusted_kdc_addr — адрес KDC-сервера доверенного домена (обычно FQDN или IP).

service_princ_password — пароль сервисного principal для связи между каталогами.

Генерации keytab​

Пример запроса для генерации keytab:

  • POST /kerberos/ktadd – генерация keytab
[
  "string"
]
описание

Массив строк, где каждая строка — это имя principal, для которого нужно сгенерировать keytab.

Примеры (string) principals:

  • HTTP/server1.your_domain.ru@YOUR.DOMAIN.RU — для веб-сервера.

  • ldap/server2.your_domain.ru@YOUR.DOMAIN.RU — для LDAP-сервиса.

Добавления principal​

Пример запроса для добавления principal:

  • POST /kerberos/principal/add – добавить principal
{
  "primary": "string",
  "instance": "string"
}
описание

primary — имя principal (обычно это пользователь или сервис, напр. user1).

instance — уточнение/роль (например, admin, host/server1).

Полное имя principal формируется как primary/instance@REALM.

  • Пример: user1/admin@YOUR.DOMAIN.RU

Удаления principal​

Пример запроса для удаления principal:

  • DELETE /kerberos/principal/delete – удалить principal
{
  "principal_name": "string"
}
описание

principal_name — полное имя principal, который нужно удалить (включая realm).

  • Пример: principal_name: "user1/admin@YOUR.DOMAIN.RU"
  • POST /kerberos/setup – настройка KDC сервера
  • POST /kerberos/setup/trust – настройка доверия
  • GET /api/kerberos/status – статус Kerberos
  • PATCH /kerberos/principal/rename – переименовать principal
  • PATCH /kerberos/principal/reset – сброс пароля principal

DNS API​

Настройка DNS​

Пример запроса для настройки DNS (зоны):

  • POST /dns/setup
{
  "dns_status": "0",
  "domain": "string",
  "dns_ip_address": "198.51.100.42",
  "tsig_key": "string"
}
описание

dns_status — состояние DNS-сервиса (обычно "0" = выключен, "1" = включен).

domain — домен, для которого настраивается зона (например, md.ru).

dns_ip_address — IP-адрес DNS-сервера.

tsig_key — TSIG-ключ для защищённых обновлений DNS-записей.

Управление DNS-записями​

Пример запроса для управление DNS-записями:

  • GET/POST/DELETE/PATCH /dns/record
{
  "record_name": "string",
  "record_type": "string",
  "zone_name": "string",
  "record_value": "string",
  "ttl": 0
}
описание

record_name — имя записи (например, www, mail).

record_type — тип DNS-записи (A, AAAA, CNAME, MX, TXT, SRV).

zone_name — имя зоны, к которой принадлежит запись (md.ru).

record_value — значение записи (например, IP-адрес или доменное имя).

ttl — время жизни записи в секундах (time-to-live).

Управление DNS-зонами​

Пример запроса для управление DNS (зонами):

  • GET/POST/DELETE/PATCH /dns/zone
[
  {
    "name": "string",
    "type": "master",
    "records": [
      {
        "type": "string",
        "records": [
          {
            "name": "string",
            "value": "string",
            "ttl": 0
          }
        ]
      }
    ]
  }
]
описание

name — имя зоны (например, example.com).

type — тип зоны (master, slave, forward).

records — список записей в зоне.

type — тип записи (например, A, MX).

records.name — имя записи (например, www).

records.value — значение записи (IP или FQDN).

records.ttl — TTL для записи.

Добавление DNS-зоны​

Пример запроса для добавление DNS (зоны):

  • POST /dns/zone
{
  "zone_name": "string",
  "zone_type": "master",
  "nameserver": "string",
  "params": [
    {
      "name": "acl",
      "value": "string"
    }
  ]
}
описание

zone_name — имя зоны (md.ru).

zone_type — тип зоны (master, slave, forward).

nameserver — основной NS-сервер для зоны.

params — дополнительные параметры:

name — тип параметра (например, acl, forwarders).

value — значение (например, IP разрешённых вторичных DNS).

Перезапуск DNS-зоны​

Пример запроса для перезагрузки DNS зоны:

  • GET /dns/zone/reload/
{
  "zone_name": "string"
}
описание

zone_name — имя зоны, которая должна быть перезагружена (например, при изменении записей).

  • GET/PATCH /dns/server/options – опции сервера
  • GET /dns/server/restart – перезапуск сервера DNS
  • GET /dns/status – статус сервиса DNS
  • GET /dns/zone/forward – список forward-зон
  • POST /dns/forward_check – проверка forward-зоны

Сетевые политики​

Добавление сетевой политики​

Пример запроса для добавления сетевой политики:

  • POST /policy
{
  "netmasks": [
    "172.0.0.0/8"
  ],
  "name": "local network",
  "priority": 2,
  "groups": [],
  "mfa_status": 0,
  "mfa_groups": [],
  "is_http": true,
  "is_ldap": true,
  "is_kerberos": true,
  "bypass_no_connection": true,
  "bypass_service_failure": true,
  "http_session_ttl": 0,
  "ldap_session_ttl": 0
}
описание

netmasks — список подсетей (CIDR), на которые действует политика.

  • Пример: 172.0.0.0/8 — все адреса в диапазоне 172...*

name — имя политики (человекочитаемое, например "local network").

priority — приоритет политики (меньшее значение = выше приоритет).

groups — список групп пользователей, на которых распространяется политика (если пусто — для всех).

mfa_status — статус MFA (многофакторной аутентификации):

  • 0 — выключено

  • 1 — включено для выбранных групп

  • 2 — включено для всех

mfa_groups — список групп, для которых требуется MFA (если mfa_status = 1).

is_http — применять ли политику к HTTP-протоколу.

is_ldap — применять ли политику к LDAP-протоколу.

is_kerberos — применять ли политику к Kerberos.

bypass_no_connection — разрешать ли доступ, если нет соединения с сервисом.

bypass_service_failure — разрешать ли доступ, если сервис недоступен/ошибка.

http_session_ttl — время жизни HTTP-сессии в секундах (0 = по умолчанию).

ldap_session_ttl — время жизни LDAP-сессии в секундах (0 = по умолчанию).

  • DELETE /policy/{policy_id} – удалить политику
  • PATCH /policy/{policy_id} – включить/выключить
  • POST /policy/swap – поменять приоритеты

Schema API​

Создание атрибута​

Пример запроса для создания атрибута:

  • POST /schema/attribute_type
{
  "oid": "string",
  "name": "string",
  "syntax": "string",
  "single_value": true,
  "no_user_modification": true,
  "is_system": true
}
описание

oid — уникальный идентификатор атрибута (OID).

name — имя атрибута (например, customAttribute).

syntax — тип данных (например, Directory String, Integer).

single_value — если true, то только одно значение (иначе допускаются множественные).

no_user_modification — если true, то атрибут нельзя изменять.

is_system — системный ли это атрибут (обычно false для пользовательских).

Удаление атрибутов​

Пример запроса для удаления несколько атрибутов:

  • POST /schema/attribute_types/delete
{
  "attribute_types_names": [
    "string"
  ]
}
описание

attribute_types_names — список имён атрибутов, которые нужно удалить.

Удлаение класса объектов​

Пример запроса для удаления класса (массовое):

  • POST /schema/object_class/delete
{
  "object_classes_names": [
    "string"
  ]
}
описание

object_classes_names — список имён objectClass, которые нужно удалить.

Создание класса объектов​

Пример запроса для создания класса объектов:

  • POST /schema/object_class
{
  "oid": "string",
  "name": "string",
  "superior_name": "string",
  "kind": "STRUCTURAL",             # STRUCTURAL, AUXILARY, ABSRTART.
  "is_system": true,
  "attribute_type_names_must": [
    "string"
  ],
  "attribute_type_names_may": [
    "string"
  ]
}
описание

oid — уникальный идентификатор objectClass (OID).

name — имя objectClass (например, customObjectClass).

superior_name — базовый класс, от которого наследуется (обычно top).

kind — тип класса:

  • STRUCTURAL — структурный (создаёт объекты в каталоге),

  • AUXILARY — вспомогательный (добавляет свойства),

  • ABSTRACT — абстрактный (используется как основа).

is_system — системный ли это класс.

attribute_type_names_must — список обязательных атрибутов.

attribute_type_names_may — список необязательных атрибутов.

Лицензии​

Загрузка лицензии​

Пример запроса для загрузки лицензии:

  • POST /lic/
{
  "company_name": "name_Multidirectory",
  "license_key": "key",
  "domain": "domain_Multidirectory",
  "signature_valid": true,
  "max_users": 500,
  "issued_date": "2025-06-17",
  "valid_from": "2025-06-17",
  "valid_to": "2026-06-17",
  "active_users": 1,
  "is_active": true
}
описание

company_name — название компании, для которой выдана лицензия.

license_key — ключ лицензии.

domain — домен, к которому привязана лицензия.

signature_valid — флаг проверки подлинности лицензии (цифровая подпись).

max_users — максимально допустимое количество пользователей.

issued_date — дата выдачи лицензии.

valid_from — дата начала действия.

valid_to — дата окончания действия.

active_users — текущее количество активных пользователей.

is_active — статус лицензии (активна/не активна).

  • GET /lic/ – получить лицензию

Аудит​

  • GET /audit/policies – список политик аудита
  • PUT /audit/policy/{id} – обновление политики аудита
  • GET /audit/destinations – список направлений аудита
  • POST /audit/destination – создать новое направление
  • PUT/DELETE /audit/destination/{id} – изменить или удалить

Сессии​

  • GET /sessions – список активных пользователей
  • DELETE /sessions/{upn} – данные/удаление сессий по пользователю
  • GET/DELETE /sessions/{upn} – удалить конкретную сессию
  • GET /sessions/ip/{ip} – список сессий по IP

Многофакторная аутентификация (MFA)​

  • POST /multifactor/setup – задать параметры MFA
  • DELETE /multifactor/keys – удалить MFA данные
  • POST /multifactor/get – получить MFA креды
  • POST /multifactor/create – callback для MFA
  • POST /multifactor/connect – инициировать двухфакторную аутентификацию