VerificationJWS politikası

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

Ne?

İstemcilerden veya diğer sistemlerden alınan JWS'deki imzayı doğrular. Bu politika, yetkilendirme veya yönlendirme kararları vermek için sonraki politikaların ya da koşulların bu değerleri inceleyebilmesi amacıyla üstbilgileri bağlam değişkenlerine de ayıklar. Ayrıntılı bir giriş için JWS ve JWT politikalarına genel bakış başlıklı makaleyi inceleyin.

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

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

Video

JWS'deki 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 için de aynıdır.

Örnekler

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

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

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

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

header.payload.signature

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

<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, çıkışını bağlam değişkenlerine yazar. Böylece API proxy'sindeki sonraki politikalar veya koşullar bu değerleri inceleyebilir. Bu politika tarafından ayarlanan değişkenlerin listesi için Akış değişkenleri başlıklı makaleyi inceleyin.

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

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

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

header..signature

Yükü içeren değişken adını <DetachedContent> öğesinde belirterek yükü VerifyJWS politikasına iletmek sizin sorumluluğunuzdadır. <DetachedContent> içinde belirtilen içerik, JWS imzası oluşturulduğundaki orijinal kodlanmamış 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, çıkışını bağlam değişkenlerine yazar. Böylece API proxy'sindeki sonraki politikalar veya koşullar bu değerleri inceleyebilir. Bu politika tarafından ayarlanan değişkenlerin listesi için Akış değişkenleri başlıklı makaleyi inceleyin.

Temel öğeleri ayarlama

JWS'yi doğrulamak 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österilmiştir:

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

En ü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 öğ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ğine ek olarak kullanılır.

<Algorithm>

<Algorithm>HS256</Algorithm>

Jetonu imzalamak için kullanılacak şifreleme algoritmasını belirtir. RS*/PS*/ES* algoritmalarında ortak/gizli anahtar çifti, HS* algoritmalarında ise paylaşılan gizli bilgiler kullanılır. Ayrıca İ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ü gerektirdiklerinden HS* algoritmalarını diğerleriyle veya ES* algoritmalarını diğerleriyle birleştiremezsiniz. RS* ve PS* algoritmalarını birleştirebilirsiniz.

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

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

Ek bir talep, standart ve kayıtlı JWS talebi adlarından biri olmayan bir ad kullanıyor. Ek bir talebin değeri dize, sayı, boole, eşlem veya dizi olabilir. Bir harita yalnızca bir ad/değer çiftleri kümesidir. Bu türlerden herhangi birine ait talebin değeri, politika yapılandırmasında açıkça veya bir akış değişkenine yapılan referans aracılığıyla dolaylı olarak belirtilebilir.

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

<DetachedContent>

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

İçerik yükü içeren oluşturulmuş bir JWS şu biçimdedir:

header.payload.signature

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

header..signature

Ayrılmış bir yük için, <DetachedContent> öğesini kullanarak yükü VerifyJWS politikasına iletmek sizin sorumluluğunuzdadır. Belirtilen içerik yükü, JWS imzası oluşturulduğundaki orijinal kodlanmamış biçimde olmalıdır.

Politika aşağıdaki durumlarda hata verir:

• JWS, ayrılmış içerik yükü içermediğinde <DetachedContent> belirtilir (hata kodu steps.jws.ContentIsNotDetached'dir).
• <DetachedContent> atlanır ve JWS'nin ayrılmış 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 listelenmediğinde politikanın hata vermesini istiyorsanız false olarak ayarlayın. VerifyJWS politikasının crit üstbilgisini yoksaymasını sağlamak için doğru olarak ayarlayın.

Bu öğeyi true (doğru) olarak ayarlamanın bir nedeni, test ortamında olmanız ve eksik bir başlık nedeniyle politikanın başarısız olmasını istememenizdir.

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

<KnownHeaders>

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

or:

<KnownHeaders ref=’variable_containing_headers’/>

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

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

VerifyJWS politikası, varsa JWS'deki crit başlığını inceler ve listelenen her öğe için <KnownHeaders> öğesinin de bu başlığı listelediğini kontrol eder. <KnownHeaders> öğesi, crit içinde listelenen öğelerin üst kümesini içerebilir. Yalnızca crit içinde listelenen tüm üstbilgilerin <KnownHeaders> öğesinde listelenmesi gerekir. Politikanı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.

İsteğe bağlı olarak, <IgnoreCriticalHeaders> öğesini true olarak ayarlayarak VerifyJWS politikasını crit üst bilgisini yoksayacak ş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 dizi ortak anahtar içeren JWKS biçiminde (RFC 7517) bir değer belirtir. Yalnızca algoritma RS256/RS384/RS512, PS256/PS384/PS512 veya ES256/ES384/ES512 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 özellik hakkında ayrıntılı bilgi için JWS'yi doğrulamak için JSON Web Anahtarı Kümesi (JWKS) kullanma başlıklı makaleyi inceleyin.

Değeri herkese açık bir URL'den getirirseniz Edge, JWKS'yi 300 saniye boyunca ö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şkenine aktarmak için ref özelliğini kullanın veya PEM kodlu anahtarı doğrudan belirtin. Yalnızca algoritma RS256/RS384/RS512, PS256/PS384/PS512 veya ES256/ES384/ES512 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 veya HS512 olduğunda kullanın. Bir akış değişkeninde anahtarı iletmek için ref özelliğini kullanın.

<Source>

<Source>JWS-variable</Source>

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

Akış değişkenleri

Başarı üzerine kurulan JWS'yi Doğrulama ve JWS'nin Kodunu Çöz politikaları, bağlam değişkenlerini görürsünüz:

jws.{policy_name}.{variable_name}

Örneğin, politika adı verify-jws ise politika, JWS'de belirtilen algoritmayı kullanın: 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, ç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>