Zasady weryfikacji JWT

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

Co

Weryfikuje podpis tokena JWT odebrany od klientów lub innych systemów. Ta zasada wyodrębnia też deklaracje do zmiennych kontekstowych, aby kolejne zasady lub warunki mogły analizować te wartości w celu podejmowania decyzji dotyczących autoryzacji lub routingu. Szczegółowe informacje znajdziesz w omówieniu zasad JWS i JWT.

Gdy ta zasada jest uruchamiana, Edge sprawdza podpis tokena JWT i sprawdza, czy token JWT jest prawidłowy zgodnie z datą wygaśnięcia i czy wcześniejszy, jeśli taki istnieje. Zasada może też opcjonalnie weryfikować wartości konkretnych deklaracji tokena JWT, takie jak temat, wydawca, grupa odbiorców lub wartość dodatkowych deklaracji.

Jeśli token JWT jest zweryfikowany i prawidłowy, wszystkie zawarte w nim deklaracje są wyodrębniane do zmiennych kontekstowych do wykorzystania w kolejnych zasadach lub warunkach i może być kontynuowane. Jeśli nie można zweryfikować podpisu JWT lub token JWT jest nieprawidłowy z powodu jednej z sygnatur czasowych, przetwarzanie zostanie zatrzymane, a w odpowiedzi zostanie zwrócony błąd.

Informacje o częściach tokena JWT oraz sposobach ich szyfrowania i podpisywania znajdziesz w dokumencie RFC7519.

Wideo

Obejrzyj krótki film, aby dowiedzieć się, jak zweryfikować podpis tokena JWT.

Przykłady

• Weryfikowanie tokena JWT podpisanego za pomocą algorytmu HS256
• Weryfikowanie tokena JWT podpisanego za pomocą algorytmu RS256

Zweryfikuj token JWT podpisany za pomocą algorytmu HS256

Ta przykładowa zasada weryfikuje token JWT podpisany za pomocą algorytmu szyfrowania HS256 HMAC z użyciem sumy kontrolnej SHA-256. Token JWT jest przekazywany w żądaniu serwera proxy za pomocą parametru formularza o nazwie jwt. Klucz jest zawarty w zmiennej o nazwie private.secretkey. Obejrzyj film powyżej, aby zobaczyć pełny przykład, w tym, jak przesłać żądanie zgodności z zasadami.

Konfiguracja zasady obejmuje informacje potrzebne Edge do dekodowania i oceny tokena JWT, na przykład miejsce znalezienia tokena JWT (w zmiennej przepływu określonej w elemencie Source), wymagany algorytm podpisywania, miejsce przechowywania tajnego klucza (przechowywanego w zmiennej przepływu brzegowego, która na przykład mogła zostać pobrana z Edge KVM), a także zestaw wymaganych deklaracji i ich wartości.

<VerifyJWT name="JWT-Verify-HS256">
    <DisplayName>JWT Verify HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <Source>request.formparam.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey encoding="base64">
        <Value ref="private.secretkey"/>
    </SecretKey>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
</VerifyJWT>

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 token JWT podpisany za pomocą algorytmu RS256

Ta przykładowa zasada weryfikuje token JWT podpisany za pomocą algorytmu RS256. Aby przeprowadzić weryfikację, musisz podać klucz publiczny. Token JWT jest przekazywany w żądaniu serwera proxy za pomocą parametru formularza o nazwie jwt. Klucz publiczny jest zawarty w zmiennej o nazwie public.publickey. Obejrzyj film powyżej, aby zobaczyć pełny przykład, w tym, jak przesłać żądanie zgodności z zasadami.

Szczegółowe informacje o wymaganiach i opcjach dotyczących poszczególnych elementów w tej przykładowej zasadzie znajdziesz w dokumentacji elementów.

<VerifyJWT name="JWT-Verify-RS256">
    <Algorithm>RS256</Algorithm>
    <Source>request.formparam.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <Value ref="public.publickey"/>
    </PublicKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>    
    </AdditionalClaims>
</VerifyJWT>

W przypadku powyższej konfiguracji token JWT z tym nagłówkiem...

{
  "typ" : "JWT", 
  "alg" : "RS256"
}

A te ładunek...

{ 
  "sub" : "apigee-seattle-hatrack-montage",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a",
  "show": "And now for something completely different."
}

... zostanie uznany za prawidłowy, jeśli można zweryfikować podpis za pomocą podanego klucza publicznego.

Token JWT z tym samym nagłówkiem, ale z tym ładunkiem...

{ 
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a",
  "show": "And now for something completely different."
}

... zostanie uznany za nieprawidłowy, nawet jeśli można zweryfikować podpis, ponieważ deklaracja „sub” zawarta w tokenie JWT nie odpowiada wymaganej wartości elementu „Subject” określonej w konfiguracji zasady.

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ślenia klucza do weryfikacji tokena JWT, zależą od wybranego algorytmu, jak pokazano w tej tabeli:

<SecretKey encoding="base16|hex|base64|base64url">
  <Value ref="private.secretkey"/>
</SecretKey>

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

<PublicKey>
  <Certificate ref="signed_cert_val_ref"/>
</PublicKey>

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

Odwołanie do elementu

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

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

<VerifyJWT name="JWT" 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*.

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable-name-here'/>

Zasada weryfikuje, czy deklaracja odbiorców w JWT odpowiada wartości określonej w konfiguracji. W przypadku braku dopasowań zasada zgłasza błąd. Ta deklaracja określa odbiorców, dla których przeznaczony jest token JWT. Jest to jedno z zarejestrowanych roszczeń wymienionych w dokumencie RFC7519.

<Dodatkowe roszczenia/roszczenie>

<AdditionalClaims>
    <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'/>
 </AdditionalClaims>

or:

<AdditionalClaims ref='claim_payload'/>

Sprawdza, czy ładunek JWT zawiera określone dodatkowe deklaracje i czy wartości zgłoszonych deklaracji są zgodne.

Dodatkowa deklaracja używa nazwy innej niż standardowa, zarejestrowana nazwa deklaracji JWT. 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.

Jeśli dodasz element <Claim>, nazwy deklaracji będą ustawiane statycznie podczas konfigurowania zasady. Możesz też przekazać obiekt JSON, aby określić nazwy deklaracji. Obiekt JSON jest przekazywany jako zmienna, więc nazwy deklaracji są określane w czasie działania.

Na przykład:

<AdditionalClaims ref='json_claims'/>

Zmienna json_claims zawiera obiekt JSON w formacie:

{
  "sub" : "person@example.com",
  "iss" : "urn://secure-issuer@example.com",
  "non-registered-claim" : {
    "This-is-a-thing" : 817,
    "https://example.com/foobar" : { "p": 42, "q": false }
  }
}

<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 JWT zawiera określone pary nazw i wartości dodatkowych deklaracji oraz czy wartości zgłoszonych deklaracji są zgodne.

Dodatkowa deklaracja używa nazwy, która nie jest standardową, zarejestrowaną nazwą deklaracji JWT. 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.

<CustomClaims>

Uwaga: obecnie element CustomClaims jest wstawiony podczas dodawania w interfejsie nowej zasady WygenerujJWT. Ten element nie działa i jest ignorowany. Prawidłowy element, którego możesz użyć zamiast niego, to <AdditionalClaims>. Interfejs zostanie zaktualizowany tak, by później wstawić odpowiednie elementy.

<Identyfikator>

<Id>explicit-jti-value-here</Id>
 -or-
<Id ref='variable-name-here'/>
 -or-
<Id/>

Sprawdza, czy token JWT zawiera określone żądanie jti. Gdy zarówno wartość tekstowa, jak i atrybut ref są puste, zasada wygeneruje jti zawierający losowy identyfikator UUID. Deklaracja identyfikatora JWT (jti) jest unikalnym identyfikatorem tokena JWT. Więcej informacji na temat jti znajdziesz w dokumencie RFC7519.

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

Ustaw wartość „false”, jeśli chcesz, by zasada zwracała błąd, gdy którykolwiek nagłówek podany w nagłówku crit tokena JWT nie jest wymieniony w elemencie <KnownHeaders>. Ustaw wartość true, aby spowodować, że zasada weryfikacji JWT ignoruje nagłówek crit.

Jednym z powodów, dla których ten element należy ustawić na wartość Prawda, jest sytuacja, w której znajdujesz się w środowisku testowym i nie możesz jeszcze spowodować błędu związanego z brakującym nagłówkiem.

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

Ustaw wartość „false” (fałsz), jeśli chcesz, by zasada zgłaszała błąd, gdy token JWT zawiera deklarację iat (wydana o) wskazującą godzinę w przyszłości. Ustaw wartość „true” (prawda), aby zasada ignorowała atrybut iat podczas weryfikacji.

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

<Issuer>

<Issuer ref='variable-name-here'/>
<Issuer>issuer-string-here</Issuer>

Zasada weryfikuje, czy wydawca w tokenie JWT pasuje do ciągu określonego w elemencie konfiguracji. Deklaracja, która identyfikuje wydawcę tokena JWT. Jest to jeden z zarejestrowanych zestawów roszczeń wymienionych w dokumencie RFC7519.

<KnownHeaders>

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

or:

<KnownHeaders ref=’variable_containing_headers’/>

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

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

Zasada weryfikacji JWT sprawdza nagłówek crit w tokenie JWT, jeśli taki istnieje, i sprawdza, czy element <KnownHeaders> zawiera też dany nagłówek w przypadku każdego wymienionego nagłówka. 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 przez zasadę w crit, który nie jest wymieniony w <KnownHeaders>, powoduje błędy zasady weryfikacji JWT.

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

<Klucz publiczny/certyfikat>

<PublicKey>
   <Certificate ref="signed_public.cert"/>
</PublicKey>
-or-
<PublicKey>
    <Certificate>
    -----BEGIN CERTIFICATE-----
    cert data
    -----END CERTIFICATE-----
    </Certificate>
</PublicKey>

Określa podpisany certyfikat używany do weryfikacji podpisu w tokenie JWT. Użyj atrybutu ref, aby przekazać podpisany certyfikat w zmiennej przepływu, lub podaj certyfikat bezpośrednio zakodowany w formacie PEM. Używaj tylko w przypadku algorytmu RS256/RS384/RS512, PS256/PS384/PS512 lub ES256/ES384/ES512.

<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 token JWT nosi identyfikator klucza, który znajduje się w zestawie JWKS, zasada użyje odpowiedniego klucza publicznego do zweryfikowania podpisu JWT. Więcej informacji o tej funkcji znajdziesz w artykule o weryfikowaniu tokena JWT 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.publickeyorcert"/>
</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 lub certyfikat publiczny używany do weryfikowania podpisu w tokenie JWT. Użyj atrybutu ref, aby przekazać klucz/certyfikat 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 encoding="base16|hex|base64|base64url">
  <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.

<Źródło>

<Source>jwt-variable</Source>

Jeśli istnieje, określa zmienną przepływu, w której zasada ma znaleźć token JWT do zweryfikowania.

<Subject>

<Subject>subject-string-here</Subject>

Zasada weryfikuje, czy podmiot w JWT pasuje do ciągu określonego w konfiguracji zasady. Deklaracja wskazuje lub zawiera informację na temat tematu tokena JWT. Jest to jeden ze standardowych zestawów twierdzeń wymienionych w dokumencie RFC7519.

<TimeAllowance>

<TimeAllowance>120s</TimeAllowance>

„Okres prolongaty” dla godzin Jeśli na przykład limit czasu jest ustawiony na 60 s, nieważny token JWT będzie traktowany jako prawidłowy przez 60 sekund po potwierdzeniu wygaśnięcia. Czas inny niż wcześniej zostanie oceniony podobnie. Domyślna wartość to 0 sekund (bez okresu prolongaty).

Zmienne przepływu

Gdy się uda, zasady Zweryfikuj JWT i Dekodowanie JWT ustawiają zmienne kontekstowe zgodnie z tym wzorcem:

jwt.{policy_name}.{variable_name}

Jeśli na przykład nazwa zasady to jwt-parse-token, zasada będzie zapisywać w zmiennej kontekstowej jwt.jwt-parse-token.decoded.claim.sub podmiot określony w tokenie JWT. (Aby zapewnić zgodność wsteczną, będzie ona też dostępna w języku: jwt.jwt-parse-token.claim.subject).

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="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "TokenExpired")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>