นโยบายVerifyJWS

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

อะไร

ยืนยันลายเซ็นใน 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 ซึ่งอาจ ดึงมาจาก KVM ของ Edge เป็นต้น)

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

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

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

<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> ตั้งค่าเป็น "จริง" เพื่อให้นโยบาย VerifyJWS ไม่สนใจส่วนหัว 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” ],
}

นโยบาย VerifyJWS จะตรวจสอบส่วนหัว crit ใน JWS หากมี และสำหรับแต่ละรายการที่แสดงไว้ นโยบายจะ ตรวจสอบว่าองค์ประกอบ <KnownHeaders> แสดงส่วนหัวนั้นด้วย องค์ประกอบ <KnownHeaders> อาจมีซูเปอร์เซ็ตของรายการที่ระบุไว้ใน 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 ใช้แอตทริบิวต์ 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>

<Source>JWS-variable</Source>

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

ตัวแปรโฟลว์

เมื่อประสบความสำเร็จ นโยบาย ยืนยัน JWS และ Decode 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>