JWS ve JWT politikalarına genel bakış

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

Bu bölümde, Apigee proxy geliştiricilerinin ilgisini çekebilecek JWT (JSON Web Jetonu) ve JWS (JSON Web İmzası) ile Apigee JWS/JWT politikaları hakkında genel bilgiler verilmektedir.

Giriş

Hem JWS hem de JWT, bağlı uygulamalar arasında iddia veya onayları paylaşmak için yaygın olarak kullanılır. JWS/JWT politikaları, Edge API proxy'lerinin şunları yapmasına olanak tanır:

  • İmzalanmış bir JWT veya JWS oluşturun.
  • İmzalanmış bir JWT veya JWS'yi ve JWS/JWT kapsamındaki hak taleplerini doğrulayın.
  • İmzalı bir JWT veya JWS'nin imzasını doğrulamadan kodunu çözün.

Son iki durumda politika, doğrulanmış iddiaları incelemek ve bu iddialara göre kararlar almak için ek politikalara veya arka uç hizmetlerinin kendilerine izin veren değişkenleri de belirler.

JWS/JWT'yi Doğrula politikası kullanılırken geçersiz bir JWS/JWT reddedilir ve hatanın oluşmasına neden olur. Benzer şekilde, JWS/JWT Kodu Çözme politikası kullanılırken bozuk bir JWS/JWT hata koşulu oluşturur.

Videolar

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

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

Kullanım alanları

JWS/JWT politikalarını kullanarak şunları yapabilirsiniz:

  • Proxy veya hedef uç nokta tarafında yeni bir JWS/JWT oluşturun. Örneğin, JWS/JWT oluşturan ve bunu istemciye döndüren bir proxy isteği akışı oluşturabilirsiniz. Alternatif olarak, proxy'yi hedef istek akışında JWS/JWT oluşturacak ve hedefe gönderilen isteğe ekleyecek şekilde tasarlayabilirsiniz. Böylece bu talepler, arka uç hizmetlerinin daha fazla güvenlik işlemi uygulayabilmesi için kullanılabilir.
  • Gelen istemci isteklerinden, hedef hizmet yanıtlarından, Hizmet Çağrısı politika yanıtlarından veya diğer kaynaklardan elde edilen bir JWS/JWT'den hak taleplerini doğrulayın ve ayıklayın. Edge, JWS/JWT'nin RSA veya HMAC algoritmaları kullanılarak üçüncü taraflarca ya da Edge'in kendisi tarafından oluşturulmuş olmasından bağımsız olarak, JWS/JWT üzerindeki imzayı doğrular.
  • JWS/JWT'nin kodunu çözün. Kod çözme, JWS/JWT'yi doğrulamadan önce JWS/JWT'deki bir hak talebinin (JWT) veya başlığın (JWS/JWT) değerinin bilinmesi gerektiğinde, JWS/JWT'yi Doğrulama politikasıyla uyumlu olarak kullanıldığında çok yararlı olur.

JWS/JWT'nin Parçaları

İmzalanmış bir JWS/JWT, bilgileri noktalarla ayrılmış üç bölümde kodlar: başlık, yük ve imza:

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

JWS, yükü JWS'den çıkaran detached bir biçimi de destekler:

header..signature

Ayrı bir JWS'de yük JWS'den ayrı olarak gönderilir. Ham, kodlanmamış JWS yükünü belirtmek için JWS'yi Doğrula politikasının <DetachedContent> öğesini kullanırsınız. Daha sonra JWS'yi Doğrula politikası, JWS'de üstbilgi ve imza ile <DetachedContent> öğesi tarafından belirtilen yük kullanılarak JWS'yi doğrular.

Jetonlar ve nasıl kodlanıp imzalandıkları hakkında daha fazla bilgi edinmek için aşağıdaki konulara bakın:

JWS ve JWT arasındaki farklar

Bağlı uygulamalar arasında hak taleplerini veya onaylarını paylaşmak için JWT veya JWS'yi kullanabilirsiniz. İkisi arasındaki en önemli fark, yükün temsilidir:

  • JWT
    • Yük her zaman bir JSON nesnesidir
    • Yük her zaman JWT'ye bağlıdır.
    • Jetonun typ başlığı her zaman JWT olarak ayarlanır.
  • JWS
    • Yük; JSON nesnesi, bayt akışı, sekizlik akış vb. herhangi bir biçimle temsil edilebilir
    • Yükün JWS'ye eklenmesi gerekmez

JWT biçimi, yükü temsil etmek için her zaman JSON nesnesi kullandığından Edge generate JWT ve doğrulama JWT politikalarında aud, iss, sub gibi yaygın Kaydedilen Hak Talebi Adlarını işlemek için yerleşik destek vardır. Bu, yükte bu hak taleplerini ayarlamak için JWT Oluştur politikasının öğelerini ve değerlerini doğrulamak için JWT'yi Doğrula politikasının öğelerini kullanabileceğiniz anlamına gelir. Daha fazlası için JWT spesifikasyonunun Kayıtlı Hak Talebi Adları bölümüne bakın.

Belirli Kayıtlı Hak Talebi Adlarını desteklemenin yanı sıra JWT Oluşturma politikası, JWT'ye rastgele adlarla hak talepleri eklemeyi doğrudan destekler. Her hak talebi basit bir ad/değer çiftidir. Burada değer sayı, boole, dize, harita veya dizi türünde olabilir.

JWS, yük için herhangi bir veri temsilini kullanabileceğinden, yüke hak talepleri ekleyemezsiniz. JWS Oluşturma politikası, JWS'nin başlığına rastgele adlarla hak talepleri eklenmesini desteklemez. Ayrıca JWS politikaları, JWS'nin yükü atladığı ayrı bir yükü destekler. Ayrılmış yük, JWS'yi ve yükü ayrı ayrı göndermenize olanak tanır. Bu özellik, çeşitli güvenlik standartları tarafından gereklidir.

İmza algoritmaları hakkında

JWS/JWT Doğrulaması ve JWS/JWT Oluşturma politikaları, bit gücü 256, 384 veya 512 olan SHA2 sağlamaları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 bir gizli anahtardan yararlanır.

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

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

RSA algoritması

RSA algoritması, kriptografik imza için bir ortak/özel anahtar çifti kullanır. RSA imzalarıyla, imzalayan taraf JWS/JWT'yi imzalamak için bir RSA özel anahtarı, doğrulama yapan taraf ise JWS/JWT üzerinde imzayı doğrulamak için eşleşen RSA ortak anahtarını kullanır. Anahtarlarda boyut gereksinimi yoktur.

RSASSA-PSS algoritması

RSASSA-PSS algoritması, RSA algoritmasında yapılan bir güncellemedir. RSS gibi RSASSA-PSS de kriptografik imza için bir RSA herkese açık/özel anahtar çifti kullanır. Anahtarın biçimi RSS ile aynıdır. İmzalayan taraf, JWS/JWT'yi imzalamak için özel bir anahtar, doğrulama yapan taraf ise JWS/JWT üzerinde imzayı doğrulamak için eşleşen ortak anahtarı kullanır. Anahtarlarda boyut gereksinimi yoktur.

ECDSA algoritması

Elips Biçimli Eğri Dijital İmza Algoritması (ECDSA) algoritması; P-256, P-384 ve P-521 eğrisine sahip elips biçimli eğri bir kriptografi algoritmasıdır. ECDSA algoritmalarını kullandığınızda, algoritma, belirtmeniz gereken ortak ve gizli anahtar türünü belirler:

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

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 Key Set (JWKS) kullanma

İmzalanmış bir JWS/JWT'yi doğrularken jetonu imzalamak için kullanılan özel anahtarla ilişkilendirilmiş olan ortak anahtarı sağlamanız gerekir. Doğrulama JWS/JWT politikalarına ortak anahtar sağlamak için iki seçeneğiniz vardır:

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

JWKS hakkında

JWKS, bir JSON Web Anahtarı (JWK) grubunu 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 Ek A. Örnek JSON Web Anahtarı Kümeleri

JWKS yapısı

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

  • kty: "RSA" veya "EC" gibi anahtar türü.
  • kid (anahtar kimliği): İsteğe bağlı herhangi bir değer olabilir (bir anahtar kümesinde yinelenen değerler olamaz). Gelen JWT, JWKS kümesinde bulunan bir anahtar kimliği taşırsa politika, JWS/JWT imzasını doğrulamak için doğru ortak anahtarı kullanır.

Aşağıda, isteğe bağlı öğe ve değerlerine ilişkin örnekler verilmiştir:

  • alg - Anahtar algoritması. 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

Sertifikayı veren kuruluştan JWS/JWT alındığında genellikle kartı veren kuruluş JWS/JWT başlığına bir Anahtar Kimliği (veya çocuk) ekler. Anahtar, JWS/JWT'nin alıcısına, imzalı JWS/JWT'deki imzayı doğrulamak için gereken ortak veya gizli anahtarı nasıl bulacağını bildirir.

Örneğin, bir sertifikayı veren kuruluşun özel anahtarla JWT imzaladığını varsayalım. "Anahtar Kimliği", JWT'yi doğrulamak için kullanılacak, eşleşen ortak anahtarı tanımlar. Genel anahtarların listesi genellikle iyi bilinen bazı uç noktalarda bulunur. Örneğin: https://www.googleapis.com/oauth2/v3/certs.

Bu, Edge'in (veya JWKS ile çalışan herhangi bir platformun) JWKS'ye sahip bir JWS/JWT ile çalışmak için gerçekleştirmesi gereken temel adım sırasıdır:

  1. Anahtar kimliğini (çocuk) bulmak için JWS/JWT başlığını inceleyin.
  2. RS256 gibi imzalama algoritmasını (alg) bulmak için JWS/JWT başlığını inceleyin.
  3. Belirli bir yayıncı için iyi bilinen uç noktanın JWKS'sinden anahtar ve kimlik listesi alın.
  4. JWKS anahtarı algoritmayı belirtiyorsa ortak anahtarı, JWS/JWT başlığında not edilen anahtar kimliğine ve eşleşen algoritmaya sahip anahtar listesinden çıkarın.
  5. JWS/JWT'deki imzayı doğrulamak için bu ortak anahtarı kullanın.

Edge API proxy geliştiricisi olarak JWS/JWT doğrulamasını gerçekleştirmek için aşağıdakileri yapmanız gerekir:

  1. Belirli bir yayıncı 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'yi Doğrulama politikasında <Source> öğesinde JWS/JWT'nin konumunu, <PublicKey/JWKS> öğesinde JWKS yükünü 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:

  • JWT'de belirtilen Anahtar Kimliği (kid) ile eşleşen Anahtar Kimliği'ne sahip bir anahtar, JWKS'de bulunmazsa JWT'yi Doğrulama politikası hata verir ve JWT'yi doğrulamaz.
  • Gelen JWT, başlıkta anahtar kimliği (kid) içermiyorsa keyid-verification-key'in bu eşlenmesi mümkün değildir.

Proxy tasarımcısı olarak kullanılacak anahtarı belirlemek sizin sorumluluğunuzdadır; bazı durumlarda bu sabit kodlu bir anahtar olabilir.