Подключиться
Yandex API Gateway

Расширение x-yc-apigateway-authorizer:function

Статья создана

Расширение x-yc-apigateway-authorizer:function используется внутри схем компонента securityScheme с типами:

Для авторизации HTTP-запроса API Gateway вызывает указанную в расширении функцию. Подробнее о структуре запроса и ответа.

Поддерживаемые параметры

В таблице ниже перечислены параметры, специфичные для API-шлюза сервиса API Gateway. Описание остальных параметров читайте в спецификации OpenAPI 3.0.

Параметр Тип Описание
function_id string Идентификатор функции.
tag string Необязательный параметр. Тег версии функции. Значение по умолчанию — $latest.
В tag осуществляется подстановка параметров.
service_account_id string Идентификатор сервисного аккаунта. Используется для авторизации при обращении к функции. Если параметр не указан, используется значение верхнеуровнего параметра service_account_id. Если верхнеуровнего параметра нет, функция вызывается без авторизации.
authorizer_result_ttl_in_seconds int Необязательный параметр. Время, в течение которого ответ функции хранится в локальном кеше API Gateway. Если параметр не указан, ответ не кешируется.

Спецификация расширения

Пример спецификации для схемы с типом HTTP Basic:

paths:
  /http/basic/authorize:
    get:
      summary: Authorized operation with http basic security scheme
      operationId: httpBasicAuthorize
      security:
        - httpBasicAuth: [ ]
      x-yc-apigateway-integration:
        type: dummy
        content:
          '*': "Authorized!"
        http_code: 200
        http_headers:
          'Content-Type': "text/plain"
components:
  securitySchemes:
    httpBasicAuth:
      type: http
      scheme: basic
      x-yc-apigateway-authorizer:
        type: function
        function_id: b095c95icnvbuf4v755l
        tag: "$latest"
        service_account_id: ajehfe41hhliq4n93q1g
        authorizer_result_ttl_in_seconds: 300

Структура запроса

JSON-структура запроса к функции:

{
    "resource": <ресурс, соответствующий запросу в спецификации>,
    "path": <фактический путь запроса>,
    "httpMethod": <название HTTP-метода>,
    "headers": <словарь со строковыми значениями HTTP-заголовков>,
    "queryStringParameters": <словарь queryString-параметров>,
    "pathParameters": <словарь значений параметров пути запроса>,
    "requestContext": <словарь с контекстом запроса>,
    "cookies": <словарь, содержащий cookies запроса>
}

Структура ответа

JSON-структура ответа:

{
    "isAuthorized": <результат авторизации — true или false>,
    "context": <словарь с контекстом авторизации>
}

Пример функции

Пример функции, в которой используется структура ответа с контекстом авторизации:

exports.handler = async function (event, context) {
    let response = {
        "isAuthorized": false
    };

    if (event.headers.authorization === "secretToken") {
        response = {
            "isAuthorized": true,
            "context": {
                "stringKey": "value",
                "numberKey": 1,
                "booleanKey": true,
                "arrayKey": ["value1", "value2"],
                "mapKey": {"value1": "value2"}
            }
        };
    }

    return response;
};

Кеширование

Ответ функции сохраняется в локальном кеше API Gateway, если в расширении задан параметр authorizer_result_ttl_in_seconds. При формировании ключа кеширования для схемы:

  • с типами HTTP Basic и HTTP Bearer используются path, operation(HTTP-метод) и заголовок Authorization;
  • с типом API Key используются path, operation(HTTP-метод) и API-ключ.

Если в течение времени, указанного в параметре authorizer_result_ttl_in_seconds, повторно придет HTTP-запрос с аналогичными path, operation и авторизационными данными, API Gateway использует ответ, сохраненный в кеше, и не будет вызывать функцию.

Контекст авторизации

Если авторизация прошла успешно, при вызове другой пользовательской функции контекст авторизации будет передан в запросе внутри поля requestContext.authorizer. Контекст авторизации может содержать данные, идентифицирующие пользователя, от которого пришел HTTP-запрос.

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

  • 401 Unauthorized — клиент не передал в HTTP-запросе авторизационные данные, которые определены схемой (например, заголовок Authorization для схемы с типом HTTP Basic).
  • 403 Forbidden — API Gateway неуспешно вызвал функцию ("isAuthorized": false).
  • 500 Internal Server Error — API Gateway не смог вызвать функцию или получил от нее ответ с некорректной структурой.
В этой статье: