นโยบาย GenerateJWS

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

อะไร

สร้าง 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 ได้ที่ส่วนต่างๆ ของ JWS/JWT

ใช้องค์ประกอบ <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>

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

<CriticalHeaders>

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

or:

<CriticalHeaders ref=’variable_containing_headers’/>

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

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

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

<DetachContent>

<DetachContent>true|false</DetachContent>

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

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

header.payload.signature

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

header..signature

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<OutputVariable>

<OutputVariable>JWS-variable</OutputVariable>

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

<Payload>

<Payload ref="flow-variable-name-he>re&quo<t; /

o>r

Payloadpay<load-val>ue/Payload

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

<PrivateKey/Id>

<PrivateKey>
  <Id ref="flow-variable-name-h>e<re"/
/>Privat<eKey

or

>Pri<va>teKey
  Idyour-id-<val>u<e-here/Id
/>PrivateKey

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

<PrivateKey/Password>

<PrivateKey>
  <Password ref="private.privatekey-passw>o<rd"/
/>PrivateKey

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

<PrivateKey/Value>

<PrivateKey>
  <Value ref="private.variable-name-h>e<re"/
/>PrivateKey

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

<SecretKey/Id>

<SecretKey>
  <Id ref="flow-variable-name-h>e<re"/
>/Secre<tKey

or
>
Se<cr>etKey
  Idyour-id-<val>u<e-here/Id
>/SecretKey

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

<SecretKey/Value>

<SecretKey>
  <Value ref="private.your-variable-n>a<me"/
>/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>