Wygeneruj zasadę JWT

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

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 wykorzystać w inny sposób. Szczegółowe wprowadzenie znajdziesz w artykule Omówienie zasad JWS i JWT.

Wideo

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

Przykłady

• Wygeneruj token JWT podpisany algorytmem HS256
• Wygeneruj token JWT podpisany algorytmem RS256

Wygeneruj token JWT podpisany algorytmem HS256.

Ten przykład zasad generuje nowy token JWT i podpisuje go za pomocą algorytmu HS256. HS256 opiera się na udostępnionym haśle do podpisywania i weryfikowania podpisu.

Gdy to działanie zasady zostanie wywołane, Edge zakoduje nagłówek i ładunek JWT, a następnie podpisze cyfrowo token JWT. Pełny przykład, w tym sposób wysyłania prośby o zastosowanie zasady, znajdziesz w filmie powyżej.

Konfiguracja zasad utworzy token JWT z zestawem standardowych deklaracji zdefiniowanych w specyfikacji JWT, w tym z godziną wygaśnięcia, a także z dodatkową deklaracją. 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 sekcji Informacje o elementach.

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

Wynikowy token JWT będzie miał ten nagłówek:

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

… i będzie zawierać ładunek z treściami podobnymi do tych:

{ 
  "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ą się różnić.

Wygeneruj token JWT podpisany algorytmem RS256.

Ten przykładowy zasób zasad generuje nowy token JWT i podpisuje go za pomocą algorytmu RS256. Generowanie podpisu RS256 wymaga klucza prywatnego RSA, który musi być podany w formacie PEM. Pełny przykład, w tym sposób wysyłania prośby o zastosowanie zasady, znajdziesz w filmie powyżej.

Gdy to działanie zasady zostanie wywołane, Edge zakoduje i podpisze cyfrowo token JWT, w tym roszczenia. Informacje o elementach tokena JWT oraz o sposobie 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>

Ustawianie kluczowych elementów

Elementy, których używasz do określania klucza używanego do generowania 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 Generowanie tokena JWT

Dokumentacja zasady generowania tokena JWT opisuje elementy i atrybuty tej zasady.

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

<GenerateJWT 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>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 zawierający roszczenie aud ustawione na określoną wartość. 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'/>

Umożliwia określenie dodatkowych par nazwa/wartość roszczenia w ładunku JWT. Możesz podać roszczenie w postaci ciągu znaków, liczby, wartości logicznej, mapy lub tablicy. Mapa to po prostu zbiór par nazwa/wartość.

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

Wygenerowany token JWT zawiera wszystkie roszczenia w obiekcie JSON.

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

Umieszcza dodatkowe pary nazwa/wartość roszczenia w nagłówku tokena JWT.

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.

<CriticalHeaders>

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

or:

<CriticalHeaders ref=’variable_containing_headers’/>

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

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

W czasie działania zasady VerifyJWT sprawdzają nagłówek crit. W przypadku każdego elementu wymienionego w nagłówku crit sprawdza, czy element <KnownHeaders> zasady VerifyJWT również zawiera ten nagłówek. Każdy nagłówek, który zasada VerifyJWT znajdzie w parametrze crit, a którego nie ma na liście w parametrze <KnownHeaders>, spowoduje niepowodzenie działania zasady VerifyJWT.

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

<ExpiresIn>

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

Określa okres ważności JWT w milisekundach, sekundach, minutach, godzinach lub dniach.

<Id>

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

Generuje token JWT z określonym roszczeniem 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.

<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 generuje token JWT zawierający roszczenie o nazwie iss,którego wartość jest ustawiona na określoną wartość. Roszczenie, które identyfikuje wystawcę tokena JWT. Jest to jeden z zarejestrowanych zbiorów roszczeń wymienionych w 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, w którym token staje się ważny. Token jest nieprawidłowy do określonego czasu. Możesz podać bezwzględną wartość czasu lub czas względny w stosunku do momentu wygenerowania tokena.

Prawidłowe wartości czasu w elemencie NotBefore dla bezwzględnych wartości czasu

W przypadku wartości czasu względnego podaj liczbę całkowitą i okres, np.:

• 10 s
• 60 m
• 12 godzin

<OutputVariable>

<OutputVariable>jwt-variable</OutputVariable>

Określa, gdzie umieścić token JWT wygenerowany przez tę zasadę. Domyślnie jest ona umieszczana 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 być uwzględniony w nagłówku JWT. Używaj tylko wtedy, gdy algorytm to 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 zasady powinny używać do odszyfrowywania klucza prywatnego. Użyj atrybutu ref, aby przekazać klucz w zmiennej przepływu. Używaj tylko wtedy, gdy algorytm to 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, który służy do podpisywania tokena JWT. Użyj atrybutu ref, aby przekazać klucz w zmiennej przepływu. Używaj 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 być uwzględniony w nagłówku JWT tokena JWT podpisanego algorytmem HMAC. Używaj tylko wtedy, gdy algorytm to HS256, HS384 lub HS512.

<SecretKey/Value>

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

Edge wymusza minimalną siłę klucza w przypadku algorytmów HS256/HS384/HS512. 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 mniejszej sile powoduje błąd w czasie działania.

<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 ustawioną na podaną wartość.Ta deklaracja identyfikuje podmiot tokena JWT lub zawiera o nim informacje. Jest to jeden z zestawów standardów roszczeń wymienionych w dokumencie RFC7519.

Zmienne przepływu

Zasada Generate JWT nie ustawia zmiennych przepływu.

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>