إنشاء سياسة JWT

أنت تعرض مستندات Apigee Edge.
انتقل إلى مستندات Apigee X. معلومات

المزايا

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

فيديو

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

نماذج

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

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

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

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

ستؤدي إعدادات السياسة هنا إلى إنشاء JWT بمجموعة من المطالبات العادية على النحو المحدّد في مواصفات JWT، بما في ذلك انتهاء الصلاحية لمدة ساعة، بالإضافة إلى مطالبة إضافية. يمكنك تضمين العدد الذي تريده من المطالبات الإضافية. اطلع على مرجع 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>

مرجع عنصر لإنشاء 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 - (اختيارية) أحد الخيارات التالية: سلسلة (تلقائي) أو رقم أو قيمة منطقية أو خريطة
• مصفوفة - (اختيارية) يتم ضبطها على صحيح للإشارة إلى ما إذا كانت القيمة مصفوفة من الأنواع. الإعداد التلقائي: خطأ.

عند تضمين العنصر <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 - (اختيارية) أحد الخيارات التالية: سلسلة (تلقائي) أو رقم أو قيمة منطقية أو خريطة
• مصفوفة - (اختيارية) يتم ضبطها على صحيح للإشارة إلى ما إذا كانت القيمة مصفوفة من الأنواع. الإعداد التلقائي: خطأ.

<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 تسرد أيضًا هذا العنوان. أي عنوان تعثر عليه سياسة التحقّق من JWT في 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 يحتوي على معرّف فريد عالمي (UUID) عشوائي. إنّ المطالبة بمعرّف 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 عندما تؤدي هذه السياسة إلى ظهور خطأ. هذه المعلومات مهمة لمعرفة ما إذا كنت تعمل على تطوير قواعد للأخطاء للتعامل معها. لمزيد من المعلومات، يمكنك الاطّلاع على المعلومات التي يجب معرفتها عن الأخطاء المتعلقة بالسياسات وأخطاء المعالجة.

أخطاء في وقت التشغيل

يمكن أن تحدث هذه الأخطاء عند تنفيذ السياسة.

أخطاء النشر

يمكن أن تحدث هذه الأخطاء عند نشر خادم وكيل يحتوي على هذه السياسة.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

Example fault rule

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