JWS ve JWT politikalarına genel bakış

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

Bu konuda, JWT (JSON Web Token) ve JWS (JSON Web Signature) ile Apigee proxy geliştiricilerinin ilgisini çekebilecek Apigee JWS/JWT politikaları hakkında genel bilgiler verilmektedir.

Giriş

Hem JWS hem de JWT, bağlı uygulamalar arasında talepleri veya onayları paylaşmak için yaygın olarak kullanılır. JWS/JWT politikaları, Edge API proxy'lerinin aşağıdakileri yapmasını sağlar:

  • İmzalı bir JWT veya JWS oluşturun.
  • İmzalı bir JWT veya JWS ile JWS/JWT içindeki talepleri doğrulayın.
  • İmzayı doğrulamadan imzalı bir JWT veya JWS kodunu çözün.

Son iki durumda politika, ek politikaların veya arka uç hizmetlerinin kendilerinin doğrulanmış talepleri incelemesine ve bu taleplere göre karar vermesine olanak tanıyan değişkenleri de belirler.

JWS/JWT politikasını doğrulama kullanılırken geçersiz bir JWS/JWT reddedilir ve hata koşuluna neden olur. Benzer şekilde, JWS/JWT kodunu çözme politikası kullanılırken hatalı biçimlendirilmiş bir JWS/JWT, hata koşuluna neden olur.

Videolar

JWT'ye hızlı bir giriş için kısa bir video izleyin. Bu video, JWT oluşturmaya özel olsa da kavramların çoğu JWS için de aynıdır.

JWT yapısı hakkında daha fazla bilgi edinmek için kısa bir video izleyin.

Kullanım alanları

JWS/JWT politikalarını kullanarak:

  • Bir Edge proxy'sinin proxy veya hedef uç nokta taraflarında yeni bir JWS/JWT oluşturun. Örneğin, JWS/JWT oluşturan ve bunu bir istemciye döndüren bir proxy isteği akışı oluşturabilirsiniz. Alternatif olarak, hedef istek akışında JWS/JWT oluşturacak ve bunu hedefe gönderilen isteğe ekleyecek şekilde bir proxy tasarlayabilirsiniz. Bu talepler daha sonra arka uç hizmetlerinin ek güvenlik işlemleri uygulamasına olanak tanımak için kullanılabilir.
  • Gelen istemci isteklerinden, hedef hizmet yanıtlarından, hizmet çağrısı politikası yanıtlarından veya diğer kaynaklardan alınan bir JWS/JWT'den iddiaları doğrulayın ve ayıklayın. Edge, JWS/JWT'nin üçüncü taraflarca mı yoksa Edge'in kendisi tarafından mı oluşturulduğuna bakılmaksızın, RSA veya HMAC algoritmalarını kullanarak JWS/JWT'deki imzayı doğrular.
  • JWS/JWT kodunu çözün. Kod çözme, JWS/JWT'nin doğrulanmasından önce JWS/JWT içindeki bir talebin (JWT) veya başlığın (JWS/JWT) değerinin bilinmesi gerektiğinde JWS/JWT politikasını doğrulama ile birlikte kullanıldığında en yararlı olur.

JWS/JWT'nin bölümleri

İmzalı bir JWS/JWT, bilgileri nokta ile ayrılmış üç bölüm halinde kodlar: başlık, yük ve imza:

header.payload.signature
  • JWS/JWT oluşturma politikası üç bölümü de oluşturur.
  • JWS/JWT'yi Doğrula politikası üç bölümü de inceler.
  • JWS/JWT'yi Çözme politikası yalnızca başlığı ve yükü inceler.

JWS, yükü JWS'den çıkaran ayrılmış biçimi de destekler:

header..signature

Ayrılmış bir JWS ile yük, JWS'den ayrı olarak gönderilir. Ham, kodlanmamış JWS yükünü belirtmek için JWS politikasını doğrulama <DetachedContent> öğesini kullanırsınız. Ardından, JWS'yi Doğrula politikası, JWS'deki üstbilgiyi ve imzayı, <DetachedContent> öğesi tarafından belirtilen yükü kullanarak JWS'yi doğrular.

Jetonlar, bunların nasıl kodlandığı ve imzalandığı hakkında daha fazla bilgi edinmek için aşağıdaki kaynaklara bakın:

JWS ile JWT arasındaki farklar

Bağlı uygulamalar arasında talepleri veya onayları paylaşmak için JWT ya da JWS kullanabilirsiniz. İkisi arasındaki en büyük fark, yükün gösterimidir:

  • JWT
    • Yük her zaman bir JSON nesnesidir.
    • Yük her zaman JWT'ye eklenir.
    • Jetonun typ üstbilgisi her zaman JWT olarak ayarlanır.
  • JWS
    • Yük, JSON nesnesi, bayt akışı, sekizli akış gibi herhangi bir biçimde gösterilebilir.
    • Yükün JWS'ye eklenmesi gerekmez.

JWT biçimi, yükü temsil etmek için her zaman bir JSON nesnesi kullandığından Edge Generate JWT ve Verify JWT politikaları, aud, iss, sub gibi yaygın Kayıtlı Talep Adlarını işlemek için yerleşik desteğe sahiptir. Bu nedenle, bu talepleri yükte ayarlamak için Generate JWT politikasının öğelerini, değerlerini doğrulamak için ise Verify JWT politikasının öğelerini kullanabilirsiniz. Daha fazla bilgi için JWT spesifikasyonunun Registered Claim Names (Kayıtlı Talep Adları) bölümüne bakın.

Generate JWT politikası, belirli Kayıtlı Talep Adlarını desteklemenin yanı sıra JWT'ye rastgele adlara sahip talepler eklemeyi de doğrudan destekler. Her talep basit bir ad/değer çiftidir. Değer; sayı, Boole, dize, eşlem veya dizi türünde olabilir.

JWS, yük için herhangi bir veri gösterimini kullanabildiğinden yüke talep ekleyemezsiniz. JWS oluşturma politikası, JWS'nin başlığına rastgele adlara sahip talepler eklemeyi destekler. Ayrıca JWS politikaları, JWS'nin yükü atladığı ayrılmış bir yükü destekler. Ayrılmış bir yük, JWS ve yükü ayrı ayrı göndermenize olanak tanır ve çeşitli güvenlik standartları tarafından zorunlu kılınır.

JWS ve JWT kullanırken şablon yerleştirmeyi önleme

Yetkisiz veri işlemeye ilişkin açıklamayı önlemek için GenerateJWT veya GenerateJWS politikalarını kullanırken aşağıdaki yönergeleri uygulayın:

  • Kullanıcı girişlerine doğrudan referans vermeyin: Şablon oluşturmayı destekleyen bir ref özelliğinde hiçbir zaman güvenilmeyen girişleri (ör. request.queryparam.* veya request.header.*) doğrudan kullanmayın.
  • Girişi temizleme: Bir JWT/JWS talebinde harici veriler kullanmanız gerekiyorsa önce bir AssignMessage politikası kullanarak girişten referans vermeden önce tüm küme parantezlerini ({ }) veya diğer şablon karakterlerini kaldırın.
  • Dizeler için açık hak talepleri kullanın: Basit dize hak talepleri için aşağıdakilerden kaçının: type="map". Varsayılan type="string" kullanıldığında, referans verilen değerin örtülü şablon oluşturması engellenir.
  • Doğrulama ve oluşturma politikaları arasındaki davranış tutarsızlığına dikkat edin: JWS ve JWT oluşturma politikaları, şablon oluşturma konusunda doğrulama politikalarından farklı şekilde davranır.

İmza algoritmaları hakkında

JWS/JWT Doğrulama ve JWS/JWT Oluşturma politikaları, 256, 384 veya 512 bitlik SHA2 sağlama toplamlarını kullanarak RSA, RSASSA-PSS, ECDSA ve HMAC algoritmalarını destekler. JWS/JWT kod çözme politikası, JWS/JWT'yi imzalamak için kullanılan algoritmadan bağımsız olarak çalışır.

HMAC algoritması

HMAC algoritması, imzayı oluşturmak (JWS/JWT'yi imzalamak olarak da bilinir) ve imzayı doğrulamak için gizli anahtar olarak bilinen paylaşılan gizli bilgilere dayanır.

Gizli anahtarın minimum uzunluğu, algoritmanın bit gücüne bağlıdır:

  • HS256: Minimum 32 bayt anahtar uzunluğu
  • HS386: Minimum 48 bayt anahtar uzunluğu
  • HS512: Minimum anahtar uzunluğu 64 bayt

RSA algoritması

RSA algoritması, kriptografik imza için ortak/özel anahtar çifti kullanır. RSA imzalarında, imzalayan taraf JWS/JWT'yi imzalamak için RSA özel anahtarı, doğrulayan taraf ise JWS/JWT'deki imzayı doğrulamak için eşleşen RSA ortak anahtarını kullanır. Anahtarlar için boyut şartı yoktur.

RSASSA-PSS algoritması

RSASSA-PSS algoritması, RSA algoritmasının güncellenmiş halidir. RSASSA-PSS, RSS gibi kriptografik imza için RSA ortak/özel anahtar çifti kullanır. Anahtarın biçimi RSS'dekiyle aynıdır. İmzalayan taraf, JWS/JWT'yi imzalamak için özel anahtar kullanır. Doğrulayan taraf ise JWS/JWT'deki imzayı doğrulamak için eşleşen ortak anahtarı kullanır. Anahtarlar için boyut şartı yoktur.

ECDSA algoritması

Elips Biçimli Eğri Dijital İmza Algoritması (ECDSA), P-256, P-384 ve P-521 eğrili elips biçimli eğri şifreleme algoritmasıdır. ECDSA algoritmalarını kullandığınızda algoritma, belirtmeniz gereken ortak ve özel anahtar türünü belirler:

Algoritma Eğri Anahtar şartı
ES256 P-256 P-256 eğrisinden (secp256r1 veya prime256v1 olarak da bilinir) oluşturulan bir anahtar
ES384 P-384 P-384 eğrisinden (secp384r1 olarak da bilinir) oluşturulan bir anahtar
ES512 P-521 P-521 eğrisinden (secp521r1 olarak da bilinir) oluşturulan bir anahtar

Anahtar şifreleme algoritmaları

JWS/JWT politikaları, OpenSSL tarafından desteklenen tüm anahtar şifreleme algoritmalarını destekler.

JWS/JWT'yi doğrulamak için JSON Web Anahtarı Kümesi (JWKS) kullanma

İmzalı bir JWS/JWT'yi doğruladığınızda, jetonu imzalamak için kullanılan özel anahtarla ilişkili ortak anahtarı sağlamanız gerekir. JWS/JWT politikalarını doğrulamak için genel anahtarı sağlamak üzere iki seçeneğiniz vardır:

  • gerçek ortak anahtar değerini (genellikle bir akış değişkeninde sağlanır) kullanın veya
  • JWKS'ye sarmalanmış bir ortak anahtar kullanın.

JWKS hakkında

JWKS, bir dizi JSON Web Anahtarı'nı (JWK'lar) temsil eden bir JSON yapısıdır. JWK, şifreleme anahtarını temsil eden bir JSON veri yapısıdır. JWK ve JWKS, RFC7517'de açıklanmıştır. JKWS örneklerini şu adreste bulabilirsiniz: Ek A. Örnek JSON Web Anahtar Kümeleri

JWKS yapısı

RFC7517, "RSA" veya "EC" gibi her anahtar türü için JWKS anahtar öğelerini açıklar. Örneğin, anahtar türüne bağlı olarak bu parametreler şunları içerebilir:

  • kty: "RSA" veya "EC" gibi anahtar türü.
  • kid (anahtar kimliği): Herhangi bir rastgele değer olabilir (anahtar kümesi içinde yinelenen değer olmamalıdır). Gelen JWT, JWKS kümesinde bulunan bir anahtar kimliği taşıyorsa politika, JWS/JWT imzasını doğrulamak için doğru ortak anahtarı kullanır.

İsteğe bağlı öğeler ve değerleriyle ilgili örnekleri aşağıda bulabilirsiniz:

  • alg: Anahtar algoritması. Bu değer, JWS/JWT'deki imzalama algoritmasıyla eşleşmelidir.
  • use: Varsa sig olmalıdır.

Aşağıdaki JWKS, gerekli öğeleri ve değerleri içerir ve Edge'de geçerli olur (https://www.googleapis.com/oauth2/v3/certs adresinden):

{
   "keys":[
      {
         "kty":"RSA",
         "alg":"RS256",
         "use":"sig",
         "kid":"ca04df587b5a7cead80abee9ea8dcf7586a78e01",
         "n":"iXn-WmrwLLBa-QDiToBozpu4Y4ThKdwORWFXQa9I75pKOvPUjUjE2Bk05TUSt7-V7KDjCq0_Nkd-X9rMRV5LKgCa0_F8YgI30QS3bUm9orFryrdOc65PUIVFVxIwMZuGDY1hj6HEJVWIr0CZdcgNIll06BasclckkUK4O-Eh7MaQrqb646ghFlG3zlgk9b2duHbDOq3s39ICPinRQWC6NqTYfqg7E8GN_NLY9srUCc_MswuUfMJ2cKT6edrhLuIwIj_74YGkpOwilr2VswKsvJ7dcoiJxheKYvKDKtZFkbKrWETTJSGX2Xeh0DFB0lqbKLVvqkM2lFU2Qx1OgtTnrw",
         "e":"AQAB"
      },
      {
          "kty":"EC",
          "alg":"ES256",
          "use":"enc",
          "kid":"k05TUSt7-V7KDjCq0_N"
          "crv":"P-256",
          "x":"Xej56MungXuFZwmk_xccvsMpCtXmqhvEEMCmHyAmKF0",
          "y":"Bozpu4Y4ThKdwORWFXQa9I75pKOvPUjUjE2Bk05TUSt",
      }
   ]
}

Proxy'nizi JWKS kullanacak şekilde tasarlama

Bir yayıncıdan JWS/JWT alındığında, yayıncı genellikle JWS/JWT başlığına bir anahtar kimliği (veya kid) ekler. Anahtar, JWS/JWT'nin alıcısına, imzalı JWS/JWT'deki imzayı doğrulamak için gereken ortak veya gizli anahtarın nasıl bulunacağını bildirir.

Örneğin, bir yayınlayıcının JWT'yi özel anahtarla imzaladığını varsayalım. "Anahtar Kimliği", JWT'yi doğrulamak için kullanılacak eşleşen ortak anahtarı tanımlar. Herkese açık anahtarların listesi genellikle iyi bilinen bir uç noktada (ör. https://www.googleapis.com/oauth2/v3/certs) bulunur.

Bu, Edge'in (veya JWKS ile çalışan herhangi bir platformun) JWKS içeren bir JWS/JWT ile çalışmak için gerçekleştirmesi gereken temel sıradır:

  1. Anahtar kimliğini (kid) bulmak için JWS/JWT başlığını inceleyin.
  2. İmzalama algoritmasını (alg) bulmak için JWS/JWT başlığını inceleyin (ör. RS256).
  3. Belirli bir yayınlayıcı için iyi bilinen uç noktanın JWKS'sinden anahtar ve kimlik listesini alın.
  4. JWKS anahtarı algoritmayı belirtiyorsa JWS/JWT üstbilgisinde belirtilen anahtar kimliğine sahip anahtarlar listesinden ve eşleşen algoritmayla ortak anahtarı ayıklayın.
  5. JWS/JWT'deki imzayı doğrulamak için bu ortak anahtarı kullanın.

Bir Edge API proxy geliştiricisi olarak JWS/JWT doğrulaması yapmak için aşağıdakileri yapmanız gerekir:

  1. Belirli bir veren için iyi bilinen uç noktadan anahtar ve kimlik listesini alın. Bu adım için bir hizmet çağrısı politikası kullanabilirsiniz.
  2. JWS/JWT politikasını doğrulama adımında, JWS/JWT'nin konumunu <Source> öğesinde, JWKS yükünü ise <PublicKey/JWKS> öğesinde belirtin. Örneğin, VerifyJWT politikası için: 
    <VerifyJWT name="JWT-Verify-RS256">
    <Algorithm>RS256</Algorithm>
    <Source>json.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <JWKS ref="public.jwks"/>
    </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>

JWT'yi Doğrula politikası diğer her şeyi yapar:

  • JWKS'de, JWT'de onaylanan anahtar kimliğiyle (kid) eşleşen bir anahtar bulunamazsa JWT'yi Doğrula politikası hata verir ve JWT'yi doğrulamaz.
  • Gelen JWT'nin üstbilgisinde anahtar kimliği (kid) yoksa bu anahtar kimliğinden doğrulama anahtarına eşleme yapılamaz.

Proxy tasarımcı olarak, kullanılacak anahtarı belirlemek sizin sorumluluğunuzdadır. Bazı durumlarda bu, sabit ve kodlanmış bir anahtar olabilir.