Omówienie zasad JWS i JWT

Przeglądasz dokumentację Apigee Edge.
Przejdź do Dokumentacja Apigee X. informacje.

W tym temacie znajdziesz ogólne informacje na temat tokena internetowego JSON (JWT) i JWS (JSON Web Signature) oraz zasady Apigee JWS/JWT, które mogą być interesujące dla programistów serwera proxy Apigee.

Wprowadzenie

Zarówno JWS, jak i JWT są zwykle używane do udostępniania deklaracji lub asercji między połączonymi aplikacji. Zasady JWS/JWT umożliwiają serwerom proxy interfejsu Edge API:

  • Wygeneruj podpisany token JWT czy JWS.
  • Sprawdzanie podpisanego JWT lub JWS i deklaracji w JWS/JWT.
  • Zdekoduj podpisany JWT lub JWS bez weryfikacji podpisu.

W dwóch ostatnich przypadkach zasada określa również zmienne, które umożliwiają stosowanie dodatkowych zasad lub i usług backendu, aby sprawdzać zweryfikowane deklaracje i podejmować na ich podstawie decyzje roszczeniami.

Jeśli używasz zasady weryfikacji JWS/JWT, nieprawidłowy plik JWS/JWT zostanie odrzucony, co spowoduje błąd. . Podobnie gdy używasz zasady dekodowania JWS/JWT nieprawidłowy format JWS/JWT spowoduje błąd. .

Filmy

Obejrzyj krótki film zawierający krótkie wprowadzenie do JWT. W tym filmie związane z generowaniem tokena JWT, wiele koncepcji jest takich samych w przypadku JWS.

Obejrzyj krótki film, aby dowiedzieć się więcej o strukturze JWT.

Przypadki użycia

Za pomocą zasad JWS/JWT możesz:

  • Wygeneruj nowy plik JWS/JWT po stronie serwera proxy lub docelowego punktu końcowego serwera proxy Edge. Dla: Możesz na przykład utworzyć przepływ żądania serwera proxy, który będzie generował plik JWS/JWT i zwracał go do klienta. Możesz też zaprojektować serwer proxy tak, aby generował kod JWS/JWT w docelowym przepływie żądania, dołącza go do żądania wysłanego do środowiska docelowego. Roszczenia te byłyby wówczas dostępne, aby umożliwić usług backendu, aby zapewnić dalsze przetwarzanie zabezpieczeń.
  • Zweryfikuj i wyodrębnij deklaracje z tokena JWS/JWT uzyskanego z przychodzących żądań klienta z miejsca docelowego odpowiedzi na zapytania dotyczące usługi, odpowiedzi na pytania dotyczące zasad dotyczących wywołań usługi lub z innych źródeł. Edge będzie zweryfikować podpis w JWS/JWT, niezależnie od tego, czy ten plik został wygenerowany przez inną firmę czy przez Edge; używając algorytmów RSA lub HMAC.
  • Dekoduj plik JWS/JWT. Dekodowanie jest najbardziej przydatne w połączeniu z zasadą weryfikacji JWS/JWT, gdy wartość deklaracji (JWT) lub nagłówka (JWS/JWT) w JWS/JWT musi być znana przed zweryfikowaniem JWS/JWT.

Elementy JWS/JWT

Podpisany plik JWS/JWT koduje informacje w 3 częściach rozdzielonych kropkami: nagłówek, ładunek i tag podpis:

header.payload.signature
  • Zasada Generate JWS/JWT tworzy wszystkie 3 części.
  • Zasada weryfikacji JWS/JWT sprawdza wszystkie 3 części.
  • Zasada dekodowania JWS/JWT bada tylko nagłówek i ładunek.

JWS obsługuje też format odłączony, który pomija ładunek w JWS:

header..signature

W przypadku odłączenia ładunku JWS ładunek jest wysyłany niezależnie od JWS. Korzystasz z Element <DetachedContent> zasady Weryfikacja JWS określający nieprzetworzony, niezakodowany ładunek JWS. Zasada weryfikacji JWS weryfikuje następnie JWS za pomocą nagłówka i podpisu w JWS i ładunku. określona przez element <DetachedContent>.

Więcej informacji o tokenach oraz sposobie ich kodowania i podpisywania:

Różnice między JWS a JWT

Aby udostępniać deklaracje lub asercje między połączonymi aplikacjami, możesz używać tokena JWT lub JWS. Główną różnicą między nimi jest reprezentacja ładunku:

  • JWT
    • Ładunek jest zawsze obiektem JSON
    • Ładunek jest zawsze dołączony do tokena JWT
    • Nagłówek typ tokena jest zawsze ustawiony na JWT
  • JWS
    • Ładunek może być reprezentowany w dowolnym formacie, np. obiektem JSON, strumieniem bajtów czy strumieniem oktetu
    • Nie trzeba łączyć ładunku z JWS.

Format JWT zawsze używa obiektu JSON do reprezentowania ładunku, dlatego token JWT Edge JWT i Sprawdź, czy zasady JWT mają wbudowaną obsługę obsługi popularnych zarejestrowanych nazw oświadczeń, takich jak aud, iss, sub i inne. Oznacza to, że możesz używać elementów Wygeneruj zasadę JWT, aby ustawić te deklaracje w ładunku, oraz elementy zasady JWT w celu potwierdzenia ich wartości. Zobacz Zarejestrowane nazwy roszczeń. specyfikacji JWT.

Oprócz obsługi określonych zarejestrowanych nazw oświadczeń, bezpośrednio generowana jest zasada JWT. umożliwia dodawanie do tokena JWT deklaracji z dowolnymi nazwami. Każde twierdzenie to prosta para nazwa/wartość, gdzie wartością może być liczba, wartość logiczna, ciąg znaków, mapa lub tablica.

Nie można dodawać deklaracji do ładunku, ponieważ JWS może używać dowolnej reprezentacji danych. Zasada Wygeneruj JWS nie obsługuje dodawania deklaracji z dowolnymi nazwami do nagłówka JWS. Dodatkowo zasady JWS obsługują ładunek odłączony, w przypadku którego JWS pomija ładunek. Odłączony ładunek umożliwia oddzielne wysyłanie JWS i ładunku i jest wymagany przez kilka standardów zabezpieczeń.

Informacje o algorytmach podpisu

Zasady weryfikacji JWS/JWT oraz generowania JWS/JWT obsługują algorytmy RSA, RSASSA-PSS, ECDSA i HMAC z SHA2 sumy kontrolne o mocy bitów 256, 384 lub 512. Zasada dekodowania JWS/JWT działa niezależnie od który był używany do podpisywania JWS/JWT.

Algorytm HMAC

Algorytm HMAC korzysta ze wspólnego obiektu tajnego, nazywanego tajnym kluczem, do tworzenia podpis (nazywany również podpisywania JWS/JWT) i weryfikacji podpisu.

Minimalna długość tajnego klucza zależy od siły bitów algorytmu:

  • HS256: minimalna długość klucza 32 bajty
  • HS386: minimalna długość klucza: 48 bajtów
  • HS512: minimalna długość klucza 64 bajty

Algorytm RSA

Algorytm RSA wykorzystuje parę kluczy publiczny/prywatny do podpisu kryptograficznego. Ze sprzedawcami podpisy, strona podpisująca używa klucza prywatnego RSA do podpisywania JWS/JWT, a strona weryfikująca używa pasującym kluczem publicznym RSA, aby zweryfikować podpis w JWS/JWT. Nie ma wymagań dotyczących rozmiaru w klawiszy.

Algorytm RSASSA-PSS

Algorytm RSASSA-PSS to aktualizacja algorytmu RSA. Podobnie jak RSS, RSASSA-PSS korzysta z tagu RSA para kluczy publiczny/prywatny na potrzeby podpisu kryptograficznego. Format klucza jest taki sam jak w przypadku RSS. Strona podpisująca używa klucza prywatnego do podpisywania JWS/JWT, a strona weryfikująca używa pasującego klucza. klucz publiczny do zweryfikowania podpisu JWS/JWT. Nie ma wymagań dotyczących rozmiaru kluczy.

Algorytm ECDSA

Algorytm podpisu cyfrowego wykorzystujący krzywe eliptyczne (Elliptic Curve Digital Signature Algorithm, ECDSA) to kryptografia wykorzystująca krzywe eliptyczne z krzywą P-256, P-384 i P-521. Gdy używasz algorytmów ECDSA, algorytm określa, typ klucza publicznego i prywatnego, które musisz określić:

Algorytm Krzywa Kluczowy wymóg
ES256 P-256 Klucz wygenerowany na podstawie krzywej P-256 (znanej też jako secp256r1 lub prime256v1)
ES384 P-384 Klucz wygenerowany na podstawie krzywej P-384 (znanej też jako secp384r1)
ES512 P-521 Klucz wygenerowany na podstawie krzywej P-521 (znanej też jako secp521r1)

Algorytmy szyfrowania kluczy

Zasady JWS/JWT obsługują wszystkie algorytmy szyfrowania kluczy obsługiwane przez OpenSSL.

Użycie zestawu kluczy internetowych JSON (JWKS) do weryfikacji kodu JWS/JWT

Podczas weryfikowania podpisanego klucza JWS/JWT musisz podać klucz publiczny, który jest powiązane z kluczem prywatnym używanym do podpisania tokena. Dostępne są 2 opcje: klucz publiczny do weryfikacji zasad JWS/JWT:

  • używając rzeczywistej wartości klucza publicznego (zwykle podawanej w zmiennej przepływu) lub
  • użyj klucza publicznego opakowanego JWKS.

Informacje o JWKS

JWKS to struktura JSON reprezentująca zbiór kluczy internetowych JSON (JWK). JWK to dane JSON reprezentującą klucz kryptograficzny. Oprogramowanie JWK i JWKS opisano w RFC7517. Zobacz przykłady w JKWS na Załącznik A. Przykładowe zestawy kluczy internetowych JSON

Struktura JWKS

RFC7517 opisuje kluczowe elementy JWKS. dla każdego typu klucza, np. „RSA” czy „EC”. Na przykład w zależności od typu klucza Mogą one obejmować:

  • kty – typ klucza, na przykład „RSA”. czy „EC”.
  • kid (identyfikator klucza) – może być dowolną wartością (bez duplikatów w kluczu). ustaw). Jeśli przychodzący token JWT zawiera identyfikator klucza, który znajduje się w zbiorze JWKS, wtedy zasada używa prawidłowego klucza publicznego do weryfikacji podpisu JWS/JWT.

Oto przykłady elementów opcjonalnych i ich wartości:

  • alg – algorytm klucza. Musi być zgodny z algorytmem podpisywania w JWS/JWT.
  • use – jeśli występuje, musi być sig.

Ten JWKS zawiera wymagane elementy i wartości i będzie prawidłowy w Edge (od 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",
      }
   ]
}

Zaprojektowanie serwera proxy tak, użyj JWKS

Gdy wydawca otrzymuje plik JWS/JWT, często umieszcza on identyfikator klucza (lub identyfikator podrzędny) w pliku JWS/JWT. nagłówek. Klucz informuje odbiorcę JWS/JWT, jak znaleźć klucz publiczny lub tajny niezbędny do zweryfikować podpis w podpisanym pliku JWS/JWT.

Załóżmy na przykład, że wydawca podpisuje JWT za pomocą klucza prywatnego. „Identyfikator klucza”, identyfikuje zgodny klucz publiczny, który ma być używany do weryfikacji tokena JWT. Lista kluczy publicznych jest zwykle dostępna na stronie dobrze znany punkt końcowy, na przykład https://www.googleapis.com/oauth2/v3/certs.

Jest to podstawowa sekwencja, którą musi wykonać Edge (lub dowolna platforma współpracująca z JWKS). użyj kodu JWS/JWT z JWKS:

  1. Sprawdź nagłówek JWS/JWT, aby znaleźć identyfikator klucza (kid).
  2. Sprawdź nagłówek JWS/JWT, aby znaleźć algorytm podpisywania (alg), np. RS256.
  3. Pobierz listę kluczy i identyfikatorów z JWKS dobrze znanego punktu końcowego danego wydawcy.
  4. Wyodrębnij klucz publiczny z listy kluczy o identyfikatorze wymienionym w nagłówku JWS/JWT oraz za pomocą algorytmu dopasowywania, jeśli klucz JWKS określa algorytm.
  5. Użyj tego klucza publicznego, aby zweryfikować podpis w JWS/JWT.

Jako programista serwera proxy interfejsu Edge API musisz wykonać te czynności, aby przeprowadzić weryfikację JWS/JWT:

  1. Pobierz listę kluczy i identyfikatorów ze znanego punktu końcowego danego wydawcy. Dostępne opcje w tym kroku użyj zasad dotyczących wywołań usług.
  2. W zasadzie weryfikacji JWS/JWT określ lokalizację pliku JWS/JWT w <Source> i ładunek JWKS w elemencie <PublicKey/JWKS>. Przykład: dla zasady 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>

Zasada weryfikacji JWT wykonuje wszystkie pozostałe czynności:

  • Jeśli klucz z identyfikatorem klucza zgodnym z identyfikatorem klucza (kid) określonym w tokenie JWT nie został znaleziony w JWKS, wtedy zasada weryfikacji JWT zwraca błąd i nie weryfikuje tokena JWT.
  • Jeśli przychodzący token JWT nie ma w nagłówku identyfikatora klucza (kid), to mapowanie identyfikator-klucz-weryfikacji jest niedostępny.

Jako projektant serwera proxy odpowiadasz za określenie klucza do użycia. w niektórych przypadkach to może być stałym, zakodowanym na stałe kluczem.