إنشاء سياسة JWT

أنت الآن بصدد الاطّلاع على مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X. info

الأدوات المستخدمة

تنشئ هذه الطريقة رمز JWT موقَّعًا، مع مجموعة قابلة للضبط من المطالبات. يمكن بعد ذلك إرجاع رمز JWT إلى العملاء أو إرساله إلى أهداف الخلفية أو استخدامه بطرق أخرى. للحصول على مقدمة مفصّلة، يُرجى الاطّلاع على نظرة عامة على سياسات JWS وJWT.

فيديو

شاهِد فيديو قصيرًا لمعرفة كيفية إنشاء رمز JWT موقَّع.

نماذج

• إنشاء رمز JWT مميّز وموقّع باستخدام خوارزمية HS256
• إنشاء رمز JWT موقَّع باستخدام خوارزمية RS256

إنشاء رمز JWT موقَّع باستخدام خوارزمية HS256

تنشئ سياسة المثال هذه رمز JWT جديدًا وتوقّعه باستخدام خوارزمية HS256. تعتمد خوارزمية HS256 على مفتاح سري مشترك لتوقيع البيانات والتحقّق من التوقيع.

عندما يتم تشغيل إجراء السياسة هذا، يرمّز Edge عنوان JWT وحمولته، ثم يوقّع رقميًا على JWT. يمكنك مشاهدة الفيديو أعلاه للحصول على مثال كامل، بما في ذلك كيفية تقديم طلب إلى السياسة.

سيؤدي إعداد السياسة هنا إلى إنشاء رمز JWT يتضمّن مجموعة من المطالبات العادية كما هو محدّد في مواصفات JWT، بما في ذلك تاريخ انتهاء صلاحية مدته ساعة واحدة، بالإضافة إلى مطالبة إضافية. يمكنك تضمين أي عدد تريده من المطالبات الإضافية. راجِع مرجع العناصر للاطّلاع على تفاصيل حول المتطلبات والخيارات لكل عنصر في نموذج السياسة هذا.

<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

يصف مرجع السياسة عناصر وسمات سياسة إنشاء رمز JWT.

ملاحظة: سيختلف الإعداد إلى حد ما حسب خوارزمية التشفير التي تستخدمها. راجِع الأمثلة للاطّلاع على أمثلة توضّح عمليات الضبط لحالات استخدام معيّنة.

السمات التي تنطبق على العنصر ذي المستوى الأعلى

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

السمات التالية مشتركة بين جميع العناصر الرئيسية للسياسة.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

استخدِم هذه السمة بالإضافة إلى سمة الاسم لتصنيف السياسة في أداة تعديل وكيل واجهة المستخدم الإدارية باستخدام اسم مختلف بلغة طبيعية.

<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 - (اختياري) إحدى القيم التالية: string (القيمة التلقائية) أو number أو boolean أو map
• 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 - (اختياري) إحدى القيم التالية: string (القيمة التلقائية) أو number أو boolean أو map
• 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 العنوان crit. بالنسبة إلى كل عنصر مُدرَج في العنوان crit، تتحقّق السياسة من أنّ العنصر <KnownHeaders> في سياسة VerifyJWT يدرج هذا العنوان أيضًا. أي عنوان تعثر عليه سياسة VerifyJWT في crit ولم يتم إدراجه أيضًا في <KnownHeaders> يؤدي إلى تعذُّر تنفيذ سياسة VerifyJWT.

<CustomClaims>

ملاحظة: يتم حاليًا إدراج عنصر CustomClaims عند إضافة سياسة GenerateJWT جديدة من خلال واجهة المستخدم. هذا العنصر غير فعّال ويتم تجاهله. العنصر الصحيح الذي يجب استخدامه بدلاً من ذلك هو <AdditionalClaims>. سيتم تعديل واجهة المستخدم لإدراج العناصر الصحيحة في وقت لاحق.

<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 يحتوي على معرّف فريد عالمي عشوائي. مطالبة معرّف JWT (jti) هي معرّف فريد لرمز JWT المميّز. لمزيد من المعلومات حول jti، يُرجى الرجوع إلى RFC7519.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

اضبط القيمة على "خطأ" إذا كنت تريد أن تعرض السياسة خطأً عند تعذُّر تحديد أي متغير مرجعي محدّد في السياسة. اضبط القيمة على "صحيح" للتعامل مع أي متغيّر لا يمكن حله كسلسلة فارغة (قيمة فارغة).

<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 يحتوي على مطالبة sub، ويتم ضبطها على القيمة المحدّدة.تحدّد هذه المطالبة موضوع رمز 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>