إنشاء سياسة JWT

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

الموضوع

تنشئ 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 - (اختياري) واحد مما يلي: سلسلة (تلقائية) أو رقم أو قيمة منطقية أو خريطة
• 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” ],
}

في وقت التشغيل، تفحص سياسة التحقّق من JWT عنوان crit. بالنسبة إلى كل عنصر مدرَج في العنوان crit، يتحقّق التطبيق من أنّ العنصر <KnownHeaders> في سياسة التحقّق من صحة المعلومات (التحقق من JWT) يدرج أيضًا هذا العنوان. ويؤدي أي عنوان تعثر عليه سياسة التحقّق من JWT في crit إذا لم يكن مُدرَجًا أيضًا في <KnownHeaders> إلى تعذُّر تنفيذ السياسة.

<CustomClaims>

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

<ExpiresIn>

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

تحدد عمر JWT بالمللي ثانية أو الثواني أو الدقائق أو الساعات أو الأيام.

<الرقم التعريفي>

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

تنشئ JWT باستخدام مطالبة jti المحدّدة. عندما تكون القيمة النصية وسمة المرجع فارغة، ستنشئ السياسة ملف jti يحتوي على معرّف فريد عالمي (UUID) عشوائي. إن مطالبة رقم JWT (jti) هي معرّف فريد لـ JWT. لمزيد من المعلومات عن jti، راجِع RFC7519.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

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