Zasady weryfikacji JWT

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

Co

Weryfikuje podpis w JWT otrzymanym od klientów lub innych systemów. Ta zasada wyodrębnia też roszczenia 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.

Gdy ta zasada jest wykonywana, Edge weryfikuje podpis tokena JWT i sprawdza, czy jest on ważny zgodnie z czasem wygaśnięcia i czasem, od którego jest ważny (jeśli są one obecne). Zasady mogą też opcjonalnie weryfikować wartości określonych roszczeń w JWT, takich jak podmiot, wystawca, odbiorca lub wartość dodatkowych roszczeń.

Jeśli JWT zostanie zweryfikowany i jest prawidłowy, wszystkie roszczenia zawarte w JWT zostaną wyodrębnione do zmiennych kontekstowych do wykorzystania przez kolejne zasady lub warunki, a żądanie będzie mogło zostać zrealizowane. Jeśli nie można zweryfikować podpisu JWT lub jeśli JWT jest nieprawidłowy z powodu jednego z sygnatur czasowych, całe przetwarzanie zostaje zatrzymane, a w odpowiedzi zwracany jest błąd.

Informacje o elementach tokena JWT oraz o sposobie ich szyfrowania i podpisywania znajdziesz w dokumencie RFC7519.

Wideo

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

Próbki

• Weryfikowanie tokena JWT podpisanego algorytmem HS256
• Weryfikowanie tokena JWT podpisanego algorytmem RS256

Weryfikowanie tokena JWT podpisanego algorytmem HS256

Ten przykładowy zasób weryfikuje token JWT podpisany algorytmem szyfrowania HS256, HMAC przy użyciu sumy kontrolnej SHA-256. Token JWT jest przekazywany w żądaniu proxy za pomocą parametru formularza o nazwie jwt. Klucz znajduje się w zmiennej o nazwie private.secretkey. Pełny przykład, w tym sposób wysyłania prośby o zastosowanie zasady, znajdziesz w filmie powyżej.

Konfiguracja zasad zawiera informacje, których Edge potrzebuje do dekodowania i oceny tokena JWT, np. miejsce, w którym znajduje się token JWT (w zmiennej przepływu określonej w elemencie Source), wymagany algorytm podpisywania, miejsce, w którym znajduje się klucz tajny (przechowywany w zmiennej przepływu Edge, która mogła zostać pobrana np. z mapy klucz-wartość Edge), oraz zestaw wymaganych roszczeń 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 proxy interfejsu API mogły sprawdzać te wartości. Listę zmiennych ustawianych przez te zasady znajdziesz w artykule Zmienne przepływu.

Weryfikowanie tokena JWT podpisanego algorytmem RS256

Ten przykładowy zasób weryfikuje token JWT podpisany algorytmem RS256. Aby przejść weryfikację, musisz podać klucz publiczny. Token JWT jest przekazywany w żądaniu proxy za pomocą parametru formularza o nazwie jwt. Klucz publiczny znajduje się w zmiennej o nazwie public.publickey. Pełny przykład, w tym sposób wysyłania prośby o zastosowanie zasady, znajdziesz w filmie powyżej.

Szczegółowe informacje o wymaganiach i opcjach dotyczących poszczególnych elementów w tych przykładowych zasadach znajdziesz w sekcji Informacje o elementach.

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

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 ważny, jeśli podpis można zweryfikować za pomocą podanego klucza publicznego.

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 podpis można zweryfikować, ponieważ roszczenie „sub” zawarte w JWT nie pasuje do wymaganej wartości elementu „Subject” określonej w konfiguracji zasad.

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 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 opisuje elementy i atrybuty zasad Verify JWT.

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

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

<Audience>

<Audience>audience-here</Audience>

or:

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

Zasady weryfikują, czy deklaracja odbiorców w JWT jest zgodna z wartością określoną w konfiguracji. Jeśli nie ma dopasowania, zasada zgłasza błąd. To roszczenie określa odbiorców, dla których jest przeznaczony JWT. Jest to jedno z zarejestrowanych roszczeń wymienionych w dokumencie 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 roszczenia i czy podane wartości roszczeń są zgodne.

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

Gdy uwzględnisz element <Claim>, nazwy roszczeń są ustawiane statycznie podczas konfigurowania zasad. Możesz też przekazać obiekt JSON, aby określić nazwy roszczeń. Ponieważ obiekt JSON jest przekazywany jako zmienna, nazwy deklaracji są określane w czasie działania programu.

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

<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 określone dodatkowe pary nazwa/wartość roszczenia oraz czy potwierdzone wartości roszczeń są zgodne.

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

<CustomClaims>

Uwaga: obecnie element CustomClaims jest wstawiany, gdy dodajesz nowe zasady GenerateJWT w interfejsie. Ten element nie działa i jest ignorowany. Zamiast niego należy użyć elementu <AdditionalClaims>. Interfejs zostanie zaktualizowany, aby wstawiać prawidłowe elementy w późniejszym czasie.

<Id>

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

Sprawdza, czy JWT zawiera konkretne roszczenie jti. Gdy wartość tekstowa i atrybut ref są puste, zasada wygeneruje identyfikator jti zawierający losowy identyfikator UUID. Roszczenie identyfikatora JWT (jti) to unikalny identyfikator tokena JWT. Więcej informacji o parametrze jti znajdziesz w dokumencie RFC7519.

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

Ustaw wartość false, jeśli chcesz, aby zasada zgłaszała błąd, gdy jakikolwiek nagłówek wymieniony w nagłówku crit tokena JWT nie jest wymieniony w elemencie <KnownHeaders>. Jeśli ma wartość true, zasada VerifyJWT 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 jesteś jeszcze gotowy na spowodowanie błędu w przypadku braku nagłówka.

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

Ustaw wartość „false” (domyślnie), jeśli chcesz, aby zasada zgłaszała błąd, gdy token JWT zawiera roszczenie iat (Issued at), które określa czas w przyszłości. Jeśli ta zasada ma wartość Prawda, podczas weryfikacji ignoruje iat.

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

<Issuer>

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

Zasada sprawdza, czy wystawca w JWT jest zgodny z ciągiem znaków określonym w elemencie konfiguracji. Roszczenie, które identyfikuje wystawcę tokena JWT. Jest to jeden z zarejestrowanych zbiorów roszczeń wymienionych w RFC7519.

<KnownHeaders>

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

or:

<KnownHeaders ref=’variable_containing_headers’/>

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

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

Zasada VerifyJWT sprawdza nagłówek crit w tokenie JWT (jeśli istnieje) i w przypadku każdego nagłówka na liście 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 VerifyJWT.

Możesz opcjonalnie skonfigurować zasadę VerifyJWT tak, aby ignorowała nagłówek crit, 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 określić 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) 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 token JWT zawiera identyfikator klucza, który występuje w zbiorze JWKS, zasada użyje prawidłowego klucza publicznego do zweryfikowania podpisu tokena JWT. Więcej informacji o tej funkcji znajdziesz w artykule Weryfikowanie tokena JWT 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.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 w JWT. Użyj atrybutu ref, aby przekazać klucz lub certyfikat w zmiennej przepływu albo 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 encoding="base16|hex|base64|base64url">
  <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.

<Source>

<Source>jwt-variable</Source>

Jeśli jest obecny, określa zmienną przepływu, w której zasada oczekuje znalezienia tokena JWT do weryfikacji.

<Subject>

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

Zasada sprawdza, czy podmiot w JWT jest zgodny z ciągiem znaków określonym w konfiguracji zasady. To roszczenie identyfikuje temat JWT lub zawiera o nim oświadczenie. Jest to jeden z zestawów standardów wymienionych w RFC7519.

<TimeAllowance>

<TimeAllowance>120s</TimeAllowance>

„Okres prolongaty” w przypadku czasu. Jeśli na przykład dopuszczalny czas wynosi 60 sekund, wygasły JWT będzie traktowany jako nadal ważny przez 60 sekund po upływie deklarowanego czasu ważności. Podobnie będzie oceniany parametr not-before-time. Domyślna wartość to 0 sekund (brak 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.

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