ภาพรวมของนโยบาย 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 โดยไม่ตรวจสอบลายเซ็น

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

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

วิดีโอ

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

วิดีโอสั้นๆ สำหรับดูข้อมูลเพิ่มเติมเกี่ยวกับโครงสร้างของ JWT

กรณีการใช้งาน

คุณใช้นโยบาย JWS/JWT เพื่อทำสิ่งต่อไปนี้ได้

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

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

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

header.payload.signature

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

JWS ยังรองรับรูปแบบเดี่ยวที่ไม่มีเพย์โหลดจาก JWS ดังนี้

header..signature

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

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

• JWT: IETF RFC7519
• JWS: IETF RFC7515

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

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

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

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

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

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

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

นโยบายการยืนยัน JWS/JWT และนโยบายการสร้าง JWS/JWT รองรับอัลกอริทึม 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 (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> ตัวอย่างเช่น สำหรับนโยบาย VerifyJWT

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

นโยบาย Verify JWT ดำเนินการอื่นๆ ทั้งหมดดังต่อไปนี้

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

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