Zweryfikuj zasady weryfikacji JWS

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

Co

Weryfikuje podpis na JWS otrzymany od klientów lub innych systemów. Ta zasada również wyodrębnia nagłówki do zmiennych kontekstowych, aby umożliwić analizę kolejnych zasad lub warunków do podejmowania 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 jest nie możemy kontynuować. Jeśli nie można zweryfikować podpisu JWS lub klucz JWS jest nieprawidłowy z powodu w odpowiedzi wystąpi jakiś typ błędu, przetwarzanie zostanie zatrzymane, a w odpowiedzi zostanie zwrócony błąd.

Informacje o częściach kodu JWS oraz sposobie ich szyfrowania i podpisywania znajdziesz tutaj: RFC7515

Wideo

Obejrzyj krótki film, aby dowiedzieć się, jak zweryfikować podpis w JWS. W tym filmie związane z weryfikacją JWT, wiele koncepcji jest jednakowych dla JWS.

Próbki

• Sprawdź załączony JWS podpisany przy użyciu kodu HS256 algorytm
• Sprawdź odłączony klucz JWS podpisany przy użyciu protokołu RS256 algorytm

Zweryfikuj załączony JWS podpisany przy użyciu HS256 algorytm

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

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

header.payload.signature

Konfiguracja zasad zawiera informacje, których Edge potrzebuje do zdekodowania i oceny JWS. np. gdzie znaleźć kod JWS (w zmiennej przepływu określonej w elemencie <Source>), wymagany algorytm podpisywania oraz gdzie można znaleźć tajny klucz (zapisany w zmiennej przepływu Edge, która może zostały pobrane np. 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 za pośrednictwem serwera proxy interfejsu API może badać te wartości. W sekcji Zmienne przepływu znajdziesz listę zmiennych ustawionych przez tę zasadę.

Sprawdź odłączony klucz JWS podpisany przy użyciu protokołu RS256 algorytm

Ta przykładowa zasada weryfikuje odłączony klucz JWS, który został podpisany za pomocą algorytmu RS256. Aby dokonać weryfikacji, musisz podać klucz publiczny. Plik 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łączona wersja JWS pomija ładunek w JWS:

header..signature

Od Ciebie zależy, czy przekażesz ładunek do zasady VerifyJWS przez określenie nazwy zmiennej zawierającej ładunek do <DetachedContent> element. Określona treść w polu <DetachedContent> musi być w oryginalnej, niezakodowanej formie w postaci 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 za pośrednictwem serwera proxy interfejsu API może badać te wartości. W sekcji Zmienne przepływu znajdziesz listę zmiennych ustawionych przez tę zasadę.

Wyznaczanie kluczowych elementów

Elementy służące do określania klucza używanego do weryfikacji JWS zależą od wybranego algorytmu. zgodnie z poniższą tabelą:

<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

Informacje o zasadach zawierają opis elementów i atrybutów zasady weryfikacji JWS.

Uwaga: konfiguracja może się nieco różnić w zależności od szyfrowania stosowanego algorytmu. Zapoznaj się z przykładami, aby zademonstrować do konkretnych zastosowań.

Atrybuty dotyczące element 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 [nazwa], aby oznaczyć zasadę etykietą w edytorze serwera proxy w interfejsie zarządzania z inną nazwą w języku naturalnym.

<Algorithm>

<Algorithm>HS256</Algorithm>

Określa algorytm szyfrowania do podpisywania tokena. algorytmy RS*/PS*/ES* wykorzystują parę kluczy publiczny/tajny, a algorytmy HS* używają wspólnego obiektu tajnego. Zobacz też . Informacje o algorytmach szyfrowania podpisu

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

<AdditionalHeaders/Claim>

<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 nazwa/wartość żądania i czy podane wartości deklaracji pasują.

Dodatkowe żądanie używa nazwy, która nie jest jedną ze standardowych, zarejestrowanych nazw deklaracji JWS. Wartością dodatkowego żądania może być ciąg, liczba, wartość logiczna, mapa lub tablica. Mapa to po prostu zbiór par nazwa/wartość. Wartość roszczenia dowolnego z tych typów można określić bezpośrednio w konfiguracji zasady lub pośrednio przez odwołanie do zmiennej przepływu.

Element <Claim> ma te atrybuty:

• name – (wymagany) nazwa roszczenia.
• ref – (opcjonalny) nazwa zmiennej przepływu. Jeśli ten parametr jest obecny, zasada użyje wartości tego parametru jako twierdzenia. Jeśli podasz zarówno atrybut ref, jak i jednoznaczną wartość roszczenia, w parametrze wartość wyraźna jest wartością domyślną i jest używana, jeśli wskazana zmienna przepływu nie została rozwiązana.
• type – (opcjonalny) jeden z: ciąg (wartość domyślna), liczba, wartość logiczna lub mapa.
• array – (opcjonalny) ustaw wartość true, aby wskazać, czy wartość jest tablicą typów. Domyślne: false (fałsz).

<DetachedContent>

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

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

header.payload.signature

Jeśli do utworzenia ładunku odłączonego zostanie użyta zasada GenerateJWS, wygenerowany JWS pominie ładunek i w formacie:

header..signature

W przypadku odłączonego ładunku Twoim obowiązkiem jest przekazanie go do zasady VerifyJWS za pomocą metody <DetachedContent> element. Określony ładunek treści musi znajdować się w sekcji w pierwotnej, niezakodowanej formie.

Zasada zgłasza błąd, gdy:

• Jeśli plik JWS nie zawiera odłączonych treści, określono <DetachedContent> ładunek (kod błędu: steps.jws.ContentIsNotDetached).
• Pole <DetachedContent> jest pomijane, a narzędzie JWS ma odłączony ładunek treści (kod błędu: steps.jws.InvalidSignature).

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

Jeśli chcesz, aby zasada zwracała błąd, gdy dowolny nagłówek wymieniony w polu nagłówka crit biblioteki JWS nie jest wymieniony w elemencie <KnownHeaders>. Ustaw wartość „true”, aby zasada VerifyJWS ignorowała nagłówek crit.

Jednym z powodów, dla których warto ustawić wartość tego elementu, jest to, że w środowisku testowym nie chcesz, aby zasada została naruszona z powodu brakującego nagłówka.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Jeśli chcesz, aby zasada zwracała błąd, gdy określona zmienna jest wskazana, ustaw wartość Fałsz. jest nierozstrzygnięta. Ustaw wartość „true”, aby traktować każdą nierozpoznawalną zmienną jako pusty ciąg znaków (null).

<KnownHeaders>

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

or:

<KnownHeaders ref=’variable_containing_headers’/>

Zasada GenerateJWS używa elementu <CriticalHeaders> do wypełniania parametru crit w tokenie. Na przykład:

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

Zasada VerifyJWS sprawdza nagłówek crit w JWS, jeśli istnieje, i dla każdego elementu na liście. sprawdza, czy element <KnownHeaders> zawiera też ten nagłówek. Element <KnownHeaders> może zawierać nadzbiór elementów wymienionych w elemencie crit. Konieczne jest jedynie, aby wszystkie nagłówki wymienione w sekcji crit były wymienione w <KnownHeaders>. każdy nagłówek znaleziony przez zasadę w sekcji crit; który nie jest wymieniony w tabeli <KnownHeaders>, powoduje błąd zasady VerifyJWS.

Opcjonalnie możesz skonfigurować zasadę VerifyJWS tak, aby ignorowała nagłówek crit przez 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) który zawiera zestaw kluczy publicznych. Używaj tylko wtedy, gdy algorytm to RS256/RS384/RS512, PS256/PS384/PS512 lub ES256/ES384/ES512.

Jeśli przychodzący JWS zawiera identyfikator klucza znajdujący się w zestawie JWKS, zasada użyje odpowiedniego klucza publicznego do weryfikacji podpisu JWS. Więcej informacji na temat tej funkcji można znaleźć w sekcji Użycie zestawu kluczy internetowych JSON (JWKS) do weryfikacji kodu JWS.

Jeśli pobierzesz wartość z publicznego adresu URL, Edge będzie przechowywać kod JWKS w pamięci podręcznej przez 300 sekund. Gdy pamięć podręczna wygaśnie, Edge ponownie pobierze 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 weryfikacji podpisu w JWS. Użyj atrybutu ref, aby przekaż klucz w zmiennej przepływu lub podaj klucz zakodowany bezpośrednio w formacie PEM. Używaj tylko wtedy, gdy algorytm 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 weryfikacji lub podpisywania tokenów za pomocą algorytmu HMAC. Tylko używanie gdy algorytm to HS256, HS384 lub HS512. Użyj atrybutu ref. aby przekazać klucz w zmiennej przepływu.

<Source>

<Source>JWS-variable</Source>

Jeśli istnieje, określa zmienną przepływu, w której zasada oczekuje, że kod JWS zostanie znaleziony weryfikacji.

Zmienne przepływu

Po pomyślnym zakończeniu zostają ustawione zasady Weryfikuj JWS i Decode JWS. zmiennych kontekstowych zgodnie z tym wzorcem:

jws.{policy_name}.{variable_name}

Jeśli na przykład nazwa zasady to verify-jws, to zasada będzie przechowywać algorytm określony w JWS na tę zmienną kontekstową: jws.verify-jws.header.algorithm

Informacje o błędzie

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 po wystąpieniu błędu działania. Więcej informacji znajdziesz w artykule Podstawowe informacje o błędach związanych z naruszeniem zasad.

Przykładowa odpowiedź na błąd

W przypadku obsługi błędów sprawdzoną metodą jest przechwycenie części błędu errorcode. . Nie polegaj na tekście zawartym w pliku 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>