นโยบาย GenerateJWT

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

อะไร

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

วิดีโอ

ชมวิดีโอสั้นๆ เพื่อดูวิธีสร้าง JWT ที่มีการลงชื่อ

ตัวอย่าง

• สร้าง JWT ที่ลงชื่อด้วย อัลกอริทึม HS256
• สร้าง JWT ที่ลงชื่อด้วย อัลกอริทึม RS256

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

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

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

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

<GenerateJWT name="JWT-Generate-HS256">
    <DisplayName>JWT Generate HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <ExpiresIn>1h</ExpiresIn>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

JWT ที่ได้จะมีส่วนหัวนี้ ...

{
  "typ" : "JWT", 
  "alg" : "HS256",
  "kid" : "1918290"
}

... และจะมีเพย์โหลดที่มีเนื้อหามีลักษณะดังนี้

{ 
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "show",
  "iat" : 1506553019,
  "exp" : 1506556619,
  "jti" : "BD1FF263-3D25-4593-A685-5EC1326E1F37",
  "show": "And now for something completely different."
}

ค่าของการอ้างสิทธิ์ iat, exp และ jti จะแตกต่างกันไป

สร้าง JWT ที่ลงชื่อด้วย RS256 อัลกอริทึม

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

เมื่อมีการเรียกใช้การทำงานของนโยบายนี้ Edge จะเข้ารหัสและลงนาม JWT แบบดิจิทัล รวมถึงการอ้างสิทธิ์ หากต้องการดูเกี่ยวกับส่วนต่างๆ ของ JWT รวมถึงวิธีเข้ารหัสและลงนาม โปรดดู RFC7519

<GenerateJWT name="JWT-Generate-RS256">
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <ExpiresIn>60m</ExpiresIn>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

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

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

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

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

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

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

<GenerateJWT name="JWT" continueOnError="false" enabled="true" async="false">

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

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

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

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

<AdditionalClaims/Claim>

<AdditionalClaims>
    <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'/>
</AdditionalClaims>

or:

<AdditionalClaims ref='claim_payload'/>

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

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

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

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

เช่น

<AdditionalClaims ref='json_claims'/>

โดยที่ตัวแปร json_claims มีออบเจ็กต์ JSON ในรูปแบบ

{
  "sub" : "person@example.com",
  "iss" : "urn://secure-issuer@example.com",
  "non-registered-claim" : {
    "This-is-a-thing" : 817,
    "https://example.com/foobar" : { "p": 42, "q": false }
  }
}

JWT ที่สร้างขึ้นมีการอ้างสิทธิ์ทั้งหมดในออบเจ็กต์ JSON

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

ใส่ชื่อ/ค่าการอ้างสิทธิ์เพิ่มเติมในส่วนหัวสำหรับ JWT

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

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

<CriticalHeaders>

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

or:

<CriticalHeaders ref=’variable_containing_headers’/>

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

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

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

<CustomClaims>

หมายเหตุ: ขณะนี้ระบบจะแทรกองค์ประกอบ CustomClaims เมื่อคุณเพิ่ม นโยบาย GenerateJWT ผ่าน UI องค์ประกอบนี้ไม่ทำงานและจะถูกละเว้น ที่ถูกต้อง องค์ประกอบที่จะใช้แทนคือ <AdditionalClaims> UI จะ เพื่อแทรกองค์ประกอบที่ถูกต้องในภายหลัง

<ExpiresIn>

<ExpiresIn>time-value-here</ExpiresIn>

ระบุอายุการใช้งานของ JWT ในหน่วยมิลลิวินาที วินาที นาที ชั่วโมง หรือวัน

<Id>

<Id>explicit-jti-value-here</Id>
 -or-
<Id ref='variable-name-here'/>
 -or-
<Id/>

สร้าง JWT ที่มีการอ้างสิทธิ์ JWT ที่เฉพาะเจาะจง เมื่อทั้งค่าข้อความและแอตทริบิวต์อ้างอิง ว่างเปล่า นโยบายจะสร้าง jti ที่มี UUID แบบสุ่ม การอ้างสิทธิ์ JWT ID (jti) คือ รหัสเฉพาะของ JWT ดูข้อมูลเพิ่มเติมเกี่ยวกับ jti ได้ที่ RFC7519

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<Issuer>

<Issuer ref='variable-name-here'/>
<Issuer>issuer-string-here</Issuer>

นโยบายจะสร้าง JWT ที่มีการอ้างสิทธิ์ที่มีชื่อว่า iss ซึ่งมีการตั้งค่า เป็นค่าที่ระบุ การอ้างสิทธิ์ที่ระบุตัวตนผู้ออกบัตร JWT นี่คือหนึ่งใน และดังที่ระบุไว้ใน RFC7519

<NotBefore>

<!-- Specify an absolute time. -->
<NotBefore>2017-08-14T11:00:21-07:00</NotBefore>
 -or-
<!-- Specify a time relative to when the token is generated. -->
<NotBefore>6h</NotBefore>

ระบุเวลาที่โทเค็นจะใช้ได้ โทเค็นไม่ถูกต้องจนถึงเวลาที่ระบุ คุณจะระบุค่าเวลาสัมบูรณ์หรือเวลาที่สัมพันธ์กับเวลาที่สร้างโทเค็นได้

ค่าเวลาที่ถูกต้องสำหรับองค์ประกอบ NotAfter สำหรับค่าเวลาสัมบูรณ์

สำหรับค่าเวลาสัมพัทธ์ ให้ระบุจำนวนเต็มและระยะเวลา เช่น

• 10 วินาที
• 60 นาที
• 12ชม

<OutputVariable>

<OutputVariable>jwt-variable</OutputVariable>

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

<PrivateKey/Id>

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

or

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

ระบุรหัสคีย์ (kid) ที่จะรวมไว้ในส่วนหัว JWT ใช้เท่านั้น เมื่ออัลกอริทึมเป็น 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 ซึ่งใช้เพื่อลงนาม JWT ใช้แอตทริบิวต์ 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) ที่จะรวมไว้ในส่วนหัว JWT ของ JWT ที่ลงนามด้วย 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 ไบต์ การใช้คีย์ที่มีขนาดต่ำกว่าจะทำให้เกิดข้อผิดพลาดรันไทม์

<Subject>

<Subject>subject-string-here</Subject>

<Subject ref="flow_variable" />

เช่น

<Subject ref="apigee.developer.email"/>

นโยบายจะสร้าง JWT ที่มีการอ้างสิทธิ์ sub โดยตั้งค่าเป็น value.คำกล่าวอ้างนี้ระบุหรือให้คำแถลงเกี่ยวกับหัวเรื่องของ JWT นี่คือหนึ่งใน ชุดการอ้างสิทธิ์มาตรฐานที่กล่าวถึงใน RFC7519

ตัวแปรโฟลว์

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

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

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="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "TokenExpired")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>