Omówienie zasad JWS i JWT

Przeglądasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. Informacje

Ten temat zawiera ogólne informacje o tokenie sieciowym JWT (JSON Web Token) i JWS (JSON Web Signature) oraz zasadach Apigee JWS/JWT, które mogą zainteresować programistów serwerów proxy Apigee.

Wstęp

Do współdzielenia deklaracji i asercji między połączonymi aplikacjami zwykle używane są JWS i JWT. Zasady JWS/JWT umożliwiają serwerom proxy Edge API:

  • Wygeneruj podpisany JWT lub JWS.
  • Zweryfikuj podpisany JWT lub JWS oraz zgłoszenia w JWS/JWT.
  • Zdekoduj podpisany JWT lub JWS bez weryfikowania podpisu.

W 2 ostatnich przypadkach zasada określa też zmienne, które zezwalają na dodatkowe zasady lub same usługi backendu na sprawdzanie zweryfikowanych deklaracji i podejmowanie decyzji na ich podstawie.

Jeśli użyjesz zasady weryfikacji JWS/JWT, nieprawidłowy token JWS/JWT zostanie odrzucony i pojawi się warunek błędu. Podobnie jeśli jest używana zasada dekodowania JWS/JWT, nieprawidłowy format JWS/JWT spowoduje błąd.

Filmy

Obejrzyj krótki film z krótkim wprowadzeniem do JWT. Ten film dotyczy generowania tokena JWT, ale wiele koncepcji jest takich samych w JWS.

Krótki film, który zawiera więcej informacji o strukturze JWT.

Przypadki użycia

Za pomocą zasad JWS/JWT możesz:

  • Wygeneruj nowy JWS/JWT po stronie serwera proxy lub docelowego punktu końcowego serwera proxy Edge. Możesz na przykład utworzyć przepływ żądania serwera proxy, który generuje JWS/JWT i zwraca go klientowi. Możesz też zaprojektować serwer proxy tak, aby generował JWS/JWT w docelowym przepływie żądania i dołączył go do żądania wysyłanego do środowiska docelowego. Roszczenia te będą wtedy dostępne, aby umożliwić usługom backendu zastosowanie dalszego przetwarzania zabezpieczeń.
  • Zweryfikuj i wyodrębnij deklaracje z JWS/JWT uzyskany z przychodzących żądań klienta, z odpowiedzi usługi docelowej, odpowiedzi zasad dotyczących wywołań usługi lub z innych źródeł. Edge sprawdzi podpis w JWS/JWT przy użyciu algorytmów RSA lub HMAC, niezależnie od tego, czy JWS/JWT został wygenerowany przez firmę zewnętrzną czy przez samą usługę Edge.
  • Zdekoduj JWS/JWT. Dekodowanie jest najbardziej przydatne, gdy jest używane w połączeniu z zasadą weryfikacji JWS/JWT, gdy wartość deklaracji (JWT) lub nagłówka (JWS/JWT) z JWS/JWT musi być znana przed zweryfikowaniem JWS/JWT.

Elementy JWS/JWT

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

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

JWS obsługuje też format detached, który pomija ładunek z JWS:

header..signature

Po odłączeniu JWS ładunek jest wysyłany niezależnie od JWS. Do określenia nieprzetworzonego, niezakodowanego ładunku JWS służy element <DetachedContent> zasady weryfikacji JWS. Następnie zasada weryfikacji JWS weryfikuje JWS przy użyciu nagłówka i podpisu w JWS oraz ładunku określonym przez element <DetachedContent>.

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

Różnice między JWS a JWT

Do współdzielenia deklaracji lub asercji między połączonymi aplikacjami możesz używać tokena JWT lub JWS. Główna różnica między nimi polega na reprezentacji ładunku:

  • JWT
    • Ładunek to zawsze obiekt JSON
    • Ładunek jest zawsze podłączony do tokena JWT
    • Nagłówek typ tokena jest zawsze ustawiony na JWT
  • JWS
    • Ładunek może być reprezentowany w dowolnym formacie, takim jak obiekt JSON, strumień bajtów czy strumień oktetu.
    • Ładunek nie musi być podłączony do JWS

Format JWT zawsze używa obiektu JSON do reprezentowania ładunku, dlatego zasady Edge Wygeneruj token JWT i Zweryfikuj tokeny JWT obsługują teraz typowe zarejestrowane nazwy roszczeń, takie jak aud, iss, sub i inne. Oznacza to, że możesz użyć elementów zasady generowania tokena JWT, aby ustawić te deklaracje w ładunku, oraz elementów zasady weryfikacji JWT, aby zweryfikować ich wartości. Więcej informacji znajdziesz w sekcji Zarejestrowane nazwy roszczenia w specyfikacji JWT.

Oprócz obsługi określonych zarejestrowanych nazw roszczeń zasada Wygeneruj token JWT bezpośrednio obsługuje dodawanie do tokena JWT deklaracji z dowolnymi nazwami. Każde żądanie składa się z prostej pary nazwa/wartość, której wartością może być liczba, wartość logiczna, ciąg znaków, mapa lub tablica.

JWS może korzystać z dowolnej reprezentacji danych dla ładunku, więc nie można do niego dodawać deklaracji. Zasada Wygeneruj JWS obsługuje dodawanie deklaracji z dowolnymi nazwami do nagłówka pliku JWS. Zasady JWS obsługują też ładunek odłączony, w przypadku którego JWS go pomija. Ładunek odłączony umożliwia osobne wysyłanie JWS i ładunku. Jest on wymagany przez kilka standardów bezpieczeństwa.

Informacje o algorytmach podpisu

Zasady weryfikacji JWS/JWT i funkcji generowania JWS/JWT obsługują algorytmy RSA, RSASSA-PSS, ECDSA i HMAC, używając sum kontrolnych SHA2 o długości bitów 256, 384 lub 512. Zasada dekodowania JWS/JWT działa niezależnie od algorytmu użytego do podpisania JWS/JWT.

Algorytm HMAC

Algorytm HMAC korzysta z udostępnionego obiektu tajnego, zwanego kluczem obiektu tajnego, do tworzenia podpisu (nazywanego też podpisywaniem JWS/JWT) i weryfikacji podpisu.

Minimalna długość tajnego klucza zależy od siły bitowej algorytmu:

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

Algorytm RSA

Algorytm RSA wykorzystuje parę kluczy (publiczny i prywatny) do podpisu kryptograficznego. W przypadku podpisów RSA strona podpisująca używa klucza prywatnego RSA do podpisywania JWS/JWT, a osoba weryfikująca używa pasującego klucza publicznego RSA do weryfikacji podpisu w JWS/JWT. Nie ma wymagań dotyczących rozmiaru kluczy.

Algorytm RSASSA-PSS

Algorytm RSASSA-PSS jest aktualizacją algorytmu RSA. Podobnie jak w przypadku RSS, RSASSA-PSS korzysta z pary kluczy publiczny/prywatny RSA do podpisu kryptograficznego. Format klucza jest taki sam jak w przypadku RSS. Strona podpisująca używa klucza prywatnego do podpisywania JWS/JWT, a osoba weryfikująca używa pasującego klucza publicznego do weryfikacji podpisu na 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 algorytm kryptograficzny oparty na krzywych eliptycznych z krzywą P-256, P-384 i P-521. Gdy używasz algorytmów ECDSA, algorytm określa typ klucza publicznego i prywatnego, który musisz określić:

Algorytm Krzywa Kluczowe wymaganie
ES256 P-256 Klucz wygenerowany na podstawie krzywej P-256 (nazywany też secp256r1 lub prime256v1)
ES384 P-384 Klucz wygenerowany na podstawie krzywej P-384 (znany też jako secp384r1)
ES512 P-521 Klucz wygenerowany na podstawie krzywej P-521 (znanej też jako secp521r1)

Algorytmy szyfrowania klucza

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

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

Gdy weryfikujesz podpisany JWS/JWT, musisz podać klucz publiczny powiązany z kluczem prywatnym używanym do podpisania tokena. Możesz udostępnić klucz publiczny do weryfikacji zasad JWS/JWT na 2 sposoby:

  • użyj rzeczywistej wartości klucza publicznego (zwykle podawanej w zmiennej przepływu) lub
  • użyć klucza publicznego opakowanego w kod JWKS.

Informacje o JWKS

JWKS to struktura JSON, która reprezentuje zestaw kluczy internetowych JSON (JWK). JWK to struktura danych JSON, która reprezentuje klucz kryptograficzny. JWK i JWKS zostały opisane w RFC7517. Zobacz przykłady JKWS w Dodatku A. Przykładowe zestawy kluczy internetowych JSON

Struktura JWKS

RFC7517 opisuje kluczowe elementy JWKS dla każdego typu klucza, np. „RSA” lub „EC”. W zależności od typu klucza parametry mogą obejmować:

  • kty – typ klucza, np. „RSA” lub „EC”.
  • kid (identyfikator klucza) – może być dowolną wartością (bez duplikatów w zestawie kluczy). Jeśli przychodzący token JWT nosi identyfikator klucza, który znajduje się w zestawie JWKS, zasada użyje odpowiedniego klucza publicznego do zweryfikowania 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 jest prawidłowy w przeglądarce Edge (z 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 do używania JWKS

Po uzyskaniu tokena JWS/JWT od wydawcy wydawca często wstawia identyfikator klucza (lub podmiotu podrzędnego) w nagłówku JWS/JWT. Klucz informuje odbiorcę JWS/JWT, jak znaleźć klucz publiczny lub tajny wymagany do zweryfikowania podpisu w podpisanym JWS/JWT.

Załóżmy na przykład, że wydawca podpisuje JWT za pomocą klucza prywatnego. „Identyfikator klucza” wskazuje pasujący klucz publiczny do weryfikacji tokena JWT. Lista kluczy publicznych jest zwykle dostępna w znanym punkcie końcowym, na przykład https://www.googleapis.com/oauth2/v3/certs.

Oto podstawowa sekwencja, którą musi wykonać Edge (lub dowolna platforma współpracująca z JWKS), aby współpracować z JWS/JWT, który ma 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 klucza wskazanym w nagłówku JWS/JWT i z algorytmem dopasowania, jeśli klucz JWKS określa algorytm.
  5. Użyj tego klucza publicznego, aby zweryfikować podpis na JWS/JWT.

Jeśli jesteś deweloperem serwera proxy 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. W tym kroku możesz użyć zasady dotyczącej objaśnienia usługi.
  2. W zasadzie weryfikacji JWS/JWT określ lokalizację JWS/JWT w elemencie <Source> i ładunku JWKS w elemencie <PublicKey/JWKS>. Na przykład w przypadku zasady Verification JWT: 
    <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 w JWKS nie znaleziono klucza z identyfikatorem klucza zgodnym z identyfikatorem klucza (kid) podanym w tokenie JWT, zasada Weryfikacja JWT zgłasza błąd i nie weryfikuje tokena JWT.
  • Jeśli przychodzący token JWT nie zawiera w nagłówku identyfikatora klucza (kid), mapowanie identyfikatora keyid-to-verification-key jest niemożliwe.

Jako projektant serwera proxy odpowiadasz za wybór klucza do użycia. W niektórych przypadkach może to być stały, zakodowany na stałe klucz.