---
canonical: https://docs.ideco.ru/v22/ru/ngfw/api/active-directory-api
---

# Active Directory/Samba DC

::: page-constructor
blocks:
  - type: content-layout-block
    textContent:
      buttons:
        - text: Классический VCE
          theme: action
          width: 'auto'
        - text: Высокопроизводительный VCE
          theme: outlined
          url: https://docs.ideco.ru/api/vpp-v22/ru/ngfw/users/ad/
          width: 'auto'
        - text: Документация
          theme: outlined
          url: https://docs.ideco.ru/v22/ru/ngfw/settings/users/active-directory/
          width: 'auto'
    resetPaddings: false
    textWidth: l
    size: m
    centered: false
:::

{% note info "" %}

Длина комментариев (`comment`) при API-запросах ограничена 255 символами.

{% endnote %}

## Управление интеграцией с доменами AD

{% cut "Получение статуса работы службы ad_backend" %}

```
GET /ad_backend/status
```

**Ответ на успешный запрос:**

```json5
{ 
    "msg": ["string"]
}
```

* `msg` - список ошибок.

Возможные ошибки:

* **no_license** - Лицензия отсутствует | License is not available

{% endcut %}

{% cut "Ввод NGFW в домен" %}

```
POST /ad_backend/domains
```

**Json-тело запроса:**

```json5
{
    "name": "string", 
    "computer_name": "string",
    "dns_ips": ["string"],
    "user": "string",
    "password": "string",
    "ldap_paths": ["string"],
    "manual_kdc_servers": ["string"],
    "upn_suffixes": ["string"]
}
```

* `name` - имя домена;
* `computer_name` - имя компьютера (NGFW) в домене;
* `dns_ips` - список IP-адресов контроллеров домена;
* `user` - имя пользователя, имеющего права на ввод компьютера в домен;
* `password` - пароль пользователя `user`;
* `ldap_paths` - список LDAP-путей для поиска групп. Максимум 10 путей. Максимальная длина строки - 1024 символа. Если список пуст, поиск идет по всему домену. Указание путей ограничивает импорт только этими группами;
* `manual_kdc_servers` - список DC-серверов. Может быть пустым по умолчанию. Максимум 30 серверов. Максимальная длина строки - 1024 символа.
* `upn_suffixes` - список альтернативных UPN-суффиксов. Может быть пустым. Указывается, если пользователям назначены UPN-суффиксы, отличающиеся от DNS-имени домена, и требуется аутентификация по UPN.

**Ответ на успешный запрос:** 

```json5
{
    "id": "string"
}
```

* `id` - идентификатор домена.

{% endcut %}

{% cut "Получение списка присоединенных доменов" %}

```
GET /ad_backend/domains
```

**Ответ на успешный запрос:**

```json5
[
    {
        "id": "string",
        "name": "string",  
        "computer_name": "string",
        "dns_ips": ["string"], 
        "user": "string",
        "ldap_paths": ["string"],
        "manual_kdc_servers": ["string"],
        "upn_suffixes": ["string"]
    },
    ...
]
```

* `id` - идентификатор домена;
* `name` - имя домена;
* `computer_name` - имя компьютера (NGFW) в домене;
* `dns_ips` - список IP-адресов контроллеров домена;
* `ldap_paths` - список LDAP-путей для поиска групп. Максимум 10 путей. Максимальная длина строки - 1024 символа. Если список пуст, поиск идет по всему домену. Указание путей ограничивает импорт только этими группами;
* `manual_kdc_servers` - список DC-серверов. Может быть пустым по умолчанию. Максимум 30 серверов. Максимальная длина строки - 1024 символа.
* `upn_suffixes` - список альтернативных UPN-суффиксов. Может быть пустым. Указывается, если пользователям назначены UPN-суффиксы, отличающиеся от DNS-имени домена, и требуется аутентификация по UPN.

{% endcut %}

{% cut "Получение статуса присоединенных доменов" %}

```
GET /ad_backend/domains/status
```

**Ответ на успешный запрос:**

```json5
[
  {
    "id": "string",
    "status": "string"
  }
]
```

* `id` - идентификатор домена;
* `status` - статус доступности домена. Может принимать одно из значений: 
  * `enabled` - включено;
  * `disabled` - выключено;
  * `unknown` - неизвестно.

{% note info "" %}

Статусы могут появляться не сразу после интеграции. Если для нужного домена статуса не оказалось, то для домена указывается статус `unknown`.

{% endnote %}

{% endcut %}

{% cut "Выполнение "переинтеграции" с AD" %}

```
PUT /ad_backend/domains/<id домена>
```

**Json-тело запроса:**

```json5
{
    "computer_name": "string",
    "dns_ips": ["string"],
    "user": "string",
    "password": "string",
    "ldap_paths": ["string"],
    "manual_kdc_servers": ["string"],
    "upn_suffixes": ["string"]
}
```

* `computer_name` - имя компьютера (NGFW) в домене;
* `dns_ips` - список IP-адресов контроллеров домена;
* `user` - имя пользователя, имеющего права на ввод компьютера в домен;
* `password` - пароль пользователя `user`;
* `ldap_paths` - список LDAP-путей для поиска групп. Максимум 10 путей. Максимальная длина строки - 1024 символа. Если список пуст, поиск идет по всему домену. Указание путей ограничивает импорт только этими группами;
* `manual_kdc_servers` - список DC-серверов. Может быть пустым по умолчанию. Максимум 30 серверов. Максимальная длина строки - 1024 символа.
* `upn_suffixes` - список альтернативных UPN-суффиксов. Может быть пустым. Указывается, если пользователям назначены UPN-суффиксы, отличающиеся от DNS-имени домена, и требуется аутентификация по UPN.

**Ответ на успешный запрос:** 200 OK

{% endcut %}

{% cut "Удаление интеграции с доменом" %}

```
DELETE /ad_backend/domains/<id домена>
```

**Ответ на успешный запрос:** 200 OK

При выводе NGFW из домена удаляются все настройки интеграции с контроллером домена, 
а также все настройки синхронизируемых групп. При этом сами
группы и пользователи в них становятся локальными.

В AD созданный для NGFW компьютер не удаляется.

{% endcut %}

{% cut "Проверка подключения к интегрированному домену" %}

```
GET /ad_backend/check_domain/<id домена>
```

**Ответ на успешный запрос:**

```json5
{
    "ad_status": "enabled" | "disabled" | "unknown"
}
```

* `ad_status` - статус подключения к домену:
  * `enabled` - установлено;
  * `disabled` - отключено или не настроено;
  * `unknown` - не определено.

Получение подключения к интегрированному домену по его id. Если статус подключения при ручной проверке изменился, то он также обновится и в `etcd`. То есть при следующем запросе списка доменов придет актуальный статус и не требуется ждать следующей ручной или автоматической (раз в 15 минут) проверки. В AD созданный для NGFW компьютер не удаляется.

{% endcut %}

{% cut "Проверка возможности интегрироваться с новым доменом" %}

```
POST /ad_backend/check_domain
```

**Json-тело запроса:**

```json5
{
    "name": "string",
    "computer_name": "string",
    "dns_ips": ["string"],
    "user": "string",
    "password": "string",
    "ldap_paths": ["string"],
    "manual_kdc_servers": ["string"]
}
```

`name` - имя домена;
`computer_name` - имя компьютера или NGFW в домене;
`dns_ips` - список IP-адресов контроллеров домена;
`user` - имя пользователя, имеющего права на ввод компьютера в домен;
`password` - пароль пользователя, имеющего права на ввод компьютера в домен;
`ldap_paths` - список LDAP-путей, по которым будет происходит поиск групп безопасности. Максимум 10 путей. Может быть пустым. Максимальная длина строки 1024 символа.
`manual_kdc_servers` - Список DC-серверов. Максимум 30 серверов. По умолчанию - пустой список. Максимальная длина строки 1024 символа.

**Ответ на успешный запрос:**

```json5
{
    "ad_status": "enabled" | "disabled" | "unknown"
}
```

* `ad_status` - статус подключения к домену:
  * `enabled` - домен доступен;
  * `disabled` - домен недоступен;
  * `unknown` - не определено.

{% endcut %}

## Авторизация

{% cut "Получение информации о пользователе по его guid и domain_id" %}

Запрос используется в связке с запросом **Обновление информации о пользователе по его guid и domain_id**.

```
GET /ad_backend/auth/user_info_by_guid?user_guid=user_guid&domain_id=domain_id
```

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

* `user_guid` - GUID пользователя AD;
* `domain_id` - идентификатор домена, в котором состоит пользователь.

**Ответ на успешный запрос:**

```json5
{
  "info": {
     "sec_groups": ["string"] | null,
     "ldap_filters": ["string"] | null,
     "domain_name": "string",
     "domain_id": "string",
     "login": "string",
     "upn": "string" | null,
     "name": "string",
     "enabled": true | false,
     "ldap_guid": "string",
     "phone_number": "string",
     "comment": "string", 
     "account_expire_date": "integer" | null, 
     "password_expire_date": "integer" | null
  },
  "error": "integer" | null,
  "is_updating": true | false
}
```

* `info` - информация о пользователе (возвращается `null` в случае ошибки):
  * `sec_groups` - список алиасов групп безопасности;
  * `ldap_filters` - список LDAP-фильтров;
  * `domain_name` - название домена;
  * `domain_id` - идентификатор домена;
  * `login` - логин пользователя;
  * `upn` - UPN-суффикс, может быть не задан;
  * `name` - имя пользователя;
  * `enabled` - состояние включенности пользователя на контроллере домена;
  * `ldap_guid` - уникальный идентификатор пользователя на контроллере домена;
  * `phone_number` - номер телефона пользователя. Может быть `None` если не указан или задан неверно;
  * `comment` - описание пользователя из AD, урезанное до 256 символов;
  * `account_expire_date` - дата истечения действия учетной записи в формате `YYYYMMDDhhmmss`, `null` - если не задана;
  * `password_expire_date` - дата истечения действия пароля в формате `YYYYMMDDhhmmss`, `null` - если не задана.
* `error` - код ошибки, если произошла ошибка при получении информации. `null` - если ошибки не было. Возможные коды ошибок:
  * `1` - `USER_NOT_FOUND` - пользователь не найден;
  * `2` - `DC_UNAVAILABLE` - контроллер домена недоступен;
  * `3` - `TIMEOUT` - превышение времени ожидания;
  * `-1` - `UNKNOWN` - неизвестная ошибка;  
* `is_updating` - статус процесса обновления:
  * `true` - запущен;
  * `false` - не запущен.

{% endcut %}

{% cut "Обновление информации о пользователе по его guid и domain_id" %}

```
POST /ad_backend/auth/user_info_by_guid
```

**Json-тело запроса:**

```json5
{
    "user_guid": "string",
    "domain_id": "string"
}
```

**Ответ на успешный запрос:** 200 OK

{% endcut %}

## Управление настройками службы

{% cut "Получение настроек авторизации" %}

```
GET /ad_backend/settings
```

**Ответ на успешный запрос:**

```json5
{
    "authorization_by_logs": true | false,
    "allowed_objects": ["string"]
}
```

* `authorization_by_logs` - опция **Авторизация через журнал безопасности Active Directory**:
  * `true` - включена;
  * `false` - выключена.
* `allowed_objects` - список ID объектов, которым разрешена авторизация по логам.

{% endcut %}

{% cut "Изменение настроек авторизации" %}

```
PATCH /ad_backend/settings
```

**Json-тело запроса:**

```json5
{
    "authorization_by_logs": true | false,
    "allowed_objects": ["string"]
}
```

* `authorization_by_logs` - опция **Авторизация через журнал безопасности Active Directory**:
  * `true` - включена;
  * `false` - выключена.
* `allowed_objects` - список ID объектов, которым разрешена авторизация по логам.

**Ответ на успешный запрос:** 200 OK

{% endcut %}

## Получение информации об объектах контроллера домена

{% cut "Получение дерева OU в заданном домене" %}

```
GET /ad_backend/domains/<id домена>/tree
```

**Ответ на успешный запрос:**

```json5
[
    {
        "name": "string",
        "guid": "string",
        "parent_guid": "string" | null
    }
    ...
]
```

* `name` - отображаемое имя группы;
* `guid` - objectGUID группы;
* `parent_guid` - objectGUID родительской группы.

Дерево представлено в виде линейного списка со всеми узлами. У каждого узла есть `guid` и `parent_guid`.

{% endcut %}

{% cut "Получение списка Forward-зон контроллера домена" %}

```
GET /ad_backend/forward_zones
```

**Ответ на успешный запрос:**

```json5
[
    {
        "id":  "string",
        "name": "string",
        "servers": ["string"],
        "enabled": true | false,
        "comment": "string"
    },
    ...
]
```

* `id` - идентификатор зоны;
* `name` - название зоны;
* `servers` - список IP-адресов DNS-серверов;
* `enabled` - статус зоны:
  * `true` - включена;
  * `false` - выключена.
* `comment` - комментарий, может быть пустым.

{% endcut %}

{% cut "Получение алиасов групп безопасности AD" %}

```
GET /security_groups
```

При запросе используется заголовок `x-ideco-etag`. Если заголовок не будет указан, то считается, что значение заголовка равно `0`.

**Ответ на успешный запрос:**

```json5
[
    {
        "id": "string",
        "type": "security_group",
        "title": "string",
        "domain_id": "strings"
    },
    ...
]
```

* `id` - идентификатор группы безопасности;
* `type` - тип, `security_group`;
* `title` - имя группы;
* `domain_id` - идентификатор домена из таблицы интеграций AD.

Возвращает список алиасов групп безопасности AD, формат аналогичен получению списка всех алиасов. Если переданное значение в заголовоке запроса `x-ideco-etag` совпадает со значением в БД, то будет возвращён пустой список алиасов. В заголовке ответа `x-ideco-etag` возвращается текущий целочисленный etag из БД.

{% endcut %}

{% cut "Получение алиасов пользователей AD" %}

```
GET /ad_users
```

При запросе используется заголовок `x-ideco-etag`. Если заголовок не будет указан, то считается, что значение заголовка равно `0`.

**Ответ на успешный запрос:**

```json5
[
    {
        "id": "string",
        "type": "ad_user",
        "title": "string",
        "domain_id": "strings"
    },
    ...
]
```

* `id` - идентификатор пользователя;
* `type` - тип, `ad_user`;
* `title` - имя пользователя;
* `domain_id` - идентификатор домена из таблицы интеграций AD.

Возвращает список алиасов групп безопасности AD, формат аналогичен получению списка всех алиасов. Если переданное значение в заголовоке запроса `x-ideco-etag` совпадает со значением в БД, то будет возвращён пустой список алиасов. В заголовке ответа `x-ideco-etag` возвращается текущий целочисленный etag из БД.

{% endcut %}
