นโยบาย GenerateJWS

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

อะไร

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

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

วิดีโอ

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

ตัวอย่าง

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

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

นโยบายตัวอย่างนี้สร้าง JWS ที่แนบมาและลงนามโดยใช้อัลกอริทึม HS256 HS256 ใช้ เกี่ยวกับความลับที่ใช้ร่วมกันสำหรับทั้งการลงชื่อและยืนยันลายเซ็น

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

header.payload.signature

ตั้งค่า <DetachContent> เป็น true เพื่อสร้างเนื้อหาที่แยกออก ดูอะไหล่ของ JWS/JWT สำหรับข้อมูลเพิ่มเติมเกี่ยวกับ และรูปแบบของ JWS

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

การกำหนดค่านโยบายด้านล่างสร้าง JWS จากเพย์โหลดที่อยู่ในตัวแปร private.payload

<GenerateJWS name="JWS-Generate-HS256">
    <DisplayName>JWS Generate HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <Payload ref="private.payload" />
    <OutputVariable>jws-variable</OutputVariable>
</GenerateJWS>

สร้าง JWS แบบถอดออกที่เซ็นชื่อด้วย RS256 อัลกอริทึม

นโยบายตัวอย่างนี้สร้าง JWS แบบถอดออกและลงนามโดยใช้อัลกอริทึม RS256 กำลังสร้าง ลายเซ็น RS256 อาศัยคีย์ส่วนตัว RSA ซึ่งต้องระบุในรูปแบบที่เข้ารหัส PEM

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

header..signature

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

<GenerateJWS name="JWS-Generate-RS256">
    <DisplayName>JWS Generate RS256</DisplayName>
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Payload ref="private.payload" />
    <DetachContent>true</DetachContent>
    <OutputVariable>jws-variable</OutputVariable>
</GenerateJWS>

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

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

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

<PrivateKey>
  <Value ref="private.privatekey"/>
  <Password ref="private.privatekey-password"/>
  <Id ref="private.privatekey-id"/>
</PrivateKey>

การอ้างอิงองค์ประกอบสำหรับ Generate JWS

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

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

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

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

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

ระบุอัลกอริทึมการเข้ารหัสเพื่อลงนามโทเค็น

<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

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

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

<CriticalHeaders>

<CriticalHeaders>a,b,c</CriticalHeaders>

or:

<CriticalHeaders ref=’variable_containing_headers’/>

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

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

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

<DetachContent>

<DetachContent>true|false</DetachContent>

ระบุว่าจะสร้าง JWS ที่มีเพย์โหลดที่แยกออกมา (<DetachContent>true</DetachContent>) หรือไม่ หรือไม่ <DetachContent>false</DetachContent>

หากคุณระบุ "เท็จ" ค่าเริ่มต้น JWS ที่สร้างขึ้นจะอยู่ในรูปแบบ

header.payload.signature

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

header..signature

หากมีเพย์โหลดที่ปลดออก คุณจะต้องส่งเพย์โหลดต้นฉบับที่ไม่ได้เข้ารหัสไปยังนโยบาย VerifyJWS โดยใช้องค์ประกอบ <DetachedContent> ของนโยบาย VerifyJWS

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<OutputVariable>

<OutputVariable>JWS-variable</OutputVariable>

ระบุตำแหน่งที่จะวาง JWS ที่นโยบายนี้สร้างขึ้น โดยค่าเริ่มต้น จะอยู่ใน ตัวแปรโฟลว์ jws.POLICYNAME.generated_jws

<Payload>

<Payload ref="flow-variable-name-here" />

or

<Payload>payload-value</Payload>

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

<PrivateKey/Id>

<PrivateKey>
  <Id ref="flow-variable-name-here"/>
</PrivateKey>

or

<PrivateKey>
  <Id>your-id-value-here</Id>
</PrivateKey>

ระบุรหัสคีย์ (kid) ที่จะรวมไว้ในส่วนหัว JWS ใช้เท่านั้น เมื่ออัลกอริทึมเป็น RS256/RS384/RS512, PS256/PS384/PS512 หรือ ES256/ES384/ES512

<PrivateKey/Password>

<PrivateKey>
  <Password ref="private.privatekey-password"/>
</PrivateKey>

ระบุรหัสผ่านที่นโยบายควรใช้เพื่อถอดรหัสคีย์ส่วนตัว หากจำเป็น ใช้เมนู ref เพื่อส่งคีย์ในตัวแปรโฟลว์ ใช้เท่านั้น เมื่ออัลกอริทึมเป็น RS256/RS384/RS512, PS256/PS384/PS512 หรือ ES256/ES384/ES512

<PrivateKey/Value>

<PrivateKey>
  <Value ref="private.variable-name-here"/>
</PrivateKey>

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

<SecretKey/Id>

<SecretKey>
  <Id ref="flow-variable-name-here"/>
</SecretKey>

or

<SecretKey>
  <Id>your-id-value-here</Id>
</SecretKey>

ระบุรหัสคีย์ (kid) ที่จะรวมไว้ในส่วนหัว JWS ของ JWS ที่ลงนามด้วย HMAC อัลกอริทึม ใช้เมื่ออัลกอริทึมเป็นหนึ่งใน HS256/HS384/HS512 เท่านั้น

<SecretKey/Value>

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

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

Edge บังคับใช้ความแรงของคีย์ขั้นต่ำสำหรับอัลกอริทึม HS256/HS384/HS512 ความยาวคีย์ขั้นต่ำ สำหรับ HS256 คือ 32 ไบต์ ส่วน HS384 เท่ากับ 48 ไบต์ และสำหรับ HS512 จะมีขนาด 64 ไบต์ การใช้คีย์ที่มีขนาดต่ำกว่าจะทำให้เกิดข้อผิดพลาดรันไทม์

ตัวแปรโฟลว์

นโยบาย Generate JWS ไม่ได้ตั้งค่าตัวแปรโฟลว์

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

ส่วนนี้จะอธิบายโค้ดข้อผิดพลาดและข้อความแสดงข้อผิดพลาดที่แสดงผลและตัวแปรข้อผิดพลาดที่ 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>