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 |
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 |
false | Opcjonalnie |
włączone |
Ustaw jako true , aby wymuszać zasadę.
Ustaw wartość |
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. |
|
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>