Обработчики запросов#

Общие сведения#

Конфигурация любого обработчика включает параметр type, определяющий тип обработчика, описанный в данной конфигурации. Остальные параметры зависят от типа обработчика и описаны отдельно для каждого типа.

DEBUG обработчик#

Данный обработчик может использоваться для отладки или как заглушка. В ответ на любой запрос, полученный этим обработчиком будет возвращена HTML-страница с кодом ответа HTTP 200, содержащая информацию об исходном запросе:

  • HTTP-метод запроса

  • целевой URL

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

{
    "type": "debug",
    "name": "DEBUG" // Имя обработчика, будет включено в ответ на запрос
}

Пустой обработчик#

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

{
    "type": "no"
}

Обработчик Token Exchange#

Данный обработчик осуществляет обмен маркера, переданного с исходным запросом, на другой через Blitz Identity Provider и передачу запроса с новым маркером на целевой сервер. Исходный запрос должен включать заголовок Proxy-Authorization с Basic-авторизацией для прокси и заголовок Authorization, содержащий строку Bearer <Исходный маркер доступа>.

{
    "type": "token-exchange",
    "te": "http://localhost/blitz/oauth/te", // Адрес эндпоинта для обмена маркера
    "required-scopes": ["users", "groups"], // Список запрашиваемых scope в новом маркере. Если данный параметр не указан, то в новый маркер будут включены все scope, разрешенные правилом обмена.
    "cache-capacity": 1000 // Максимальное количество закэшированных маркеров, по умолчанию 1000
}

GraphQL-обработчик#

GraphQL-обработчик проверяет наличие у клиента права на выполнение GraphQL-запроса по заданным правилам доступа. Краткое описание логики обработчика:

  1. Выбрать правила, соответствующие запросу.

  2. Проверить условия всех правил типа DENY. Если хотя бы одно правило было выполнено, вернуть ошибку.

  3. Проверить условия всех правил типа ALLOW. Если хотя бы одно правило было выполнено, передать запрос на целевой сервер.

  4. Если для запроса не нашлось подходящих правил или не одно правило было выполнено, вернуть ошибку.

../_images/graphql-access-rules-selection.jpg 
{
  "type": "graph-ql",
  "name": "graphql-test", // Название обработчика. Совпадает с названием папки, содержащей описание правил
  "rules": ["Access to employee CRM"], // Правила, используемые обработчиком.
  "log-requests": "true" // Логирование полученных GraphQL-запросов, по умолчанию false
}

Описание правил хранится следующим образом:

blitz-keeper.conf
/graphl-test
  Access to employee CRM.conf

То есть в той же директории, что и конфигурационный файл blitz-keeper.conf должна находиться папка, название которой совпадает с именем GraphQL-обработчика. Внутри этой папки должнынаходится файлы с описанием правил. Название файлов соответствуют шаблону <Имя правила>.conf.

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

{
  "name": "Access to employee CRM", // Имя правила
  "enabled": true, // Признак включенности правила. По умолчанию true
  "type": "ALLOW", // Тип правила: ALLOW или DENY
  "conditions": { // Условия прохождения правил
    "user": { // Условия, относящиеся к пользователю
      "rights": [ // Права, которые должны быть у пользователя. Список может быть пустым
        "crm",
        "crm_chief"
      ],
      "groups": [ // Группы, в которые должен входить пользователя. Список может быть пустым
        "graphql-users"
      ],
      // Условия, которым должны удовлетворять аттрибуты пользователя. Список может быть пустым
      "attrs": [
        {
          "name": "chief", // Название аттрибута
          // Операция сравнения EQUAL или NOT_EQUAL
          // Для числовых значений также доступны операции: GREATER, GREATER_OR_EQUAL, LESS, LESS_OR_EQUAL
          "op": "EQUAL",
          "value": "true" // Значение, с которым будет проводиться сравнение
        }
      ]
    },
    "client": { // Условия, относящиеся к клиенту
      "rights": [
        "dashboard" // Права, которые должны быть у клиента. Список может быть пустым
      ],
      "tags": [
        "crm_ready" // Теги, которые должны быть у прав клиента. Список может быть пустым
      ]
    }
  },
  "target-operations": [ // Запросы, которым соответствует правило
    {
      "type": "QUERY", // Тип запроса QUERY или MUTATION
      "name": "getEmployeesTasks", // Название операции
      "fields": [ // Список полей верхнего уровня в запросе
        {
          "name": "tasks", // Название поля
          "args": [ // Опциональный список аргументов при обращении к полю
            "emp_id"
          ]
        }
      ]
    },
    {
      "type": "QUERY",
      // Для shorthand QUERY запросов имя операции может быть не указано
      // Но в этом случае нужно явно указать опцию shorthand=true
      "shorthand": "true",
      "fields": [
        {
          "name": "employees"
        }
      ]
    }
  ]
}

Цепочка обработчиков#

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

С помощью цепочек можно комбинировать логику обработчиков. Например, добавить в запрос новый маркер доступа с помощью Token Exchange обработчика, а затем проверить наличие прав на выполнение GraphQL-запроса с помощью GraphQL-обработчика. и

{
  "type": "chain",
  "handlers-chain": ["te", "graphql"] // Список ключей обработчиков из секции handlers (порядок важен). Описание секции handlers см. ниже.
}

Общие настройки обработчиков#

Общие настройки обработчиков могут вынесены в секцию handlers конфигурационного файла blitz-keeper. Это позволяет избежать дублирования при описании обработчиков в секции locations. Также обработчики, используемые в цепочках, должны быть полностью описаны в секции handlers. Примеры приведены ниже.

{
  "handlers": {
    "te-handler": {
      "type": "token-exchange",
      "te": "http://localhost/blitz/oauth/te"
    }
  },
  "services" : {
    "my-service" : {
      "display-name" : "Тест",
      "locations" : {
        "/foo" : {
          // Будут использоваться только настройки из секции handler.te-handler
          "handler": "te-handler",
          "methods": ["get"]
        },
        "/bar" : {
          // Будут использоваться настройки из секции handler.te-handler
          // Так же к ним будет добавлена опция required-scopes
          "handler": "te-handler",
          "required-scopes": ["bar"],
          "methods": ["get"]
        },
        "/spam" : {
          // Будут использоваться настройки из секции handler.te-handler
          // Опция te будет переопределена
          "handler": "te-handler",
          "te": "http://spam/blitz/oauth/te",
          "methods": ["get"]
        },
        "/standalone" : {
          // Будут использоваться только настройки из данной секции
          "type": "token-exchange",
          "te": "http://standalone/blitz/oauth/te",
          "required-scopes": ["standalone"],
          "methods": ["get"]
        }
      }
    }
  },
  // Остальные настройки...
}
Цепочка обработчиков#
{
  "handlers": {
    "te": {
      "type": "token-exchange",
      "te": "http://te"
    },
    "debug": {
      "type": "debug",
      "name": "DEBUG"
    },
    "chain": {
      "type": "chain",
      // Цепочка ссылается на обработчики te и debug, объявленные выше
      "handlers-chain": ["te", "debug"]
    }
  },
  // Остальные настройки...
}