Использование API-шлюзов для чёрных/белых списков

• Записи в чёрные/белые списки при использовании API добавляются непосредственно в базу данных сессий на шлюзах, при этом в веб-интерфейсе системы управления такие записи изначально не отображаются. Поэтому для загрузки данных записей в веб-интерфейсе системы управления необходимо после загрузки непосредственно записей выполнить синхронизацию чёрных/белых списков.
• Собранные со шлюзов записи сохраняются в автоматически создаваемом в базе данных веб-интерфейса списке с названием <имя-портала>-API в случае добавления записи для конкретного портала или в список с названием <имя-активной-конфигурации>-API в случае добавления записи в глобальный список, автоматически создаваемый список сразу привязывается к порталу или конфигурации соответственно.

  Создание чёрных и белых списков

• Синхронизация списков. В процессе синхронизации чёрных/белых списков со шлюзов (узлов NGate кластера) в уже существующий автоматически сгенерированный список (или в новый, если список ранее не был создан) добавляются только отсутствующие в этом списке записи. В то же время записи, существующие в списке, но удалённые на шлюзах, не будут автоматически удалены.
  Важно, что синхронизация чёрных/белых списков автоматически выполняется перед каждой публикацией конфигурации. Поэтому, если администратор хочет проверить пришедшие со шлюзов записи и, например, удалить некоторые из записей, то Администратор должен:

  1. выполнить публикацию конфигурации;
  2. только после успешной публикации изменять или удалять автоматический созданный чёрно/белый список по своим требованиям;
  3. после завершения внесения изменений нужно выполнить повторную публикацию;
  4. оставшиеся в автоматически созданных списках записи будут добавлены в предварительно очищенную базу данных сессий на шлюзах при запуске соответствующего сервиса.

• Чёрные списки: https://<ngate>:7019/api/v1/blacklist
• Белые списки: https://<ngate>:7019/api/v1/whitelist

• action – обязательное действие, которое необходимо совершить с записью – добавить или удалить, соответственно «add» или «remove»;
• portal_name – (опциональное) hostname портала для применения списка. Если поле отсутствует, используется глобальный список;
• cert — (опциональное) может быть строкой, списком строк, структурой без attr, структурой с attr, списком таких структур.
  • attr (опциональное) может быть одна из строк: cert_serial, cert_sha1_fingerprint, cert_gost_fingerprint, upn или список из них. Если attr задан, то соответствующие атрибуты сертификата будут добавлены или удалены из списка, если не задан то сертификаты добавляются и удаляются из списка по отпечатку GOST2012 256bit;
  • text (обязательное) должен находиться текст сертификата. Сертификаты добавляются и удаляются из списка по отпечатку GOST2012 256bit, в случае если не указано что-то иное посредством задания attr;
  • Пример строки:

    {
        "cert": "MIICFjCCAcOgAwIBAgIMXyn2W15damn954qpMAoGCCqFAwcBAQMCMG0xITAfBgNV..."
      }

  • Пример списка строк:

    {
        "cert": [
          "MIICFjCCAcOgAwIBAgIMXyn2W15damn954qpMAoGCCqFAwcBAQMCMG0xITAfBgNV...",
          "MIICFjCCAcOgAwIBAgIMXyn2W15damn954qpMAoGCCqFAwcBAQMCMG0xITAfBgNV..."
        ]
      }

  • Пример структуры без attr:

    {
        "cert": {
          "text": "MIICFjCCAcOgAwIBAgIMXyn2W15damn954qpMAoGCCqFAwcBAQMCMG0xITAfBgNV..."
        }
      }

  • Пример структуры с attr:

    {
        "cert": {
          "attr": "cert_serial",
          "text": "MIICFjCCAcOgAwIBAgIMXyn2W15damn954qpMAoGCCqFAwcBAQMCMG0xITAfBgNV..."
        }
      }

  • Пример списка структур без attr

    {
        "cert": [
          {
            "text": "MIICFjCCAcOgAwIBAgIMXyn2W15damn954qpMAoGCCqFAwcBAQMCMG0xITAfBgNV..."
          },
          {
            "text": "MIICFjCCAcOgAwIBAgIMXyn2W15damn954qpMAoGCCqFAwcBAQMCMG0xITAfBgNV..."
          }
        ]
      }

  • Пример списка структур с attr

    {
        "cert": [
          {
            "attr": "cert_serial",
            "text": "MIICFjCCAcOgAwIBAgIMXyn2W15damn954qpMAoGCCqFAwcBAQMCMG0xITAfBgNV..."
          },
          {
            "attr": "cert_sha1_fingerprint",
            "text": "MIICFjCCAcOgAwIBAgIMXyn2W15damn954qpMAoGCCqFAwcBAQMCMG0xITAfBgNV..."
          }
        ]
      }

• cert_serial — (опциональное) строка или список строк — добавляет/удаляет из списка серийные номера сертификатов;
• cert_sha1_fingerprint — (опциональное) строка или список строк — добавляет/удаляет из списка отпечатки сертификатов;
• login — (опциональное) строка или список строк — добавляет/удаляет из списка логины пользователей;
• upn — (опциональное) строка или список строк — добавляет/удаляет из списка UPN пользователей;
• ldap_dn — (опциональное) строка или список строк — добавляет/удаляет из списка полные LDAP DN пользователей;
• client_ip — (опциональное) но может использоваться только при значении action равном add и на URL https://<ngate>:7019/api/v1/blacklist. Строка, содержащая VPN IP пользователя, которого необходимо добавить в черный список. Такой пользователь будет добавлен по всем возможным полям;
• sess_id — (опциональное) но может использоваться только при значении action равном add и на URL https://<ngate>:7019/api/v1/blacklist. Строка, содержащая ID сессии, пользователя которой необходимо добавить в черный список. Такой пользователь будет добавлен по всем возможным полям.

• /opt/cprocsp/bin/amd64/curl -q -k -v -X PATCH https://<ngate>:7019/api/v1/blacklist -H 'Authentication: Bearer cn2…YX' -H ‘Content-Type: application/json’ -E 14e…6a -d '{"action": "add", "login": "ivanov"}'

• /opt/cprocsp/bin/amd64/curl -q -k -v -X PATCH https://<ngate>:7019/api/v1/whitelist -H 'Authentication: Bearer cn2…YX' -H ‘Content-Type: application/json’ -E 14e…6a -d '{"action": "add", "login": "ivanov"}'

• cn2…YX – API токен, должен иметь права на редактирование списков;
• 14e…6a – отпечаток сертификата сервиса API.

{
    "blacklisted_by": {
        "cert_serail": "0x12…",
        "cert_sha1_fingerprint": "e9a7…",
        "cert_gost_fingerprint": "10a…"
    }
 }

[
  {
    "context": {
      "field": "some_unknown_field"
    },
    "message": "Unexpected field is added",
    "tag": "unexpected_field"
  }
]

• cert_error — ошибка чтения файла сертификата;
• parse_error — ошибка в анализе полей сертификата;
• value_duplication — попытка добавить в список дубликат записи;
• required_field_lost — в теле запроса отсутствует одно из обязательных полей.

• Чёрные списки: https://<ngate>:7019/api/v1/blacklist
• Белые списки: https://<ngate>:7019/api/v1/whitelist

• /opt/cprocsp/bin/amd64/curl -q -k -v -X PATCH https://<ngate>:7019/api/v1/blacklist -H 'Authentication: Bearer cn2…YX' -H ‘Content-Type: application/json’ -E 14e…6a -d '{"action": "remove", "login": "ivanov"}'

• /opt/cprocsp/bin/amd64/curl -q -k -v -X PATCH https://<ngate>:7019/api/v1/whitelist -H 'Authentication: Bearer cn2…YX' -H ‘Content-Type: application/json’ -E 14e…6a -d '{"action": "remove", "login": "ivanov"}'