ถอดรหัสนโยบาย JWT

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

อะไร

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

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

วิดีโอ

ชมวิดีโอสั้นๆ เพื่อเรียนรู้วิธีการถอดรหัส JWT

ตัวอย่าง: ถอดรหัส JWT

นโยบายที่แสดงด้านล่างได้ถอดรหัส JWT ที่พบในตัวแปรโฟลว์ var.jwt ตัวแปรนี้ต้องมีอยู่และมี JWT ที่ใช้งานได้ (ถอดรหัสได้) นโยบายนี้สามารถรับ JWT จากตัวแปรโฟลว์ใดก็ได้

<DecodeJWT name="JWT-Decode-HS256">
    <DisplayName>JWT Verify HS256</DisplayName>
    <Source>var.jwt</Source>
</DecodeJWT>

นโยบายจะเขียนเอาต์พุตไปยังตัวแปรบริบทเพื่อให้นโยบายหรือเงื่อนไขต่อๆ ไปในพร็อกซี API ตรวจสอบค่าเหล่านั้นได้ ดูรายการตัวแปรที่กำหนดโดยนโยบายนี้ได้ที่ตัวแปรโฟลว์

การอ้างอิงองค์ประกอบสำหรับการถอดรหัส JWT

ข้อมูลอ้างอิงนโยบายจะอธิบายองค์ประกอบและแอตทริบิวต์ของนโยบายการถอดรหัส JWT

แอตทริบิวต์ที่ใช้กับองค์ประกอบระดับบนสุด

<DecodeJWT name="JWT" continueOnError="false" enabled="true" async="false">

แอตทริบิวต์ต่อไปนี้มีอยู่ในองค์ประกอบระดับบนสุดของนโยบายทั้งหมด

แอตทริบิวต์ คำอธิบาย ค่าเริ่มต้น การปรากฏ
ชื่อ ชื่อภายในของนโยบาย จำกัดอักขระที่ใช้ในชื่อได้ดังต่อไปนี้ A-Z0-9._\-$ % แต่ UI การจัดการ Edge จะบังคับใช้ข้อจํากัดเพิ่มเติม เช่น นําอักขระที่ไม่ใช่ตัวอักษรและตัวเลขคละกันออกโดยอัตโนมัติ

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

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

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

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

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

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

ค่าเริ่มต้น หากคุณไม่ใส่องค์ประกอบนี้ ระบบจะใช้ค่าของแอตทริบิวต์ชื่อของนโยบาย
การปรากฏ ไม่บังคับ
ประเภท สตริง

<ที่มา>

<Source>jwt-variable</Source>

หากมี ให้ระบุตัวแปรโฟลว์ที่นโยบายคาดว่าจะค้นหา JWT เพื่อถอดรหัส

ค่าเริ่มต้น request.header.authorization (ดูข้อมูลสำคัญเกี่ยวกับค่าเริ่มต้นในหมายเหตุด้านบน)
การปรากฏ ไม่บังคับ
ประเภท สตริง
ค่าที่ถูกต้อง ชื่อตัวแปรโฟลว์ Edge

ตัวแปรโฟลว์

เมื่อสำเร็จ นโยบาย ยืนยัน JWT และ ถอดรหัส 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 ค่าของการอ้างสิทธิ์ที่มีชื่อ (มาตรฐานหรือเพิ่มเติม) ในเพย์โหลด โดยจะตั้งค่า 1 รายการสำหรับการอ้างสิทธิ์ทุกรายการในเพย์โหลด
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 ในกรณีของ ConfirmJWT ตัวแปรนี้จะเป็นจริงเมื่อลายเซ็นได้รับการยืนยัน และเวลาปัจจุบันคือก่อนที่โทเค็นจะหมดอายุ และหลังจากค่า notBefore ของโทเค็น หากมี มิฉะนั้น จะเป็นเท็จ

ในกรณีของ DecodeJWT ตัวแปรนี้จะไม่ตั้งค่าไว้

การอ้างอิงข้อผิดพลาด

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

ข้อผิดพลาดเกี่ยวกับรันไทม์

ข้อผิดพลาดเหล่านี้อาจเกิดขึ้นเมื่อนโยบายทำงาน

รหัสข้อผิดพลาด สถานะ HTTP สาเหตุ แก้ไข
steps.jwt.FailedToDecode 401 เกิดขึ้นเมื่อนโยบายถอดรหัส JWT ไม่ได้ JWT อาจมีรูปแบบไม่ถูกต้อง ไม่ถูกต้อง หรือถอดรหัสไม่ได้
steps.jwt.FailedToResolveVariable 401 เกิดขึ้นเมื่อไม่มีตัวแปรโฟลว์ที่ระบุในองค์ประกอบ <Source> ของนโยบายอยู่
steps.jwt.InvalidToken 401 เกิดขึ้นเมื่อตัวแปรโฟลว์ที่ระบุในองค์ประกอบ <Source> ของนโยบายอยู่นอกขอบเขตหรือแก้ไขไม่ได้

ข้อผิดพลาดในการทำให้ใช้งานได้

ข้อผิดพลาดเหล่านี้อาจเกิดขึ้นเมื่อคุณใช้พร็อกซีที่มีนโยบายนี้

ชื่อข้อผิดพลาด สาเหตุ แก้ไข
InvalidEmptyElement เกิดขึ้นเมื่อไม่ได้ระบุตัวแปรโฟลว์ที่มี JWT ที่จะถอดรหัสในองค์ประกอบ <Source> ของนโยบาย

ตัวแปรของข้อผิดพลาด

ระบบจะตั้งค่าตัวแปรเหล่านี้เมื่อเกิดข้อผิดพลาดรันไทม์ ดูข้อมูลเพิ่มเติมได้ที่สิ่งที่คุณต้องทราบเกี่ยวกับข้อผิดพลาดของนโยบาย

ตัวแปร สถานที่ ตัวอย่าง
fault.name="fault_name" fault_name คือชื่อของข้อผิดพลาดตามที่แสดงในตารางข้อผิดพลาดรันไทม์ด้านบน ชื่อข้อผิดพลาดคือส่วนสุดท้ายของโค้ดข้อผิดพลาด fault.name Matches "TokenExpired"
JWT.failed นโยบาย JWT ทั้งหมดจะกำหนดตัวแปรเดียวกันในกรณีที่เกิดข้อผิดพลาด JWT.failed = true

ตัวอย่างการตอบกลับข้อผิดพลาด

รหัสข้อผิดพลาดของนโยบาย JWT

สำหรับการจัดการข้อผิดพลาด แนวทางปฏิบัติแนะนำคือดักส่วน errorcode ของการตอบสนองข้อผิดพลาด อย่าใช้ข้อความใน faultstring เนื่องจากอาจมีการเปลี่ยนแปลง

ตัวอย่างกฎข้อผิดพลาด

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