นโยบายVerifyJWT

คุณกำลังดูเอกสารประกอบของ 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 จะบังคับใช้ข้อจำกัดเพิ่มเติม เช่น การนำอักขระที่ไม่ใช่ตัวอักษรและตัวเลขออกโดยอัตโนมัติ

คุณอาจใช้องค์ประกอบ <displayname></displayname> เพื่อ ติดป้ายกำกับนโยบายในเครื่องมือแก้ไขพร็อกซีของ UI การจัดการด้วยชื่อ ภาษาธรรมชาติที่แตกต่างกันก็ได้

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

ตั้งค่าเป็น true เพื่อให้การดำเนินการโฟลว์ดำเนินต่อไปแม้หลังจากที่นโยบาย ล้มเหลว

เท็จ ไม่บังคับ
เปิดใช้อยู่ ตั้งค่าเป็น true เพื่อบังคับใช้นโยบาย

ตั้งค่าเป็น false เพื่อ "ปิด" นโยบาย ระบบจะไม่บังคับใช้นโยบาย แม้ว่าจะยังแนบอยู่กับโฟลว์ก็ตาม

จริง ไม่บังคับ
ไม่พร้อมกัน เลิกใช้งานแอตทริบิวต์นี้แล้ว เท็จ เลิกใช้

<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
ประเภท สตริง
ค่าที่ใช้ได้

สำหรับ encoding ค่าที่ใช้ได้คือ hex, base16, base64 หรือ base64url ค่าการเข้ารหัส hex และ base16 เป็นคำพ้องความหมาย

ใช้แอตทริบิวต์ ref เพื่อส่งคีย์ในตัวแปรโฟลว์

หมายเหตุ: หากเป็นตัวแปรโฟลว์ จะต้องมีคำนำหน้า "private" เช่น private.mysecret

<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 วินาที (ไม่มีระยะเวลาผ่อนผัน)
การตรวจหาบุคคลในบ้าน ไม่บังคับ
ประเภท สตริง
ค่าที่ใช้ได้ ค่าหรือการอ้างอิงไปยังตัวแปรโฟลว์ที่มีค่า ช่วงเวลาสามารถ ระบุได้ดังนี้
  • s = วินาที
  • m = นาที
  • h = ชั่วโมง
  • d = วัน

ตัวแปรโฟลว์

เมื่อสำเร็จ นโยบาย 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.
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.
MissingNameForAdditionalClaim If the name of the claim is not specified in the child element <Claim> of the <AdditionalClaims> element, the deployment will fail.
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.
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.
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.
InvalidValueForElement If the value specified in the <Algorithm> element is not a supported value, the deployment will fail.
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.
InvalidKeyConfiguration If the child element <Value> is not defined in the <PrivateKey> or <SecretKey> elements, the deployment will fail.
EmptyElementForKeyConfiguration If the ref attribute of the child element <Value> of the <PrivateKey> or <SecretKey> elements is empty or unspecified, the deployment will fail.
InvalidConfigurationForVerify This error occurs if the <Id> element is defined within the <SecretKey> element.
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.
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.
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.

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

JWT Policy Fault Codes

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>