JWT politikasını doğrulayın

Apigee Edge belgelerini görüntülüyorsunuz.
. Git: Apigee X belgeleri. bilgi

Ne?

İstemcilerden veya diğer sistemlerden alınan bir JWT'deki imzayı doğrular. Bu politika ayrıca sonraki politikaların veya koşulların inceleyebilmesi için hak taleplerini bağlam değişkenlerine ayırır bu değerleri kullanarak yetkilendirme veya yönlendirme kararları verebilirsiniz. Ayrıntılı bilgi için JWS ve JWT politikalarına genel bakış sayfasına göz atın.

Bu politika yürütüldüğünde Edge bir JWT'nin imzasını doğrular ve JWT'nin son geçerlilik tarihine göre ve varsa daha önce kullanılacak şekilde de geçerlidir. Politika isteğe bağlı olarak JWT ile ilgili belirli iddiaların değerlerini de doğrularsınız (konu, kartı veren kuruluş, veya ek hak taleplerinin değeri olabilir.

JWT doğrulanmış 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 ayıklanır ve istek devam etmesine izin veriliyor. JWT imzası doğrulanamazsa veya JWT; bu hata nedeniyle tüm işleme durur ve yanıtta bir hata döndürülür.

JWT'nin bölümleri ve bunların nasıl şifrelenip imzalandığı hakkında bilgi edinmek için RFC7519'a bakın.

Video

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

Örnekler

• HS256 ile imzalanmış bir JWT'yi doğrulayın algoritma
• RS256 ile imzalanmış bir JWT'yi doğrulama algoritma

HS256 ile imzalanmış bir JWT'yi doğrulayın algoritma

Bu örnek politika, HS256 şifreleme algoritması HMAC ile imzalanan bir JWT'yi doğrular sağlayabilir. JWT, proxy isteğinde jwt Anahtar, private.secretkey adlı bir değişkende yer alır. Politikaya nasıl istekte bulunabileceğiniz de dahil olmak üzere 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. JWT'nin nerede bulunacağı (Kaynak öğesinde belirtilen bir akış değişkeninde) gizli anahtarın bulunacağı (Edge akış değişkeninde saklanan Edge KVM'den alınmıştır) ve bir dizi gerekli talep ile bunların değerler.

<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 sonraki politikalar veya koşullar bu değerleri inceleyebilir. Ayrıntılı bilgi için Akış değişkenleri bu politika tarafından ayarlanan değişkenlerin listesini oluşturun.

RS256 ile imzalanmış bir JWT'yi doğrulama algoritma

Bu örnek politika, RS256 algoritmasıyla imzalanan bir JWT'yi doğrular. Doğrulamak için: ortak anahtarı sağlamanız gerekir. JWT, proxy isteğinde bir form parametresi kullanılarak iletilir jwt olarak adlandırıldı. Ortak anahtar, public.publickey adlı bir değişkende bulunur. Politikaya nasıl istekte bulunabileceğiniz de dahil olmak üzere eksiksiz bir örnek için yukarıdaki videoyu izleyin.

Bu kılavuzdaki her bir öğeyle ilgili gereksinimler ve seçenekler için Öğe referansına bakın. örnek politika.

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

... imzanın herkes tarafından doğrulanabildiği durumlarda geçerli kabul edilir. tuşuna basın.

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

... imzanın geçersiz olduğu kabul edilecektir. Bunun nedeni, "alt" JWT'ye dahil edilen hak talebi, gerekli "Konu" değeriyle eşleşmiyor öğesini politika yapılandırmasında belirtilir.

Politika, çıktısını bağlam değişkenlerine yazar, böylece sonraki politikalar veya koşullar bu değerleri inceleyebilir. Ayrıntılı bilgi için Akış değişkenleri bu politika tarafından ayarlanan değişkenlerin listesini oluşturun.

Temel öğeleri ayarlama

JWT'yi doğrulamak için kullanılan anahtarı belirtmek için kullandığınız öğeler, seçilen algoritmaya bağlı olarak değişir. aşağıdaki tabloda gösterildiği gibi):

<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 öğelerini ve özellikleri açıklanır.

Not: Yapılandırma, şifrelemeye bağlı olarak biraz farklılık gösterir. belirlemektir. Aşağıdaki örnekler için Örnekler'e bakın: yapılandırmalarına yardımcı olur.

Proje hedefini üst düzey öğe

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

Yönetim kullanıcı arayüzü proxy düzenleyicisinde politikayı etiketlemek için ad özelliğine ek olarak kullanın doğal bir dille değiştirin.

<Algorithm>

<Algorithm>HS256</Algorithm>

Jetonu imzalamak için kullanılacak şifreleme algoritmasını belirtir. RS*/PS*/ES* algoritmaları bir ortak/gizli anahtar çifti kullanır, HS* algoritmaları ortak bir sır kullanır. Şu kaynakları da inceleyin: İmza şifreleme algoritmaları hakkında.

Virgülle ayırarak birden çok değer belirtebilirsiniz. Örneğin "HS256, HS512" veya "RS256, PS256". Ancak, HS* algoritmalarını diğer algoritmalarla veya ES* algoritmalarını başka algoritmalarla birleştiremezsiniz, çünkü belirli bir anahtar türü gerektirir. 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ırma. Eşleşme olmazsa politika hata verir. Bu iddia, JWT'nin hedeflendiği alıcılar. Bu, şurada belirtilen kayıtlı hak taleplerinden biridir: RFC7519.

<AdditionalClaims/Claim>

<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 hak talebi değerleri eşleşiyor.

Diğer hak taleplerinde, standart ve kayıtlı JWT hak talebi adlarından biri olmayan bir ad kullanılıyor. Ek bir talebin değeri bir dize, sayı, boole, harita veya dizi olabilir. Harita bir ad/değer çiftleri kümesidir. Bu türlerin herhangi birindeki bir hak talebinin değeri belirtilebilir doğrudan politika yapılandırmasında veya bir akış değişkenine referans vererek dolaylı şekilde değiştirebilirsiniz.

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

• name - (Zorunlu) Hak talebinin adı.
• ref - (İsteğe bağlı) Bir akış değişkeninin adı. Varsa politika, değişkeninin hak talebi olarak kabul edildiğini gösterir. Hem bir ref özelliği hem de açık bir hak talebi değeri belirtilirse açık değer varsayılan değerdir 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
• dizi - (İsteğe bağlı) Değerin bir tür dizisi olup olmadığını belirtmek için true olarak ayarlayın. Varsayılan: false (yanlış) değerini alır.

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

Örneğin:

<AdditionalClaims ref='json_claims'/>

json_claims değişkeninin şu biçimde bir JSON nesnesi içerdiği durumda:

{
  "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 }
  }
}

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

JWT başlığının, belirtilen ek talep adı/değer çiftlerini içerdiğini ve bildirilen hak talebi değerlerinin eşleştiğini doğrular.

Ek hak talebinde, standart ve kayıtlı JWT hak talebi adlarından biri olmayan bir ad kullanılıyor. Ek bir talebin değeri bir dize, sayı, boole, harita veya dizi olabilir. Harita bir ad/değer çiftleri kümesidir. Bu türlerin herhangi birindeki bir hak talebinin değeri belirtilebilir doğrudan politika yapılandırmasında veya bir akış değişkenine referans vererek dolaylı şekilde değiştirebilirsiniz.

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

• name - (Zorunlu) Hak talebinin adı.
• ref - (İsteğe bağlı) Bir akış değişkeninin adı. Varsa politika, değişkeninin hak talebi olarak kabul edildiğini gösterir. Hem bir ref özelliği hem de açık bir hak talebi değeri belirtilirse açık değer varsayılan değerdir 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
• dizi - (İsteğe bağlı) Değerin bir tür dizisi olup olmadığını belirtmek için true olarak ayarlayın. Varsayılan: false (yanlış) değerini alır.

<CustomClaims>

Not: Şu anda yeni bir Kullanıcı arayüzü aracılığıyla JWT politikası oluşturun. Bu öğe işlevsel olmadığı için yoksayıldı. Doğru öğesi <AdditionalClaims>. Kullanıcı arayüzü doğru öğeleri daha sonra ekleyecek şekilde güncellenir.

<Id>

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

JWT'nin ilgili jti hak talebine sahip olduğunu doğrular. Metin değeri ve referans özelliği boşsa politika, rastgele UUID içeren bir jti oluşturur. JWT kimliği (jti) hak 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ığı, <KnownHeaders> öğesinde listelenmiyor. VerifyJWT politikasının, crit başlığını yoksaymasına neden olmak için doğru değerine ayarlayın.

Bu öğeyi doğru değerine ayarlamanın nedenlerinden biri, test ortamında olmanız ve henüz bir hata oluşmasına yol açmaya hazır değildir.

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

Bir JWT şunu içerdiğinde politikanın hata vermesini istiyorsanız false (varsayılan) değerine ayarlayın: Gelecekteki bir zamanı belirten iat (Yayınlanma tarihi) hak talebi. Doğrulama sırasında politikanın iat öğesini yoksaymasına neden olmak için doğru değerine ayarlayın.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Başvurulan herhangi bir değişken belirtildiğinde politikanın hata vermesini istiyorsanız false (yanlış) değerine ayarlayın bu politikada çözülemez. Çözümlenemeyen değişkenleri boş dize olarak ele almak için doğru değerine ayarlanır (boş).

<Issuer>

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

Politika, JWT'deki kartı veren kuruluşun yapılandırma öğesi. JWT'yi veren kuruluşu tanımlayan bir hak talebi. Bu, RFC7519'da belirtilen kayıtlı hak talepleri grubudur.

<KnownHeaders>

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

or:

<KnownHeaders ref=’variable_containing_headers’/>

GenerateJWT politikası,<CriticalHeaders> bir JWT'deki crit üstbilgisidir. Örneğin:

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

VerifyJWT politikası, JWT'deki crit üstbilgisini (varsa ve listelenen her başlık için) inceler. <KnownHeaders> öğesinin bu başlığı da listeleyip listelemediğini kontrol eder. İlgili içeriği oluşturmak için kullanılan <KnownHeaders> öğesi, crit'te listelenen öğelerin üst kümesini içerebilir. crit'te listelenen tüm başlıkların <KnownHeaders> öğesi. Politikanın crit'te bulduğu herhangi bir başlık aynı zamanda <KnownHeaders> içinde de listelenmeyen bir veri kümesi, VerifyJWT politikasının başarısız olmasına neden olur.

İsterseniz VerifyJWT politikasını, crit üstbilgisini yoksayacak şekilde yapılandırabilirsiniz. <IgnoreCriticalHeaders> öğesi true olarak ayarlanıyor.

<PublicKey/Certificate>

<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 imzalanmış sertifikayı belirtir. Şunlar için ref özelliğini kullanın: imzalanmış sertifikayı bir akış değişkeninde iletme veya PEM kodlu sertifikayı doğrudan belirtme. Yalnızca algoritma RS256/RS384/RS512, PS256/PS384/PS512 veya ES256/ES384/ES512 özelliklerinden 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 değeri JWKS biçiminde (RFC 7517) belirtir içeren bir dizi ortak anahtar içerir. Yalnızca algoritma RS256/RS384/RS512 değerlerinden biri olduğunda kullanın. PS256/PS384/PS512 veya ES256/ES384/ES512.

Gelen JWT, JWT imzasını içeriyorsa politika, JWT imzasını doğrulamak için doğru ortak anahtarı kullanır. Ayrıntılı bilgi bkz. JWT'yi doğrulamak için JSON Web Anahtarı Seti (JWKS) kullanma.

Değeri herkese açık bir URL'den getirirseniz Edge, JWKS'yi 300 saniyelik bir süre boyunca ö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'deki imzayı doğrulamak için kullanılan ortak anahtarı veya ortak sertifikayı belirtir. Şunlar için ref özelliğini kullanın: anahtarı/sertifikayı bir akış değişkeninde geçirin veya PEM kodlu anahtarı doğrudan belirtin. Yalnızca RS256/RS384/RS512, PS256/PS384/PS512 veya ES256/ES384/ES512 olabilir.

<SecretKey/Value>

<SecretKey encoding="base16|hex|base64|base64url">
  <Value ref="private.your-variable-name"/>
</SecretKey>

HMAC algoritmasıyla jetonları doğrulamak veya imzalamak için kullanılan gizli anahtarı sağlar. Yalnızca kullanım olması gerekir.

<Source>

<Source>jwt-variable</Source>

Varsa politikanın JWT'yi bulmayı beklediği akış değişkenini doğrulayın.

<Subject>

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

Politika, JWT'deki konunun, politikada belirtilen dizeyle eşleştiğini doğrular yapılandırma. Bu iddia, JWT'nin konusunu tanımlar veya bu konuda bir açıklamada bulunur. Bu RFC7519'da belirtilen standart iddia gruplarından biri.

<TimeAllowance>

<TimeAllowance>120s</TimeAllowance>

"Ek süre" zamandır. Örneğin, izin süresi 60 sn olarak yapılandırılmışsa Süresi dolmuş bir JWT, belirtilen geçerlilik süresinden sonra 60 saniye boyunca hâlâ geçerli olarak değerlendirilir. İlgili içeriği oluşturmak için kullanılan olmayanlar benzer şekilde değerlendirilir. Varsayılan olarak 0 saniyeye ayarlanır (ek süre yoktur).

Flow variables

Upon success, the Verify JWT and Decode JWT policies set context variables according to this pattern:

jwt.{policy_name}.{variable_name}

For example, if the policy name is jwt-parse-token , then the policy will store the subject specified in the JWT to the context variable named jwt.jwt-parse-token.decoded.claim.sub. (For backward compatibility, it will also be available in jwt.jwt-parse-token.claim.subject)

Hata referansı

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

Example fault rule

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