Wygeneruj zasadę JWT

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

Co

Generuje podpisany token JWT z konfigurowalnym zestawem deklaracji. Token JWT można następnie zwrócić do przesyłanych do celów backendu lub 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

• Wygeneruj token JWT podpisany Algorytm HS256
• Wygeneruj token JWT podpisany Algorytm RS256

Wygeneruj token JWT podpisany przy użyciu HS256 algorytm

Ta przykładowa zasada generuje nowy token JWT i podpisuje go za pomocą algorytmu HS256. Zasady HS256 na udostępnionym obiekcie tajnym zarówno do podpisywania, jak i weryfikacji podpisu.

Po aktywowaniu tego działania związanego z zasadami Edge koduje nagłówek i ładunek JWT, a następnie cyfrowo będzie podpisany token JWT. Pełny przykład wraz z instrukcjami zgłaszania żądania dotyczącego tych zasad znajdziesz w filmie powyżej.

Konfiguracja zasady utworzy token JWT z zestawem standardowych deklaracji zdefiniowanych przez specyfikację JWT, w tym datę wygaśnięcia wynoszącą 1 godzinę, a także dodatkowe roszczenie. Dostępne opcje Uwzględnić dowolną liczbę dodatkowych roszczeń. Szczegółowe informacje na temat elementu znajdziesz w dokumentacji elementu wymagań i opcji dla każdego elementu wymienionego w tych przykładowych zasadach.

<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 mieć ł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ść roszczeń iat, exp i jti. będą różne.

Generowanie tokena JWT podpisanego przy użyciu RS256 algorytm

Ta przykładowa zasada generuje nowy token JWT i podpisuje go za pomocą algorytmu RS256. Generowanie Podpis RS256 opiera się na kluczu prywatnym RSA, który należy podać w postaci zakodowanej w formacie PEM. Pełny przykład wraz z instrukcjami zgłaszania żądania dotyczącego tych zasad znajdziesz w filmie powyżej.

Po wywołaniu tego działania związanego z zasadami Edge koduje i podpisuje cyfrowo token JWT wraz z deklaracjami. Informacje o częściach tokena JWT oraz 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>

Wyznaczanie kluczowych elementów

Elementy używane do określania klucza używanego do generowania tokena JWT zależą od wybranego algorytmu: zgodnie z poniższą tabelą:

<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 na potrzeby generowania tokena JWT

Dokumentacja zasady zawiera opis elementów i atrybutów zasady Generate JWT.

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, które zastosuj 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 [nazwa], aby oznaczyć zasadę etykietą w edytorze serwera proxy w interfejsie zarządzania z 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 deklarację aud ustawioną na określoną wartość . Ta deklaracja wskazuje odbiorców, dla których jest przeznaczony token JWT. To jest jeden 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 podanie dodatkowych par nazwa/wartość deklaracji JWT w ładunku. Możesz określić jako ciąg, liczbę, wartość logiczną, mapę lub tablicę. Mapa to po prostu zestaw nazw/wartości pary.

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

Wygenerowany token JWT zawiera wszystkie deklaracja 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 dodatkową parę nazwy i wartości deklaracji w nagłówku tokena JWT.

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

<CriticalHeaders>

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

or:

<CriticalHeaders ref=’variable_containing_headers’/>

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

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

W czasie działania zasada VerifyJWT sprawdza nagłówek crit. W przypadku każdego elementu wymienionego w nagłówku crit sprawdza, czy element <KnownHeaders> zasady weryfikacji JWT zawiera również ten nagłówek. Dowolny nagłówek znaleziony przez zasadę VerifyJWT w crit który nie jest wymieniony w <KnownHeaders>, powoduje niepowodzenie zasady VerifyJWT.

<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 użytkownika może zostać zaktualizowany, aby później wstawić prawidłowe elementy.

<ExpiresIn>

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

Określa czas życia tokena 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 konkretną deklaracjami jti. Gdy wartość tekstowa i atrybut ref są jednocześnie puste, zasada wygeneruje kod jti zawierający losowy identyfikator UUID. Deklaracja identyfikatora JWT (jti) jest – unikalny identyfikator tokena JWT. Więcej informacji na temat jti znajdziesz w dokumencie RFC7519.

<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 generuje token JWT zawierający deklarację o nazwie iss i ustawionej wartości do określonej wartości. Deklaracja identyfikująca wydawcę JWT. To jest jeden z zarejestrowany zestaw 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, po którym token stanie się ważny. Token jest nieważny do określonego czasu. Możesz podać bezwzględną wartość czasu lub czas wygenerowania tokena.

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

Jako względne wartości czasu podaj liczbę całkowitą i przedział czasu, 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 umieszczany w sekcji zmienna 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) do umieszczenia w nagłówku JWT. Tylko używanie 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 zasada ma używać do odszyfrowania klucza prywatnego. Użyj ref, aby przekazać klucz w zmiennej przepływu. Tylko używanie 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 jest używany do podpisywania tokena JWT. Użyj atrybutu ref, aby przekazać 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ć zawarty w nagłówku JWT tokena JWT podpisanego za pomocą HMAC algorytmem bezpieczeństwa. Używaj tylko wtedy, gdy algorytm należy do kategorii HS256/HS384/HS512.

<SecretKey/Value>

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

Edge wymusza minimalną siłę klucza w algorytmach HS256/HS384/HS512. Minimalna długość klucza W przypadku HS256 – 32 bajty, w przypadku HS384 – 48 bajtów, a w przypadku HS512 – 64 bajty. Użycie klucza o mniejszej mocy 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 ustawioną na określoną wartość value.Ta deklaracja określa lub zawiera deklarację na temat podmiotu tokena JWT. To jest jeden z standardowy zestaw roszczeń wymienionych w dokumencie RFC7519.

Zmienne przepływu

Zasada Wygeneruj token JWT nie ustawia zmiennych przepływu.

Informacje o błędzie

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

Example fault rule

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