GenerateJWS politikası

Apigee Edge belgelerini görüntülüyorsunuz.
Apigee X belgelerine gidin. bilgi

Ne?

Yapılandırılabilir bir talep grubuyla imzalı bir JWS oluşturur. JWS daha sonra istemcilere döndürülebilir, arka uç hedeflerine iletilebilir veya başka şekillerde kullanılabilir. Ayrıntılı bir giriş için JWS ve JWT politikalarına genel bakış başlıklı makaleyi inceleyin.

JWS'nin bölümleri, şifrelenme ve imzalanma şekilleri hakkında bilgi edinmek için RFC7515'e bakın.

Video

İmzalı bir JWT oluşturmayı öğrenmek için kısa bir video izleyin. Bu video, JWT oluşturmaya özel olsa da kavramların çoğu JWS için de aynıdır.

Örnekler

• HS256 algoritmasıyla imzalanmış ekli bir JWS oluşturma
• RS256 algoritmasıyla imzalanmış ayrılmış bir JWS oluşturma

HS256 algoritmasıyla imzalanmış ekli bir JWS oluşturun.

Bu örnek politika, eklenmiş bir JWS oluşturur ve bunu HS256 algoritmasını kullanarak imzalar. HS256, hem imzalamak hem de imzayı doğrulamak için paylaşılan bir gizli bilgiye dayanır.

Ekli bir JWS, kodlanmış başlığı, yükü ve imzayı içerir:

header.payload.signature

Ayrılmış içerik oluşturmak için <DetachContent> değerini doğru olarak ayarlayın. JWS'nin yapısı ve biçimi hakkında daha fazla bilgi için JWS/JWT'nin bölümleri başlıklı makaleyi inceleyin.

Ham, kodlanmamış JWS yükünü belirtmek için <Payload> öğesini kullanın. Bu örnekte, bir değişken yükü içeriyor. Bu politika işlemi tetiklendiğinde Edge, JWS başlığını ve yükünü kodlar, ardından JWS'yi dijital olarak imzalamak için kodlanmış imzayı ekler.

Aşağıdaki politika yapılandırması, private.payload değişkeninde bulunan bir yükten JWS oluşturur.

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

RS256 algoritmasıyla imzalanmış ayrılmış bir JWS oluşturun.

Bu örnek politika, ayrılmış bir JWS oluşturur ve RS256 algoritmasını kullanarak imzalar. RS256 imzası oluşturmak için RSA özel anahtarı gerekir. Bu anahtar, PEM kodlamalı biçimde sağlanmalıdır.

Ayrılmış bir JWS, JWS'den yükü çıkarır:

header..signature

Ham, kodlanmamış JWS yükünü belirtmek için <Payload> öğesini kullanın. Bu politika tetiklendiğinde Edge, JWS başlığını ve yükünü kodlar, ardından kodlanmış imzayı oluşturmak için bunları kullanır. Ancak oluşturulan JWS, yükü atlar. VerifyJWS politikasının <DetachedContent> öğesini kullanarak yükü VerifyJWS politikasına iletmek sizin sorumluluğunuzdadır.

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

Temel öğeleri ayarlama

JWS'yi oluşturmak için kullanılan anahtarı belirtmek üzere kullandığınız öğeler, seçilen algoritmaya bağlıdır. Bu öğeler aşağıdaki tabloda gösterilmektedir:

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

Generate JWS için öğe referansı

Politika referansı, JWS oluşturma politikasının öğelerini ve özelliklerini açıklar.

Not: Yapılandırma, kullandığınız şifreleme algoritmasına bağlı olarak biraz farklılık gösterir. Belirli kullanım alanlarına yönelik yapılandırmaları gösteren örnekler için Örnekler bölümüne bakın.

Üst düzey öğe için geçerli olan özellikler

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

Aşağıdaki özellikler, tüm politika üst öğeleri için ortaktır.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Politikayı yönetim kullanıcı arayüzü proxy düzenleyicisinde farklı bir doğal dil adıyla etiketlemek için ad özelliğiyle birlikte kullanın.

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

Jetonu imzalamak için şifreleme algoritmasını belirtir.

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

Ek talep adı/değer çiftlerini JWS'nin üstbilgisine yerleştirir.

<Claim> öğesi şu özellikleri alır:

• name: (Zorunlu) Hak talebinin adı.
• ref: (İsteğe bağlı) Bir akış değişkeninin adı. Bu değişken varsa politika, bu değişkenin değerini talep olarak kullanır. Hem ref özelliği hem de açık bir talep değeri belirtilirse açık değer varsayılan değer olur ve referans verilen akış değişkeni çözümlenmemişse kullanılır. başlıklı makaleyi inceleyin.
• type: (İsteğe bağlı) Şu değerlerden biri: dize (varsayılan), sayı, Boole veya eşlem
• array: (İsteğe bağlı) Değerin bir tür dizisi olup olmadığını belirtmek için true olarak ayarlayın. Varsayılan: false.

<CriticalHeaders>

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

or:

<CriticalHeaders ref=’variable_containing_headers’/>

JWS'ye önemli üstbilgi olan crit'i ekler. crit üstbilgisi, JWS alıcısı tarafından bilinmesi ve tanınması gereken üstbilgi adlarının bir dizisidir. Örneğin:

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

Çalışma zamanında, VerifyJWS politikası crit üstbilgisini inceler. crit üstbilgisinde listelenen her üstbilgi için, VerifyJWS politikasının <KnownHeaders> öğesinin de bu üstbilgiyi listelediği kontrol edilir. VerifyJWS politikasının crit içinde bulduğu ve <KnownHeaders> içinde listelenmeyen tüm üstbilgiler, VerifyJWS politikasının başarısız olmasına neden olur.

<DetachContent>

<DetachContent>true|false</DetachContent>

JWS'nin ayrılmış bir yükle mi (<DetachContent>true</DetachContent>) yoksa ayrılmış bir yük olmadan mı (<DetachContent>false</DetachContent>) oluşturulacağını belirtir.

Varsayılan değer olan false'u belirtirseniz oluşturulan JWS şu biçimde olur:

header.payload.signature

Ayrılmış yük oluşturmak için true değerini belirtirseniz oluşturulan JWS, yükü atlar ve şu biçimde olur:

header..signature

Ayrılmış bir yükte, VerifyJWS politikası'nın <DetachedContent> öğesini kullanarak orijinal kodlanmamış yükü VerifyJWS politikasına iletmek sizin sorumluluğunuzdadır.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Politikada belirtilen referans verilen değişkenlerden herhangi biri çözümlenemediğinde politikanın hata vermesini istiyorsanız yanlış olarak ayarlayın. Çözülemeyen değişkenleri boş dize (null) olarak değerlendirmek için true olarak ayarlayın.

<OutputVariable>

<OutputVariable>JWS-variable</OutputVariable>

Bu politika tarafından oluşturulan JWS'nin nereye yerleştirileceğini belirtir. Varsayılan olarak jws.POLICYNAME.generated_jws akış değişkenine yerleştirilir.

<Payload>

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

or

<Payload>payload-value</Payload>

Kodlanmamış, ham JWS yükünü belirtir. Yükü içeren bir değişken veya dize belirtin.

<PrivateKey/Id>

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

or

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

JWS başlığına eklenecek anahtar kimliğini (kid) belirtir. Yalnızca algoritma RS256/RS384/RS512, PS256/PS384/PS512 veya ES256/ES384/ES512 olduğunda kullanın.

<PrivateKey/Password>

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

Gerekirse politikanın özel anahtarın şifresini çözmek için kullanması gereken şifreyi belirtin. Anahtarı bir akış değişkeninde iletmek için ref özelliğini kullanın. Yalnızca algoritma RS256/RS384/RS512, PS256/PS384/PS512 veya ES256/ES384/ES512 olduğunda kullanın.

<PrivateKey/Value>

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

JWS'yi imzalamak için kullanılan PEM kodlamalı özel anahtarı belirtir. Bir akış değişkeninde anahtarı iletmek için ref özelliğini kullanın. Yalnızca algoritma RS256/RS384/RS512, PS256/PS384/PS512 veya ES256/ES384/ES512 olduğunda kullanın.

<SecretKey/Id>

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

or

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

Bir HMAC algoritmasıyla imzalanmış JWS'nin JWS üstbilgisine eklenecek anahtar kimliğini (kid) belirtir. Yalnızca algoritma HS256/HS384/HS512 olduğunda kullanın.

<SecretKey/Value>

<SecretKey>
  <Value ref="private.your-variable-name"/>
</SecretKey>

Jetonları HMAC algoritmasıyla doğrulamak veya imzalamak için kullanılan gizli anahtarı sağlar. Yalnızca algoritma HS256/HS384/HS512 olduğunda kullanın. Anahtarı bir akış değişkeninde iletmek için ref özelliğini kullanın.

Edge, HS256/HS384/HS512 algoritmaları için minimum anahtar gücü uygular. HS256 için minimum anahtar uzunluğu 32 bayt, HS384 için 48 bayt ve HS512 için 64 bayttır. Daha düşük güçlü bir anahtar kullanmak çalışma zamanı hatasına neden olur.

Akış değişkenleri

JWS oluşturma politikası, akış değişkenlerini ayarlamaz.

Hata referansı

Bu bölümde, bu politika bir hatayı tetiklediğinde Edge tarafından ayarlanan hata kodları ile hata mesajları ve döndürülen hata mesajları ile Edge tarafından ayarlanan hata değişkenleri açıklanmaktadır. Hataları ele almak için hata kuralları geliştirip geliştirmediğinizi bilmeniz önemlidir. Daha fazla bilgi için Politika hataları hakkında bilmeniz gerekenler ve Hataları işleme bölümlerine bakın.

Çalışma zamanı hataları

Politika yürütüldüğünde bu hatalar ortaya çıkabilir.

Dağıtım hataları

Bu hatalar, bu politikayı içeren bir proxy dağıttığınızda ortaya çıkabilir.

Hata değişkenleri

Bu değişkenler, çalışma zamanı hatası oluştuğunda ayarlanır. Daha fazla bilgi için Bilmeniz gerekenler hakkında daha fazla bilgi edinin.

Örnek hata yanıtı

Hata giderme için en iyi uygulama, hatanın errorcode kısmını yakalamaktır tıklayın. Değişebileceği için faultstring içindeki metne güvenmeyin.

Örnek hata kuralı

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