ภาพรวมของนโยบาย JWS และ JWT

คุณกำลังดูเอกสารประกอบของ Apigee Edge
ไปที่เอกสารประกอบของ Apigee X ข้อมูล

หัวข้อนี้ให้ข้อมูลทั่วไปเกี่ยวกับ JWT (JSON Web Token) และ JWS (JSON Web Signature) และนโยบาย Apigee JWS/JWT ที่นักพัฒนาพร็อกซี Apigee อาจสนใจ

เกริ่นนำ

โดยทั่วไปแล้ว ทั้ง JWS และ JWT จะใช้เพื่อแชร์การอ้างสิทธิ์หรือการยืนยันระหว่างแอปพลิเคชันที่เชื่อมต่อ นโยบาย JWS/JWT เปิดใช้พร็อกซี Edge API เพื่อดำเนินการต่อไปนี้

  • สร้าง JWT หรือ JWS ที่ลงชื่อ
  • ยืนยัน JWT หรือ JWS ที่ลงนามแล้ว และการอ้างสิทธิ์ใน JWS/JWT
  • ถอดรหัส JWT หรือ JWS ที่ลงนามโดยไม่ต้องตรวจสอบลายเซ็น

ใน 2 กรณีหลัง นโยบายยังตั้งค่าตัวแปรที่อนุญาตนโยบายเพิ่มเติม ซึ่งก็คือ ตัวบริการเองหรือ บริการแบ็กเอนด์ เพื่อตรวจสอบการอ้างสิทธิ์ที่ผ่านการตรวจสอบแล้ว และเพื่อทำการตัดสินใจตามการอ้างสิทธิ์เหล่านั้น

เมื่อใช้นโยบายยืนยัน JWS/JWT ระบบจะปฏิเสธ JWS/JWT ที่ไม่ถูกต้องและส่งผลให้เกิดข้อผิดพลาด ในทํานองเดียวกัน เมื่อใช้นโยบายการถอดรหัส JWS/JWT รูปแบบ JWS/JWT ที่มีรูปแบบไม่ถูกต้องจะทําให้เกิดเงื่อนไขข้อผิดพลาด

วิดีโอ

ชมวิดีโอสั้นๆ เพื่อทำความรู้จักกับ JWT แม้ว่าวิดีโอนี้จะมีเนื้อหาเกี่ยวกับการสร้าง JWT โดยเฉพาะ แต่แนวคิดส่วนใหญ่ของ JWS ก็เหมือนกัน

อะไรคือวิดีโอสั้นๆ ที่ได้เรียนรู้เพิ่มเติมเกี่ยวกับโครงสร้าง JWT

Use Case

คุณสามารถใช้นโยบาย JWS/JWT เพื่อดําเนินการต่อไปนี้

  • สร้าง JWS/JWT ใหม่บนพร็อกซีหรือฝั่งปลายทางเป้าหมายของพร็อกซี Edge ตัวอย่างเช่น คุณอาจสร้างโฟลว์คำขอพร็อกซีที่สร้าง JWS/JWT และส่งกลับไปยังไคลเอ็นต์ หรือคุณอาจออกแบบพร็อกซีเพื่อให้สร้าง JWS/JWT บนโฟลว์คำขอเป้าหมาย และต่อเชื่อมกับคำขอที่ส่งไปยังเป้าหมายก็ได้ การอ้างสิทธิ์ดังกล่าวจะพร้อมเปิดใช้บริการแบ็กเอนด์เพื่อใช้การประมวลผลความปลอดภัยเพิ่มเติม
  • ยืนยันและแยกการอ้างสิทธิ์จาก JWS/JWT ที่ได้จากคำขอของไคลเอ็นต์ขาเข้า จากการตอบกลับบริการเป้าหมาย จากการตอบกลับนโยบายคำขอราคาเสนอบริการ หรือจากแหล่งที่มาอื่นๆ Edge จะยืนยันลายเซ็นบน JWS/JWT ไม่ว่า JWS/JWT จะสร้างขึ้นโดยบุคคลที่สามหรือ Edge เอง โดยใช้อัลกอริทึม RSA หรือ HMAC
  • ถอดรหัส JWS/JWT การถอดรหัสจะมีประโยชน์มากที่สุดเมื่อใช้ร่วมกับนโยบายยืนยัน JWS/JWT ในกรณีที่ต้องทราบค่าของการอ้างสิทธิ์ (JWT) หรือส่วนหัว (JWS/JWT) จากภายใน JWS/JWT ก่อนที่จะยืนยัน JWS/JWT

ส่วนต่างๆ ของ JWS/JWT

JWS/JWT ที่มีลายเซ็นเข้ารหัสข้อมูลเป็น 3 ส่วนแยกกันด้วยจุด ได้แก่ ส่วนหัว เพย์โหลด และลายเซ็น

header.payload.signature
  • นโยบายสร้าง JWS/JWT จะสร้างทั้ง 3 ส่วน
  • นโยบายยืนยัน JWS/JWT จะตรวจสอบทั้ง 3 ส่วน
  • นโยบายการถอดรหัส JWS/JWT จะตรวจสอบส่วนหัวและเพย์โหลดเท่านั้น

JWS ยังรองรับรูปแบบdetached ซึ่งละเว้นเพย์โหลดจาก JWS ดังนี้

header..signature

เมื่อมี JWS ที่ปลดออกแล้ว ระบบจะส่งเปย์โหลดแยกจาก JWS คุณใช้องค์ประกอบ <DetachedContent> ของนโยบาย "ยืนยัน JWS" เพื่อระบุเพย์โหลด JWS แบบข้อมูลดิบ จากนั้นนโยบาย "ยืนยัน JWS" จะยืนยัน JWS โดยใช้ส่วนหัวและลายเซ็นใน JWS และเพย์โหลดที่ระบุโดยองค์ประกอบ <DetachedContent>

ดูข้อมูลเพิ่มเติมเกี่ยวกับโทเค็นและวิธีเข้ารหัสและรับรองโทเค็นได้ที่

ความแตกต่างระหว่าง JWS กับ JWT

คุณใช้ JWT หรือ JWS เพื่อแชร์การอ้างสิทธิ์หรือการยืนยันระหว่างแอปพลิเคชันที่เชื่อมต่อได้ ความแตกต่างที่สำคัญระหว่างแอตทริบิวต์ทั้ง 2 ประเภทคือการแสดงเปย์โหลด ดังนี้

  • JWT
    • เพย์โหลดเป็นออบเจ็กต์ JSON เสมอ
    • เพย์โหลดจะแนบอยู่กับ JWT เสมอ
    • ส่วนหัว typ ของโทเค็นตั้งค่าเป็น JWT เสมอ
  • JWS
    • เพย์โหลดอาจแสดงในรูปแบบใดก็ได้ เช่น ออบเจ็กต์ JSON, สตรีมไบต์, สตรีมอ็อกเท็ต และอื่นๆ
    • เพย์โหลดไม่จำเป็นต้องแนบไปกับ JWS

เนื่องจากรูปแบบ JWT ใช้ออบเจ็กต์ JSON เพื่อแสดงเพย์โหลดเสมอ นโยบาย Edge Generate JWT และ Confirm JWT จึงมีการสนับสนุนในตัวเพื่อจัดการชื่อการอ้างสิทธิ์ที่จดทะเบียนโดยทั่วไป เช่น aud, iss, sub และอื่นๆ ซึ่งหมายความว่าคุณจะใช้องค์ประกอบของนโยบายสร้าง JWT เพื่อตั้งค่าการอ้างสิทธิ์เหล่านี้ในเพย์โหลดได้ และใช้องค์ประกอบของนโยบาย "ยืนยัน JWT" เพื่อยืนยันค่า ดูข้อมูลเพิ่มเติมได้ที่ส่วนชื่อการอ้างสิทธิ์ที่จดทะเบียนของข้อกำหนด JWT

นอกเหนือจากการสนับสนุนชื่อการอ้างสิทธิ์ที่จดทะเบียนบางชื่อแล้ว นโยบายการสร้าง JWT ยังรองรับการเพิ่มการอ้างสิทธิ์ที่มีชื่อตามอำเภอใจให้กับ JWT โดยตรงด้วย การอ้างสิทธิ์แต่ละรายการเป็นคู่ของชื่อ/ค่าที่ไม่ซับซ้อน โดยค่าจะเป็นประเภทตัวเลข บูลีน สตริง แผนที่ หรืออาร์เรย์

เนื่องจาก JWS สามารถใช้การนำเสนอข้อมูลใดก็ได้สำหรับเพย์โหลด คุณจึงไม่สามารถเพิ่มการอ้างสิทธิ์ในเพย์โหลดได้ นโยบายสร้าง JWS รองรับการเพิ่มการอ้างสิทธิ์ที่มีชื่อที่กำหนดเองในส่วนหัวของ JWS นอกจากนี้ นโยบาย JWS ยังรองรับเพย์โหลดแบบปลดออก โดยที่ JWS จะข้ามเพย์โหลด เพย์โหลดที่ปลดออกจะช่วยให้คุณส่ง JWS และเพย์โหลดแยกกัน ซึ่งเป็นสิ่งจำเป็นสำหรับมาตรฐานความปลอดภัยหลายข้อ

เกี่ยวกับอัลกอริทึมลายเซ็น

การยืนยัน JWS/JWT และนโยบาย JWS/JWT Generation รองรับอัลกอริทึม RSA, RSASSA-PSS, ECDSA และ HMAC โดยใช้ผลรวมตรวจสอบของ SHA2 ที่เป็นค่าของบิต 256, 384 หรือ 512 นโยบายการถอดรหัส JWS/JWT จะใช้ได้โดยไม่คำนึงถึงอัลกอริทึมที่ใช้ในการลงนาม JWS/JWT

อัลกอริทึม HMAC

อัลกอริทึม HMAC ใช้ข้อมูลลับที่ใช้ร่วมกัน หรือที่เรียกว่าคีย์ลับ ในการสร้างลายเซ็น (หรือที่เรียกว่าการลงนาม JWS/JWT) และในการยืนยันลายเซ็น

ความยาวขั้นต่ำของคีย์ลับขึ้นอยู่กับความแรงของบิตของอัลกอริทึม ดังนี้

  • HS256: ความยาวคีย์ขั้นต่ำ 32 ไบต์
  • HS386: ความยาวคีย์ขั้นต่ำ 48 ไบต์
  • HS512: ความยาวคีย์ขั้นต่ำ 64 ไบต์

อัลกอริทึม RSA

อัลกอริทึม RSA ใช้คู่คีย์สาธารณะ/ส่วนตัวสำหรับลายเซ็นที่เข้ารหัส หากมีลายเซ็น RSA ฝ่ายที่ลงนามจะใช้คีย์ส่วนตัว RSA เพื่อลงนาม JWS/JWT และฝ่ายที่ทำการยืนยันจะใช้คีย์สาธารณะ RSA ที่ตรงกันเพื่อยืนยันลายเซ็นบน JWS/JWT ไม่มีข้อกำหนดด้านขนาดบนคีย์

อัลกอริทึม RSASSA-PSS

อัลกอริทึม RSASSA-PSS เป็นการอัปเดตอัลกอริทึม RSA RSASSA-PSS ใช้คู่คีย์สาธารณะ/ส่วนตัว RSA สำหรับลายเซ็นการเข้ารหัสเช่นเดียวกับ RSS รูปแบบของคีย์จะเหมือนกับของ RSS ฝ่ายที่ลงนามใช้คีย์ส่วนตัวเพื่อลงนาม JWS/JWT และฝ่ายที่ทำการยืนยันจะใช้คีย์สาธารณะที่ตรงกันเพื่อยืนยันลายเซ็นบน JWS/JWT ไม่มีข้อกำหนดด้านขนาดสำหรับคีย์

อัลกอริทึม ECDSA

อัลกอริทึม Elliptic Curve Digital Signature Algorithm (ECDSA) เป็นอัลกอริทึมการเข้ารหัสโดยใช้เส้นโค้งรูปวงรีที่มีเส้นโค้ง P-256, P-384 และ P-521 เมื่อคุณใช้อัลกอริทึม ECDSA อัลกอริทึมจะเป็นตัวกำหนดประเภทของคีย์สาธารณะและคีย์ส่วนตัว คุณต้องระบุสิ่งต่อไปนี้

อัลกอริทึม โค้งมน ข้อกำหนดหลัก
ES256 P-256 คีย์ที่สร้างจากเส้นโค้ง P-256 (หรือที่เรียกว่า secp256r1 หรือ Prime256v1)
ES384 P-384 คีย์ที่สร้างจากเส้นโค้ง P-384 (หรือที่เรียกว่า secp384r1)
ES512 P-521 คีย์ที่สร้างจากเส้นโค้ง P-521 (หรือที่เรียกว่า secp521r1)

อัลกอริทึมการเข้ารหัสคีย์

นโยบาย JWS/JWT รองรับอัลกอริทึมการเข้ารหัสคีย์ทั้งหมดที่ OpenSSL รองรับ

การใช้ชุดคีย์เว็บ JSON (JWKS) เพื่อยืนยัน JWS/JWT

เมื่อยืนยัน JWS/JWT ที่ลงนามแล้ว คุณจะต้องระบุคีย์สาธารณะที่เชื่อมโยงกับคีย์ส่วนตัวที่ใช้ลงนามโทเค็น คุณมี 2 ตัวเลือกในการระบุคีย์สาธารณะสำหรับยืนยันนโยบาย JWS/JWT ดังนี้

  • ใช้ค่าคีย์สาธารณะจริง (โดยปกติจะระบุอยู่ในตัวแปรโฟลว์) หรือ
  • ใช้คีย์สาธารณะที่รวมอยู่ใน JWKS

เกี่ยวกับ JWKS

JWKS เป็นโครงสร้าง JSON ที่แสดงชุดของ JSON Web Key (JWK) JWK เป็นโครงสร้างข้อมูล JSON ที่แสดงคีย์การเข้ารหัส JWK และ JWKS มีคำอธิบายอยู่ใน RFC7517 ดูตัวอย่าง JKWS ได้ที่ภาคผนวก A ตัวอย่างชุดคีย์เว็บ JSON

โครงสร้าง JWKS

RFC7517 อธิบายองค์ประกอบหลักของ JWKS สำหรับคีย์แต่ละประเภท เช่น "RSA" หรือ "EC" ตัวอย่างเช่น โดยขึ้นอยู่กับประเภทคีย์ พารามิเตอร์เหล่านี้อาจรวมถึงสิ่งต่อไปนี้

  • kty - ประเภทคีย์ เช่น "RSA" หรือ "EC"
  • kid (รหัสคีย์) - เป็นค่าใดก็ได้ที่กำหนดเอง (ไม่ซ้ำภายในชุดคีย์) หาก JWT ขาเข้ามีรหัสคีย์ซึ่งอยู่ในชุดของ JWKS นโยบายจะใช้คีย์สาธารณะที่ถูกต้องเพื่อยืนยันลายเซ็นของ JWS/JWT

ต่อไปนี้เป็นตัวอย่างองค์ประกอบที่ไม่บังคับและค่า

  • alg - อัลกอริทึมหลัก โดยต้องตรงกับอัลกอริทึมการรับรองใน JWS/JWT
  • use - หากมี ต้องใช้ sig

JWKS ต่อไปนี้มีองค์ประกอบและค่าที่จำเป็น และจะใช้ได้ใน Edge (จาก https://www.googleapis.com/oauth2/v3/certs)

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

การออกแบบพร็อกซีเพื่อใช้ JWKS

เมื่อได้ JWS/JWT มาจากผู้ออกบัตร ผู้ออกบัตรมักจะแทรกรหัสคีย์ (หรือเด็ก) ในส่วนหัว JWS/JWT คีย์จะบอกผู้รับของ JWS/JWT วิธีค้นหาคีย์สาธารณะหรือรหัสลับที่จำเป็นในการยืนยันลายเซ็นใน JWS/JWT ที่ลงนามแล้ว

ตัวอย่างเช่น สมมติว่าผู้ออกบัตรเซ็นชื่อใน JWT ด้วยคีย์ส่วนตัว "รหัสคีย์" ระบุคีย์สาธารณะที่ตรงกันเพื่อใช้ยืนยัน JWT โดยทั่วไปแล้ว รายการคีย์สาธารณะจะมีอยู่ที่ปลายทางที่รู้จักกันดีบางรายการ เช่น https://www.googleapis.com/oauth2/v3/certs

นี่เป็นลำดับพื้นฐานที่ Edge (หรือแพลตฟอร์มที่ทำงานร่วมกับ JWKS) ต้องใช้เพื่อทำงานกับ JWS/JWT ที่มี JWKS

  1. ตรวจสอบส่วนหัว JWS/JWT เพื่อค้นหารหัสคีย์ (kid)
  2. ตรวจสอบส่วนหัว JWS/JWT เพื่อค้นหาอัลกอริทึมการลงชื่อ (alg) เช่น RS256
  3. เรียกดูรายการคีย์และรหัสจาก JWKS ของปลายทางที่รู้จักสำหรับผู้ออกบัตรที่ระบุ
  4. แยกคีย์สาธารณะจากรายการคีย์ด้วยรหัสคีย์ที่ระบุไว้ในส่วนหัว JWS/JWT และด้วยอัลกอริทึมการจับคู่ หากคีย์ JWKS ระบุอัลกอริทึม
  5. ใช้คีย์สาธารณะนั้นเพื่อยืนยันลายเซ็นบน JWS/JWT

ในฐานะนักพัฒนาพร็อกซี Edge API คุณจะต้องทำสิ่งต่อไปนี้เพื่อดำเนินการยืนยัน JWS/JWT

  1. เรียกดูรายการคีย์และรหัสจากปลายทางที่รู้จักของผู้ออกบัตร คุณใช้นโยบายคำขอราคาเสนอบริการสำหรับขั้นตอนนี้ได้
  2. ในนโยบาย "ยืนยัน JWS/JWT" ให้ระบุตำแหน่งของ JWS/JWT ในองค์ประกอบ <Source> และเพย์โหลด JWKS ในองค์ประกอบ <PublicKey/JWKS> ตัวอย่างเช่น สำหรับนโยบาย ConfirmJWT 
    <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 จะดำเนินการอื่นๆ ทั้งหมดดังนี้

  • หากไม่พบคีย์ที่มีรหัสคีย์ที่ตรงกับรหัสคีย์ (kid) ที่ยืนยันใน JWT ใน JWT นโยบายยืนยัน JWT จะแสดงข้อผิดพลาดและไม่ตรวจสอบ JWT
  • หาก JWT ขาเข้าไม่มีรหัสคีย์ (kid) ในส่วนหัว จะไม่สามารถจับคู่ keyid-to-verification-key นี้ได้

ในฐานะผู้ออกแบบพร็อกซี คุณเป็นผู้รับผิดชอบในการกำหนดคีย์ที่จะใช้ ในบางกรณีการดำเนินการนี้อาจเป็นคีย์แบบคงที่และฮาร์ดโค้ด