Wygeneruj zasadę JWT

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

Co

Generuje podpisany token JWT z konfigurowalnym zestawem deklaracji. Token JWT można następnie zwrócić klientom, przesłać do miejsc docelowych backendu lub użyć w inny sposób. Szczegółowe informacje znajdziesz w omówieniu zasad JWS i JWT.

Wideo

Obejrzyj krótki film, aby dowiedzieć się, jak wygenerować podpisany token JWT.

Przykłady

• Generowanie tokena JWT podpisanym algorytmem HS256
• Generowanie tokena JWT podpisanym algorytmem RS256

Generowanie tokena JWT podpisanego za pomocą algorytmu HS256

Ta przykładowa zasada generuje nowy token JWT i podpisuje go za pomocą algorytmu HS256. HS256 wykorzystuje wspólny obiekt tajny do podpisywania i weryfikacji podpisu.

Po uruchomieniu tego działania zasady Edge zakoduje nagłówek i ładunek JWT, a następnie podpisuje token JWT cyfrowo. Obejrzyj film powyżej, aby zobaczyć pełny przykład, w tym, jak przesłać żądanie zgodności z zasadami.

Ta konfiguracja zasad utworzy token JWT z zestawem standardowych deklaracji zgodnie ze specyfikacją JWT, w tym wygaśnięciem po upływie godziny oraz dodatkowym zgłoszeniem. Możesz dodać dowolną liczbę dodatkowych roszczeń. Szczegółowe informacje o wymaganiach i opcjach dotyczących poszczególnych elementów w tych przykładowych zasadach znajdziesz w dokumentacji elementów.

<GenerateJWT name="JWT-Generate-HS256">
    <DisplayName>JWT Generate HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <ExpiresIn>1h</ExpiresIn>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

Powstały token JWT będzie miał ten nagłówek...

{
  "typ" : "JWT", 
  "alg" : "HS256",
  "kid" : "1918290"
}

...i będzie zawierać ładunek z treścią podobną do tej:

{ 
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "show",
  "iat" : 1506553019,
  "exp" : 1506556619,
  "jti" : "BD1FF263-3D25-4593-A685-5EC1326E1F37",
  "show": "And now for something completely different."
}

Wartości roszczeń iat, exp i jti będą różne.

Generowanie tokena JWT podpisanym algorytmem RS256

Ta przykładowa zasada generuje nowy token JWT i podpisuje go za pomocą algorytmu RS256. Generowanie podpisu RS256 odbywa się przy użyciu klucza prywatnego RSA, który należy podać w postaci zakodowanej w formacie PEM. Obejrzyj film powyżej, aby zobaczyć pełny przykład, w tym, jak przesłać żądanie zgodności z zasadami.

Po uruchomieniu tego działania zasady Edge zakoduje i cyfrowo podpisze token JWT wraz z deklaracjami. Informacje o częściach tokena JWT oraz sposobach ich szyfrowania i podpisywania znajdziesz w dokumencie RFC7519.

<GenerateJWT name="JWT-Generate-RS256">
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <ExpiresIn>60m</ExpiresIn>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

Wyznaczanie kluczowych elementów

Elementy, których używasz do określenia klucza użytego do wygenerowania tokena JWT, zależą od wybranego algorytmu, jak pokazano w tej tabeli:

<SecretKey>
  <Value ref="private.secretkey"/>
  <Id>1918290</Id>
</SecretKey>

<PrivateKey>
  <Value ref="private.privatekey"/>
  <Password ref="private.privatekey-password"/>
  <Id ref="private.privatekey-id"/>
</PrivateKey>

Dokumentacja elementu w przypadku generowania tokena JWT

Dokumentacja zasad zawiera opis elementów i atrybutów zasady Wygeneruj token 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

<GenerateJWT 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>algorithm-here</Algorithm>

Określa algorytm szyfrowania do podpisywania tokena.

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

Zasada generuje token JWT z deklaracjami aud ustawionymi na określoną wartość. 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'/>

Pozwala określić dodatkowe pary nazwy i wartości deklaracji w ładunku JWT. Możesz określić deklarację wyraźnie jako ciąg znaków, liczbę, wartość logiczną, mapę lub tablica. Mapa to po prostu zestaw par nazwa/wartość.

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 w wygenerowanym tokenie JWT 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 }
  }
}

Wygenerowany token JWT zawiera wszystkie deklaracje w obiekcie JSON.

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

Umieszcza dodatkowe pary nazwy i wartości deklaracji w nagłówku tokena JWT.

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.

<CriticalHeaders>

<CriticalHeaders>a,b,c</CriticalHeaders>

or:

<CriticalHeaders ref=’variable_containing_headers’/>

Dodaje krytyczny nagłówek crit do nagłówka JWT. Nagłówek crit to tablica nazw nagłówków, które muszą być znane i rozpoznawane przez odbiornik JWT. Na przykład:

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

W czasie działania zasada weryfikacji JWT sprawdza nagłówek crit. W przypadku każdego elementu wymienionego w nagłówku crit sprawdza, czy element <KnownHeaders> zasady weryfikacji JWT też zawiera ten nagłówek. Każdy nagłówek, który znajduje się w zasadzie weryfikacji JWT w crit, a nie jest wymieniony w <KnownHeaders>, powoduje niepowodzenie zasady weryfikacji JWT.

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

<ExpiresIn>

<ExpiresIn>time-value-here</ExpiresIn>

Określa czas życia tokena JWT w milisekundach, sekundach, minutach, godzinach lub dniach.

<Identyfikator>

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

Generuje token JWT z konkretnym żądaniem 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.

<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 generuje token JWT zawierający deklaracja o nazwie iss,która ma ustawioną wartość. Deklaracja, która identyfikuje wydawcę tokena JWT. Jest to jeden z zarejestrowanych zestawów roszczeń wymienionych w dokumencie RFC7519.

<NotBefore>

<!-- Specify an absolute time. -->
<NotBefore>2017-08-14T11:00:21-07:00</NotBefore>
 -or-
<!-- Specify a time relative to when the token is generated. -->
<NotBefore>6h</NotBefore>

Określa czas, kiedy token staje się ważny. Token jest nieprawidłowy do określonego momentu. Możesz podać bezwzględną wartość czasu lub czas w stosunku do czasu wygenerowania tokena.

Prawidłowe wartości czasu elementu NotBefore w przypadku bezwzględnych wartości czasu

W przypadku względnych wartości czasu podaj liczbę całkowitą i okres, na przykład:

• 10 s
• 60 min
• 12 godzin

<OutputVariable>

<OutputVariable>jwt-variable</OutputVariable>

Określa, gdzie umieścić token JWT wygenerowany przez tę zasadę. Domyślnie jest on umieszczony w zmiennej przepływu jwt.POLICYNAME.generated_jwt.

<PrivateKey/Id>

<PrivateKey>
  <Id ref="flow-variable-name-here"/>
</PrivateKey>

or

<PrivateKey>
  <Id>your-id-value-here</Id>
</PrivateKey>

Określa identyfikator klucza (kid), który ma zostać uwzględniony w nagłówku JWT. Używaj tylko wtedy, gdy algorytmem jest RS256/RS384/RS512, PS256/PS384/PS512 lub ES256/ES384/ES512.

<PrivateKey/Password>

<PrivateKey>
  <Password ref="private.privatekey-password"/>
</PrivateKey>

W razie potrzeby podaj hasło, którego zasada ma używać do odszyfrowywania klucza prywatnego. Użyj atrybutu ref, aby przekazać klucz w zmiennej przepływu. Używaj tylko wtedy, gdy algorytmem jest RS256/RS384/RS512, PS256/PS384/PS512 lub ES256/ES384/ES512.

<PrivateKey/Value>

<PrivateKey>
  <Value ref="private.variable-name-here"/>
</PrivateKey>

Określa klucz prywatny zakodowany w formacie PEM używany do podpisywania tokena JWT. Użyj atrybutu ref, aby przekazać klucz w zmiennej przepływu. Użyj tylko wtedy, gdy algorytm to RS256/RS384/RS512, PS256/PS384/PS512 lub ES256/ES384/ES512.

<SecretKey/Id>

<SecretKey>
  <Id ref="flow-variable-name-here"/>
</SecretKey>

or

<SecretKey>
  <Id>your-id-value-here</Id>
</SecretKey>

Określa identyfikator klucza (kid), który ma zostać uwzględniony w nagłówku JWT tokena JWT podpisanym algorytmem HMAC. Używaj tylko wtedy, gdy algorytm to HS256/HS384/HS512.

<SecretKey/Value>

<SecretKey>
  <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 typ HS256/HS384/HS512. Użyj atrybutu ref, aby przekazać klucz w zmiennej przepływu.

W przypadku algorytmów HS256/HS384/HS512 Edge wymusza minimalną siłę klucza. Minimalna długość klucza w przypadku HS256 to 32 bajty, w przypadku HS384 – 48 bajtów, a w przypadku HS512 – 64 bajty. Użycie klucza o niższej sile powoduje błąd środowiska wykonawczego.

<Subject>

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

<Subject ref="flow_variable" />

Na przykład:

<Subject ref="apigee.developer.email"/>

Zasada generuje token JWT zawierający deklarację sub z określoną wartością.Ta deklaracja identyfikuje temat JWT lub zawiera instrukcję na jego temat. Jest to jeden ze standardowych zestawów twierdzeń wymienionych w dokumencie RFC7519.

Zmienne przepływu

Zasada tworzenia tokena JWT nie ustawia zmiennych przepływu.

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>