Yandex Cloud
  • Сервисы
  • Решения
  • Почему Yandex Cloud
  • Сообщество
  • Тарифы
  • Документация
  • Связаться с нами
Подключиться
Language / Region
Проект Яндекса
© 2023 ООО «Яндекс.Облако»
Yandex API Gateway
  • Начало работы
  • Пошаговые инструкции
    • Все инструкции
    • Создание API-шлюза
    • Изменение API-шлюза и его спецификации
    • Подключение домена
    • Удаление API-шлюза
    • Мониторинг
    • Просмотр журнала выполнения
  • Практические руководства
    • Все практические руководства
    • Развертывание веб-приложения с использованием Java Servlet API
    • Разработка навыка Алисы и сайта с авторизацией
    • Разработка Slack-бота
    • Разработка Telegram-бота
    • Разработка пользовательской интеграции
    • Разработка CRUD API для сервиса фильмов
    • Работа с API-шлюзом по протоколу WebSocket
  • Концепции
    • Взаимосвязь ресурсов сервиса
    • Расширения спецификации
      • Обзор
      • Статический ответ
      • Вызов функции
      • Интеграция с Serverless Containers
      • Обращение по HTTP
      • Интеграция с Object Storage
      • Интеграция с DataSphere
      • Интеграция с Data Streams
      • Интеграция с Message Queue
      • Интеграция с YDB
      • Жадные параметры
      • Обобщенный HTTP-метод
      • Авторизация с помощью функции
      • Поддержка протокола WebSocket
    • Квоты и лимиты
  • Управление доступом
  • Правила тарификации
  • Справочник API
    • Аутентификация в API
    • gRPC (англ.)
      • Overview
      • ApiGatewayService
      • OperationService
    • REST (англ.)
      • Overview
      • ApiGateway
        • Overview
        • addDomain
        • create
        • delete
        • get
        • getOpenapiSpec
        • list
        • listAccessBindings
        • listOperations
        • removeDomain
        • setAccessBindings
        • update
        • updateAccessBindings
  • Справочник API Websocket
    • Аутентификация в API
    • gRPC (англ.)
      • Overview
      • ConnectionService
    • REST (англ.)
      • Overview
      • Connection
        • Overview
        • disconnect
        • get
        • send
  • Вопросы и ответы
  1. Концепции
  2. Расширения спецификации
  3. Авторизация с помощью функции

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

Статья создана
Yandex Cloud
,
улучшена
AShipulin
  • Поддерживаемые параметры
  • Спецификация расширения
  • Структура запроса
  • Структура ответа
  • Пример функции
  • Кеширование
  • Контекст авторизации
  • Возможные ошибки

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

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

Для авторизации 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: ajehfe84hhlaq4n59q1
        authorizer_result_ttl_in_seconds: 300

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

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

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

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

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

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

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

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

JavaScript
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. При формировании ключа кеширования для схемы:

  • с типами 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 не смог вызвать функцию или получил от нее ответ с некорректной структурой.

Была ли статья полезна?

Language / Region
Проект Яндекса
© 2023 ООО «Яндекс.Облако»
В этой статье:
  • Поддерживаемые параметры
  • Спецификация расширения
  • Структура запроса
  • Структура ответа
  • Пример функции
  • Кеширование
  • Контекст авторизации
  • Возможные ошибки