คุณกำลังดูเอกสารประกอบของ Apigee Edge
ไปที่เอกสารประกอบของ
Apigee X info
อะไร
ยืนยันลายเซ็นใน JWT ที่ได้รับจากไคลเอ็นต์หรือระบบอื่นๆ นโยบายนี้ยัง ดึงข้อมูลการอ้างสิทธิ์ลงในตัวแปรบริบท เพื่อให้นโยบายหรือเงื่อนไขที่ตามมาสามารถตรวจสอบ ค่าเหล่านั้นเพื่อทำการตัดสินใจเกี่ยวกับการให้สิทธิ์หรือการกำหนดเส้นทาง ดูคำแนะนำแบบละเอียดได้ที่ภาพรวมนโยบาย JWS และ JWT
เมื่อนโยบายนี้ทำงาน Edge จะยืนยันลายเซ็นของ JWT และยืนยันว่า JWT นั้น ถูกต้องตามเวลาหมดอายุและเวลาที่ใช้ได้หากมี นอกจากนี้ นโยบายยังสามารถตรวจสอบค่าของการอ้างสิทธิ์ที่เฉพาะเจาะจงใน JWT ได้ด้วย เช่น เรื่อง ผู้ออก กลุ่มเป้าหมาย หรือค่าของการอ้างสิทธิ์เพิ่มเติม
หาก JWT ได้รับการยืนยันและถูกต้อง ระบบจะดึงข้อมูลการอ้างสิทธิ์ทั้งหมดที่อยู่ใน JWT ลงในตัวแปรบริบทเพื่อให้เป็นไปตามนโยบายหรือเงื่อนไขที่ตามมา และระบบจะอนุญาตให้คำขอ ดำเนินการต่อ หากยืนยันลายเซ็น JWT ไม่ได้หรือ JWT ไม่ถูกต้องเนื่องจาก การประทับเวลาใดเวลาหนึ่ง ระบบจะหยุดการประมวลผลทั้งหมดและแสดงข้อผิดพลาดในการตอบกลับ
หากต้องการดูข้อมูลเกี่ยวกับส่วนต่างๆ ของ JWT รวมถึงวิธีเข้ารหัสและลงนาม โปรดดู RFC7519
วิดีโอ
ดูวิดีโอสั้นๆ เพื่อดูวิธียืนยันลายเซ็นใน JWT
ตัวอย่าง
ยืนยัน JWT ที่ลงนามด้วยอัลกอริทึม HS256
นโยบายตัวอย่างนี้จะยืนยัน JWT ที่ลงนามด้วยอัลกอริทึมการเข้ารหัส HS256, HMAC
โดยใช้การตรวจสอบข้อผิดพลาด SHA-256 ระบบจะส่ง JWT ในคำขอพร็อกซีโดยใช้พารามิเตอร์แบบฟอร์มชื่อ
jwt คีย์อยู่ในตัวแปรที่ชื่อ private.secretkey
ดูตัวอย่างฉบับเต็มได้ในวิดีโอด้านบน ซึ่งรวมถึงวิธีส่งคำขอเกี่ยวกับนโยบาย
การกำหนดค่านโยบายประกอบด้วยข้อมูลที่ Edge ต้องใช้ในการถอดรหัสและประเมิน JWT เช่น ตำแหน่งที่จะค้นหา JWT (ในตัวแปรโฟลว์ที่ระบุในองค์ประกอบแหล่งที่มา) อัลกอริทึมการลงนามที่จำเป็น ตำแหน่งที่จะค้นหาคีย์ลับ (จัดเก็บไว้ในตัวแปรโฟลว์ของ Edge ซึ่งอาจ ดึงมาจาก KVM ของ Edge เป็นต้น) และชุดการอ้างสิทธิ์ที่จำเป็นและค่าของ การอ้างสิทธิ์เหล่านั้น
<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>นโยบายจะเขียนเอาต์พุตไปยังตัวแปรบริบทเพื่อให้เงื่อนไขหรือนโยบายที่ตามมา ในพร็อกซี API สามารถตรวจสอบค่าเหล่านั้นได้ ดูรายการตัวแปรที่นโยบายนี้ตั้งค่าได้ที่ตัวแปรโฟลว์
ยืนยัน JWT ที่ลงนามด้วยอัลกอริทึม RS256
นโยบายตัวอย่างนี้จะยืนยัน JWT ที่ลงนามด้วยอัลกอริทึม RS256 หากต้องการยืนยัน
คุณต้องระบุคีย์สาธารณะ ระบบจะส่ง JWT ในคำขอพร็อกซีโดยใช้พารามิเตอร์แบบฟอร์ม
ชื่อ jwt คีย์สาธารณะอยู่ในตัวแปรชื่อ public.publickey
ดูตัวอย่างฉบับเต็มได้ในวิดีโอด้านบน ซึ่งรวมถึงวิธีส่งคำขอเกี่ยวกับนโยบาย
ดูรายละเอียดเกี่ยวกับข้อกำหนดและตัวเลือกสำหรับแต่ละองค์ประกอบในนโยบายตัวอย่างนี้ได้ที่ข้อมูลอ้างอิงขององค์ประกอบ
<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>สำหรับการกำหนดค่าข้างต้น JWT ที่มีส่วนหัวนี้ …
{
"typ" : "JWT",
"alg" : "RS256"
}และเพย์โหลดนี้ …
{
"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."
}… จะถือว่าถูกต้อง หากยืนยันลายเซ็นด้วยคีย์สาธารณะที่ระบุได้
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."
}… จะถือว่าไม่ถูกต้อง แม้ว่าจะตรวจสอบลายเซ็นได้ก็ตาม เนื่องจากอ้างสิทธิ์ "sub" ที่รวมอยู่ใน JWT ไม่ตรงกับค่าที่จำเป็นขององค์ประกอบ "Subject" ตามที่ระบุไว้ในการกำหนดค่านโยบาย
นโยบายจะเขียนเอาต์พุตไปยังตัวแปรบริบทเพื่อให้เงื่อนไขหรือนโยบายที่ตามมา ในพร็อกซี API สามารถตรวจสอบค่าเหล่านั้นได้ ดูรายการตัวแปรที่นโยบายนี้ตั้งค่าได้ที่ตัวแปรโฟลว์
การตั้งค่าองค์ประกอบหลัก
องค์ประกอบที่คุณใช้เพื่อระบุคีย์ที่ใช้ในการยืนยัน JWT จะขึ้นอยู่กับอัลกอริทึมที่เลือก ดังที่แสดงในตารางต่อไปนี้
| อัลกอริทึม | องค์ประกอบสำคัญ | |
|---|---|---|
| HS* |
<SecretKey encoding="base16|hex|base64|base64url"> <Value ref="private.secretkey"/> </SecretKey> |
|
| RS*, ES*, PS* | <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> |
|
| *ดูข้อมูลเพิ่มเติมเกี่ยวกับข้อกำหนดของคีย์ได้ที่ เกี่ยวกับอัลกอริทึมการเข้ารหัสลายเซ็น | ||
การอ้างอิงองค์ประกอบ
การอ้างอิงนโยบายจะอธิบายองค์ประกอบและแอตทริบิวต์ของนโยบายการยืนยัน JWT
หมายเหตุ: การกำหนดค่าจะแตกต่างกันเล็กน้อยขึ้นอยู่กับอัลกอริทึมการเข้ารหัส ที่คุณใช้ ดูตัวอย่างที่แสดงการกำหนดค่าสำหรับ Use Case ที่เฉพาะเจาะจงได้ในตัวอย่าง
แอตทริบิวต์ที่ใช้กับองค์ประกอบระดับบนสุด
<VerifyJWT name="JWT" continueOnError="false" enabled="true" async="false">
แอตทริบิวต์ต่อไปนี้เป็นแอตทริบิวต์ทั่วไปขององค์ประกอบระดับบนของนโยบายทั้งหมด
| แอตทริบิวต์ | คำอธิบาย | ค่าเริ่มต้น | การตรวจหาบุคคลในบ้าน |
|---|---|---|---|
| name |
ชื่อภายในของนโยบาย อักขระที่คุณใช้ในชื่อได้จะจำกัดไว้เฉพาะอักขระต่อไปนี้
A-Z0-9._\-$ % อย่างไรก็ตาม UI การจัดการ Edge จะบังคับใช้ข้อจำกัดเพิ่มเติม เช่น การนำอักขระที่ไม่ใช่ตัวอักษรและตัวเลขออกโดยอัตโนมัติ
คุณอาจใช้องค์ประกอบ |
ไม่มี | ต้องระบุ |
| continueOnError |
ตั้งค่าเป็น false เพื่อแสดงข้อผิดพลาดเมื่อนโยบายไม่สำเร็จ ซึ่งเป็นลักษณะการทำงานที่คาดไว้
สำหรับนโยบายส่วนใหญ่
ตั้งค่าเป็น |
เท็จ | ไม่บังคับ |
| เปิดใช้อยู่ |
ตั้งค่าเป็น true เพื่อบังคับใช้นโยบาย
ตั้งค่าเป็น |
จริง | ไม่บังคับ |
| ไม่พร้อมกัน | เลิกใช้งานแอตทริบิวต์นี้แล้ว | เท็จ | เลิกใช้ |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
ใช้เพิ่มเติมจากแอตทริบิวต์ชื่อเพื่อติดป้ายกำกับนโยบายในโปรแกรมแก้ไขพร็อกซีของ UI การจัดการ ด้วยชื่อภาษาธรรมชาติที่แตกต่างกัน
| ค่าเริ่มต้น | หากคุณละเว้นองค์ประกอบนี้ ระบบจะใช้ค่าของแอตทริบิวต์ชื่อของนโยบาย |
| การตรวจหาบุคคลในบ้าน | ไม่บังคับ |
| ประเภท | สตริง |
<Algorithm>
<Algorithm>HS256</Algorithm>
ระบุอัลกอริทึมการเข้ารหัสเพื่อลงนามในโทเค็น อัลกอริทึม RS*/PS*/ES* ใช้คู่คีย์สาธารณะ/คีย์ลับ ในขณะที่อัลกอริทึม HS* ใช้ข้อมูลลับที่ใช้ร่วมกัน ดู เกี่ยวกับอัลกอริทึมการเข้ารหัสลายเซ็นด้วย
คุณระบุค่าหลายค่าได้โดยคั่นด้วยเครื่องหมายจุลภาค เช่น "HS256, HS512" หรือ "RS256, PS256" อย่างไรก็ตาม คุณไม่สามารถรวมอัลกอริทึม HS* กับอัลกอริทึมอื่นๆ หรืออัลกอริทึม ES* กับอัลกอริทึมอื่นๆ ได้เนื่องจากต้องใช้คีย์ประเภทที่เฉพาะเจาะจง คุณสามารถรวมอัลกอริทึม RS* และ PS* ได้
| ค่าเริ่มต้น | ไม่มี |
| การตรวจหาบุคคลในบ้าน | ต้องระบุ |
| ประเภท | สตริงของค่าที่คั่นด้วยคอมมา |
| ค่าที่ใช้ได้ | HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512 |
<Audience>
<Audience>audience-here</Audience> or: <Audience ref='variable-name-here'/>
นโยบายจะยืนยันว่าการอ้างสิทธิ์กลุ่มเป้าหมายใน JWT ตรงกับค่าที่ระบุในการกำหนดค่า หากไม่มีรายการที่ตรงกัน นโยบายจะแสดงข้อผิดพลาด การอ้างสิทธิ์นี้ระบุผู้รับที่ JWT มีไว้สำหรับ นี่คือการอ้างสิทธิ์ที่ลงทะเบียนรายการหนึ่งที่ระบุไว้ใน RFC7519
| ค่าเริ่มต้น | ไม่มี |
| การตรวจหาบุคคลในบ้าน | ไม่บังคับ |
| ประเภท | สตริง |
| ค่าที่ใช้ได้ | ตัวแปรโฟลว์หรือสตริงที่ระบุกลุ่มเป้าหมาย |
<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 มีการอ้างสิทธิ์เพิ่มเติมที่ระบุ และค่าการอ้างสิทธิ์ที่ยืนยันตรงกัน
การอ้างสิทธิ์เพิ่มเติมใช้ชื่อที่ไม่ใช่ชื่อการอ้างสิทธิ์ JWT มาตรฐานที่ลงทะเบียนไว้ ค่าของการอ้างสิทธิ์เพิ่มเติมอาจเป็นสตริง ตัวเลข บูลีน แมป หรืออาร์เรย์ แผนที่ เป็นเพียงชุดของคู่ชื่อ/ค่า คุณระบุค่าสำหรับการอ้างสิทธิ์ประเภทใดประเภทหนึ่งเหล่านี้ได้ อย่างชัดเจนในการกำหนดค่านโยบาย หรือโดยอ้อมผ่านการอ้างอิงถึงตัวแปรโฟลว์
| ค่าเริ่มต้น | ไม่มี |
| การตรวจหาบุคคลในบ้าน | ไม่บังคับ |
| ประเภท | สตริง ตัวเลข บูลีน หรือแผนที่ |
| อาร์เรย์ | ตั้งค่าเป็น true เพื่อระบุว่าค่าเป็นอาร์เรย์ของประเภทหรือไม่ ค่าเริ่มต้น: false |
| ค่าที่ใช้ได้ | ค่าใดก็ตามที่คุณต้องการใช้สำหรับการอ้างสิทธิ์เพิ่มเติม |
องค์ประกอบ <Claim> มีแอตทริบิวต์ต่อไปนี้
- name - (ต้องระบุ) ชื่อของการอ้างสิทธิ์
- ref - (ไม่บังคับ) ชื่อของตัวแปรโฟลว์ หากมี นโยบายจะใช้ค่าของตัวแปรนี้เป็นคำกล่าวอ้าง หากระบุทั้งแอตทริบิวต์ ref และค่าการอ้างสิทธิ์ที่ชัดเจน ค่าที่ชัดเจนจะเป็นค่าเริ่มต้น และจะใช้หากตัวแปรโฟลว์ที่อ้างอิงไม่ได้รับการแก้ไข
- type - (ไม่บังคับ) ค่าใดค่าหนึ่งต่อไปนี้ สตริง (ค่าเริ่มต้น) ตัวเลข บูลีน หรือแผนที่
- array - (ไม่บังคับ) ตั้งค่าเป็น true เพื่อระบุว่าค่าเป็นอาร์เรย์ของประเภทหรือไม่ ค่าเริ่มต้น: false
เมื่อคุณรวมองค์ประกอบ <Claim> ระบบจะตั้งชื่อการอ้างสิทธิ์แบบคงที่เมื่อคุณ
กำหนดค่านโยบาย หรือจะส่งออบเจ็กต์ JSON เพื่อระบุชื่อการอ้างสิทธิ์ก็ได้
เนื่องจากมีการส่งออบเจ็กต์ JSON เป็นตัวแปร ระบบจึงกำหนดชื่อการอ้างสิทธิ์ขณะรันไทม์
เช่น
<AdditionalClaims ref='json_claims'/>
โดยที่ตัวแปร json_claims มีออบเจ็กต์ JSON ในรูปแบบต่อไปนี้
{ "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 มีคู่ชื่อ/ค่าการอ้างสิทธิ์เพิ่มเติมที่ระบุ และค่าการอ้างสิทธิ์ที่ยืนยันตรงกัน
การอ้างสิทธิ์เพิ่มเติมใช้ชื่อที่ไม่ใช่ชื่อการอ้างสิทธิ์ JWT ที่ลงทะเบียนมาตรฐาน ค่าของการอ้างสิทธิ์เพิ่มเติมอาจเป็นสตริง ตัวเลข บูลีน แมป หรืออาร์เรย์ แผนที่ เป็นเพียงชุดของคู่ชื่อ/ค่า คุณระบุค่าสำหรับการอ้างสิทธิ์ประเภทใดประเภทหนึ่งเหล่านี้ได้ อย่างชัดเจนในการกำหนดค่านโยบาย หรือโดยอ้อมผ่านการอ้างอิงถึงตัวแปรโฟลว์
| ค่าเริ่มต้น | ไม่มี |
| การตรวจหาบุคคลในบ้าน | ไม่บังคับ |
| ประเภท |
สตริง (ค่าเริ่มต้น), ตัวเลข, บูลีน หรือแผนที่ ค่าเริ่มต้นของประเภทจะเป็นสตริง หากไม่ได้ระบุประเภท |
| อาร์เรย์ | ตั้งค่าเป็น true เพื่อระบุว่าค่าเป็นอาร์เรย์ของประเภทหรือไม่ ค่าเริ่มต้น: false |
| ค่าที่ใช้ได้ | ค่าใดก็ตามที่คุณต้องการใช้สำหรับการอ้างสิทธิ์เพิ่มเติม |
องค์ประกอบ <Claim> มีแอตทริบิวต์ต่อไปนี้
- name - (ต้องระบุ) ชื่อของการอ้างสิทธิ์
- ref - (ไม่บังคับ) ชื่อของตัวแปรโฟลว์ หากมี นโยบายจะใช้ค่าของตัวแปรนี้เป็นคำกล่าวอ้าง หากระบุทั้งแอตทริบิวต์ ref และค่าการอ้างสิทธิ์ที่ชัดเจน ค่าที่ชัดเจนจะเป็นค่าเริ่มต้น และจะใช้หากตัวแปรโฟลว์ที่อ้างอิงไม่ได้รับการแก้ไข
- type - (ไม่บังคับ) ค่าใดค่าหนึ่งต่อไปนี้ สตริง (ค่าเริ่มต้น) ตัวเลข บูลีน หรือแผนที่
- array - (ไม่บังคับ) ตั้งค่าเป็น true เพื่อระบุว่าค่าเป็นอาร์เรย์ของประเภทหรือไม่ ค่าเริ่มต้น: false
<CustomClaims>
หมายเหตุ: ปัจจุบันระบบจะแทรกองค์ประกอบ CustomClaims เมื่อคุณเพิ่มนโยบาย GenerateJWT ใหม่ผ่าน UI องค์ประกอบนี้ใช้งานไม่ได้และระบบจะละเว้น องค์ประกอบที่ถูกต้อง ซึ่งควรใช้แทนคือ <AdditionalClaims> เราจะอัปเดต UI เพื่อแทรกองค์ประกอบที่ถูกต้องในภายหลัง
<Id>
<Id>explicit-jti-value-here</Id> -or- <Id ref='variable-name-here'/> -or- <Id/>
ยืนยันว่า JWT มีการอ้างสิทธิ์ jti ที่เฉพาะเจาะจง เมื่อค่าข้อความและแอตทริบิวต์ ref ว่างเปล่าทั้งคู่ นโยบายจะสร้าง jti ที่มี UUID แบบสุ่ม การอ้างสิทธิ์รหัส JWT (jti) คือตัวระบุที่ไม่ซ้ำกันสำหรับ JWT ดูข้อมูลเพิ่มเติมเกี่ยวกับ jti ได้ที่ RFC7519
| ค่าเริ่มต้น | ไม่มี |
| การตรวจหาบุคคลในบ้าน | ไม่บังคับ |
| ประเภท | สตริงหรือการอ้างอิง |
| ค่าที่ใช้ได้ | สตริงหรือชื่อของตัวแปรโฟลว์ที่มีรหัส |
<IgnoreCriticalHeaders>
<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>
ตั้งค่าเป็น "เท็จ" หากต้องการให้นโยบายแสดงข้อผิดพลาดเมื่อส่วนหัวใดก็ตามที่แสดงในส่วนหัว
crit ของ JWT ไม่ได้แสดงในองค์ประกอบ <KnownHeaders>
ตั้งค่าเป็น "จริง" เพื่อให้นโยบาย VerifyJWT ไม่สนใจส่วนหัว crit
เหตุผลหนึ่งที่ควรตั้งค่าองค์ประกอบนี้เป็น "จริง" คือหากคุณอยู่ในสภาพแวดล้อมการทดสอบและยังไม่พร้อม ที่จะทำให้เกิดข้อผิดพลาดในส่วนหัวที่ขาดหายไป
| ค่าเริ่มต้น | เท็จ |
| การตรวจหาบุคคลในบ้าน | ไม่บังคับ |
| ประเภท | บูลีน |
| ค่าที่ใช้ได้ | จริงหรือเท็จ |
<IgnoreIssuedAt>
<IgnoreIssuedAt>true|false</IgnoreIssuedAt>
ตั้งค่าเป็น "เท็จ" (ค่าเริ่มต้น) หากต้องการให้นโยบายแสดงข้อผิดพลาดเมื่อ JWT มีการอ้างสิทธิ์
iat (ออกที่) ที่ระบุเวลาในอนาคต
ตั้งค่าเป็น "จริง" เพื่อให้นโยบายไม่สนใจ iat ระหว่างการยืนยัน
| ค่าเริ่มต้น | เท็จ |
| การตรวจหาบุคคลในบ้าน | ไม่บังคับ |
| ประเภท | บูลีน |
| ค่าที่ใช้ได้ | จริงหรือเท็จ |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
ตั้งค่าเป็น "เท็จ" หากต้องการให้นโยบายแสดงข้อผิดพลาดเมื่อตัวแปรที่อ้างอิงซึ่งระบุ ในนโยบายไม่สามารถแก้ไขได้ ตั้งค่าเป็น true เพื่อถือว่าตัวแปรที่แก้ไม่ได้เป็นสตริงว่าง (null)
| ค่าเริ่มต้น | เท็จ |
| การตรวจหาบุคคลในบ้าน | ไม่บังคับ |
| ประเภท | บูลีน |
| ค่าที่ใช้ได้ | จริงหรือเท็จ |
<ผู้ออกใบรับรอง>
<Issuer ref='variable-name-here'/> <Issuer>issuer-string-here</Issuer>
นโยบายจะยืนยันว่าผู้ออกใน JWT ตรงกับสตริงที่ระบุในองค์ประกอบการกำหนดค่า การอ้างสิทธิ์ที่ระบุผู้ออก JWT ซึ่งเป็นหนึ่งในชุดการอ้างสิทธิ์ที่ลงทะเบียนไว้ตามที่ระบุไว้ใน RFC7519
| ค่าเริ่มต้น | ไม่มี |
| การตรวจหาบุคคลในบ้าน | ไม่บังคับ |
| ประเภท | สตริงหรือการอ้างอิง |
| ค่าที่ใช้ได้ | ตามแต่ละประเทศ |
<KnownHeaders>
<KnownHeaders>a,b,c</KnownHeaders> or: <KnownHeaders ref=’variable_containing_headers’/>
นโยบาย GenerateJWT ใช้องค์ประกอบ <CriticalHeaders> เพื่อป้อนข้อมูลส่วนหัว crit ใน JWT เช่น
{
“typ: “...”,
“alg” : “...”,
“crit” : [ “a”, “b”, “c” ],
}นโยบาย VerifyJWT จะตรวจสอบส่วนหัว crit ใน JWT หากมี และสำหรับส่วนหัวแต่ละรายการที่ระบุไว้ นโยบายจะ
ตรวจสอบว่าองค์ประกอบ <KnownHeaders> ระบุส่วนหัวนั้นด้วย องค์ประกอบ
<KnownHeaders> อาจมีซูเปอร์เซ็ตของรายการที่ระบุไว้ใน crit
คุณเพียงแค่ต้องตรวจสอบว่าส่วนหัวทั้งหมดที่ระบุไว้ใน crit แสดงอยู่ในองค์ประกอบ
<KnownHeaders> ส่วนหัวใดๆ ที่นโยบายพบใน crit
ซึ่งไม่ได้อยู่ใน <KnownHeaders> จะทําให้นโยบาย VerifyJWT ไม่สําเร็จ
คุณเลือกกำหนดค่านโยบาย VerifyJWT ให้ไม่สนใจส่วนหัว crit ได้โดย
ตั้งค่าองค์ประกอบ <IgnoreCriticalHeaders> เป็น true
| ค่าเริ่มต้น | ไม่มี |
| การตรวจหาบุคคลในบ้าน | ไม่บังคับ |
| ประเภท | อาร์เรย์สตริงที่คั่นด้วยคอมมา |
| ค่าที่ใช้ได้ | อาร์เรย์หรือชื่อของตัวแปรที่มีอาร์เรย์ |
<PublicKey/Certificate>
<PublicKey> <Certificate ref="signed_public.cert"/> </PublicKey> -or- <PublicKey> <Certificate> -----BEGIN CERTIFICATE----- cert data -----END CERTIFICATE----- </Certificate> </PublicKey>
ระบุใบรับรองที่ลงชื่อซึ่งใช้เพื่อยืนยันลายเซ็นใน JWT ใช้แอตทริบิวต์ ref เพื่อ ส่งใบรับรองที่ลงชื่อแล้วในตัวแปรโฟลว์ หรือระบุใบรับรองที่เข้ารหัสด้วย PEM โดยตรง ใช้เฉพาะเมื่ออัลกอริทึมเป็น RS256/RS384/RS512, PS256/PS384/PS512 หรือ ES256/ES384/ES512 เท่านั้น
| ค่าเริ่มต้น | ไม่มี |
| การตรวจหาบุคคลในบ้าน | หากต้องการยืนยัน JWT ที่ลงนามด้วยอัลกอริทึม RSA คุณต้องใช้องค์ประกอบใบรับรอง, JWKS หรือค่า |
| ประเภท | สตริง |
| ค่าที่ใช้ได้ | ตัวแปรโฟลว์หรือสตริง |
<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>
ระบุค่าในรูปแบบ JWKS (RFC 7517) ซึ่งมีชุดคีย์สาธารณะ ใช้เฉพาะเมื่ออัลกอริทึมเป็น RS256/RS384/RS512, PS256/PS384/PS512 หรือ ES256/ES384/ES512
หาก JWT ขาเข้ามีรหัสคีย์ที่อยู่ในชุด JWKS นโยบายจะใช้คีย์สาธารณะที่ถูกต้องเพื่อยืนยันลายเซ็น JWT ดูรายละเอียด เกี่ยวกับฟีเจอร์นี้ได้ที่ การใช้ชุดคีย์เว็บ JSON (JWKS) เพื่อยืนยัน JWT
หากคุณดึงค่าจาก URL สาธารณะ Edge จะแคช JWKS เป็นระยะเวลา 300 วินาที เมื่อแคชหมดอายุ Edge จะดึงข้อมูล JWKS อีกครั้ง
| ค่าเริ่มต้น | ไม่มี |
| การตรวจหาบุคคลในบ้าน | หากต้องการยืนยัน JWT โดยใช้อัลกอริทึม RSA คุณต้องใช้ใบรับรอง, JWKS หรือองค์ประกอบค่า |
| ประเภท | สตริง |
| ค่าที่ใช้ได้ | ตัวแปรโฟลว์ ค่าสตริง หรือ URL |
<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 ใช้แอตทริบิวต์ ref เพื่อ ส่งคีย์/ใบรับรองในตัวแปรโฟลว์ หรือระบุคีย์ที่เข้ารหัส PEM โดยตรง ใช้เฉพาะเมื่ออัลกอริทึมเป็น RS256/RS384/RS512, PS256/PS384/PS512 หรือ ES256/ES384/ES512 เท่านั้น
| ค่าเริ่มต้น | ไม่มี |
| การตรวจหาบุคคลในบ้าน | หากต้องการยืนยัน JWT ที่ลงนามด้วยอัลกอริทึม RSA คุณต้องใช้องค์ประกอบใบรับรอง, JWKS หรือค่า |
| ประเภท | สตริง |
| ค่าที่ใช้ได้ | ตัวแปรโฟลว์หรือสตริง |
<SecretKey/Value>
<SecretKey encoding="base16|hex|base64|base64url"> <Value ref="private.your-variable-name"/> </SecretKey>
ระบุคีย์ลับที่ใช้เพื่อยืนยันหรือลงนามโทเค็นด้วยอัลกอริทึม HMAC ใช้เฉพาะ เมื่ออัลกอริทึมเป็น HS256, HS384 หรือ HS512
| ค่าเริ่มต้น | ไม่มี |
| การตรวจหาบุคคลในบ้าน | ต้องระบุสำหรับอัลกอริทึม HMAC |
| ประเภท | สตริง |
| ค่าที่ใช้ได้ |
สำหรับ ใช้แอตทริบิวต์ ref เพื่อส่งคีย์ในตัวแปรโฟลว์ หมายเหตุ: หากเป็นตัวแปรโฟลว์ จะต้องมีคำนำหน้า "private" เช่น
|
<Source>
<Source>jwt-variable</Source>
หากมี จะระบุตัวแปรโฟลว์ที่นโยบายคาดว่าจะพบ JWT เพื่อ ยืนยัน
| ค่าเริ่มต้น | request.header.authorization (ดูข้อมูลสำคัญเกี่ยวกับค่าเริ่มต้นได้ที่หมายเหตุข้างต้น
) |
| การตรวจหาบุคคลในบ้าน | ไม่บังคับ |
| ประเภท | สตริง |
| ค่าที่ใช้ได้ | ชื่อตัวแปรโฟลว์ Edge |
<Subject>
<Subject>subject-string-here</Subject>
นโยบายจะยืนยันว่าเรื่องใน JWT ตรงกับสตริงที่ระบุในการกำหนดค่านโยบาย การอ้างสิทธิ์นี้จะระบุหรือแถลงเกี่ยวกับเรื่องของ JWT ซึ่งเป็น หนึ่งในชุดการอ้างสิทธิ์มาตรฐานที่กล่าวถึงใน RFC7519
| ค่าเริ่มต้น | ไม่มี |
| การตรวจหาบุคคลในบ้าน | ไม่บังคับ |
| ประเภท | สตริง |
| ค่าที่ใช้ได้ | ค่าที่ระบุเรื่องหนึ่งๆ โดยไม่ซ้ำกัน |
<TimeAllowance>
<TimeAllowance>120s</TimeAllowance>
"ระยะเวลาผ่อนผัน" สำหรับเวลา เช่น หากกำหนดค่าระยะเวลาที่อนุญาตเป็น 60 วินาที ระบบจะถือว่า JWT ที่หมดอายุแล้วยังคงใช้งานได้เป็นเวลา 60 วินาทีหลังจากที่อ้างว่าหมดอายุ ระบบจะประเมิน not-before-time ในลักษณะเดียวกัน ค่าเริ่มต้นคือ 0 วินาที (ไม่มีระยะเวลาผ่อนผัน)
| ค่าเริ่มต้น | 0 วินาที (ไม่มีระยะเวลาผ่อนผัน) |
| การตรวจหาบุคคลในบ้าน | ไม่บังคับ |
| ประเภท | สตริง |
| ค่าที่ใช้ได้ |
ค่าหรือการอ้างอิงไปยังตัวแปรโฟลว์ที่มีค่า ช่วงเวลาสามารถ
ระบุได้ดังนี้
|
ตัวแปรโฟลว์
เมื่อสำเร็จ นโยบาย Verify JWT และ Decode JWT ที่ตั้งไว้ ตัวแปรบริบทตามรูปแบบนี้:
jwt.{policy_name}.{variable_name}
ตัวอย่างเช่น หากชื่อนโยบายคือ jwt-parse-token ระบบจะจัดเก็บนโยบายนี้ไว้
เรื่องที่ระบุใน JWT ไปยังตัวแปรบริบทชื่อ jwt.jwt-parse-token.decoded.claim.sub
(สำหรับความเข้ากันได้แบบย้อนหลัง จะพร้อมใช้งานใน jwt.jwt-parse-token.claim.subject ด้วย)
| ชื่อตัวแปร | คำอธิบาย |
|---|---|
claim.audience |
การอ้างสิทธิ์กลุ่มเป้าหมายของ JWT ค่านี้อาจเป็นสตริง หรืออาร์เรย์ของสตริง |
claim.expiry |
วันที่/เวลาหมดอายุ แสดงเป็นมิลลิวินาทีตั้งแต่ Epoch |
claim.issuedat |
วันที่ที่ออกโทเค็น ซึ่งแสดงเป็นมิลลิวินาทีตั้งแต่ Epoch |
claim.issuer |
คำกล่าวอ้างของผู้ออกบัตร JWT |
claim.notbefore |
หาก JWT มีการอ้างสิทธิ์ nbf ตัวแปรนี้จะมีค่า แสดงเป็นมิลลิวินาทีตั้งแต่ Epoch |
claim.subject |
คำกล่าวอ้างของ JWT |
claim.name |
ค่าของการอ้างสิทธิ์ที่มีชื่อ (มาตรฐานหรือเพิ่มเติม) ในเพย์โหลด หนึ่งในรายการเหล่านี้จะถูกตั้งค่าไว้สำหรับ การอ้างสิทธิ์ทั้งหมดในเพย์โหลด |
decoded.claim.name |
ค่าที่แยกวิเคราะห์ได้ JSON ของการอ้างสิทธิ์ที่มีชื่อ (มาตรฐานหรือเพิ่มเติม) ในเพย์โหลด มีการตั้งค่า 1 ตัวแปรสำหรับ
การอ้างสิทธิ์ทั้งหมดในเพย์โหลด เช่น คุณสามารถใช้ decoded.claim.iat เพื่อ
ดึงเวลาที่ออกของ JWT ซึ่งแสดงเป็นวินาทีนับตั้งแต่ Epoch ขณะที่คุณ
ก็สามารถใช้ตัวแปรโฟลว์ claim.name ได้เช่นกัน ซึ่งก็คือ
ตัวแปรที่แนะนำให้ใช้ในการเข้าถึงการอ้างสิทธิ์ |
decoded.header.name |
ค่าที่แยกวิเคราะห์ได้ JSON ของส่วนหัวในเพย์โหลด มีการตั้งค่า 1 ตัวแปรสำหรับ
ทุกส่วนหัวในเพย์โหลด แม้ว่าคุณจะใช้ตัวแปรโฟลว์ header.name ได้เช่นกัน
นี่คือตัวแปรที่แนะนำเพื่อใช้ในการเข้าถึงส่วนหัว |
expiry_formatted |
วันที่/เวลาหมดอายุ ซึ่งจะอยู่ในรูปแบบสตริงที่มนุษย์อ่านได้ ตัวอย่าง 2017-09-28T21:30:45.000+0000 |
header.algorithm |
อัลกอริทึมการเซ็นชื่อที่ใช้บน JWT เช่น RS256, HS384 และอื่นๆ ดูข้อมูลเพิ่มเติมในพารามิเตอร์ส่วนหัว(อัลกอริทึม) |
header.kid |
รหัสคีย์หากมีการเพิ่มไว้เมื่อสร้าง JWT โปรดดูเพิ่มเติม "การใช้ชุดคีย์เว็บ JSON (JWKS)" ที่ JWT ภาพรวมนโยบายเพื่อยืนยัน JWT ดูข้อมูลเพิ่มเติมที่พารามิเตอร์ส่วนหัวของ(รหัสคีย์) |
header.type |
จะตั้งค่าเป็น JWT |
header.name |
ค่าของส่วนหัวที่มีชื่อ (มาตรฐานหรือเพิ่มเติม) หนึ่งในรายการเหล่านี้จะถูกตั้งค่าไว้สำหรับ ส่วนหัวเพิ่มเติมทั้งหมดในส่วนหัวของ JWT |
header-json |
ส่วนหัวในรูปแบบ JSON |
is_expired |
จริงหรือเท็จ |
payload-claim-names |
อาร์เรย์ของการอ้างสิทธิ์ที่ JWT สนับสนุน |
payload-json |
เพย์โหลดในรูปแบบ JSON
|
seconds_remaining |
จำนวนวินาทีก่อนที่โทเค็นจะหมดอายุ หากโทเค็นหมดอายุ จำนวนจะเป็นลบ |
time_remaining_formatted |
เวลาที่เหลือก่อนที่โทเค็นจะหมดอายุ โดยมีรูปแบบเป็นสตริงที่มนุษย์อ่านได้ ตัวอย่าง: 00:59:59.926 |
valid |
ในกรณีของ VerifyJWT ตัวแปรนี้จะเป็นจริงเมื่อยืนยันลายเซ็นแล้ว และ
เวลาปัจจุบันคือก่อนที่โทเค็นจะหมดอายุ และหลังจากค่า notbefore ของโทเค็น หาก
อยู่ หากไม่เลือก จะเป็นเท็จ
ในกรณีของ DecodeJWT จะไม่มีการตั้งค่าตัวแปรนี้ |
ข้อมูลอ้างอิงข้อผิดพลาด
This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.
Runtime errors
These errors can occur when the policy executes.
| Fault code | HTTP status | Occurs when |
|---|---|---|
steps.jwt.AlgorithmInTokenNotPresentInConfiguration |
401 | Occurs when the verification policy has multiple algorithms. |
steps.jwt.AlgorithmMismatch |
401 | The algorithm specified in the Generate policy did not match the one expected in the Verify policy. The algorithms specified must match. |
steps.jwt.FailedToDecode |
401 | The policy was unable to decode the JWT. The JWT is possibly corrupted. |
steps.jwt.GenerationFailed |
401 | The policy was unable to generate the JWT. |
steps.jwt.InsufficientKeyLength |
401 | For a key less than 32 bytes for the HS256 algorithm, less than 48 bytes for the HS386 algortithm, and less than 64 bytes for the HS512 algorithm. |
steps.jwt.InvalidClaim |
401 | For a missing claim or claim mismatch, or a missing header or header mismatch. |
steps.jwt.InvalidCurve |
401 | The curve specified by the key is not valid for the Elliptic Curve algorithm. |
steps.jwt.InvalidJsonFormat |
401 | Invalid JSON found in the header or payload. |
steps.jwt.InvalidToken |
401 | This error occurs when the JWT signature verification fails. |
steps.jwt.JwtAudienceMismatch |
401 | The audience claim failed on token verification. |
steps.jwt.JwtIssuerMismatch |
401 | The issuer claim failed on token verification. |
steps.jwt.JwtSubjectMismatch |
401 | The subject claim failed on token verification. |
steps.jwt.KeyIdMissing |
401 | The Verify policy uses a JWKS as a source for public keys, but the signed JWT does not
include a kid property in the header. |
steps.jwt.KeyParsingFailed |
401 | The public key could not be parsed from the given key information. |
steps.jwt.NoAlgorithmFoundInHeader |
401 | Occurs when the JWT contains no algorithm header. |
steps.jwt.NoMatchingPublicKey |
401 | The Verify policy uses a JWKS as a source for public keys, but the kid
in the signed JWT is not listed in the JWKS. |
steps.jwt.SigningFailed |
401 | In GenerateJWT, for a key less than the minimum size for the HS384 or HS512 algorithms |
steps.jwt.TokenExpired |
401 | The policy attempts to verify an expired token. |
steps.jwt.TokenNotYetValid |
401 | The token is not yet valid. |
steps.jwt.UnhandledCriticalHeader |
401 | A header found by the Verify JWT policy in the crit header is not
listed in KnownHeaders. |
steps.jwt.UnknownException |
401 | An unknown exception occurred. |
steps.jwt.WrongKeyType |
401 | Wrong type of key specified. For example, if you specify an RSA key for an Elliptic Curve algorithm, or a curve key for an RSA algorithm. |
Deployment errors
These errors can occur when you deploy a proxy containing this policy.
| Error name | Cause | Fix |
|---|---|---|
InvalidNameForAdditionalClaim |
The deployment will fail if the claim used in the child element <Claim>
of the <AdditionalClaims> element is one of the following registered names:
kid, iss, sub, aud, iat,
exp, nbf, or jti.
|
build |
InvalidTypeForAdditionalClaim |
If the claim used in the child element <Claim>
of the <AdditionalClaims> element is not of type string, number,
boolean, or map, the deployment will fail.
|
build |
MissingNameForAdditionalClaim |
If the name of the claim is not specified in the child element <Claim>
of the <AdditionalClaims> element, the deployment will fail.
|
build |
InvalidNameForAdditionalHeader |
This error ccurs when the name of the claim used in the child element <Claim>
of the <AdditionalClaims> element is either alg or typ.
|
build |
InvalidTypeForAdditionalHeader |
If the type of claim used in the child element <Claim>
of the <AdditionalClaims> element is not of type string, number,
boolean, or map, the deployment will fail.
|
build |
InvalidValueOfArrayAttribute |
This error occurs when the value of the array attribute in the child element <Claim>
of the <AdditionalClaims> element is not set to true or false.
|
build |
InvalidValueForElement |
If the value specified in the <Algorithm> element is not a supported value,
the deployment will fail.
|
build |
MissingConfigurationElement |
This error will occur if the <PrivateKey> element is not used with
RSA family algorithms or the <SecretKey> element is not used with HS Family
algorithms.
|
build |
InvalidKeyConfiguration |
If the child element <Value> is not defined in the <PrivateKey>
or <SecretKey> elements, the deployment will fail.
|
build |
EmptyElementForKeyConfiguration |
If the ref attribute of the child element <Value> of the <PrivateKey>
or <SecretKey> elements is empty or unspecified, the deployment will fail.
|
build |
InvalidConfigurationForVerify |
This error occurs if the <Id> element is defined within the
<SecretKey> element.
|
build |
InvalidEmptyElement |
This error occurs if the <Source> element of the Verify JWT policy
is empty. If present, it must be defined with an Edge flow variable name.
|
build |
InvalidPublicKeyValue |
If the value used in the child element <JWKS> of the <PublicKey> element
does not use a valid format as specified in RFC 7517,
the deployment will fail.
|
build |
InvalidConfigurationForActionAndAlgorithm |
If the <PrivateKey> element is used with HS Family algorithms or
the <SecretKey> element is used with RSA Family algorithms, the
deployment will fail.
|
build |
Fault variables
These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.
| Variables | Where | Example |
|---|---|---|
fault.name="fault_name" |
fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. | fault.name Matches "TokenExpired" |
JWT.failed |
All JWT policies set the same variable in the case of a failure. | JWT.failed = true |
Example error response
For error handling, the best practice is to trap the errorcode part of the error
response. Do not rely on the text in the faultstring, because it could change.
Example fault rule
<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>