Zweryfikuj zasady weryfikacji JWS

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

Co

Weryfikuje podpis na JWS otrzymanym z klientów lub innych systemów. Ta zasada wyodrębnia też nagłówki do zmiennych kontekstowych, aby kolejne zasady lub warunki mogły analizować te wartości przy podejmowaniu decyzji dotyczących autoryzacji lub routingu. Szczegółowe informacje znajdziesz w omówieniu zasad JWS i JWT.

Jeśli JWS jest zweryfikowany i prawidłowy, żądanie może być kontynuowane. Jeśli nie można zweryfikować podpisu JWS lub jeśli JWS jest nieprawidłowy z powodu błędu jakiegoś typu, przetwarzanie zostanie zatrzymane, a w odpowiedzi zostanie zwrócony błąd.

Informacje o częściach JWS oraz sposobach ich szyfrowania i podpisywania znajdziesz w dokumencie RFC7515.

Wideo

Obejrzyj krótki film, aby dowiedzieć się, jak zweryfikować podpis na JWS. Chociaż film dotyczy weryfikacji tokena JWT, wiele koncepcji jest takich samych w JWS.

Przykłady

• Zweryfikuj załączony algorytm JWS podpisany za pomocą algorytmu HS256
• Zweryfikuj odłączony interfejs JWS podpisany algorytmem RS256

Zweryfikuj załączony algorytm JWS podpisany za pomocą algorytmu HS256

Ta przykładowa zasada weryfikuje dołączony protokół JWS, który został podpisany algorytmem szyfrowania HS256 (HMAC) z użyciem sumy kontrolnej SHA-256. JWS jest przekazywany w żądaniu serwera proxy za pomocą parametru formularza o nazwie JWS. Klucz jest zawarty w zmiennej o nazwie private.secretkey.

Załączony JWS zawiera zakodowany nagłówek, ładunek i podpis:

header.payload.signature

Konfiguracja zasady obejmuje informacje potrzebne Edge do dekodowania i oceny JWS, na przykład miejsce znalezienia JWS (w zmiennej przepływu określonej w elemencie <Source>), wymagany algorytm podpisywania oraz miejsce znalezienia tajnego klucza (przechowywanego w zmiennej przepływu brzegowego, który mógł zostać pobrany na przykład z Edge KVM).

<VerifyJWS name="JWS-Verify-HS256">
    <DisplayName>JWS Verify HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <Source>request.formparam.JWS</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
    </SecretKey>
</VerifyJWS>

Zasada zapisuje dane wyjściowe w zmiennych kontekstowych, aby kolejne zasady lub warunki w serwerze proxy interfejsu API mogły analizować te wartości. Listę zmiennych ustawionych przez tę zasadę znajdziesz w sekcji Zmienne przepływu.

Zweryfikuj odłączony protokół JWS podpisany algorytmem RS256

Ta przykładowa zasada weryfikuje odłączony protokół JWS podpisany algorytmem RS256. Aby przeprowadzić weryfikację, musisz podać klucz publiczny. JWS jest przekazywany w żądaniu serwera proxy za pomocą parametru formularza o nazwie JWS. Klucz publiczny jest zawarty w zmiennej o nazwie public.publickey.

Odłączony JWS pomija ładunek z JWS:

header..signature

Do Ciebie należy przekazanie ładunku do zasady WeryfikacjaJWS przez podanie w elemencie <DetachedContent> nazwy zmiennej zawierającej ładunek. Określona treść w pliku <DetachedContent> musi mieć oryginalną, niezakodowaną formę z momentu utworzenia podpisu JWS.

<VerifyJWS name="JWS-Verify-RS256">
    <DisplayName>JWS Verify RS256</DisplayName>
    <Algorithm>RS256</Algorithm>
    <Source>request.formparam.JWS</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <Value ref="public.publickey"/>
    </PublicKey>
    <DetachedContent>private.payload</DetachedContent>
</VerifyJWS>

Zasada zapisuje dane wyjściowe w zmiennych kontekstowych, aby kolejne zasady lub warunki w serwerze proxy interfejsu API mogły analizować te wartości. Listę zmiennych ustawionych przez tę zasadę znajdziesz w sekcji Zmienne przepływu.

Wyznaczanie kluczowych elementów

Elementy, których używasz do określania klucza używanego do weryfikacji JWS, zależą od wybranego algorytmu, jak pokazano w tej tabeli:

<SecretKey>
  <Value ref="private.secretkey"/>
</SecretKey>

<PublicKey>
  <Value ref="rsa_public_key"/>
</PublicKey>

<PublicKey>
  <JWKS ref="jwks_val_ref_or_url"/>
</PublicKey>

Odwołanie do elementu

Dokumentacja zasad zawiera opis elementów i atrybutów zasady weryfikacji JWS.

Uwaga: konfiguracja będzie nieco się różnić w zależności od użytego algorytmu szyfrowania. W sekcji Przykłady znajdziesz przykłady konfiguracji dla konkretnych przypadków użycia.

Atrybuty stosowane do elementu najwyższego poziomu

<VerifyJWS name="JWS" continueOnError="false" enabled="true" async="false">

Poniższe atrybuty są wspólne dla wszystkich elementów nadrzędnych zasad.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Użyj oprócz atrybutu name, aby oznaczyć zasadę w edytorze serwera proxy interfejsu zarządzania inną nazwą w języku naturalnym.

<Algorithm>

<Algorithm>HS256</Algorithm>

Określa algorytm szyfrowania do podpisywania tokena. Algorytmy RS*/PS*/ES* stosują parę kluczy publiczny/tajny, a algorytmy HS* korzystają z wspólnego obiektu tajnego. Zobacz też Informacje o algorytmach szyfrowania podpisów.

Możesz podać wiele wartości, rozdzielając je przecinkami. Na przykład „HS256, HS512” lub „RS256, PS256”. Nie można jednak łączyć algorytmów HS* z żadnymi innymi algorytmami ani algorytmami ES*, ponieważ wymagają one określonego typu klucza. Możesz połączyć algorytmy RS* i PS*.

<Dodatkowe nagłówki/roszczenie>

<AdditionalHeaders>
    <Claim name='claim1'>explicit-value-of-claim-here</Claim>
    <Claim name='claim2' ref='variable-name-here'/>
    <Claim name='claim3' ref='variable-name-here' type='boolean'/>
    <Claim name='claim4' ref='variable-name' type='string' array='true'/>
 </AdditionalHeaders>

Sprawdza, czy nagłówek JWS zawiera określone dodatkowe pary nazwy i wartości stwierdzenia oraz czy wartości zgłoszonego stwierdzenia są zgodne.

Dodatkowe zgłoszenie używa nazwy, która nie jest jedną ze standardowych, zarejestrowanych nazw roszczeń JWS. Wartością dodatkowego zgłoszenia może być ciąg, liczba, wartość logiczna, mapa lub tablica. Mapa to po prostu zestaw par nazwa/wartość. Wartość deklaracji dowolnego z tych typów można określić bezpośrednio w konfiguracji zasad lub pośrednio przez odniesienie do zmiennej przepływu.

Element <Claim> przyjmuje te atrybuty:

• name – (wymagany) nazwa roszczenia.
• ref – (opcjonalny) nazwa zmiennej przepływu. Jeśli ta zmienna jest obecna, zasada będzie używać jej jako wartości deklaracji. Jeśli określony jest zarówno atrybut ref, jak i jawna wartość deklaracji, domyślna wartość jest jawna. Jest ona używana, gdy wskazywana zmienna przepływu jest nierozstrzygnięta.
• type – (opcjonalny) 1 z: ciąg znaków (domyślny), liczba, wartość logiczna lub mapa.
• tablica – (opcjonalnie) ustaw na true, by wskazać, czy wartość jest tablicą typów. Wartość domyślna: false.

<DetachedContent>

<DetachedContent>variable-name-here</DetachedContent>

Wygenerowany JWS z ładunkiem treści ma postać:

header.payload.signature

Jeśli do utworzenia ładunku odłączonego używasz zasady WygenerujJWS, wygenerowany JWS pominie ładunek i będzie miał postać:

header..signature

W przypadku ładunku odłączonego to Ty musisz przekazać ładunek do zasady VerificationJWS za pomocą elementu <DetachedContent>. Określony ładunek treści musi mieć oryginalną, niezakodowaną formę z momentu utworzenia podpisu JWS.

Zasada zgłasza błąd, gdy:

• Wartość <DetachedContent> jest określana, gdy JWS nie zawiera odłączonego ładunku treści (kod błędu to steps.jws.ContentIsNotDetached).
• Zostanie pominięty <DetachedContent>, a JWS ma odłączony ładunek treści (kod błędu to steps.jws.InvalidSignature).

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

Ustaw wartość false, jeśli chcesz, aby zasada zwracała błąd, gdy dowolny nagłówek wymieniony w nagłówku crit na serwerze JWS nie jest wymieniony w elemencie <KnownHeaders>. Ustaw na wartość true, aby spowodować, że zasada WeryfikacjaJWS ignorowała nagłówek crit.

Jednym z powodów, dla których ten element ma wartość Prawda, jest sytuacja, gdy korzystasz w środowisku testowym i nie chcesz, aby zasada zakończyła się niepowodzeniem z powodu braku nagłówka.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Ustaw wartość „false”, jeśli chcesz, by zasada zgłaszała błąd, gdy jakakolwiek przywołana zmienna określona w zasadzie jest nierozwiązana. Ustaw wartość „true”, aby traktować każdą nierozwiązaną zmienną jako pusty ciąg znaków (null).

<KnownHeaders>

<KnownHeaders>a,b,c</KnownHeaders>

or:

<KnownHeaders ref=’variable_containing_headers’/>

Zasada WygenerujJWS wykorzystuje element <CriticalHeaders> do wypełniania nagłówka crit w tokenie. Na przykład:

{
  “typ: “...”,
  “alg” : “...”,
  “crit” : [ “a”, “b”, “c” ],
}

Zasada WeryfikacjaJWS sprawdza nagłówek crit w JWS, jeśli taki istnieje, i sprawdza, czy w przypadku każdego wymienionego elementu znajduje się jego lista, czy element <KnownHeaders> również zawiera ten nagłówek. Element <KnownHeaders> może zawierać nadzbiór elementów wymienionych w polu crit. W elemencie <KnownHeaders> muszą być tylko wszystkie nagłówki wymienione w parametrze crit. Każdy nagłówek znaleziony w elemencie crit, który nie jest wymieniony w metodzie <KnownHeaders>, powoduje błędy w zasadzie VerJWS.

Opcjonalnie możesz skonfigurować zasadęVerifyJWS tak, aby ignorowała nagłówek crit, ustawiając element <IgnoreCriticalHeaders> na true.

<PublicKey/JWKS>

<!-- Specify the JWKS. -->
<PublicKey>
   <JWKS>jwks-value-here</JWKS>
</PublicKey>

or:

<!-- Specify a variable containing the JWKS. -->
<PublicKey>
   <JWKS ref="public.jwks"/>
</PublicKey>

or:

<!-- Specify a public URL that returns the JWKS.
The URL is static, meaning you cannot set it using a variable. -->
<PublicKey>
   <JWKS uri="jwks-url"/>
</PublicKey>

Określa wartość w formacie JWKS (RFC 7517) zawierającą zestaw kluczy publicznych. Użyj tylko wtedy, gdy algorytm to RS256/RS384/RS512, PS256/PS384/PS512 lub ES256/ES384/ES512.

Jeśli przychodzący JWS nosi identyfikator klucza obecny w zestawie JWKS, zasada użyje odpowiedniego klucza publicznego do zweryfikowania podpisu JWS. Szczegółowe informacje o tej funkcji znajdziesz w artykule o weryfikowaniu JWS za pomocą zestawu kluczy Web JSON (JWKS).

Jeśli pobierasz wartość z publicznego adresu URL, Edge przechowuje JWKS w pamięci podręcznej przez 300 sekund. Po wygaśnięciu pamięci podręcznej Edge ponownie pobiera JWKS.

<PublicKey/Value>

<PublicKey>
   <Value ref="public.publickey"/>
</PublicKey>
-or-
<PublicKey>
    <Value>
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW
    Q0UrCw5c0+Y707KX3PpXkZGbtTT4nvU1jC0d1lHV8MfUyRXmpmnNxJHAC2F73IyN
    C5TBtXMORc+us7A2cTtC4gZV256bT4h3sIEMsDl0Joz9K9MPzVPFxa1i0RgNt06n
    Xn/Bs2UbbLlKP5Q1HPxewUDEh0gVMqz9wdIGwH1pPxKvd3NltYGfPsUQovlof3l2
    ALvO7i5Yrm96kknfFEWf1EjmCCKvz2vjVbBb6mp1ZpYfc9MOTZVpQcXSbzb/BWUo
    ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx
    DQIDAQAB
    -----END PUBLIC KEY-----
    </Value>
</PublicKey>

Określa klucz publiczny używany do weryfikowania podpisu na serwerze JWS. Użyj atrybutu ref, aby przekazać klucz w zmiennej przepływu, lub podaj klucz bezpośrednio zakodowany w formacie PEM. Użyj tylko wtedy, gdy algorytm to RS256/RS384/RS512, PS256/PS384/PS512 lub ES256/ES384/ES512.

<SecretKey/Value>

<SecretKey>
  <Value ref="private.your-variable-name"/>
</SecretKey>

Udostępnia tajny klucz używany do weryfikowania lub podpisywania tokenów za pomocą algorytmu HMAC. Używaj tylko wtedy, gdy algorytm ma wartość HS256, HS384, HS512. Użyj atrybutu ref, aby przekazać klucz w zmiennej przepływu.

<Źródło>

<Source>JWS-variable</Source>

Jeśli ta opcja jest obecna, określa zmienną przepływu, w której zasada ma znaleźć JWS do zweryfikowania.

Zmienne przepływu

Po pomyślnym zakończeniu zasady Verify JWS i Decode JWS ustawiają zmienne kontekstowe zgodnie z tym wzorcem:

jws.{policy_name}.{variable_name}

Jeśli na przykład nazwa zasady to verify-jws, to zasada zapisze algorytm określony w JWS w tej zmiennej kontekstowej: jws.verify-jws.header.algorithm

Informacje o błędach

W tej sekcji opisujemy kody błędów i komunikaty o błędach, które są zwracane, oraz zmienne błędów ustawiane przez Edge, gdy ta zasada wywołuje błąd. Te informacje są ważne, jeśli opracowujesz reguły dotyczące błędów do obsługi takich błędów. Więcej informacji znajdziesz w sekcjach Co musisz wiedzieć o błędach zasad i Postępowanie w przypadku błędów.

Błędy w czasie wykonywania

Te błędy mogą wystąpić podczas wykonywania zasady.

Błędy wdrażania

Te błędy mogą wystąpić podczas wdrażania serwera proxy zawierającego te zasady.

Zmienne błędów

Te zmienne są ustawiane, gdy wystąpi błąd środowiska wykonawczego. Więcej informacji znajdziesz w artykule Co musisz wiedzieć o błędach związanych z naruszeniem zasad.

Przykładowa odpowiedź na błąd

W przypadku obsługi błędów najlepiej jest zablokować część errorcode odpowiedzi błędu. Nie polegaj na tekście w polu faultstring, ponieważ może się on zmienić.

Przykładowa reguła błędu

<FaultRules>
    <FaultRule name="JWS Policy Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "TokenExpired")</Condition>
        </Step>
        <Condition>JWS.failed=true</Condition>
    </FaultRule>
</FaultRules>