Zasada dekodowania JWS

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

Co

Dekoduje nagłówek JWS bez weryfikacji podpisu na JWS i zapisuje każdy nagłówek w zmiennej przepływu. Ta zasada jest najbardziej przydatna, gdy jest używana w połączeniu z zasadąVerifyJWS, gdy wartość nagłówka z JWS musi być znana przed zweryfikowaniem podpisu JWS.

Ładunek JWS może mieć dołączony ładunek w ten sposób:

header.payload.signature

JWS może też pominąć ładunek (tzw. detached) i mieć postać:

header..signature

Zasada DecodeJWS działa z obydwoma formularzami, ponieważ dekoduje tylko część nagłówka JWS. Zasada DecodeJWS działa też niezależnie od algorytmu użytego do podpisania JWS.

Szczegółowe informacje i omówienie formatu JWS znajdziesz w opisie zasad JWS i JWT.

Wideo

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

Przykład: dekodowanie JWS

Zasada przedstawiona poniżej dekoduje JWS w zmiennej przepływu var.JWS. Ta zmienna musi być obecna i zawierać realny (decodowalny) plik JWS. Zasada może uzyskać JWS z dowolnej zmiennej przepływu.

<DecodeJWS name="JWS-Decode-HS256">
    <DisplayName>JWS Verify HS256</DisplayName>
    <Source>var.JWS</Source>
</DecodeJWS>

W każdym nagłówku w nagłówku pliku JWS zasada ustawia zmienną przepływu o nazwie:

jws.policy-name.header.header-name

Jeśli JWS ma dołączony ładunek, ustawia do ładunku zmienną przepływu jws.policy-name.header.payload. W przypadku odłączonego ładunku wartość payload jest pusta. Pełną listę zmiennych ustawionych przez tę zasadę znajdziesz w sekcji Zmienne przepływu.

Dokumentacja elementu Decode JWS

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

Atrybuty stosowane do elementu najwyższego poziomu

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

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

Atrybut Opis Domyślnie Obecność
nazwa Wewnętrzna nazwa zasady. Znaki, których możesz używać w nazwie, są ograniczone do: A-Z0-9._\-$ %. Interfejs zarządzania brzegowymi wymusza jednak dodatkowe ograniczenia, takie jak automatyczne usuwanie znaków niealfanumerycznych.

Opcjonalnie możesz użyć elementu <displayname></displayname>, aby oznaczyć zasadę w edytorze serwera proxy interfejsu zarządzania inną nazwą w języku naturalnym.

Nie dotyczy Wymagane
continueOnError Ustaw wartość false, aby zwracać błąd w przypadku niepowodzenia zasady. Jest to normalne działanie większości zasad.

Ustaw jako true, aby wykonywanie przepływu było kontynuowane nawet po awarii zasady.

false Opcjonalnie
włączone Ustaw jako true, aby wymuszać zasadę.

Ustaw wartość false, aby „wyłączyć” zasadę. Zasada nie będzie egzekwowana, nawet jeśli pozostanie dołączona do procesu.

prawda Opcjonalnie
async Ten atrybut został wycofany. false Wycofano

<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.

Domyślnie Jeśli pominiesz ten element, zostanie użyta wartość atrybutu nazwa zasady.
Obecność Opcjonalnie
Typ Ciąg znaków

<Ź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 zdekodowania.

Domyślnie request.header.authorization (Ważne informacje o wartości domyślnej znajdziesz powyżej).
Obecność Opcjonalnie
Typ Ciąg znaków
Prawidłowe wartości Nazwa zmiennej przepływu Edge

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

Nazwa zmiennej Opis
decoded.header.name Poddawana analizie JSON wartość nagłówka w ładunku. Dla każdego nagłówka w ładunku ustawiana jest 1 zmienna. Chociaż możesz też używać zmiennych przepływu header.name, jest to zalecana zmienna, która pozwala uzyskiwać dostęp do nagłówka.
header.algorithm Algorytm podpisywania używany w JWS. Na przykład RS256, HS384 itd. Więcej informacji znajdziesz w sekcji Parametr nagłówka(algorytm).
header.kid Identyfikator klucza, jeśli został dodany podczas generowania JWS. Aby dowiedzieć się, jak zweryfikować JWS, zapoznaj się też z sekcją o korzystaniu z zestawu kluczy sieciowych JSON (JWKS) w omówieniu zasad JWT i JWS. Więcej informacji znajdziesz w sekcji Parametr nagłówka(identyfikator klucza).
header.type Wartość typu nagłówka. Więcej informacji znajdziesz w sekcji Parametr nagłówka(typ).
header.name Wartość nazwanego nagłówka (standardowa lub dodatkowa). Jeden z nich zostanie ustawiony dla każdego dodatkowego nagłówka w części nagłówka pliku JWS.
header-json Nagłówek w formacie JSON.
payload Ładunek JWS, jeśli do JWS jest dołączony ładunek. W przypadku odłączonego ładunku ta zmienna jest pusta.
valid W przypadku WeryfikacjaJWS ta zmienna ma wartość prawdziwą, gdy podpis jest weryfikowany, a bieżący czas przypada przed wygaśnięciem tokena i po wartości notBefore tokena, jeśli występują. W przeciwnym razie ma wartość Fałsz.

W przypadku DecodeJWS ta zmienna nie jest ustawiona.

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.

Kod błędu Stan HTTP Występuje, gdy
steps.jws.FailedToDecode 401 Nie udało się zdekodować JWS za pomocą zasady. Być może JWS jest uszkodzony.
steps.jws.FailedToResolveVariable 401 Występuje, gdy zmienna przepływu określona w elemencie <Source> zasady nie istnieje.
steps.jws.InvalidClaim 401 Brak zgodności z deklaracją lub zgłoszeniem albo brak zgodności nagłówka lub nagłówka.
steps.jws.InvalidJsonFormat 401 W nagłówku JWS znaleziono nieprawidłowy kod JSON.
steps.jws.InvalidJws 401 Ten błąd występuje, gdy weryfikacja podpisu JWS nie powiedzie się.
steps.jws.InvalidPayload 401 Ładunek JWS jest nieprawidłowy.
steps.jws.InvalidSignature 401 Element <DetachedContent> jest pominięty, a JWS ma odłączony ładunek treści.
steps.jws.MissingPayload 401 Brak ładunku JWS.
steps.jws.NoAlgorithmFoundInHeader 401 Występuje, gdy JWS pomija nagłówek algorytmu.
steps.jws.UnknownException 401 Wystąpił nieznany wyjątek.

Błędy wdrażania

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

Nazwa błędu Występuje, gdy
InvalidAlgorithm Jedyne prawidłowe wartości to: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, HS256, HS384, HS512.

EmptyElementForKeyConfiguration

FailedToResolveVariable

InvalidConfigurationForActionAndAlgorithmFamily

InvalidConfigurationForVerify

InvalidEmptyElement

InvalidFamiliesForAlgorithm

InvalidKeyConfiguration

InvalidNameForAdditionalClaim

InvalidNameForAdditionalHeader

InvalidPublicKeyId

InvalidPublicKeyValue

InvalidSecretInConfig

InvalidTypeForAdditionalClaim

InvalidTypeForAdditionalHeader

InvalidValueForElement

InvalidValueOfArrayAttribute

InvalidVariableNameForSecret

MissingConfigurationElement

MissingElementForKeyConfiguration

MissingNameForAdditionalClaim

MissingNameForAdditionalHeader

Inne możliwe błędy wdrażania.

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.

Zmienne Gdzie Przykład
fault.name="fault_name" fault_name to nazwa błędu podana w tabeli Błędy środowiska wykonawczego powyżej. Nazwa błędu to ostatnia część kodu. fault.name Matches "TokenExpired"
JWS.failed Wszystkie zasady JWS ustawiają tę samą zmienną w przypadku niepowodzenia. jws.JWS-Policy.failed = true

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>