นโยบายVerifyJWS

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

อะไร

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

หาก JWS ได้รับการยืนยันและถูกต้องแล้ว คำขอจะได้รับอนุญาตให้ดำเนินการต่อ หากยืนยันลายเซ็น 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

คุณจะส่งผ่านเพย์โหลดไปยังนโยบาย ConfirmJWS ได้โดยการระบุชื่อตัวแปรที่มีเพย์โหลดไปยังองค์ประกอบ <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>

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

ข้อมูลอ้างอิงนโยบายจะอธิบายองค์ประกอบและแอตทริบิวต์ของนโยบาย "ยืนยัน JWS"

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

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

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

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

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

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

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

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

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<KnownHeaders>

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

or:

<KnownHeaders ref=’variable_containing_headers’/>

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

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

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

คุณจะกำหนดค่านโยบาย ConfirmJWS ให้ละเว้นส่วนหัว 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 ใช้แอตทริบิวต์ ref เพื่อส่งคีย์ในตัวแปรโฟลว์ หรือระบุคีย์ที่เข้ารหัส 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>JWS-variable</Source>

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

ตัวแปรโฟลว์

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

jws.{policy_name}.{variable_name}

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

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

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

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

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

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

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

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

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

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

สำหรับการจัดการข้อผิดพลาด แนวทางปฏิบัติแนะนำคือดักส่วน 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>