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 JWT'deki imzayı doğrular. Bu politika, sonraki politikaların veya koşulların yetkilendirme ya da yönlendirme kararları vermek için bu değerleri inceleyebilmesi amacıyla talepleri bağlam değişkenlerine de ayırır. Ayrıntılı bir giriş için JWS ve JWT politikalarına genel bakış başlıklı makaleyi inceleyin.

Bu politika yürütüldüğünde Edge, JWT'nin imzasını doğrular ve varsa JWT'nin geçerlilik bitiş ve geçerlilik başlangıç zamanlarına göre geçerli olduğunu doğrular. Politika, JWT'deki belirli hak taleplerinin değerlerini (ör. konu, veren, kitle veya ek hak taleplerinin değeri) isteğe bağlı olarak da doğrulayabilir.

JWT doğrulanır ve geçerliyse JWT'de yer alan tüm talepler, sonraki politikalar veya koşullar tarafından kullanılmak üzere bağlam değişkenlerine çıkarılır ve isteğin devam etmesine izin verilir. JWT imzası doğrulanamazsa veya zaman damgalarından biri nedeniyle JWT geçersizse tüm işlemler durdurulur ve yanıtta 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'deki 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'yi doğrulama

Bu örnek politika, SHA-256 denetim toplamı kullanılarak HS256 şifreleme algoritması, HMAC ile imzalanmış bir JWT'yi doğrular. JWT, jwt adlı bir form parametresi kullanılarak proxy isteğine iletilir. Anahtar, private.secretkey adlı bir değişkende yer alıyor. Politikayla ilgili nasıl talepte bulunacağınız da dahil olmak üzere eksiksiz bir örnek için yukarıdaki videoyu izleyin.

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

<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, çı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ış bir JWT'yi 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, jwt adlı bir form parametresi kullanılarak proxy isteğine iletilir. Ortak anahtar, public.publickey adlı bir değişkende bulunur. Politikayla ilgili nasıl talepte bulunacağınız da dahil olmak üzere eksiksiz bir örnek için yukarıdaki videoyu izleyin.

Bu örnek politikadaki her bir öğeyle ilgili şartlar 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 üstbilgiye sahip bir JWT …

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

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

… imzası, sağlanan ortak anahtarla doğrulanabiliyorsa geçerli kabul edilir.

Aynı başlığa sahip ancak bu yükü içeren 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."
}

… imzası doğrulanabilse bile geçersiz kabul edilir. Bunun nedeni, JWT'de yer alan "sub" talebinin, politika yapılandırmasında belirtildiği gibi "Subject" öğesinin gerekli değeriyle eşleşmemesidir.

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

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

En ü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 öğ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.

<Audience>

<Audience>audience-here</Audience>

or:

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

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

<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 onaylanan talep değerlerinin eşleştiğini doğrular.

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

<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 iletebilirsiniz. JSON nesnesi değişken olarak iletildiğinden talep 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 }
  }
}

<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 onaylanan talep değerlerinin eşleştiğini doğrular.

Ek bir talep, standart ve kayıtlı JWT 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.

<CustomClaims>

Not: Şu anda, kullanıcı arayüzü üzerinden yeni bir GenerateJWT politikası eklediğinizde CustomClaims öğesi eklenir. Bu öğe işlevsel değildir ve yoksayılır. Bunun yerine kullanılması gereken doğru öğe <AdditionalClaims>'dir. Kullanıcı arayüzü, doğru öğeleri daha sonra ekleyecek şekilde güncellenecektir.

<Id>

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

JWT'nin belirli bir jti talebine sahip olduğunu doğrular. Metin değeri ve ref özelliği boş olduğunda politika, rastgele bir UUID içeren bir jti oluşturur. JWT kimliği (jti) hak talebi, JWT'nin benzersiz tanımlayıcısı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 olarak ayarlayın. VerifyJWT politikasının crit üstbilgisini yoksayması için doğru olarak ayarlayın.

Bu öğeyi doğru olarak ayarlamanın bir nedeni, test ortamında olmanız ve henüz eksik bir üstbilginin hataya neden olmasını istememenizdir.

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

Politikanın, gelecekteki bir zamanı belirten iat (Verildiği zaman) talebi içeren bir JWT'de hata vermesini istiyorsanız false (yanlış) olarak ayarlayın (varsayılan). Politikanın doğrulama sırasında iat değerini yoksayması için doğru olarak ayarlayın.

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

<Issuer>

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

Politika, JWT'deki verenin yapılandırma öğesinde belirtilen dizeyle eşleştiğini doğrular. JWT'nin yayınlayıcısını tanımlayan talep. Bu, RFC7519'da belirtilen kayıtlı talep grubundan biridir.

<KnownHeaders>

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

or:

<KnownHeaders ref=’variable_containing_headers’/>

GenerateJWT politikası, JWT'deki <CriticalHeaders> öğesini kullanarak crit başlığını doldurur. Örneğin:

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

VerifyJWT politikası, varsa JWT'deki crit üstbilgisini inceler ve listelenen her üstbilgi için <KnownHeaders> öğesinin de bu üstbilgiyi 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, VerifyJWT politikasının başarısız olmasına neden olur.

İsteğe bağlı olarak, <IgnoreCriticalHeaders> öğesini true olarak ayarlayarak VerifyJWT politikasını crit üstbilgisini yoksayacak şekilde yapılandırabilirsiniz.

<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 imzalı sertifikayı belirtir. İmzalı sertifikayı bir akış değişkeninde iletmek veya PEM kodlu sertifikayı doğrudan belirtmek için ref özelliğini kullanın. Yalnızca algoritma RS256/RS384/RS512, PS256/PS384/PS512 veya ES256/ES384/ES512 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 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 JWT, JWKS kümesinde bulunan bir anahtar kimliği taşıyorsa politika, JWT imzasını doğrulamak için doğru ortak anahtarı kullanır. Bu özellik hakkında ayrıntılı bilgi için JWT'yi doğrulamak için JSON Web Anahtar Seti (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.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. Anahtarı/sertifikayı bir akış değişkeninde iletmek 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 encoding="base16|hex|base64|base64url">
  <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.

<Source>

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

Politika, JWT'deki konunun politika yapılandırmasında belirtilen dizeyle eşleştiğini doğrular. Bu talep, JWT'nin konusunu tanımlar veya bu konuda bir açıklama yapar. Bu, RFC7519'da belirtilen standart talep grubundan biridir.

<TimeAllowance>

<TimeAllowance>120s</TimeAllowance>

Saatler için "ek süre". Örneğin, zaman izni 60 saniye olarak yapılandırılmışsa süresi dolmuş bir JWT, belirtilen geçerlilik bitiş tarihinden sonraki 60 saniye boyunca geçerli olarak kabul edilir. not-before-time değeri de benzer şekilde değerlendirilir. Varsayılan olarak 0 saniye (ek süre yok) değerine ayarlanır.

Akış değişkenleri

Başarının ardından, JWT'yi doğrulayın ve JWT kodunu çözme politikaları ayarlandı. bağlam değişkenlerini görürsünüz:

jwt.{policy_name}.{variable_name}

Örneğin, politika adı jwt-parse-token ise politika, JWT'de belirtilen konu, jwt.jwt-parse-token.decoded.claim.sub adlı bağlam değişkenine. (Geriye dönük uyumluluk için jwt.jwt-parse-token.claim.subject içinde de kullanılabilir)

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