Wygeneruj zasadę JWS

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

Co

Generuje podpisany JWS z konfigurowalnym zestawem deklaracji. JWS 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.

Informacje o elementach JWS oraz o sposobie 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 przypadku tokena JWS.

Przykłady

Wygeneruj załączony podpis JWS podpisany algorytmem HS256.

Ta przykładowa zasada generuje dołączony JWS i podpisuje go za pomocą algorytmu HS256. HS256 opiera się na udostępnionym haśle do podpisywania i weryfikowania podpisu.

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

header.payload.signature

Ustaw wartość <DetachContent> na true, aby wygenerować odłączone treści. 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. Gdy to działanie zasady zostanie wywołane, Edge zakoduje nagłówek i ładunek JWS, a następnie doda zakodowany podpis, aby cyfrowo podpisać JWS.

Konfiguracja zasad poniżej 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 podpis JWS podpisany algorytmem RS256.

Ten przykład zasad generuje odłączony JWS i podpisuje go za pomocą algorytmu RS256. Generowanie podpisu RS256 wymaga klucza prywatnego RSA, który musi być podany w formacie PEM.

Odłączony JWS nie zawiera ładunku:

header..signature

Użyj elementu <Payload>, aby określić nieprzetworzony, niezakodowany ładunek JWS. Gdy ta zasada jest aktywowana, Edge koduje nagłówek i ładunek JWS, a następnie używa ich do wygenerowania zakodowanego podpisu. Wygenerowany JWS nie zawiera jednak ładunku. To Ty musisz przekazać ładunek do zasady VerifyJWS za pomocą elementu <DetachedContent> zasady VerifyJWS.

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

Ustawianie kluczowych elementów

Elementy, których używasz do określania klucza używanego do generowania JWS, zależą od wybranego algorytmu, jak pokazano w tej tabeli:

Algorytm Kluczowe elementy
HS{256/384/512}* 
<SecretKey>
  <Value ref="private.secretkey"/>
  <Id>1918290</Id>
</SecretKey>
RS/PS/ES{256/384/512}* 
<PrivateKey>
  <Value ref="private.privatekey"/>
  <Password ref="private.privatekey-password"/>
  <Id ref="private.privatekey-id"/>
</PrivateKey>

Elementy <Password> i <Id> są opcjonalne.
* Więcej informacji o wymaganiach dotyczących kluczy znajdziesz w artykule Algorytmy szyfrowania podpisów.

Odwołanie do elementu w przypadku funkcji Generate JWS

Dokumentacja zasady Generate JWS 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 dla konkretnych przypadków użycia znajdziesz w sekcji Przykłady.

Atrybuty, które mają zastosowanie do elementu najwyższego poziomu

<GenerateJWS name="JWS" continueOnError="false" enabled="true" async="false">

Te atrybuty są wspólne dla wszystkich elementów nadrzędnych zasad.

Atrybut Opis Domyślna Obecność
nazwa Wewnętrzna nazwa zasady. W nazwie możesz używać tylko tych znaków:A-Z0-9._\-$ %. Interfejs zarządzania Edge wymusza jednak dodatkowe ograniczenia, takie jak automatyczne usuwanie znaków, które nie są alfanumeryczne.

Opcjonalnie możesz użyć elementu <displayname></displayname>, aby oznaczyć zasadę w edytorze serwera proxy interfejsu zarządzania inną nazwą w języku naturalnym.

 Nie dotyczy Wymagane
continueOnError Ustaw wartość false, aby zwracać błąd, gdy zasada nie działa. Jest to prawidłowe działanie w przypadku większości zasad.

Ustaw wartość true, aby wykonywanie przepływu było kontynuowane nawet po niepowodzeniu zasad.

 fałsz Opcjonalny
włączone Ustaw wartość true, aby wymusić stosowanie zasady.

Ustaw wartość false, aby „wyłączyć” zasadę. Zasada nie będzie egzekwowana, nawet jeśli pozostanie dołączona do automatyzacji.

 prawda Opcjonalny
asynchroniczny Ten atrybut został wycofany. fałsz Wycofano

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

Domyślna Jeśli pominiesz ten element, zostanie użyta wartość atrybutu name zasady.
Obecność Opcjonalny
Typ Ciąg znaków

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

Określa algorytm szyfrowania do podpisywania tokena.

Domyślna Nie dotyczy
Obecność Wymagane
Typ Ciąg znaków
Prawidłowe wartości HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512

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

Domyślna Nie dotyczy
Obecność Opcjonalny
Prawidłowe wartości Dowolna wartość, której chcesz użyć w przypadku dodatkowego roszczenia. Możesz podać roszczenie w postaci ciągu znaków, liczby, wartości logicznej, mapy lub tablicy.

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

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

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

Domyślna Nie dotyczy
Obecność Opcjonalny
Typ Tablica ciągów tekstowych rozdzielonych przecinkami
Prawidłowe wartości Tablica lub nazwa zmiennej zawierającej tablicę.

<DetachContent>

<DetachContent>true|false</DetachContent>

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

Jeśli określisz wartość „false” (domyślną), wygenerowany JWS będzie miał postać:

header.payload.signature

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

header..signature

W przypadku odłączonego ładunku musisz przekazać oryginalny, niezakodowany ładunek do zasady VerifyJWS za pomocą elementu <DetachedContent> zasady VerifyJWS.

Domyślna fałsz
Obecność Opcjonalny
Typ Wartość logiczna
Prawidłowe wartości true or false

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

Domyślna fałsz
Obecność Opcjonalny
Typ Wartość logiczna
Prawidłowe wartości true or false

<OutputVariable>

<OutputVariable>JWS-variable</OutputVariable>

Określa, gdzie umieścić JWS wygenerowany przez tę zasadę. Domyślnie jest ona umieszczana w zmiennej przepływu jws.POLICYNAME.generated_jws.

Domyślna jws.POLICYNAME.generated_jws
Obecność Opcjonalny
Typ Ciąg znaków (nazwa zmiennej przepływu)

<Payload>

<Payload ref="flow-variable-name-he>re&quo<t; /

o>r

Payloadpay<load-val>ue/Payload

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

Domyślna Nie dotyczy
Obecność Wymagane
Typ Ciąg znaków, tablica bajtów, strumień lub dowolna inna reprezentacja niezakodowanego ładunku JWS.

<PrivateKey/Id>

<PrivateKey>
  <Id ref="flow-variable-name-h>e<re"/
/>Privat<eKey

or

>Pri<va>teKey
  Idyour-id-<val>u<e-here/Id
/>PrivateKey

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

Domyślna Nie dotyczy
Obecność Opcjonalny
Typ Ciąg znaków
Prawidłowe wartości Zmienna przepływu lub ciąg znaków

<PrivateKey/Password>

<PrivateKey>
  <Password ref="private.privatekey-passw>o<rd"/
/>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.

Domyślna Nie dotyczy
Obecność Opcjonalny
Typ Ciąg znaków
Prawidłowe wartości Odwołanie do zmiennej przepływu.

Uwaga: musisz określić zmienną przepływu. Edge odrzuci jako nieprawidłową konfigurację zasad, w której hasło jest podane w postaci zwykłego tekstu. Zmienna przepływu musi mieć prefiks „private”. Na przykład private.mypassword

<PrivateKey/Value>

<PrivateKey>
  <Value ref="private.variable-name-h>e<re"/
/>PrivateKey

Określa klucz prywatny z kodowaniem PEM używany do podpisywania JWS. 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.

Domyślna Nie dotyczy
Obecność Wymagane do wygenerowania JWS za pomocą algorytmu RS256.
Typ Ciąg znaków
Prawidłowe wartości Zmienna przepływu zawierająca ciąg znaków reprezentujący wartość klucza prywatnego RSA z kodowaniem PEM.

Uwaga: zmienna przepływu musi mieć prefiks „private”. Na przykład:private.mykey

<SecretKey/Id>

<SecretKey>
  <Id ref="flow-variable-name-h>e<re"/
>/Secre<tKey

or
>
Se<cr>etKey
  Idyour-id-<val>u<e-here/Id
>/SecretKey

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

Domyślna Nie dotyczy
Obecność Opcjonalny
Typ Ciąg znaków
Prawidłowe wartości Zmienna przepływu lub ciąg znaków

<SecretKey/Value>

<SecretKey>
  <Value ref="private.your-variable-n>a<me"/
>/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.

Domyślna Nie dotyczy
Obecność Wymagane w przypadku algorytmów HMAC.
Typ Ciąg znaków
Prawidłowe wartości zmienna przepływu odwołująca się do ciągu znaków;

Uwaga: jeśli jest to zmienna przepływu, musi mieć prefiks „private”. Na przykład private.mysecret

Zmienne przepływu

Zasada Generate JWS nie ustawia zmiennych przepływu.

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

Kod błędu Stan HTTP Występuje, gdy
steps.jws.GenerationFailed 401 Za pomocą zasady nie udało się wygenerować pakietu JWS.
steps.jws.InsufficientKeyLength 401 Dla klucza krótszego niż 32 bajty dla algorytmu HS256
steps.jws.InvalidClaim 401 Brak zgodności z deklaracją lub zgłoszeniem albo brak zgodności nagłówka lub nagłówka.
steps.jws.InvalidCurve 401 Krzywa określona przez klucz jest nieprawidłowa dla algorytmu krzywych eliptycznych.
steps.jws.InvalidJsonFormat 401 W nagłówku JWS znaleziono nieprawidłowy kod JSON.
steps.jws.InvalidPayload 401 Ładunek JWS jest nieprawidłowy.
steps.jws.InvalidSignature 401 Element <DetachedContent> jest pominięty, a JWS ma odłączony ładunek treści.
steps.jws.KeyIdMissing 401 Zasada weryfikacji używa JWKS jako źródła kluczy publicznych, ale podpisany JWS nie zawiera w nagłówku właściwości kid.
steps.jws.KeyParsingFailed 401 Nie udało się przeanalizować klucza publicznego na podstawie podanych informacji o kluczu.
steps.jws.MissingPayload 401 Brak ładunku JWS.
steps.jws.NoAlgorithmFoundInHeader 401 Występuje, gdy JWS pomija nagłówek algorytmu.
steps.jws.SigningFailed 401 W WygenerujJWS klucz mniejszy niż minimalny rozmiar algorytmów HS384 lub HS512
steps.jws.UnknownException 401 Wystąpił nieznany wyjątek.
steps.jws.WrongKeyType 401 Podano nieprawidłowy typ klucza. Możesz na przykład podać klucz RSA dla algorytmu krzywych eliptycznych lub klucz krzywej dla algorytmu RSA.

Błędy wdrażania

Te błędy mogą wystąpić podczas wdrażania serwera proxy zawierającego te zasady.

Nazwa błędu Występuje, gdy
InvalidAlgorithm Jedyne prawidłowe wartości to: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, HS256, HS384, HS512.

EmptyElementForKeyConfiguration

FailedToResolveVariable

InvalidConfigurationForActionAndAlgorithmFamily

InvalidConfigurationForVerify

InvalidEmptyElement

InvalidFamiliesForAlgorithm

InvalidKeyConfiguration

InvalidNameForAdditionalClaim

InvalidNameForAdditionalHeader

InvalidPublicKeyId

InvalidPublicKeyValue

InvalidSecretInConfig

InvalidTypeForAdditionalClaim

InvalidTypeForAdditionalHeader

InvalidValueForElement

InvalidValueOfArrayAttribute

InvalidVariableNameForSecret

MissingConfigurationElement

MissingElementForKeyConfiguration

MissingNameForAdditionalClaim

MissingNameForAdditionalHeader

 Inne możliwe błędy wdrażania.

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.

Zmienne Gdzie Przykład
fault.name="fault_name" fault_name to nazwa błędu podana w tabeli Błędy czasu działania powyżej. Nazwa błędu to ostatnia część kodu błędu. fault.name Matches "TokenExpired"
JWS.failed Wszystkie zasady JWS ustawiają tę samą zmienną w przypadku awarii. jws.JWS-Policy.failed = true

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