Обзор политик JWS и JWT

Вы просматриваете документацию Apigee Edge .
Перейдите к документации Apigee X. информация

В этом разделе представлена ​​общая информация о JWT (веб-токен JSON) и JWS (веб-подпись JSON), а также политиках Apigee JWS/JWT, которые могут представлять интерес для разработчиков прокси-серверов Apigee.

Введение

И JWS, и JWT обычно используются для обмена утверждениями или утверждениями между подключенными приложениями. Политики JWS/JWT позволяют прокси-серверам Edge API:

  • Создайте подписанный JWT или JWS .
  • Проверьте подписанный JWT или JWS и утверждения в JWS/JWT.
  • Декодируйте подписанный JWT или JWS без проверки подписи.

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

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

Видео

Посмотрите короткое видео для быстрого ознакомления с JWT. Хотя это видео посвящено созданию JWT, многие концепции одинаковы и для JWS.

Какое короткое видео, чтобы узнать больше о структуре JWT.

Варианты использования

Вы можете использовать политики JWS/JWT для:

  • Создайте новый JWS/JWT на стороне прокси-сервера или целевой конечной точки пограничного прокси-сервера. Например, вы можете создать поток запросов прокси, который генерирует JWS/JWT и возвращает его клиенту. Или вы можете спроектировать прокси-сервер так, чтобы он генерировал JWS/JWT в целевом потоке запросов и присоединял его к запросу, отправленному целевому объекту. Затем эти утверждения будут доступны, что позволит серверным службам применить дальнейшую обработку безопасности.
  • Проверяйте и извлекайте утверждения из JWS/JWT, полученные из входящих запросов клиентов, из ответов целевых служб, из ответов политики вызова службы или из других источников. Edge проверит подпись на JWS/JWT независимо от того, был ли JWS/JWT сгенерирован третьей стороной или самим Edge, используя алгоритмы RSA или HMAC.
  • Декодируйте JWS/JWT. Декодирование наиболее полезно при использовании совместно с политикой Verify JWS/JWT, когда значение утверждения (JWT) или заголовка (JWS/JWT) из JWS/JWT должно быть известно перед проверкой JWS/JWT.

Части JWS/JWT

Подписанный JWS/JWT кодирует информацию в трех частях, разделенных точками: заголовок, полезные данные и подпись:

header.payload.signature
  • Политика «Создать JWS/JWT» создает все три части.
  • Политика Verify JWS/JWT проверяет все три части.
  • Политика декодирования JWS/JWT проверяет только заголовок и полезные данные.

JWS также поддерживает отдельный формат, в котором полезные данные из JWS отсутствуют:

header..signature

При отключенном JWS полезные данные отправляются отдельно от JWS. Вы используете элемент <DetachedContent> политики Verify JWS, чтобы указать необработанные, незакодированные полезные данные JWS. Затем политика Verify JWS проверяет JWS, используя заголовок и подпись в JWS, а также полезные данные, указанные элементом <DetachedContent> .

Чтобы узнать больше о токенах и о том, как они кодируются и подписываются, см.:

Различия между JWS и JWT

Вы можете использовать JWT или JWS для совместного использования утверждений или утверждений между подключенными приложениями. Основное различие между ними заключается в представлении полезной нагрузки:

  • JWT
    • Полезная нагрузка всегда представляет собой объект JSON.
    • Полезная нагрузка всегда привязана к JWT.
    • Заголовок typ токена всегда имеет значение JWT
  • JWS
    • Полезная нагрузка может быть представлена ​​в любом формате, например объекте JSON, потоке байтов, потоке октетов и т. д.
    • Полезная нагрузка не обязательно должна быть прикреплена к JWS.

Поскольку формат JWT всегда использует объект JSON для представления полезных данных, политики Edge Generate JWT и Verify JWT имеют встроенную поддержку для обработки общих зарегистрированных имен утверждений, таких как aud , iss , sub и других. Это означает, что вы можете использовать элементы политики «Создать JWT» для установки этих утверждений в полезные данные, а элементы политики «Проверить JWT» — для проверки их значений. Дополнительные сведения см. в разделе «Зарегистрированные имена утверждений» спецификации JWT.

Помимо поддержки определенных зарегистрированных имен утверждений, политика «Создать JWT» напрямую поддерживает добавление утверждений с произвольными именами в JWT. Каждое утверждение представляет собой простую пару имя/значение, где значение может иметь числовой тип, логическое значение, строку, карту или массив.

Поскольку JWS может использовать любое представление данных для полезных данных, вы не можете добавлять утверждения к полезным данным. Политика «Создать JWS» поддерживает добавление утверждений с произвольными именами в заголовок JWS. Кроме того, политики JWS поддерживают отсоединенную полезную нагрузку, при которой JWS опускает полезную нагрузку. Отдельная полезная нагрузка позволяет отправлять JWS и полезную нагрузку отдельно и требуется несколькими стандартами безопасности.

Об алгоритмах подписи

Политики проверки JWS/JWT и генерации JWS/JWT поддерживают алгоритмы RSA, RSASSA-PSS, ECDSA и HMAC с использованием контрольных сумм SHA2 разрядности 256, 384 или 512. Политика декодирования JWS/JWT работает независимо от используемого алгоритма. используется для подписи JWS/JWT.

Алгоритм HMAC

Алгоритм HMAC использует общий секрет, известный как секретный ключ, для создания подписи (также известной как подпись JWS/JWT) и для проверки подписи.

Минимальная длина секретного ключа зависит от разрядности алгоритма:

  • HS256: минимальная длина ключа 32 байта.
  • HS386: минимальная длина ключа 48 байт.
  • HS512: минимальная длина ключа 64 байта.

Алгоритм RSA

Алгоритм RSA использует пару открытого/закрытого ключей для криптографической подписи. При использовании подписей RSA подписывающая сторона использует закрытый ключ RSA для подписи JWS/JWT, а проверяющая сторона использует соответствующий открытый ключ RSA для проверки подписи на JWS/JWT. Никаких требований к размеру ключей нет.

Алгоритм RSASSA-PSS

Алгоритм RSASSA-PSS является обновлением алгоритма RSA. Как и RSS, RSASSA-PSS использует пару открытого/закрытого ключей RSA для криптографической подписи. Формат ключа такой же, как и для RSS. Подписывающая сторона использует закрытый ключ для подписи JWS/JWT, а проверяющая сторона использует соответствующий открытый ключ для проверки подписи на JWS/JWT. Никаких требований к размеру ключей нет.

Алгоритм ECDSA

Алгоритм цифровой подписи с эллиптической кривой (ECDSA) — это алгоритм криптографии с эллиптической кривой с кривыми P-256, P-384 и P-521. Когда вы используете алгоритмы ECDSA, алгоритм определяет тип открытого и закрытого ключа, который вы должны указать:

Алгоритм Изгиб Ключевое требование
ES256 П-256 Ключ, сгенерированный на основе кривой P-256 (также известный как secp256r1 или prime256v1).
ES384 П-384 Ключ, сгенерированный на основе кривой P-384 (также известный как secp384r1).
ES512 П-521 Ключ, созданный на основе кривой P-521 (также известной как secp521r1).

Алгоритмы шифрования ключей

Политики JWS/JWT поддерживают все алгоритмы шифрования ключей, поддерживаемые OpenSSL .

Использование набора веб-ключей JSON (JWKS) для проверки JWS/JWT

При проверке подписанного JWS/JWT вам необходимо предоставить открытый ключ, связанный с закрытым ключом, используемым для подписи токена. У вас есть два варианта предоставления открытого ключа для проверки политик JWS/JWT:

  • используйте фактическое значение открытого ключа (обычно указанное в переменной потока) или
  • используйте открытый ключ, завернутый в JWKS.

О JWKS

JWKS — это структура JSON, представляющая набор веб-ключей JSON (JWK). JWK — это структура данных JSON, представляющая криптографический ключ. JWK и JWKS описаны в RFC7517 . См. примеры JKWS в Приложении A. Примеры наборов веб-ключей JSON.

Структура JWKS

RFC7517 описывает ключевые элементы JWKS для каждого типа ключа, например «RSA» или «EC». Например, в зависимости от типа ключа эти параметры могут включать:

  • kty — тип ключа, например «RSA» или «EC».
  • kid (идентификатор ключа) — может быть любым произвольным значением (никаких дубликатов в наборе ключей). Если входящий JWT имеет идентификатор ключа, который присутствует в наборе JWKS, то политика будет использовать правильный открытый ключ для проверки подписи JWS/JWT.

Ниже приведены примеры необязательных элементов и их значений:

  • alg — Ключевой алгоритм. Он должен соответствовать алгоритму подписи в JWS/JWT.
  • использование - Если присутствует, должен быть подписан.

Следующий JWKS включает необходимые элементы и значения и будет действителен в Edge (с https://www.googleapis.com/oauth2/v3/certs ): 

{  
   "keys":[  
      {  
         "kty":"RSA",
         "alg":"RS256",
         "use":"sig",
         "kid":"ca04df587b5a7cead80abee9ea8dcf7586a78e01",
         "n":"iXn-WmrwLLBa-QDiToBozpu4Y4ThKdwORWFXQa9I75pKOvPUjUjE2Bk05TUSt7-V7KDjCq0_Nkd-X9rMRV5LKgCa0_F8YgI30QS3bUm9orFryrdOc65PUIVFVxIwMZuGDY1hj6HEJVWIr0CZdcgNIll06BasclckkUK4O-Eh7MaQrqb646ghFlG3zlgk9b2duHbDOq3s39ICPinRQWC6NqTYfqg7E8GN_NLY9srUCc_MswuUfMJ2cKT6edrhLuIwIj_74YGkpOwilr2VswKsvJ7dcoiJxheKYvKDKtZFkbKrWETTJSGX2Xeh0DFB0lqbKLVvqkM2lFU2Qx1OgtTnrw",
         "e":"AQAB"
      },
      {
          "kty":"EC",
          "alg":"ES256",
          "use":"enc",
          "kid":"k05TUSt7-V7KDjCq0_N"
          "crv":"P-256",
          "x":"Xej56MungXuFZwmk_xccvsMpCtXmqhvEEMCmHyAmKF0",
          "y":"Bozpu4Y4ThKdwORWFXQa9I75pKOvPUjUjE2Bk05TUSt",
      }
   ]
}

Разработка прокси для использования JWKS

Когда JWS/JWT получен от эмитента, часто эмитент вставляет идентификатор ключа (или kid) в заголовок JWS/JWT. Ключ сообщает получателю JWS/JWT, как найти открытый или секретный ключ, необходимый для проверки подписи подписанного JWS/JWT.

В качестве примера предположим, что эмитент подписывает JWT закрытым ключом. «Идентификатор ключа» идентифицирует соответствующий открытый ключ, который будет использоваться для проверки JWT. Список открытых ключей обычно доступен на какой-либо известной конечной точке, например: https://www.googleapis.com/oauth2/v3/certs .

Это основная последовательность действий, которую Edge (или любая платформа, работающая с JWKS) должен выполнить для работы с JWS/JWT, имеющим JWKS:

  1. Изучите заголовок JWS/JWT, чтобы найти идентификатор ключа (ребенок).
  2. Проверьте заголовок JWS/JWT, чтобы найти алгоритм подписи (alg), например RS256.
  3. Получите список ключей и идентификаторов из JWKS известной конечной точки для данного эмитента.
  4. Извлеките открытый ключ из списка ключей с идентификатором ключа, указанным в заголовке JWS/JWT, и с помощью алгоритма сопоставления, если ключ JWKS определяет алгоритм.
  5. Используйте этот открытый ключ для проверки подписи на JWS/JWT.

Как разработчику прокси-сервера Edge API вам необходимо выполнить следующие действия для проверки JWS/JWT:

  1. Получите список ключей и идентификаторов из известной конечной точки для данного эмитента. Для этого шага вы можете использовать политику вызова обслуживания.
  2. В политике Verify JWS/JWT укажите расположение JWS/JWT в элементе <Source> и полезные данные JWKS в элементе <PublicKey/JWKS> . Например, для политики VerifyJWT: 
    <VerifyJWT name="JWT-Verify-RS256">
    <Algorithm>RS256</Algorithm>
    <Source>json.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <JWKS ref="public.jwks"/>
    </PublicKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>    
    </AdditionalClaims>
</VerifyJWT>

Политика Verify JWT делает все остальное:

  • Если ключ с идентификатором ключа, соответствующим идентификатору ключа (kid), указанному в JWT, не найден в JWKS, то политика проверки JWT выдает ошибку и не проверяет JWT.
  • Если входящий JWT не содержит идентификатора ключа (kid) в заголовке, то сопоставление keyid с ключом проверки невозможно.

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