Wygeneruj zasadę JWS

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

Co

Generuje podpisany JWS z konfigurowalnym zestawem deklaracji. JWS może być następnie zwracany do klientów, przesyłany do celów backendu lub wykorzystywany w inny sposób. Szczegółowe informacje znajdziesz w omówieniu zasad JWS i JWT.

Informacje o częściach JWS oraz sposobach ich szyfrowania i podpisywania znajdziesz w dokumencie RFC7515.

Wideo

Obejrzyj krótki film, aby dowiedzieć się, jak wygenerować podpisany token JWT. Ten film dotyczy generowania tokena JWT, ale wiele koncepcji jest takich samych w JWS.

Przykłady

• Wygeneruj załączony algorytm JWS podpisany za pomocą algorytmu HS256
• Wygeneruj odłączony interfejs JWS podpisany algorytmem RS256

Wygeneruj załączony algorytm JWS podpisany za pomocą algorytmu HS256

Ta przykładowa zasada generuje dołączony pakiet JWS i podpisuje go algorytmem HS256. HS256 wykorzystuje wspólny obiekt tajny do podpisywania i weryfikacji podpisu.

Załączony JWS zawiera zakodowany nagłówek, ładunek i podpis:

header.payload.signature

Aby generować odłączone treści, ustaw <DetachContent> na „true”. Więcej informacji o strukturze i formacie JWS znajdziesz w sekcji Elementy JWS/JWT.

Użyj elementu <Payload>, aby określić nieprzetworzony, niezakodowany ładunek JWS. W tym przykładzie zmienna zawiera ładunek. Po uruchomieniu tego działania zasady Edge koduje nagłówek i ładunek JWS, a następnie dodaje zakodowany podpis w celu cyfrowego podpisywania JWS.

Poniższa konfiguracja zasad tworzy JWS z ładunku zawartego w zmiennej private.payload.

<GenerateJWS name="JWS-Generate-HS256">
    <DisplayName>JWS Generate HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <Payload ref="private.payload" />
    <OutputVariable>jws-variable</OutputVariable>
</GenerateJWS>

Wygeneruj odłączony interfejs JWS podpisany algorytmem RS256

Ta przykładowa zasada generuje odłączony interfejs JWS i podpisuje je 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.

Odłączony JWS pomija ładunek z JWS:

header..signature

Użyj elementu <Payload>, aby określić nieprzetworzony, niezakodowany ładunek JWS. Po uruchomieniu tej zasady Edge koduje nagłówek i ładunek JWS, a następnie używa ich do wygenerowania zakodowanego podpisu. Wygenerowany JWS pominie jednak ładunek. Do Ciebie należy przekazywanie ładunku do zasady VerificationJWS za pomocą elementu <DetachedContent> zasadyVerifyJWS.

<GenerateJWS name="JWS-Generate-RS256">
    <DisplayName>JWS Generate RS256</DisplayName>
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Payload ref="private.payload" />
    <DetachContent>true</DetachContent>
    <OutputVariable>jws-variable</OutputVariable>
</GenerateJWS>

Wyznaczanie kluczowych elementów

Elementy, których używasz do określenia klucza użytego do wygenerowania JWS, 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 dla generowania JWS

Dokumentacja zasad zawiera opis elementów i atrybutów zasady generowania JWS.

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

<GenerateJWS name="JWS" 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.

<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 nazwa/wartość roszczenia w nagłówku JWS.

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 do pliku JWS nagłówek krytyczny crit. Nagłówek crit to tablica nazw nagłówków, które muszą być znane i rozpoznawane przez odbiornik JWS. Na przykład:

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

W czasie działania zasadaVerifyJWS sprawdza nagłówek crit. W przypadku każdego nagłówka wymienionego w nagłówku crit sprawdza ona, czy element <KnownHeaders> zasady WeryfikacjaJWS również zawiera ten nagłówek. Każdy nagłówek, który jest znaleziony w elemencie crit przez zasadę WeryfikacjaJWS, a nie wymieniony w zasadzie <KnownHeaders>, powoduje niepowodzenie zasadyVerifyJWS.

<DetachContent>

<DetachContent>true|false</DetachContent>

Określa, czy ma być generowany JWS z odłączonym ładunkiem (<DetachContent>true</DetachContent>), czy nie (<DetachContent>false</DetachContent>).

Jeśli podasz wartość false (fałsz), wygenerowany plik JWS będzie miał domyślną postać:

header.payload.signature

Jeśli podasz wartość true, aby utworzyć ładunek odłączony, wygenerowany JWS pominie ładunek i będzie miał postać:

header..signature

W przypadku odłączonego ładunku to Ty decydujesz o tym, czy chcesz przekazać oryginalny niezakodowany ładunek do zasadyVerifyJWS, korzystając z elementu <DetachedContent> zasadyVerifyJWS.

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

<OutputVariable>

<OutputVariable>JWS-variable</OutputVariable>

Określa, gdzie należy umieścić oprogramowanie JWS wygenerowane przez tę zasadę. Domyślnie jest on umieszczony w zmiennej przepływu jws.POLICYNAME.generated_jws.

<Payload>

<Payload ref="flow-variable-name-here" />

or

<Payload>payload-value</Payload>

Określa nieprzetworzony, niezakodowany ładunek JWS. Określ zmienną zawierającą ładunek lub ciąg znaków.

<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 uwzględnienia w nagłówku JWS. 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 JWS. 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 JWS pliku JWS podpisanego za pomocą algorytmu 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.

Zmienne przepływu

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