Omówienie zasad JWS i JWT

Wyświetlasz dokumentację Apigee Edge.
Przejdź do dokumentacji Apigee X. info

Ten artykuł zawiera ogólne informacje o tokenach internetowych JSON (JWT) i podpisach internetowych JSON (JWS) oraz o zasadach JWS/JWT Apigee, które mogą zainteresować deweloperów serwerów proxy Apigee.

Wprowadzenie

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

  • generowanie podpisanego tokena JWT lub JWS;
  • weryfikowanie podpisanego tokena JWT lub JWS oraz deklaracji w JWS/JWT;
  • dekodowanie podpisanego tokena JWT lub JWS bez sprawdzania podpisu.

W 2 ostatnich przypadkach zasada ustawia też zmienne, które umożliwiają dodatkowym zasadom lub samym usługom backendu sprawdzanie zweryfikowanych deklaracji i podejmowanie decyzji na ich podstawie.

Jeśli używasz zasady Verify JWS/JWT, nieprawidłowy token JWS/JWT zostanie odrzucony i spowoduje błąd warunek. Podobnie, jeśli używasz zasady Decode JWS/JWT, nieprawidłowo sformułowany token JWS/JWT spowoduje błąd.

Filmy

Obejrzyj krótki film, aby szybko zapoznać się z tokenami JWT. Ten film dotyczy generowania tokena JWT, ale wiele koncepcji jest takich samych w przypadku tokenów JWS.

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

Przypadki użycia

Zasady JWS/JWT możesz stosować do tych celów:

  • Generowanie nowego tokena JWS/JWT po stronie serwera proxy lub punktu końcowego docelowego serwera proxy Edge. Możesz na przykład utworzyć przepływ żądania serwera proxy, który generuje token JWS/JWT i zwraca go do klienta. Możesz też zaprojektować serwer proxy tak, aby generował token JWS/JWT w przepływie żądania docelowego i dołączał go do żądania wysyłanego do miejsca docelowego. Te deklaracje będą wtedy dostępne, aby umożliwić usługom backendu dalsze przetwarzanie zabezpieczeń.
  • Weryfikowanie i wyodrębnianie deklaracji z tokena JWS/JWT uzyskanego z przychodzących żądań klientów, odpowiedzi usług docelowych odpowiedzi zasad wywołania usługi lub innych źródeł. Edge zweryfikuje podpis w tokenie JWS/JWT, niezależnie od tego, czy został on wygenerowany przez firmę zewnętrzną czy przez Edge, przy użyciu algorytmów RSA lub HMAC.
  • Dekodowanie tokena JWS/JWT. Dekodowanie jest najbardziej przydatne w połączeniu z zasadą Verify JWS/JWT, gdy wartość deklaracji (JWT) lub nagłówka (JWS/JWT) w tokenie JWS/JWT musi być znana przed zweryfikowaniem tokena JWS/JWT.

Elementy tokena JWS/JWT

Podpisany token JWS/JWT koduje informacje w 3 częściach oddzielonych kropkami: nagłówku, ładunku i podpisie:

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

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

header..signature

W przypadku odłączonego tokena JWS ładunek jest wysyłany oddzielnie od tokena JWS. Aby określić nieprzetworzony, niezakodowany ładunek tokena JWS, użyj elementu <DetachedContent> zasady Verify JWS. Zasada Verify JWS weryfikuje token JWS, używając nagłówka i podpisu w tokenie JWS oraz ładunku określonego przez element <DetachedContent>.

Więcej informacji o tokenach oraz o tym, jak są kodowane i podpisywane, znajdziesz w tych dokumentach:

Różnice między tokenami JWS i JWT

Do udostępniania 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 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. jako obiekt JSON, strumień bajtów, strumień oktetów itp.
    • Ładunek nie musi być dołączony do tokena JWS.

Ponieważ format JWT zawsze używa obiektu JSON do reprezentowania ładunku, zasady Edge Generate JWT i Verify JWT mają wbudowaną obsługę typowych zarejestrowanych nazw deklaracji, takich jak aud, iss, sub i inne. Oznacza to, że możesz używać elementów zasady Generate JWT do ustawiania tych deklaracji w ładunku oraz elementów zasady Verify JWT do weryfikowania ich wartości. Więcej informacji znajdziesz w sekcji Zarejestrowane nazwy deklaracji w specyfikacji JWT.

Oprócz obsługi niektórych zarejestrowanych nazw deklaracji zasada Generate JWT bezpośrednio obsługuje dodawanie do tokena JWT deklaracji o dowolnych nazwach. Każda deklaracja to prosta para nazwa/wartość, w której wartość może być typu liczba, wartość logiczna, ciąg znaków, mapa lub tablica.

Ponieważ token JWS może używać dowolnej reprezentacji danych dla ładunku, nie możesz dodawać do niego deklaracji. Zasada Generate JWS obsługuje dodawanie do nagłówka tokena JWS deklaracji o dowolnych nazwach. Zasady JWS obsługują też odłączony ładunek, w którym token JWS pomija ładunek. Odłączony ładunek umożliwia wysyłanie tokena JWS i ładunku oddzielnie i jest wymagany przez kilka standardów bezpieczeństwa.

Zapobieganie wstrzykiwaniu szablonów podczas korzystania z tokenów JWS i JWT

Aby zapobiec nieautoryzowanemu ujawnieniu danych, podczas korzystania z zasad GenerateJWT lub GenerateJWS postępuj zgodnie z tymi wytycznymi:

  • Unikaj bezpośrednich odwołań do danych wejściowych użytkownika: nigdy nie używaj niezaufanych danych wejściowych (np. request.queryparam.* lub request.header.*) bezpośrednio w atrybucie ref, który obsługuje szablony.
  • Oczyszczaj dane wejściowe: jeśli musisz używać danych zewnętrznych w deklaracji JWT/JWS, najpierw użyj zasady AssignMessage , aby usunąć z danych wejściowych wszystkie nawiasy klamrowe ({ }) lub inne znaki szablonu , zanim się do nich odwołasz.
  • Używaj jawnych deklaracji ciągów znaków: w przypadku prostych deklaracji ciągów znaków unikaj używania type="map". Użycie domyślnego ustawienia type="string" zapobiega niejawnemu tworzeniu szablonów wartości, do której się odwołujesz.
  • Zwróć uwagę na niespójność zachowania między zasadami weryfikacji i generowania: zasady generowania tokenów JWS i JWT zachowują się inaczej niż zasady weryfikacji w odniesieniu do szablonów.

Algorytmy podpisu

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

Algorytm HMAC

Algorytm HMAC opiera się na udostępnionym haśle, zwanym kluczem tajnym, do tworzenia podpisu (zwanego też podpisywaniem tokena JWS/JWT) i do weryfikowania podpisu.

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

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

Algorytm RSA

Algorytm RSA używa pary kluczy publiczny/prywatny do podpisu kryptograficznego. W przypadku podpisów RSA strona podpisująca używa klucza prywatnego RSA do podpisania tokena JWS/JWT, a strona weryfikująca używa pasującego klucza publicznego RSA do zweryfikowania podpisu w tokenie JWS/JWT. Nie ma wymagań dotyczących rozmiaru kluczy.

Algorytm RSASSA-PSS

Algorytm RSASSA-PSS jest aktualizacją algorytmu RSA. Podobnie jak RSS, RSASSA-PSS używa 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 podpisania tokena JWS/JWT, a strona weryfikująca używa pasującego klucza publicznego do zweryfikowania podpisu w tokenie 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 kryptografii wykorzystujący krzywe eliptyczne algorytm 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 podać:

Algorytm Krzywa Wymagania dotyczące klucza
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żywanie zestawu kluczy internetowych JSON (JWKS) do weryfikowania tokena JWS/JWT

Podczas weryfikowania podpisanego tokena JWS/JWT musisz podać klucz publiczny powiązany z kluczem prywatnym używanym do podpisywania tokena. Aby podać klucz publiczny w zasadach weryfikacji tokenów JWS/JWT, masz 2 opcje dla:

  • użyj rzeczywistej wartości klucza publicznego (zwykle podawanej w zmiennej przepływu) lub
  • użyj klucza publicznego opakowanego w 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 są opisane w dokumencie RFC7517. Przykłady JKWS znajdziesz w Dodatku A. Przykładowe zestawy kluczy internetowych JSON

Struktura JWKS

RFC7517 opisuje elementy klucza JWKS dla każdego typu klucza, np. „RSA” lub „EC”. Na przykład w zależności od typu klucza, te parametry mogą obejmować:

  • kty – typ klucza, np. „RSA” lub „EC”.
  • kid (identyfikator klucza) – może to być dowolna wartość (bez duplikatów w zestawie kluczy ). Jeśli przychodzący token JWT zawiera identyfikator klucza, który jest obecny w zestawie JWKS, zasada użyje prawidłowego klucza publicznego do zweryfikowania podpisu JWS/JWT.

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

  • alg – algorytm klucza. Musi być zgodny z algorytmem podpisywania w tokenie JWS/JWT.
  • use – jeśli jest obecny, musi mieć wartość sig.

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

Projektowanie serwera proxy do używania JWKS

Gdy token JWS/JWT jest pobierany od wystawcy, często wstawia on identyfikator klucza (lub kid) do nagłówka tokena JWS/JWT. Klucz informuje odbiorcę tokena JWS/JWT, jak znaleźć klucz publiczny lub tajny niezbędny do zweryfikowania podpisu w podpisanym tokenie JWS/JWT.

Załóżmy na przykład, że wystawca podpisuje token JWT kluczem prywatnym. „Identyfikator klucza” identyfikuje pasujący klucz publiczny, który ma być używany do weryfikowania tokena JWT. Lista kluczy publicznych jest zwykle dostępna w dobrze znanym punkcie końcowym, np. https://www.googleapis.com/oauth2/v3/certs.

Jest to podstawowa sekwencja, którą Edge (lub dowolna platforma współpracująca z JWKS) musi wykonać aby współpracować z tokenem JWS/JWT, który ma JWKS:

  1. Sprawdź nagłówek tokena JWS/JWT, aby znaleźć identyfikator klucza (kid).
  2. Sprawdź nagłówek tokena JWS/JWT, aby znaleźć algorytm podpisywania (alg), np. RS256.
  3. Pobierz listę kluczy i identyfikatorów z JWKS znanego punktu końcowego dla danego wystawcy.
  4. Wyodrębnij klucz publiczny z listy kluczy z identyfikatorem klucza podanym w nagłówku tokena JWS/JWT i z pasującym algorytmem, jeśli klucz JWKS określa algorytm.
  5. Użyj tego klucza publicznego do zweryfikowania podpisu w tokenie JWS/JWT.

Aby przeprowadzić weryfikację tokena JWS/JWT, jako deweloper serwera proxy interfejsu API Edge musisz wykonać te czynności:

  1. Pobierz listę kluczy i identyfikatorów ze znanego punktu końcowego dla danego wystawcy. W tym kroku możesz użyć zasady wywołania usługi.
  2. W zasadzie Verify JWS/JWT określ lokalizację tokena JWS/JWT w elemencie <Source> oraz ładunek JWKS w elemencie <PublicKey/JWKS>. Na przykład, w przypadku 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 Verify JWT wykonuje wszystkie pozostałe czynności:

  • Jeśli w JWKS nie zostanie znaleziony klucz z identyfikatorem klucza, który pasuje do identyfikatora klucza (kid) podanego w tokenie JWT, zasada Verify JWT zgłosi błąd i nie zweryfikuje tokena JWT.
  • Jeśli przychodzący token JWT nie zawiera identyfikatora klucza (kid) w nagłówku, to mapowanie identyfikatora klucza na klucz weryfikacji nie jest możliwe.

Jako projektant serwera proxy odpowiadasz za określenie klucza, którego należy użyć. W niektórych przypadkach może to być stały, zakodowany na stałe klucz.