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

<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 และวิธีเข้ารหัสและรับรองส่วนต่างๆ ของ 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>

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

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

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

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

<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 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 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> ของนโยบาย ConfirmJWT แสดงส่วนหัวดังกล่าวด้วย ส่วนหัวที่นโยบาย ConfirmJWT ใน crit ซึ่งไม่ได้ระบุไว้ใน <KnownHeaders> จะทำให้นโยบาย ConfirmJWT ล้มเหลว

<CustomClaims>

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

<ExpiresIn>

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

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

<รหัส>

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

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

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

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

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

• 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 ที่มีการอ้างสิทธิ์ย่อยโดยตั้งค่าให้กับค่าที่ระบุ และการอ้างสิทธิ์นี้จะระบุหรือระบุคำชี้แจงเกี่ยวกับประเด็นของ JWT ซึ่งเป็นหนึ่งในชุดการอ้างสิทธิ์มาตรฐานที่กล่าวถึงใน RFC7519

ตัวแปรโฟลว์

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

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

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

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

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

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

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

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

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

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

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