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

Расширение x-yc-apigateway-authorizer:jwt используется внутри схем компонента securityScheme с типом OpenId Connect. Для авторизации HTTP-запроса API Gateway валидирует токен, а также проверяет его подпись при помощи публичных ключей, ссылка на которые указывается в расширении. Подробнее о стандарте JWT.

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

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

При этом указывать стандартный для спецификации OpenAPI 3.0 параметр openIdConnectUrl необязательно, если указан параметр jwksUri.

Объект IdentitySource может содержать следующие параметры:

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

Алгоритм авторизации вызова APIАлгоритм авторизации вызова API

Авторизация запросов с помощью JWT выполняется по следующему алгоритму:

1. API Gateway проверяет наличие токена в identitySource и удаляет из него префикс, если он указан в спецификации.

2. Если в спецификации разрешено кеширование результата авторизации и время жизни закешированной записи не истекло, API Gateway возвращает закешированный результат авторизации. Иначе — декодирует заголовок и тело токена.

3. API Gateway определяет адрес получения публичного ключа, необходимого для валидации электронной подписи JWS токена. Для этого используется значение параметра jwksUri. Если в спецификации не указан параметр jwksUri, API Gateway, используя значение стандартного для OpenAPI параметра openIdConnectUrl, делает запрос на указанный в параметре адрес и извлекает адрес публичных ключей из поля jwks_uri, расположенного в теле ответа.

4. Если в спецификации разрешено кеширование публичных ключей и время жизни закешированной записи не истекло, API Gateway использует адрес получения публичных ключей и идентификатор публичного ключа (задан в поле kid заголовка JWT), чтобы попытаться извлечь публичный ключ из локального кеша. Иначе — делает запрос на получение публичного ключа по адресу. Из тела ответа выбирается публичный ключ, идентификатор которого соответствует значению поля kid в заголовке JWT. Полученный публичный ключ кешируется, если это предусматривает спецификация.

5. API Gateway проверяет соответствие алгоритмов подписи токена и публичного ключа.

6. API Gateway проверяет подпись токена.

7. API Gateway проверяет поля тела токена:

   • exp — должно быть больше текущего времени в UTC.
   • nbf — должно быть меньше текущего времени в UTC.
   • iat — должно быть меньше текущего времени в UTC.
   • iss — должно иметь одно из значений, указанных в параметре спецификации issuers.
   • aud — должно иметь одно из значений, указанных в параметре спецификации audiences.

   Подробнее о полях читайте в стандарте JWT.

8. API Gateway проверяет, что в теле токена содержатся поля, указанные в параметре спецификации requiredClaims.

9. API Gateway проверяет, что у владельца токена (значение поля scope токена) есть все права, которые необходимы, чтобы получить запрашиваемый ресурс.

Если хотя бы одна из проверок не пройдена, API Gateway отказывает в доступе к запрашиваемому ресурсу и возвращает статус-код 403.

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

Пример спецификации расширения:

paths:
  /jwt/header/authorize:
    get:
      summary: Authorized operation with OpenId Connect security scheme and JWT in header
      operationId: httpOpenIdAuthorizeWithJwtInHeader
      security:
        - jwtHeaderAuthorizer:
          - profile:read
          - profile:write
      x-yc-apigateway-integration:
        type: dummy
        content:
          '*': "Authorized!"
        http_code: 200
        http_headers:
          'Content-Type': "text/plain"
components:
  securitySchemes:
    jwtHeaderAuthorizer:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
      x-yc-apigateway-authorizer:
        type: jwt
        authorizer_result_ttl_in_seconds: 3000
        jwkTtlInSeconds: 5000
        jwksUri: https://example.com/.well-known/jwks.json
        issuers:
          - https://example.com
          - https://example2.com
        audiences:
          - audience-1
          - audience-2
        identitySource:
          in: header
          name: Authorization
          prefix: "Bearer "
        requiredClaims:
          - role
          - email

В данном примере при обращении к ресурсу с названием /jwt/query/authorize API Gateway валидирует токен, находящийся в заголовке Authorization. Чтобы получить токен, из значения целевого заголовка удаляется префикс Bearer.

Для успешной авторизации:

• подпись токена и стандартные поля должны быть корректны;
• токен должен содержать поля role и email;
• значение поля iss должно быть равно https://example.com или https://example2.com;
• значение поля aud должно быть равно audience-1 или audience-2;
• в токене должны быть указаны права profile:read и profile:write.

Кеширование результата авторизацииКеширование результата авторизации

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

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

Например, для идентификатора ресурса в спецификации /user/{id} и в запросе /user/1234 при значении параметра authorizer_result_caching_mode, равном path, для формирования ключа кеширования будет использоваться /user/{id}, а при значении, равном uri, — /user/123.

Кеширование публичных ключейКеширование публичных ключей

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

При формировании ключа кеширования используется идентификатор публичного ключа (значение поля kid из заголовка JWT) и адрес, по которому получен публичный ключ.

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

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

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

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

• 401 Unauthorized — клиент не передал в HTTP-запросе авторизационные данные или передаваемый токен некорректен, например подпись невалидна, пропущены требуемые поля, истек срок жизни токена и прочее.
• 403 Forbidden — в токене отсутствуют права (поле scope), необходимые для доступа к запрашиваемому ресурсу.
• 500 Internal Server Error — API Gateway не смог получить конфигурацию OpenID Connect или публичный ключ или возвращенное значение имеет некорректную структуру.

Примеры использованияПримеры использования

• Развертывание веб-приложения с JWT-авторизацией в Yandex API Gateway и аутентификацией в Firebase