GenerateJWS politikası

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

Ne

Yapılandırılabilir hak talepleri grubunu içeren 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ı tanıtım için JWS ve JWT politikalarına genel bakış başlıklı makaleyi inceleyin.

JWS'nin bölümleri ve bunların nasıl şifrelenip imzalandığı hakkında bilgi edinmek için RFC7515 sayfasına bakın.

Video

İmzalanmış bir JWT'nin nasıl oluşturulacağını öğrenmek için kısa bir video izleyin. Bu video JWT oluşturmaya özel olsa da çoğu JWS kavramı aynıdır.

Örnekler

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

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

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

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

header.payload.signature

Ayrılmış içerik oluşturmak için <DetachContent> değerini true olarak ayarlayın. JWS'nin yapısı ve biçimi hakkında daha fazla bilgi edinmek için JWS/JWT parçaları bölümünü inceleyin.

Ham, kodlanmamış JWS yükünü belirtmek için <Payload> öğesini kullanın. Bu örnekte, bir değişken yükü içerir. 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 yükten bir 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ı bir JWS oluşturma

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

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

header..signature

Ham, kodlanmamış JWS yükünü belirtmek için <Payload> öğesini kullanın. Bu politika tetiklendiğinde Edge, JWS üst bilgisini ve yükünü kodlar ve kodlanmış imzayı oluşturmak için bunları kullanır. Ancak oluşturulan JWS, yükü atlar. Yükü, VerificationJWS politikasının <DetachedContent> öğesini kullanarak DoğrulamaJWS politikasına geçirmek 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 unsurları ayarlama

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

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

JWS Oluşturma için öğe referansı

Politika referansında, Generate JWS politikasının öğeleri ve özellikleri açıklanmaktadır.

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 öğelerinde ortaktır.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Yönetim arayüzü proxy düzenleyicisinde politikayı farklı bir doğal dil adıyla etiketlemek için name özelliğine ek olarak kullanın.

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

Jetonu imzalayacak şifreleme algoritmasını belirtir.

<Ek Başlık/Hak Talebi>

<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 hak talebi adını/değer çiftini JWS'nin başlığına yerleştirir.

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

• name - (Zorunlu) Hak talebinin adı.
• ref - (İsteğe bağlı) Bir akış değişkeninin adı. Politika varsa bu değişkenin değerini iddia olarak kullanır. Hem ref özelliği hem de açık hak talebi değeri belirtilirse açıkça belirtilen değer varsayılan değer olur ve başvurulan akış değişkeni çözümlenmemişse kullanılır.
• type - (İsteğe bağlı) Şunlardan biri: dize (varsayılan), sayı, boole veya harita
• 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 kritik başlık olan crit'i ekler. crit başlığı, JWS alıcısı tarafından bilinmesi ve tanınması gereken başlık adları dizisidir. Örneğin:

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

Çalışma zamanında VerifyJWS politikası, crit üstbilgisini inceler. crit başlığında listelenen her başlık için, VerificationJWS politikasının <KnownHeaders> öğesinin, bu başlığın da listelenip listelenmediğini kontrol eder. VerificationJWS politikasının crit içinde bulduğu, ancak <KnownHeaders> içinde de listelenmeyen herhangi bir başlık, VerificationJWS politikasının başarısız olmasına neden olur.

<DetachContent>

<DetachContent>true|false</DetachContent>

JWS'nin ayrı bir yük ile (<DetachContent>true</DetachContent>) oluşturulup oluşturulmayacağını (<DetachContent>false</DetachContent>) belirtir.

Yanlış değerini belirtirseniz varsayılan olarak 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ış yük söz konusu olduğunda, orijinal kodlanmamış yükü DoğrulamaJWS politikasının <DetachedContent> öğesini kullanarak VerifyJWS politikasına iletmek sizin sorumluluğunuzdadır.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Politikada belirtilen referans verilen herhangi bir değişken çözümlenemez durumda olduğunda politikanın hata vermesini istiyorsanız "false" (yanlış) değerine ayarlayın. Çözümlenemeyen değişkenleri boş dize (null) olarak ele almak için değeri 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>

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

<PrivateKey/Id>

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

or

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

JWS üstbilgisine dahil edilecek anahtar kimliğini (kid) belirtir. Yalnızca algoritma RS256/RS384/RS512, PS256/PS384/PS512 veya ES256/ES384/ES512 değerlerinden biri 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 değerlerinden biri olduğunda kullanın.

<PrivateKey/Value>

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

JWS'yi imzalamak için kullanılan PEM kodlu özel anahtarı belirtir. 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 değerlerinden biri olduğunda kullanın.

<Gizli Anahtar/Kimlik>

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

or

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

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

<SecretKey/Value>

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

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

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

Akış değişkenleri

JWS Oluştur 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, bir çalışma zamanı hatası oluştuğunda ayarlanır. Daha fazla bilgi için Politika hataları hakkında bilmeniz gerekenler bölümüne bakın.

Örnek hata yanıtı

Hata işleme için en iyi uygulama, hata yanıtının errorcode bölümünü yakalamaktır. Değişebileceği için faultstring içindeki metne güvenmeyin.

Hata kuralı örneği

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