Zweryfikuj zasady weryfikacji JWS

Wyświetlasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. info

Co

weryfikuje podpis w JWS otrzymanym od klientów lub innych systemów, Ta zasada wyodrębnia też nagłówki do zmiennych kontekstowych, dzięki czemu kolejne zasady lub warunki mogą sprawdzać te wartości, aby podejmować decyzje dotyczące autoryzacji lub routingu. Szczegółowe wprowadzenie znajdziesz w artykule Omówienie zasad JWS i JWT.

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

Informacje o elementach JWS oraz o sposobie ich szyfrowania i podpisywania znajdziesz w dokumencie RFC7515.

Wideo

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

Próbki

• Weryfikowanie dołączonego podpisu JWS utworzonego za pomocą algorytmu HS256
• Weryfikowanie odłączonego podpisu JWS podpisanego algorytmem RS256

Sprawdzanie dołączonego podpisu JWS utworzonego za pomocą algorytmu HS256

Ten przykładowy zasób zasad weryfikuje dołączony podpis JWS, który został podpisany za pomocą algorytmu szyfrowania HS256, HMAC z użyciem sumy kontrolnej SHA-256. JWS jest przekazywany w żądaniu proxy za pomocą parametru formularza o nazwie JWS. Klucz znajduje się w zmiennej o nazwie private.secretkey.

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

header.payload.signature

Konfiguracja zasady zawiera informacje, których Edge potrzebuje do zdekodowania i oceny JWS, np. gdzie znaleźć JWS (w zmiennej przepływu określonej w elemencie <Source>), wymagany algorytm podpisywania i gdzie znaleźć klucz tajny (przechowywany w zmiennej przepływu Edge, która mogła zostać pobrana np. z KVM Edge).

<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 proxy interfejsu API mogły sprawdzać te wartości. Listę zmiennych ustawianych przez te zasady znajdziesz w artykule Zmienne przepływu.

Weryfikowanie odłączonego podpisu JWS podpisanego algorytmem RS256

Ten przykładowy zasób weryfikuje odłączony JWS podpisany algorytmem RS256. Aby przejść weryfikację, musisz podać klucz publiczny. JWS jest przekazywany w żądaniu proxy za pomocą parametru formularza o nazwie JWS. Klucz publiczny znajduje się w zmiennej o nazwie public.publickey.

Odłączony JWS nie zawiera ładunku:

header..signature

To Ty musisz przekazać ładunek do zasady VerifyJWS, określając nazwę zmiennej zawierającej ładunek w elemencie <DetachedContent>. Określona treść w <DetachedContent> musi mieć oryginalną, niezakodowaną postać, w jakiej była w momencie tworzenia 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 proxy interfejsu API mogły sprawdzać te wartości. Listę zmiennych ustawianych przez te zasady znajdziesz w artykule Zmienne przepływu.

Ustawianie kluczowych elementów

Elementy, których używasz do określania klucza używanego do weryfikacji tokena 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 zasady Weryfikuj JWS opisuje elementy i atrybuty tej zasady.

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

Atrybuty, które mają zastosowanie do elementu najwyższego poziomu

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

Te atrybuty są wspólne dla wszystkich elementów nadrzędnych zasad.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Użyj tego atrybutu w połączeniu z atrybutem name, aby oznaczyć zasadę w edytorze 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* wykorzystują parę kluczy publiczny/tajny, a algorytmy HS* – udostępnione hasło. Zobacz też Informacje o algorytmach szyfrowania podpisu.

Możesz podać kilka wartości rozdzielonych przecinkami. Na przykład „HS256, HS512” lub „RS256, PS256”. Nie możesz jednak łączyć algorytmów HS* z żadnymi innymi ani algorytmów ES* z żadnymi innymi, ponieważ wymagają one 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ść roszczenia oraz czy potwierdzone wartości roszczeń są zgodne.

Dodatkowe roszczenie używa nazwy, która nie jest jedną ze standardowych, zarejestrowanych nazw roszczeń JWS. Wartość dodatkowego roszczenia może być ciągiem znaków, liczbą, wartością logiczną, mapą lub tablicą. Mapa to po prostu zbiór par nazwa/wartość. Wartość roszczenia dowolnego z tych typów można określić bezpośrednio w konfiguracji zasad lub pośrednio przez odwołanie do zmiennej przepływu.

Element <Claim> ma te atrybuty:

• name – (wymagany) nazwa deklaracji.
• ref – (opcjonalnie) nazwa zmiennej przepływu. Jeśli ta zmienna jest obecna, zasada użyje jej wartości jako roszczenia. Jeśli podasz zarówno atrybut ref, jak i wartość roszczenia, wartość ta będzie domyślna i zostanie użyta, jeśli odwołanie do zmiennej przepływu nie zostanie rozpoznane.
• type – (opcjonalnie) jeden z tych typów: string (domyślnie), number, boolean lub map.
• array – (opcjonalnie) ustaw na true, aby wskazać, czy wartość jest tablicą typów. Domyślnie: false.

<DetachedContent>

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

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

header.payload.signature

Jeśli do utworzenia odłączonego ładunku używasz zasady GenerateJWS, wygenerowany JWS pomija ładunek i ma postać:

header..signature

W przypadku odłączonego ładunku musisz przekazać go do zasady VerifyJWS za pomocą elementu <DetachedContent>. Określony ładunek treści musi być w oryginalnej, niezakodowanej formie, w jakiej był w momencie tworzenia podpisu JWS.

Zasada zwraca błąd, gdy:

• <DetachedContent> jest podany, gdy JWS nie zawiera odłączonego ładunku treści (kod błędu to steps.jws.ContentIsNotDetached).
• <DetachedContent> jest pomijany, 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 zgłaszała błąd, gdy którykolwiek nagłówek wymieniony w nagłówku crit JWS nie jest wymieniony w elemencie <KnownHeaders>. Jeśli ma wartość Prawda, zasada VerifyJWS ignoruje nagłówek crit.

Jednym z powodów ustawienia tego elementu na wartość „true” jest sytuacja, w której znajdujesz się w środowisku testowym i nie chcesz, aby zasady nie działały z powodu braku nagłówka.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Ustaw wartość „fałsz”, jeśli chcesz, aby zasada zgłaszała błąd, gdy nie można rozpoznać żadnej zmiennej, do której odwołuje się zasada. Ustaw wartość „true”, aby traktować każdą nierozwiązywalną zmienną jako pusty ciąg (null).

<KnownHeaders>

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

or:

<KnownHeaders ref=’variable_containing_headers’/>

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

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

Zasada VerifyJWS sprawdza nagłówek crit w JWS (jeśli istnieje) i w przypadku każdego wymienionego elementu sprawdza, czy element <KnownHeaders> również zawiera ten nagłówek. Element <KnownHeaders> może zawierać nadzbiór elementów wymienionych w crit. Wystarczy, że wszystkie nagłówki wymienione w parametrze crit będą wymienione w elemencie <KnownHeaders>. Każdy nagłówek, który zasada znajdzie w crit, a którego nie ma na liście w <KnownHeaders>, spowoduje niepowodzenie zasady VerifyJWS.

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żywaj tylko wtedy, gdy algorytm to RS256/RS384/RS512, PS256/PS384/PS512 lub ES256/ES384/ES512.

Jeśli przychodzący JWS zawiera identyfikator klucza, który występuje w zbiorze JWKS, zasada użyje prawidłowego klucza publicznego do zweryfikowania podpisu JWS. Więcej informacji o tej funkcji znajdziesz w artykule Weryfikowanie podpisu JWS za pomocą zestawu kluczy internetowych JSON (JWKS).

Jeśli pobierzesz wartość z publicznego adresu URL, pamięć podręczna na serwerach brzegowych będzie przechowywać JWKS 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 przekazać klucz w zmiennej przepływu lub bezpośrednio określić klucz zakodowany w formacie PEM. Używaj 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>

Zawiera klucz tajny używany do weryfikacji lub podpisywania tokenów za pomocą algorytmu HMAC. Używaj tylko wtedy, 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 jest obecny, określa zmienną przepływu, w której zasada oczekuje znalezienia JWS do zweryfikowania.

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

Odwołanie do błędu

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>