VerificationJWS politikası

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

Ne

İstemcilerden veya diğer sistemlerden alınan bir JWS'deki imzayı doğrular. Bu politika, üst bilgileri bağlam değişkenlerine de çıkarır. Böylece sonraki politikalar veya koşullar, yetkilendirme ya da yönlendirme kararları vermek için bu değerleri inceleyebilir. Ayrıntılı tanıtım için JWS ve JWT politikalarına genel bakış başlıklı makaleyi inceleyin.

JWS doğrulanmış ve geçerliyse isteğin devam etmesine izin verilir. JWS imzası doğrulanamazsa veya bir hata nedeniyle JWS geçersizse tüm işleme durur ve yanıtta bir hata döndürülür.

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

Video

JWS'de imzayı nasıl doğrulayacağınızı öğrenmek için kısa bir video izleyin. Bu video JWT'nin doğrulanmasına özel olsa da birçok kavram JWS ile aynıdır.

Örnekler

• HS256 algoritmasıyla imzalanmış ekli bir JWS'yi doğrulama
• RS256 algoritmasıyla imzalanmış ayrı bir JWS'yi doğrulama

HS256 algoritmasıyla imzalanmış ekli bir JWS'yi doğrulama

Bu örnek politika, HS256 şifreleme algoritmasıyla (SHA-256 sağlaması) HMAC kullanılarak imzalanan, ekli bir JWS'yi doğrular. JWS, proxy isteğinde JWS adlı bir form parametresi kullanılarak iletilir. Anahtar, private.secretkey adlı bir değişkende yer alıyor.

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

header.payload.signature

Politika yapılandırması, Edge'in JWS'nin kodunu çözmesi ve değerlendirmesi için gereken bilgileri içerir. Örneğin, JWS'nin nerede bulunacağı (<Source> öğesinde belirtilen bir akış değişkeninde), gerekli imzalama algoritması ve gizli anahtarın nerede bulunacağı (örneğin Edge KVM'den alınmış olabilecek bir Edge akış değişkeninde saklanır).

<VerifyJWS name="JWS-Verify-HS256">
    <DisplayName>JWS Verify HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <Source>request.formparam.JWS</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
    </SecretKey>
</VerifyJWS>

Politika, çıktısını bağlam değişkenlerine yazar. Böylece, API proxy'sinde sonraki politikalar veya koşullar bu değerleri inceleyebilir. Bu politika tarafından ayarlanan değişkenlerin listesi için Akış değişkenleri bölümüne bakın.

RS256 algoritmasıyla imzalanmış ayrı bir JWS'yi doğrulama

Bu örnek politika, RS256 algoritmasıyla imzalanmış ayrı bir JWS'yi doğrular. Doğrulamak için ortak anahtarı sağlamanız gerekir. JWS, proxy isteğinde JWS adlı bir form parametresi kullanılarak iletilir. Ortak anahtar, public.publickey adlı bir değişkende yer alıyor.

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

header..signature

Yükü <DetachedContent> öğesine içeren değişken adını belirterek yükü ValidJWS politikasına iletmek sizin sorumluluğunuzdadır. <DetachedContent> içinde belirtilen içerik, JWS imzası oluşturulurken kodlanmamış orijinal biçimde olmalıdır.

<VerifyJWS name="JWS-Verify-RS256">
    <DisplayName>JWS Verify RS256</DisplayName>
    <Algorithm>RS256</Algorithm>
    <Source>request.formparam.JWS</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <Value ref="public.publickey"/>
    </PublicKey>
    <DetachedContent>private.payload</DetachedContent>
</VerifyJWS>

Politika, çıktısını bağlam değişkenlerine yazar. Böylece, API proxy'sinde sonraki politikalar veya koşullar bu değerleri inceleyebilir. Bu politika tarafından ayarlanan değişkenlerin listesi için Akış değişkenleri bölümüne bakın.

Temel unsurları ayarlama

JWS'yi doğrulamak 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"/>
</SecretKey>

<PublicKey>
  <Value ref="rsa_public_key"/>
</PublicKey>

<PublicKey>
  <JWKS ref="jwks_val_ref_or_url"/>
</PublicKey>

Öğe referansı

Politika referansında, JWS'yi Doğrula 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

<VerifyJWS 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>HS256</Algorithm>

Jetonu imzalayacak şifreleme algoritmasını belirtir. RS*/PS*/ES* algoritmaları bir ortak/gizli anahtar çifti kullanırken HS* algoritmaları, paylaşılan bir gizli anahtar kullanır. İmza şifreleme algoritmaları hakkında başlıklı makaleyi de inceleyin.

Virgülle ayrılmış birden çok değer belirtebilirsiniz. Örneğin, "HS256, HS512" veya "RS256, PS256". Ancak belirli bir anahtar türü gerektirdiğinden HS* algoritmalarını diğer algoritmalarla veya ES* algoritmalarını diğer algoritmalarla birleştiremezsiniz. RS* ve PS* algoritmalarını birleştirebilirsiniz.

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

JWS başlığının belirtilen ek hak talebi ad/değer çiftlerini içerdiğini ve iddia edilen hak talebi değerlerinin eşleştiğini doğrular.

Ek hak talebi, standart, kayıtlı JWS hak talebi adlarından biri olmayan bir ad kullanır. Ek talebin değeri; dize, sayı, boole, harita veya dizi olabilir. Harita, basit bir şekilde ifade etmek gerekirse, bir dizi ad/değer çiftinden oluşur. Bu türlerin herhangi birindeki talebin değeri, politika yapılandırmasında açıkça belirtilebilir veya dolaylı olarak bir akış değişkenine referansla belirtilebilir.

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

<DetachedContent>

<DetachedContent>variable-name-here</DetachedContent>

Oluşturulan ve içerik yükü içeren bir JWS şu biçimdedir:

header.payload.signature

Ayrılmış yük oluşturmak için GenerateJWS politikasını kullanırsanız oluşturulan JWS, yükü atlar ve şu biçimde olur:

header..signature

Ayrılmış yük söz konusu olduğunda, <DetachedContent> öğesini kullanarak yükü Doğrulayıcı JWS politikasına aktarmak sizin sorumluluğunuzdadır. Belirtilen içerik yükü, JWS imzası oluşturulurken olduğu gibi orijinal kodlanmamış biçimde olmalıdır.

Politika aşağıdaki durumlarda hata verir:

• <DetachedContent>, JWS, ayrılmış içerik yükü içermiyorsa belirtilir (hata kodu: steps.jws.ContentIsNotDetached).
• <DetachedContent> çıkarılır ve JWS'nin ayrı bir içerik yükü vardır (hata kodu: steps.jws.InvalidSignature).

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

JWS'nin crit başlığında listelenen herhangi bir başlık <KnownHeaders> öğesinde listelenmeyen politikanın hata vermesini istiyorsanız false (yanlış) değerine ayarlayın. ValidJWS politikasının crit üstbilgisini yoksaymasına neden olmak için true (doğru) değerine ayarlayın.

Bu öğenin doğru değerine ayarlanması, test ortamında olmanız ve eksik başlık nedeniyle politikanın başarısız olmasını istememenizdir.

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

<KnownHeaders>

<KnownHeaders>a,b,c</KnownHeaders>

or:

<KnownHeaders ref=’variable_containing_headers’/>

GenerateJWS politikası, crit başlığını bir jetonda doldurmak için <CriticalHeaders> öğesini kullanır. Örneğin:

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

DoğrulamaJWS politikası, JWS'deki crit başlığını (varsa) inceler ve listelenen her öğe için <KnownHeaders> öğesinin bu başlığın da listelenip listelenmediğini kontrol eder. <KnownHeaders> öğesi, crit'te listelenen öğelerin üst kümesini içerebilir. Yalnızca crit'te listelenen tüm başlıkların <KnownHeaders> öğesinde listelenmesi gerekir. Politikanın crit alanında 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.

İsterseniz <IgnoreCriticalHeaders> öğesini true değerine ayarlayarak VerificationJWS politikasını crit üst bilgisini yok sayacak şekilde yapılandırabilirsiniz.

<PublicKey/JWKS>

<!-- Specify the JWKS. -->
<PublicKey>
   <JWKS>jwks-value-here</JWKS>
</PublicKey>

or:

<!-- Specify a variable containing the JWKS. -->
<PublicKey>
   <JWKS ref="public.jwks"/>
</PublicKey>

or:

<!-- Specify a public URL that returns the JWKS.
The URL is static, meaning you cannot set it using a variable. -->
<PublicKey>
   <JWKS uri="jwks-url"/>
</PublicKey>

Bir ortak anahtar grubu içeren JWKS biçiminde (RFC 7517) bir değer belirtir. Yalnızca algoritma RS256/RS384/RS512, PS256/PS384/PS512 veya ES256/ES384/ES512 değerlerinden biri olduğunda kullanın.

Gelen JWS, JWKS kümesinde bulunan bir anahtar kimliği taşıyorsa politika, JWS imzasını doğrulamak için doğru ortak anahtarı kullanır. Bu özellikle ilgili ayrıntılı bilgi için JWS'i doğrulamak için JSON Web Key Set (JWKS) kullanma konulu makaleye göz atın.

Değeri herkese açık bir URL'den getirirseniz Edge, JWKS'yi 300 saniye süreyle önbelleğe alır. Önbelleğin süresi dolduğunda Edge, JWKS'yi tekrar getirir.

<PublicKey/Value>

<PublicKey>
   <Value ref="public.publickey"/>
</PublicKey>
-or-
<PublicKey>
    <Value>
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW
    Q0UrCw5c0+Y707KX3PpXkZGbtTT4nvU1jC0d1lHV8MfUyRXmpmnNxJHAC2F73IyN
    C5TBtXMORc+us7A2cTtC4gZV256bT4h3sIEMsDl0Joz9K9MPzVPFxa1i0RgNt06n
    Xn/Bs2UbbLlKP5Q1HPxewUDEh0gVMqz9wdIGwH1pPxKvd3NltYGfPsUQovlof3l2
    ALvO7i5Yrm96kknfFEWf1EjmCCKvz2vjVbBb6mp1ZpYfc9MOTZVpQcXSbzb/BWUo
    ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx
    DQIDAQAB
    -----END PUBLIC KEY-----
    </Value>
</PublicKey>

JWS'deki imzayı doğrulamak için kullanılan ortak anahtarı belirtir. Anahtarı bir akış değişkeninde geçirmek için ref özelliğini kullanın veya PEM kodlamalı anahtarı doğrudan belirtin. Yalnızca algoritma RS256/RS384/RS512, PS256/PS384/PS512 veya ES256/ES384/ES512 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 algoritma HS256, HS384, HS512 değerlerinden biri olduğunda kullanın. Anahtarı bir akış değişkeninde iletmek için ref özelliğini kullanın.

<Kaynak>

<Source>JWS-variable</Source>

Varsa politikanın doğrulamak için JWS'yi bulmayı beklediği akış değişkenini belirtir.

Akış değişkenleri

Başarılı olunca, JWS'yi Doğrula ve JWS'nin Kodunu Çöz politikaları bağlam değişkenlerini şu kalıba göre ayarlar:

jws.{policy_name}.{variable_name}

Örneğin, politika adı verify-jws ise politika, JWS'de belirtilen algoritmayı şu bağlam değişkeninde depolar: jws.verify-jws.header.algorithm

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. Bu bilgiyi, 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>