นโยบายVerifyJWS

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

อะไร

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

หาก JWS ได้รับการยืนยันความถูกต้องแล้ว คำขอจะเป็น ได้รับอนุญาตให้ดำเนินการต่อ หากไม่สามารถยืนยันลายเซ็น JWS หรือ JWS ไม่ถูกต้องเนื่องจาก ข้อผิดพลาดบางประเภท การประมวลผลทั้งหมดจะหยุดลง และระบบจะแสดงข้อผิดพลาดในการตอบกลับ

หากต้องการเรียนรู้เกี่ยวกับส่วนต่างๆ ของ JWS รวมถึงวิธีเข้ารหัสและเซ็นชื่อ โปรดดูที่ RFC7515

วิดีโอ

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

ลองฟัง

• ยืนยัน JWS ที่แนบมาซึ่งลงนามด้วย HS256 อัลกอริทึม
• ยืนยัน JWS ที่ปลดออกซึ่งลงนามด้วย RS256 อัลกอริทึม

ยืนยัน JWS ที่แนบมาซึ่งลงนามด้วย HS256 อัลกอริทึม

นโยบายตัวอย่างนี้ยืนยัน JWS ที่แนบมาซึ่งลงนามด้วยอัลกอริทึมการเข้ารหัส HS256 ซึ่งก็คือ HMAC โดยใช้ผลรวมตรวจสอบ SHA-256 JWS จะส่งผ่านในคำขอพร็อกซีโดยใช้พารามิเตอร์ฟอร์มที่ชื่อ JWS คีย์อยู่ในตัวแปรที่ชื่อ private.secretkey

JWS ที่แนบมีส่วนหัวที่เข้ารหัส เพย์โหลด และลายเซ็น ดังนี้

header.payload.signature

การกำหนดค่านโยบายจะมีข้อมูลที่ Edge ต้องใช้ในการถอดรหัสและประเมิน JWS เช่น ตำแหน่งที่จะหา JWS (ในตัวแปรโฟลว์ที่ระบุในองค์ประกอบ <Source>) อัลกอริทึมการลงนามที่จำเป็น และตำแหน่งของคีย์ลับ (จัดเก็บไว้ในตัวแปรโฟลว์ Edge ซึ่งอาจ ได้มาจาก Edge KVM เป็นต้น)

<VerifyJWS name="JWS-Verify-HS256">
    <DisplayName>JWS Verify HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <Source>request.formparam.JWS</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
    </SecretKey>
</VerifyJWS>

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

ตรวจสอบ JWS แบบถอดออกที่ลงนามด้วย RS256 อัลกอริทึม

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

JWS ที่ปลดออกจะยกเว้นเพย์โหลดจาก JWS:

header..signature

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

<VerifyJWS name="JWS-Verify-RS256">
    <DisplayName>JWS Verify RS256</DisplayName>
    <Algorithm>RS256</Algorithm>
    <Source>request.formparam.JWS</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <Value ref="public.publickey"/>
    </PublicKey>
    <DetachedContent>private.payload</DetachedContent>
</VerifyJWS>

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

การกำหนดองค์ประกอบหลัก

องค์ประกอบที่ใช้ระบุคีย์ที่ใช้ยืนยัน JWS จะขึ้นอยู่กับอัลกอริทึมที่เลือก ดังที่แสดงในตารางต่อไปนี้

<SecretKey>
  <Value ref="private.secretkey"/>
</SecretKey>

<PublicKey>
  <Value ref="rsa_public_key"/>
</PublicKey>

<PublicKey>
  <JWKS ref="jwks_val_ref_or_url"/>
</PublicKey>

การอ้างอิงองค์ประกอบ

การอ้างอิงนโยบายอธิบายองค์ประกอบและแอตทริบิวต์ของนโยบาย Verify JWS

หมายเหตุ: การกำหนดค่าจะแตกต่างกันไปขึ้นอยู่กับการเข้ารหัส อัลกอริทึมที่คุณใช้ ดูตัวอย่างสำหรับตัวอย่างที่แสดง สำหรับ Use Case เฉพาะ

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

<VerifyJWS name="JWS" continueOnError="false" enabled="true" async="false">

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

<Algorithm>

<Algorithm>HS256</Algorithm>

ระบุอัลกอริทึมการเข้ารหัสเพื่อลงนามโทเค็น อัลกอริทึม RS*/PS*/ES* ใช้คู่คีย์สาธารณะ/ลับ ขณะที่อัลกอริทึม HS* ใช้ข้อมูลลับที่ใช้ร่วมกัน ดูเพิ่มเติมที่ เกี่ยวกับอัลกอริทึมการเข้ารหัสลายเซ็น

คุณระบุค่าได้หลายค่าโดยคั่นด้วยเครื่องหมายจุลภาค เช่น "HS256, HS512" หรือ "RS256, PS256" อย่างไรก็ตาม คุณไม่สามารถรวมอัลกอริทึม HS* กับอัลกอริทึมอื่นๆ หรือ ES* กับอัลกอริทึมอื่นๆ ได้ เนื่องจาก ต้องระบุประเภทคีย์ที่เฉพาะเจาะจง คุณรวมอัลกอริทึม RS* และ PS* ได้

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

ตรวจสอบว่าส่วนหัว JWS มีคู่ของชื่อ/ค่าการอ้างสิทธิ์เพิ่มเติมที่ระบุ และค่าการอ้างสิทธิ์ที่ยืนยันนั้นตรงกัน

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

องค์ประกอบ <Claim> ใช้แอตทริบิวต์ต่อไปนี้

• name - (ต้องระบุ) ชื่อของการอ้างสิทธิ์
• ref - (ไม่บังคับ) ชื่อของตัวแปรโฟลว์ หากมี นโยบายจะใช้ค่าของค่านี้ เป็นการอ้างสิทธิ์ ถ้ามีการระบุทั้งแอตทริบิวต์ ref และค่าการอ้างสิทธิ์ที่ชัดเจนค่า Explicit เป็นค่าเริ่มต้น และจะใช้เมื่อตัวแปรโฟลว์ที่อ้างอิงยังไม่ได้รับการระบุ
• type - (ไม่บังคับ) ข้อใดข้อหนึ่ง: สตริง (ค่าเริ่มต้น) ตัวเลข บูลีน หรือแผนที่
• array - (ไม่บังคับ) ตั้งค่าเป็น true เพื่อระบุว่าค่านั้นเป็นอาร์เรย์ประเภท ค่าเริ่มต้น: เท็จ

<DetachedContent>

<DetachedContent>variable-name-here</DetachedContent>

JWS ที่สร้างขึ้นซึ่งมีเพย์โหลดเนื้อหาจะอยู่ในรูปแบบดังนี้

header.payload.signature

หากคุณใช้นโยบาย GenerateJWS เพื่อสร้างเพย์โหลดที่แยกต่างหาก JWS ที่สร้างขึ้นจะละเว้นเพย์โหลดและ ในแบบฟอร์ม:

header..signature

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

โดยนโยบายจะแสดงข้อผิดพลาดในกรณีต่อไปนี้

• ระบุ <DetachedContent> เมื่อ JWS ไม่มีเนื้อหาที่แยกออก เพย์โหลด (รหัสข้อผิดพลาดคือ steps.jws.ContentIsNotDetached)
• ละเว้น <DetachedContent> และ JWS มีเพย์โหลดเนื้อหาที่แยกออกไป (รหัสข้อผิดพลาดคือ steps.jws.InvalidSignature)

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

ตั้งค่าเป็น "เท็จ" หากต้องการให้นโยบายแสดงข้อผิดพลาดเมื่อมีส่วนหัวแสดงอยู่ใน ส่วนหัว crit ของ JWS ไม่แสดงในองค์ประกอบ <KnownHeaders> ตั้งค่าเป็น true เพื่อให้นโยบาย VerifyJWS ไม่สนใจส่วนหัว crit

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

ตั้งค่าเป็น "เท็จ" หากต้องการให้นโยบายแสดงข้อผิดพลาดเมื่อระบุตัวแปรที่อ้างอิงไว้ ในนโยบายนั้นไม่สามารถแก้ปัญหาได้ ตั้งค่าเป็น "จริง" เพื่อจัดการตัวแปรที่แปลงไม่ได้ใดๆ เป็นสตริงว่าง (Null)

<KnownHeaders>

<KnownHeaders>a,b,c</KnownHeaders>

or:

<KnownHeaders ref=’variable_containing_headers’/>

นโยบาย GenerateJWS ใช้องค์ประกอบ <CriticalHeaders> เพื่อป้อนข้อมูล ส่วนหัว crit ในโทเค็น เช่น

{
  “typ: “...”,
  “alg” : “...”,
  “crit” : [ “a”, “b”, “c” ],
}

นโยบาย VerifyJWS จะตรวจสอบส่วนหัว crit ใน JWS (หากมี) และสำหรับรายการแต่ละรายการที่ระบุไว้ ตรวจสอบว่าองค์ประกอบ <KnownHeaders> แสดงส่วนหัวนั้นด้วย เอลิเมนต์ <KnownHeaders> สามารถมี Superset ของรายการที่ระบุใน crit ได้ จำเป็นต้องระบุส่วนหัวทั้งหมดที่ระบุใน crit ไว้ในส่วน องค์ประกอบ <KnownHeaders> ส่วนหัวทั้งหมดที่นโยบายพบใน crit ที่ไม่ได้แสดงอยู่ใน <KnownHeaders> จะทำให้นโยบาย VerifyJWS ล้มเหลว

คุณเลือกกำหนดค่านโยบาย VerifyJWS เพื่อละเว้นส่วนหัว crit ได้โดยทำดังนี้ กำลังตั้งค่าองค์ประกอบ <IgnoreCriticalHeaders> เป็น true

<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

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

หากคุณดึงค่าจาก URL สาธารณะ Edge จะแคช JWKS เป็นระยะเวลา 300 วินาที เมื่อแคชหมดอายุ Edge จะดึงข้อมูล JWKS อีกครั้ง

<PublicKey/Value>

<PublicKey>
   <Value ref="public.publickey"/>
</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>

ระบุคีย์สาธารณะที่ใช้เพื่อยืนยันลายเซ็นใน JWS ใช้แอตทริบิวต์อ้างอิงเพื่อ ส่งคีย์ในตัวแปรโฟลว์ หรือระบุคีย์ที่เข้ารหัส PEM โดยตรง ใช้เมื่อ ซึ่งเป็นหนึ่งใน RS256/RS384/RS512, PS256/PS384/PS512 หรือ ES256/ES384/ES512

<SecretKey/Value>

<SecretKey>
  <Value ref="private.your-variable-name"/>
</SecretKey>

ระบุคีย์ลับที่ใช้เพื่อยืนยันหรือลงนามโทเค็นด้วยอัลกอริทึม HMAC ใช้เท่านั้น เมื่ออัลกอริทึมเป็น HS256, HS384, HS512 ใช้แอตทริบิวต์ ref เพื่อส่งคีย์ในตัวแปรโฟลว์ได้

<Source>

<Source>JWS-variable</Source>

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

ตัวแปรโฟลว์

เมื่อประสบความสำเร็จ นโยบาย ยืนยัน JWS และ Decode JWS ที่ตั้งไว้ ตัวแปรบริบทตามรูปแบบนี้:

jws.{policy_name}.{variable_name}

ตัวอย่างเช่น หากชื่อนโยบายคือ verify-jws ระบบก็จะเก็บนโยบายนั้นไว้ อัลกอริทึมที่ระบุใน JWS กับตัวแปรบริบทนี้: วันที่ jws.verify-jws.header.algorithm

ข้อมูลอ้างอิงข้อผิดพลาด

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.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

ตัวแปรความผิดพลาด

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

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

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

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

<FaultRules>
    <FaultRule name="JWS Policy Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "TokenExpired")</Condition>
        </Step>
        <Condition>JWS.failed=true</Condition>
    </FaultRule>
</FaultRules>