JWT politikasını doğrulayın

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

Ne

İstemcilerden veya diğer sistemlerden alınan bir JWT'deki imzayı doğrular. Bu politika, hak taleplerini 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.

Bu politika uygulandığında Edge, JWT'nin imzasını doğrular ve JWT'nin geçerlilik bitiş tarihine göre geçerli olduğunu ve varsa JWT'nin imzalanmadan önce olmadığını doğrular. Politika isteğe bağlı olarak JWT'deki belirli hak taleplerinin değerlerini (ör. konu, kartı veren kuruluş, kitle veya ek hak taleplerinin değeri) de doğrulayabilir.

JWT doğrulanır ve geçerliyse JWT kapsamındaki tüm hak talepleri, sonraki politikalar veya koşullar tarafından kullanılmak üzere bağlam değişkenlerine aktarılır ve isteğin devam etmesine izin verilir. JWT imzası doğrulanamazsa veya JWT, zaman damgalarından biri nedeniyle geçersizse tüm işleme durur ve yanıtta bir hata döndürülür.

JWT'nin parçaları ve nasıl şifrelenip imzalandığı hakkında bilgi edinmek için RFC7519 sayfasına bakın.

Video

JWT'de imzayı nasıl doğrulayacağınızı öğrenmek için kısa bir video izleyin.

Örnekler

• HS256 algoritmasıyla imzalanmış bir JWT'yi doğrulama
• RS256 algoritmasıyla imzalanmış bir JWT'yi doğrulama

HS256 algoritmasıyla imzalanmış bir JWT doğrulama

Bu örnek politika, HS256 şifreleme algoritmasıyla (SHA-256 sağlaması) HMAC kullanılarak imzalanan bir JWT'yi doğrular. JWT, proxy isteğinde jwt adlı bir form parametresi kullanılarak iletilir. Anahtar, private.secretkey adlı bir değişkende yer alıyor. Politikadan nasıl istekte bulunulacağını da içeren eksiksiz bir örnek için yukarıdaki videoyu izleyin.

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

<VerifyJWT name="JWT-Verify-HS256">
    <DisplayName>JWT Verify HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <Source>request.formparam.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey encoding="base64">
        <Value ref="private.secretkey"/>
    </SecretKey>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
</VerifyJWT>

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ış bir JWT doğrulama

Bu örnek politika, RS256 algoritmasıyla imzalanmış bir JWT'yi doğrular. Doğrulamak için ortak anahtarı sağlamanız gerekir. JWT, proxy isteğinde jwt adlı bir form parametresi kullanılarak iletilir. Ortak anahtar, public.publickey adlı bir değişkende yer alıyor. Politikadan nasıl istekte bulunulacağını da içeren eksiksiz bir örnek için yukarıdaki videoyu izleyin.

Bu örnek politikadaki her öğeyle ilgili koşullar ve seçenekler hakkında ayrıntılı bilgi için Öğe referansına bakın.

<VerifyJWT name="JWT-Verify-RS256">
    <Algorithm>RS256</Algorithm>
    <Source>request.formparam.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <Value ref="public.publickey"/>
    </PublicKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>    
    </AdditionalClaims>
</VerifyJWT>

Yukarıdaki yapılandırma için şu başlığa sahip bir JWT...

{
  "typ" : "JWT", 
  "alg" : "RS256"
}

Ve bu yük ...

{ 
  "sub" : "apigee-seattle-hatrack-montage",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a",
  "show": "And now for something completely different."
}

... imza sağlanan ortak anahtarla doğrulanabilirse geçerli olarak kabul edilir.

Aynı başlığa ancak bu yüke sahip bir JWT ...

{ 
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a",
  "show": "And now for something completely different."
}

... JWT'deki "sub" hak talebi, politika yapılandırmasında belirtilen "Subject" öğesi için gereken değerle eşleşmediğinden imza doğrulanabilir olsa bile geçersiz olarak belirlenecektir.

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

JWT'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 encoding="base16|hex|base64|base64url">
  <Value ref="private.secretkey"/>
</SecretKey>

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

<PublicKey>
  <Certificate ref="signed_cert_val_ref"/>
</PublicKey>

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

Öğe referansı

Politika referansında, JWT'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

<VerifyJWT name="JWT" 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.

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable-name-here'/>

Politika, JWT'deki kitle hak talebinin yapılandırmada belirtilen değerle eşleştiğini doğrular. Eşleşme yoksa politika hata verir. Bu hak talebi, JWT'nin amaçlandığı alıcıları tanımlar. Bu, RFC7519'da belirtilen kayıtlı hak taleplerinden biridir.

<AdditionalClaims/Claims> (EkHak Talebi/Hak Talebi)

<AdditionalClaims>
    <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'/>
 </AdditionalClaims>

or:

<AdditionalClaims ref='claim_payload'/>

JWT yükünün belirtilen ek talepleri içerdiğini ve iddia edilen iddia değerlerinin eşleştiğini doğrular.

Ek hak talebinde, standart, kayıtlı JWT hak talebi adlarından biri olmayan bir ad kullanılıyor. Ek talebin değeri bir 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.

<Claim> öğesini eklediğinizde, politikayı yapılandırırken hak talebi adları statik olarak ayarlanır. Alternatif olarak, hak talebi adlarını belirtmek için bir JSON nesnesi aktarabilirsiniz. JSON nesnesi değişken olarak iletildiğinden, hak talebi adları çalışma zamanında belirlenir.

Örneğin:

<AdditionalClaims ref='json_claims'/>

Burada, json_claims değişkeni şu biçimde bir JSON nesnesi içerir:

{
  "sub" : "person@example.com",
  "iss" : "urn://secure-issuer@example.com",
  "non-registered-claim" : {
    "This-is-a-thing" : 817,
    "https://example.com/foobar" : { "p": 42, "q": false }
  }
}

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

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

Ek hak talebi, standart, kayıtlı JWT hak talebi adlarından biri olmayan bir ad kullanıyor. 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.

<CustomClaims>

Not: Şu anda kullanıcı arayüzü üzerinden yeni bir GenerateJWT politikası eklediğinizde bir CustomClaims öğesi ekleniyor. Bu öğe çalışmıyor ve yoksayıldı. Bunun yerine kullanılacak doğru öğe, <AdditionalClaims> öğesidir. Kullanıcı arayüzü, doğru öğeleri daha sonra eklemek için güncellenecektir.

<Kimlik>

<Id>explicit-jti-value-here</Id>
 -or-
<Id ref='variable-name-here'/>
 -or-
<Id/>

JWT'nin belirli jti talebine sahip olduğunu doğrular. Metin değeri ve ref özelliği boş olduğunda politika, rastgele UUID içeren bir jti oluşturur. JWT kimliği (jti) talebi, JWT için benzersiz bir tanımlayıcıdır. jti hakkında daha fazla bilgi için RFC7519'a bakın.

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

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

Bu öğenin doğru değerine ayarlanmasının nedenlerinden biri, bir test ortamındaysanız ve eksik bir başlıkta hataya neden olmaya henüz hazır değilseniz olabilir.

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

Bir JWT, gelecekteki bir saati belirten iat (Yayınlanma zamanı) iddiası içerdiğinde politikanın hata vermesini istiyorsanız false (varsayılan) değerine ayarlayın. Politikanın, doğrulama sırasında iat politikasını yok sayması için true (doğru) değerine ayarlayın.

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

<Issuer>

<Issuer ref='variable-name-here'/>
<Issuer>issuer-string-here</Issuer>

Politika, JWT'deki yayıncının yapılandırma öğesinde belirtilen dizeyle eşleştiğini doğrular. JWT'yi veren kuruluşu tanımlayan bir hak talebi. Bu, RFC7519'da belirtilen kayıtlı hak taleplerinden biridir.

<KnownHeaders>

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

or:

<KnownHeaders ref=’variable_containing_headers’/>

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

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

DoğrulamaJWT politikası, JWT'deki crit başlığını (varsa) inceler ve listelenen her başlık için <KnownHeaders> öğesinin bu başlığı da listeleyip listelemediğ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'te bulduğu ancak <KnownHeaders> içinde de listelenmeyen herhangi bir başlık, VerificationJWT politikasının başarısız olmasına neden olur.

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

<PublicKey/Sertifika>

<PublicKey>
   <Certificate ref="signed_public.cert"/>
</PublicKey>
-or-
<PublicKey>
    <Certificate>
    -----BEGIN CERTIFICATE-----
    cert data
    -----END CERTIFICATE-----
    </Certificate>
</PublicKey>

JWT'deki imzayı doğrulamak için kullanılan imzalı sertifikayı belirtir. İmzalanmış sertifikayı bir akış değişkeninde geçirmek için ref özelliğini kullanın veya PEM kodlu sertifikayı doğrudan belirtin. Yalnızca algoritma RS256/RS384/RS512, PS256/PS384/PS512 veya ES256/ES384/ES512 değerlerinden biri olduğunda kullanın.

<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 JWT, JWKS kümesinde bulunan bir anahtar kimliği taşırsa politika, JWT imzasını doğrulamak için doğru ortak anahtarı kullanır. Bu özellikle ilgili ayrıntılar için JWT'yi doğrulamak için JSON Web Anahtar Kümesi (JWKS) kullanma bölümüne bakı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.publickeyorcert"/>
</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>

JWT üzerinde imzayı doğrulamak için kullanılan ortak anahtarı veya ortak sertifikayı belirtir. Anahtarı/sertifikayı 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 encoding="base16|hex|base64|base64url">
  <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..

<Kaynak>

<Source>jwt-variable</Source>

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

<Subject>

<Subject>subject-string-here</Subject>

Bu politika, JWT'deki konunun politika yapılandırmasında belirtilen dizeyle eşleştiğini doğrular. Bu iddia, JWT'nin konusunu tanımlayan veya bununla ilgili bir beyanda bulunan iddialardır. Bu, RFC7519'da belirtilen standart iddia gruplarından biridir.

<TimeAllowance>

<TimeAllowance>120s</TimeAllowance>

Süre için "ek yayınlanma süresi"dir. Örneğin, süre 60 saniye olarak yapılandırılırsa süresi dolan bir JWT, süre sonu iddiasının ardından 60 saniye boyunca hâlâ geçerli olarak değerlendirilir. Öncesinde olmayan zaman da benzer şekilde değerlendirilir. Varsayılan olarak 0 saniyedir (ek yayınlanma süresi yoktur).

Akış değişkenleri

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

jwt.{policy_name}.{variable_name}

Örneğin, politika adı jwt-parse-token ise politika , JWT'de belirtilen konuyu jwt.jwt-parse-token.decoded.claim.sub adlı bağlam değişkeninde saklar. (Geriye dönük uyumluluk için jwt.jwt-parse-token.claim.subject sürümünde de kullanıma sunulacaktır)

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