Использование API Системы управления.

Использование API для Системы управления при создании чёрных/белых списков

API Системы управления используется для редактирования чёрных/белых списков, хранящихся в базе данных веб-интерфейса Системы управления. Это означает, что, например, при добавлении записи в тот или иной список, эта запись будет видна только в веб-интерфейсе. Чтобы запись заработала на шлюзах необходимо через веб-интерфейс выполнить публикацию, привязав измененный список к порталу или конфигурации, если список ещё не привязан. Использование API Системы управления подходит для не срочных блокировок и разрешений доступа пользователей.

Для добавления/удаления в чёрный/белый список, необходимо с устройства, находящегося вне кластера, послать на Систему управления один из описанных в данном разделе запросов.

Создание списка

Для создания черного или белого списка необходимо соответственно отправить PUT запрос на соответствующий URL:
  • Чёрные списки: https://<ngate>:7023/ext/api/blacklist/
  • Белые списки: https://<ngate>:7023/ext/api/whitelist/
В теле запроса необходимо передать JSON, содержащий следующие поля:
  • name – наименование создаваемого списка;
  • description – описание списка, необязательный параметр;
Пример запроса для чёрного списка:
  • /opt/cprocsp/bin/amd64/curl -q -k -v –X PUT https://<ngate>:7023/ext/api/blacklist/ -H 'Authentication: Bearer cn2…YX' -E 14e…6a -H ‘Content-Type: application/json’ -d '{"name": "BlackList", "description": "…"}'
Пример запроса для белого списка:
  • /opt/cprocsp/bin/amd64/curl -q -k -v –X PUT https://<ngate>:7023/ext/api/whitelist/ -H 'Authentication: Bearer cn2…YX' -E 14e…6a -H ‘Content-Type: application/json’ -d '{"name": "BlackList", "description": "…"}'

Где:

  • cn2…YX – API токен, должен иметь права на редактирование списков;
  • 14e…6a – отпечаток сертификата сервиса API.
В случае успеха возвращается 201 код и JSON следующего формата:
{
    "configurations": [],
    "description": "…",
    "id": 1,
    "name": "BlackList",
    "portals": [],
    "type": "blacklist"
}
Где:
  • description – ранее введенное описание списка;
  • configurations – список названий конфигураций, к которым привязан список;
  • id – идентификатор списка, который потребуется для удаления списка или для его получения;
  • name – ранее введенное наименование списка;
  • portals – список названий порталов, к которым привязан список;
  • type – тип списка: blacklist – черный список, whitelist – белый список.

Получение одного списка

Для получения данных о чёрном или белом списке необходимо отправить GET запрос на соответствующий URL:
  • Чёрные списки: https://<ngate>:7023/ext/api/blacklist/<id>/
  • Белые списки: https://<ngate>:7023/ext/api/whitelist/<id>/
Где:
  • <ngate> – имя машины;

  • <id> – идентификатор списка.

Запрос отправляется с пустым телом.

Пример запроса для чёрного списка:
  • /opt/cprocsp/bin/amd64/curl -q -k -v https://<ngate>:7023/ext/api/blacklist/1/ -H 'Authentication: Bearer cn2…YX' -E 14e…6a
Пример запроса для белого списка:
  • /opt/cprocsp/bin/amd64/curl -q -k -v https://<ngate>:7023/ext/api/whitelist/1/ -H 'Authentication: Bearer cn2…YX' -E 14e…6a

Где:

  • cn2…YX – API токен, должен иметь права на редактирование списков;
  • 14e…6a – отпечаток сертификата сервиса API.
В случае успеха возвращается 200 код и JSON следующего формата:
{
    "configurations": [],
    "description": "…",
    "id": 1,
    "name": "BlackList",
    "portals": [],
    "type": "blacklist"
    "entries": […]
}
Где:
  • description – ранее введенное описание списка;
  • configurations – список названий конфигураций, к которым привязан список;
  • id – идентификатор списка, который потребуется для удаления списка или для его получения;
  • name – ранее введенное наименование списка;
  • portals – список названий порталов, к которым привязан список;
  • type – тип списка: blacklist – черный список, whitelist – белый список;
  • entries – список записей в списке.

Получение всех списков

Для получения данных о черном или белом списке необходимо соответственно отправить GET запрос на соответствующий URL:
  • Чёрные списки: https://<ngate>:7023/ext/api/blacklist/
  • Белые списки: https://<ngate>:7023/ext/api/whitelist/
Где:
  • <ngate> – имя машины;

Запрос отправляется с пустым телом.

Пример запроса приведён для чёрного списка:
  • /opt/cprocsp/bin/amd64/curl -q -k -v https://<ngate>:7023/ext/api/blacklist/ -H 'Authentication: Bearer cn2…YX' -E 14e…6a
Пример запроса для белого списка:
  • /opt/cprocsp/bin/amd64/curl -q -k -v https://<ngate>:7023/ext/api/whitelist/ -H 'Authentication: Bearer cn2…YX' -E 14e…6a

Где:

  • cn2…YX – API токен, должен иметь права на редактирование списков;
  • 14e…6a – отпечаток сертификата сервиса API.
В случае успеха возвращается 200 код и JSON следующего формата:
{
    "configurations": [],
    "description": "…",
    "id": 1,
    "name": "BlackList",
    "portals": [],
    "type": "blacklist"    
}
{
        "configurations": [],
        "description": "Automatically generated Black List …",
        "id": 2,
        "name": " portal_name-API",
        "portals": [
            "portal_name"
        ],
        "type": "blacklist"
    }
Здесь находится список из словарей. Значение строк в каждом:
  • description – ранее введенное описание списка;
  • configurations – список названий конфигураций, к которым привязан список;
  • id – идентификатор списка, который потребуется для удаления списка или для его получения;
  • name – ранее введенное наименование списка;
  • portals – список названий порталов, к которым привязан список;
  • type – тип списка: blacklist – черный список, whitelist – белый список;

Удаление списка

Для получения данных о черном или белом списке необходимо соответственно отправить GET запрос на соответствующий URL:
  • Чёрные списки: https://<ngate>:7023/ext/api/blacklist/<id>/
  • Белые списки: https://<ngate>:7023/ext/api/whitelist/<id>/

Запрос отправляется с пустым телом.

Где:
  • <ngate> – имя машины;

  • <id> – идентификатор списка.

Пример запроса для чёрного списка:
  • /opt/cprocsp/bin/amd64/curl -q -k -v –X DELETE https://<ngate>:7023/ext/api/blacklist/1/ -H 'Authentication: Bearer cn2…YX' -E 14e…6a
Пример запроса для белого списка:
  • /opt/cprocsp/bin/amd64/curl -q -k -v –X DELETE https://<ngate>:7023/ext/api/whitelist/1/ -H 'Authentication: Bearer cn2…YX' -E 14e…6a

Где:

  • cn2…YX – API токен, должен иметь права на редактирование списков;
  • 14e…6a – отпечаток сертификата сервиса API.
В случае успеха возвращается 205 код и JSON следующего формата с сообщением об успешном удалении чёрного или белого списка:
{
    "detail": "BlackList deleted"
}

Добавление и удаление из списка по сертификату

Для добавления/удаления из черного или белого списка по сертификату необходимо отправить PATCH запрос на соответствующий URL:
  • Чёрные списки: https://<ngate>:7023/ext/api/blacklist/<id>/
  • Белые списки: https://<ngate>:7023/ext/api/whitelist/<id>/
Где:
  • <ngate> – имя машины;

  • <id> – идентификатор списка.

В качестве запроса необходимо указать действие action: добавить add или удалить remove. А в URL указать объект запроса: чёрный список blacklist или белый список whitelist.

Пример запроса для добавления в чёрный список:
  • /opt/cprocsp/bin/amd64/curl -q -k -v –X PATCH https://<ngate>:7023/ext/api/blacklist/1/ -H 'Authentication: Bearer cn2…YX' -E 14e…6a –F ‘action=”add”’ –F ‘file=@”cert.cer”’ –F ‘content_type=”serial”’ –F ‘comment=”…”’
Пример запроса для удаления из чёрного списка:
  • /opt/cprocsp/bin/amd64/curl -q -k -v –X PATCH https://<ngate>:7023/ext/api/blacklist/1/ -H 'Authentication: Bearer cn2…YX' -E 14e…6a –F ‘action=”remove”’ –F ‘file=@”cert.cer”’ –F ‘content_type=”serial”’ –F
Пример запроса для добавления в белый список:
  • /opt/cprocsp/bin/amd64/curl -q -k -v –X PATCH https://<ngate>:7023/ext/api/whitelist/1/ -H 'Authentication: Bearer cn2…YX' -E 14e…6a –F ‘action=”add”’ –F ‘file=@”cert.cer”’ –F ‘content_type=”serial”’ –F ‘comment=”…”’
Пример запроса для удаления из белого списка:
  • /opt/cprocsp/bin/amd64/curl -q -k -v –X PATCH https://<ngate>:7023/ext/api/whitelist/1/ -H 'Authentication: Bearer cn2…YX' -E 14e…6a –F ‘action=”remove”’ –F ‘file=@”cert.cer”’ –F ‘content_type=”serial”’ –F

Где:

  • cn2…YX – API токен, должен иметь права на редактирование списков;
  • 14e…6a – отпечаток сертификата сервиса API.
  • action – действие, которое необходимо выполнить с полем сертификата: добавить (add) или удалить (remove), обязательный параметр;
  • file – файл сертификата;
  • content_type – тип содержимого сертификата, который нужно добавить в черный список, опционально, значение может быть только одним из следующих: cert_serial – серийный номер; cert_sha1_fingerprint – SHA-1 хеш; cert_gost_fingerprint – ГОСТ хеш, является значением по умолчанию; upn – User Principle Name;
  • comment – комментарий к записи, который будет отображаться в журналах (logs), как причина блокировки. Опциональный параметр, может быть использован только при создании записи.
В случае успеха возвращается 200 код и JSON следующего формата:
{
    "comment": "…",
    "content_type": "cert_serial",
    "id": 1,
    "owner": "APITokenName",
    "owner_type": "api_mc",
    "user_identifier": "0x41C…AB"
}
Где:
  • comment – заданный ранее комментарий к записи;
  • content_type – тип атрибута, по которому пользователь будет блокироваться;
  • id – идентификатор записи;
  • owner – владелец, в случае, если запись была создана через API, поле хранит название использованного токена, в случае, если запись была создана через веб интерфейс, поле хранит имя пользователя;
  • owner_type – тип владельца, может быть одним из следующих: user – пользователь, создавший запись через веб-интерфейс; api_mc – владелец создал запись через API Системы управления; api_node – владелец создал запись через API-шлюз; crl – запись была создана из CRL.
  • user_identifier – значение выбранного атрибута, которое теперь будет блокироваться.
При успешном удалении записи возвращается 205 код и JSON следующего формата:
{
    “detail”: “User control entry deleted”
}

Добавление и удаление из списка по атрибуту

Для добавления/удаления из чёрного или белого списка по атрибуту необходимо отправить PATCH запрос на соответствующий URL:
  • Чёрные списки: https://<ngate>:7023/ext/api/blacklist/<id>/
  • Белые списки: https://<ngate>:7023/ext/api/whitelist/<id>/
Где:
  • <ngate> – имя машины;

  • <id> – идентификатор списка.

В качестве запроса необходимо указать действие action: добавить add или удалить remove. А в URL указать объект запроса: чёрный список blacklist или белый список whitelist.

Пример запроса для добавления в чёрный список:
  • /opt/cprocsp/bin/amd64/curl -q -k -v –X PATCH https://<ngate>:7023/ext/api/blacklist/1/ -H 'Authentication: Bearer cn2…YX' -E 14e…6a -H 'Content-Type: application/json' -d '{"action": "add", "login": "user1", “comment”: “…”}'
Пример запроса для удаления из чёрного списка:
  • /opt/cprocsp/bin/amd64/curl -q -k -v –X PATCH https://<ngate>:7023/ext/api/blacklist/1/ -H 'Authentication: Bearer cn2…YX' -E 14e…6a -H 'Content-Type: application/json' -d '{"action": "remove", "login": "user1"}'
Пример запроса для добавления в белый список:
  • /opt/cprocsp/bin/amd64/curl -q -k -v –X PATCH https://<ngate>:7023/ext/api/whitelist/1/ -H 'Authentication: Bearer cn2…YX' -E 14e…6a -H 'Content-Type: application/json' -d '{"action": "add", "login": "user1", “comment”: “…”}'
Пример запроса для удаления из белого списка:
  • /opt/cprocsp/bin/amd64/curl -q -k -v –X PATCH https://<ngate>:7023/ext/api/whitelist/1/ -H 'Authentication: Bearer cn2…YX' -E 14e…6a -H 'Content-Type: application/json' -d '{"action": "remove", "login": "user1"}'

Где:

  • cn2…YX – API токен, должен иметь права на редактирование списков;
  • 14e…6a – отпечаток сертификата сервиса API.
  • action – действие, которое необходимо выполнить с полем сертификата: добавить (add) или удалить (remove), обязательный параметр;
  • атрибут сертификата в формате "<параметр>": "значение": cert_serial – серийный номер сертификата; cert_sha1_fingerprint – SHA-1 хеш сертификата; cert_gost_fingerprint – ГОСТ хеш сертификата; upn – User Principle Name; login – логин пользователя; ldap_dn – LDAP DN пользователя;
  • comment – комментарий к записи, который будет отображаться в журналах (logs), как причина блокировки. Опциональный параметр, может быть использован только при создании записи.
В случае успеха при добавлении возвращается 200 код и JSON следующего формата:
{
    "comment": "…",
    "content_type": "login",
    "id": 2,
    "owner": "APITokenName",
    "owner_type": "api_mc",
    "user_identifier": "user1"
}
Где:
  • comment – заданный ранее комментарий к записи;
  • content_type – тип атрибута, по которому пользователь будет блокироваться;
  • id – идентификатор записи;
  • owner – владелец, в случае, если запись была создана через API, поле хранит название использованного токена, в случае, если запись была создана через веб интерфейс, поле хранит имя пользователя;
  • owner_type – тип владельца, может быть одним из следующих: user – пользователь, создавший запись через веб-интерфейс; api_mc – владелец, который создал запись через API Системы управления; api_node – владелец создал запись через API-шлюз; crl – запись была создана из CRL.
  • user_identifier – значение выбранного атрибута, которое теперь будет блокироваться.
При успешном удалении записи возвращается 205 код и JSON следующего формата:
{
    “detail”: “User control entry deleted”
}

Синхронизация списков со шлюзом

Особенности процесса синхронизации:
  • При синхронизации списков СУ со шлюзом собранные со шлюзов записи сохраняются в автоматически создаваемом в базе данных веб-интерфейса СУ чёрном/белом списке с названием вида <имя-портала>-API (в случае добавления на шлюзе записи для конкретного портала) или в список с названием вида <имя-активной-конфигурации>-API (в случае добавления записи на шлюзе в глобальный список). Автоматически создаваемый список сразу привязывается к порталу или конфигурации соответственно.
  • Синхронизация списков. В процессе синхронизации чёрных/белых списков со шлюзов (узлов NGate кластера) в уже существующий автоматически сгенерированный список (или в новый, если список ранее не был создан) добавляются только отсутствующие в этом списке записи. В то же время записи, существующие в списке, но удалённые на шлюзах, не будут автоматически удалены.
    Важно, что синхронизация чёрных/белых списков автоматически выполняется перед каждой публикацией конфигурации. Поэтому, если администратор хочет проверить пришедшие со шлюзов записи и, например, удалить некоторые из записей, то Администратор должен:
    1. выполнить публикацию конфигурации;
    2. только после успешной публикации изменять или удалять автоматический созданный чёрно/белый список по своим требованиям;
    3. после завершения внесения изменений нужно выполнить повторную публикацию;
    4. оставшиеся в автоматически созданных списках записи будут добавлены в предварительно очищенную базу данных сессий на шлюзах при запуске соответствующего сервиса.
Для синхронизации чёрных и белых списков со шлюзом необходимо отправить POST запрос на URL:
  • https://<ngate>:7023/ext/api/cluster/<id>/blackwhitelist/
В теле запроса необходимо указать действие action – синхронизация synchronize. Здесь <id> - идентификатор кластера.
Пример запроса:
  • /opt/cprocsp/bin/amd64/curl -q -k -v –X POST https://<ngate>:7023/ext/api/cluster/1/blackwhitelist/ -H 'Authentication: Bearer cn2…YX' -E 14e…6a -H 'Content-Type: application/json' -d '{"action": "synchronize"}'

Где:

  • cn2…YX – API токен, должен иметь права на редактирование списков;
  • 14e…6a – отпечаток сертификата сервиса API.
  • action – действие, которое необходимо выполнить, в данном случае синхронизация synchronize.

Получение списка кластеров

Для получения списка существующих кластеров необходимо отправить GET запрос на URL:
  • https://<ngate>:7023/ext/api/cluster/

Пример запроса: /opt/cprocsp/bin/amd64/curl -q -k -v –X GET https://<ngate>:7023/ext/api/cluster/ -H 'Authentication: Bearer cn2…YX' -E 14e…6a

Где:

  • <ngate> – имя машины;
  • cn2…YX – API токен, должен иметь права на редактирование списков;
  • 14e…6a – отпечаток сертификата сервиса API.
В случае успеха при добавлении возвращается 200 код и JSON следующего формата:
[
{
    "cluster_codename": "Cluster-of-afraid-mastiff",
    "comment": "…",
    "id": 1,
    "name": "Cluster1"
}
]
Где:
  • cluster_codename – кодовое имя кластера;
  • comment – описание кластера;
  • id – идентификатор кластера;
  • name – наименование кластера.