Zasady weryfikacji JWT

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

Co

Weryfikuje podpis JWT otrzymany od klientów lub innych systemów. Ta zasada również wyodrębnia deklaracje 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.

Gdy ta zasada jest wykonywana, Edge weryfikuje podpis JWT i sprawdza, czy ten token ważne według daty ważności i godziny „nie przed”, jeśli występują. Zasada może opcjonalnie Sprawdź też wartości konkretnych deklaracji JWT, takie jak podmiot, wydawca, odbiorców lub wartość dodatkowych roszczeń.

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, a żądanie jest nie możemy kontynuować. Jeśli nie można zweryfikować podpisu JWT lub jest on nieprawidłowy z powodu w jednym z sygnatur czasowych przetwarzanie zostanie wstrzymane, a w odpowiedzi zostanie zwrócony błąd.

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

Wideo

Obejrzyj krótki film, aby dowiedzieć się, jak sprawdzić podpis w tokenie JWT.

Próbki

• Zweryfikuj token JWT podpisany przy użyciu HS256 algorytm
• Weryfikowanie tokena JWT podpisanego przy użyciu RS256 algorytm

Weryfikowanie tokena JWT podpisanygo przy użyciu HS256 algorytm

Ta przykładowa zasada weryfikuje token JWT podpisany przy użyciu 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 private.secretkey. Pełny przykład wraz z instrukcjami zgłaszania żądania dotyczącego tych zasad znajdziesz w filmie powyżej.

Konfiguracja zasady zawiera informacje, które Edge musi zdekodować i ocenić token JWT. np. gdzie znaleźć token JWT (w zmiennej przepływu określonej w elemencie źródłowym), wymagany jest algorytmu podpisywania, gdzie można znaleźć tajny klucz (zapisany w zmiennej przepływu Edge, która może zostały pobrane np. z Edge KVM), a także zbiór wymaganych roszczeń oraz ich .

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

Weryfikacja tokena JWT podpisany przy użyciu RS256 algorytm

Ta przykładowa zasada weryfikuje token JWT podpisany przy użyciu algorytmu RS256. Aby dokonać weryfikacji, 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. Pełny przykład wraz z instrukcjami zgłaszania żądania dotyczącego tych zasad znajdziesz w filmie powyżej.

Szczegółowe informacje o wymaganiach i opcjach dla każdego elementu znajdziesz w dokumentacji Element przykładowej zasady.

<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 ten ł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 podpis może zostać zweryfikowany za pomocą podanych publicznie .

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 wtedy, gdy uda się zweryfikować podpis, ponieważ „subskrypcja” deklaracja uwzględniona w tokenie JWT nie pasuje do wymaganej wartości „Subject” jako element określone w konfiguracji zasady.

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 używane do określania klucza używanego do weryfikacji tokena JWT zależą od wybranego algorytmu. zgodnie z poniższą tabelą:

<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 zasady zawiera opis jej elementów i atrybutów.

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

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

<Audience>

<Audience>audience-here</Audience>

or:

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

Ta zasada sprawdza, czy deklaracja odbiorców w tokenie JWT jest zgodna z wartością określoną w konfiguracji. Jeśli nie ma dopasowania, zasada zgłasza błąd. To twierdzenie określa dla których jest przeznaczony token JWT. Jest to jedno z zarejestrowanych roszczeń wymienionych w RFC7519.

<AdditionalClaims/Claim>

<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 pole dopasowania potwierdzonych wartości roszczenia.

Dodatkowa deklaracja używa nazwy, która nie jest jedną ze standardowych, zarejestrowanych nazw deklaracji JWT. 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).

Jeśli uwzględnisz element <Claim>, nazwy roszczeń będą ustawiane statycznie, gdy skonfiguruj zasadę. Możesz też przekazać obiekt JSON, aby określić nazwy twierdzeń. Obiekt JSON jest przekazywany jako zmienna, więc nazwy roszczeń są określane w czasie działania.

Na przykład:

<AdditionalClaims ref='json_claims'/>

Gdzie 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 }
  }
}

<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 JWT zawiera podane dodatkowe pary nazwy/wartości deklaracji i czy podane wartości deklaracji są zgodne.

Dodatkowa deklaracja używa nazwy, która nie jest jedną ze standardowych, zarejestrowanych nazw deklaracji JWT. 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).

<CustomClaims>

Uwaga: obecnie element CustomClaims jest wstawiony podczas dodawania nowego elementu Wygeneruj zasadę JWT za pomocą interfejsu użytkownika. Ten element nie działa i jest ignorowany. Prawidłowo zostanie użyty element <AdditionalClaims>. Interfejs zostanie później zaktualizowany, aby wstawić prawidłowe elementy.

<Id>

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

Sprawdza, czy token JWT ma konkretną deklarację jti. Kiedy wartość tekstowa i odsyłacz są puste, zasada wygeneruje identyfikator jti zawierający losowy identyfikator UUID. Identyfikator JWT Deklaracja (jti) to unikalny identyfikator JWT. Więcej informacji na temat jti znajdziesz w dokumencie RFC7519.

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

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

Jednym z powodów, dla których warto ustawić wartość tego elementu, jest to, że w środowisku testowym gotowy do zgłoszenia awarii brakującego nagłówka.

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

Ustaw wartość false (fałsz) (domyślnie), jeśli zasada ma generować błąd, gdy token JWT zawiera Roszczenie iat (wystawione w dniu) określające godzinę w przyszłości. Ustaw wartość Prawda, aby zasada ignorowała iat podczas weryfikacji.

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

<Issuer>

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

Zasada sprawdza, czy wydawca w tokenie JWT jest zgodny z ciągiem określonym w . Deklaracja identyfikująca wydawcę JWT. To jest jeden z zarejestrowany zestaw roszczeń wymienionych w dokumencie RFC7519.

<KnownHeaders>

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

or:

<KnownHeaders ref=’variable_containing_headers’/>

Zasada GenerateJWT używa elementu <CriticalHeaders> do wypełniania pola crit w JWT. Na przykład:

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

Zasada VerifyJWT sprawdza nagłówek crit w tokenie JWT (jeśli istnieje) i każdy nagłówek, który go zawiera. 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 <KnownHeaders>, powoduje niepowodzenie zasady VerifyJWT.

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

<PublicKey/Certificate>

<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 tokena JWT. Użyj atrybutu ref, aby przekazać podpisany certyfikat w zmiennej przepływu lub bezpośrednio wskazać certyfikat zakodowany w formacie PEM. Używaj tylko wtedy, gdy algorytm to 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) 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 token JWT zawiera identyfikator klucza znajdujący się w zestawie JWKS, zasada użyje odpowiedniego klucza publicznego do weryfikacji podpisu JWT. Więcej informacji na temat tej funkcji można znaleźć w sekcji Użycie zestawu kluczy internetowych JSON (JWKS) do weryfikacji tokena JWT

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.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 weryfikacji podpisu tokena JWT. Użyj atrybutu ref, aby przekazać klucz/certyfikat w zmiennej przepływu lub bezpośrednio podać klucz zakodowany w formacie PEM. Używaj tylko wtedy, gdy algorytm 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 weryfikacji lub podpisywania tokenów za pomocą algorytmu HMAC. Tylko używanie gdy algorytm to HS256, HS384 lub HS512.

<Source>

<Source>jwt-variable</Source>

Jeśli ten parametr jest używany, określa zmienną przepływu, w której zasada spodziewa się znaleźć token JWT weryfikacji.

<Subject>

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

Zasada sprawdza, czy podmiot w tokenie JWT jest zgodny z ciągiem określonym w zasadzie. konfiguracji. Ta deklaracja określa lub zawiera oświadczenie na temat podmiotu tokena JWT. To jest jednego ze standardowych zestawów deklaracji wymienionych w dokumencie RFC7519.

<TimeAllowance>

<TimeAllowance>120s</TimeAllowance>

„Okres prolongaty” . Jeśli np. limit czasu jest ustawiony na 60 sekund, nieważny token JWT będzie traktowany jako nadal ważny przez 60 sekund od potwierdzonego wygaśnięcia. czasu „nie przed czasem” będą oceniane w podobny sposób. Domyślna wartość to 0 sekund (bez okresu prolongaty).

Zmienne przepływu

Gdy operacja się uda, zostaną ustawione zasady Zweryfikuj token JWT i dekoduj JWT zmiennych kontekstowych zgodnie z tym wzorcem:

jwt.{policy_name}.{variable_name}

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

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