นโยบาย GenerateJWT

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

อะไร

สร้าง 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 รวมถึงวิธีเข้ารหัสและลงนาม โปรดดู 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

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

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

<CriticalHeaders>

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

or:

<CriticalHeaders ref=’variable_containing_headers’/>

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

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

ในเวลาเรียกใช้ VerifyJWT policy จะตรวจสอบส่วนหัว 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 ที่มีอ้างสิทธิ์ jti ที่เฉพาะเจาะจง เมื่อค่าข้อความและแอตทริบิวต์ ref ว่างเปล่าทั้งคู่ นโยบายจะสร้าง jti ที่มี UUID แบบสุ่ม การอ้างสิทธิ์รหัส JWT (jti) คือตัวระบุที่ไม่ซ้ำกันสำหรับ JWT ดูข้อมูลเพิ่มเติมเกี่ยวกับ jti ได้ที่ RFC7519

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<ผู้ออกใบรับรอง>

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

ตัวแปรโฟลว์

นโยบาย Generate 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>