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

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

• HTTP Basic;
• HTTP Bearer;
• API Key.

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

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

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

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

Пример спецификации для схемы с типом 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: b095c95icnvb********
        tag: "$latest"
        service_account_id: ajehfe84hhl********
        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;
};

secretToken — это авторизационные данные зарегистрированного пользователя или доверенного клиента, например Basic <base64(логин:пароль)> или Bearer <JWT-токен>.

КешированиеКеширование

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

Состав ключа кеширования зависит от типа авторизации и значения параметра authorizer_result_caching_mode.

Например, для следующей спецификации при выполнении запроса /user/123 ключ кеширования сформируется из значения /user/{id}, GET и значения заголовка Authorization. Если изменить значение параметра authorizer_result_caching_mode на uri, ключа кеширования сформируется из /user/123, GET и значения заголовка Authorization.

paths:
  /user/{id}:
    get:
      summary: Authorized operation with http basic security scheme
      operationId: httpBasicAuthorize
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: Numeric ID of the user to get
      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: b095c95icnvb********
        tag: "$latest"
        service_account_id: ajehfe84hhl********
        authorizer_result_ttl_in_seconds: 300
        authorizer_result_caching_mode: path

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

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

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

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

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