سياسة OAuthV2

يتم الآن عرض مستندات Apigee Edge.
يمكنك الاطّلاع على وثائق Apigee X.

الموضوع

إنّ بروتوكول OAuthV2 هو سياسة متعدّدة الأوجه لإجراء عمليات التحكّم المتعلّقة بنوع منح OAuth 2.0. هذه هي السياسة الأساسية المُستخدَمة في ضبط نقاط نهاية OAuth 2.0 على Apigee Edge.

ملاحظة: إذا كنت تريد معرفة المزيد من المعلومات عن OAuth على Apigee Edge، يمكنك الاطّلاع على صفحة OAuth الرئيسية. وتوفّر هذه الميزة روابط إلى الموارد والعيّنات والفيديوهات وغيرها. يمكنك الاطّلاع على نموذج بروتوكول OAuth المتقدّم على GitHub للتعرّف على طريقة جيدة لاستخدام هذه السياسة في تطبيق يعمل.

العيّنات

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuth-v20-2">
    <DisplayName>OAuth v2.0 2</DisplayName>
    <Operation>VerifyAccessToken</Operation>
    <AccessTokenPrefix>Bearer</AccessTokenPrefix> <!-- Optional, default is Bearer -->
</OAuthV2>

$ curl -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

<OAuthV2 enabled="true" continueOnError="false" async="false" name="generateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <AppEndUser>Doe</AppEndUser>
    <UserName>jdoe</UserName>
    <PassWord>jdoe</PassWord>
    <GrantType>grant_type</GrantType>
    <ClientId>a_valid_client_id</ClientId>
    <SupportedGrantTypes>
        <GrantType>password</GrantType>
    </SupportedGrantTypes>
</OAuthV2>

var client_id = context.getVariable("local_clientid");
var client_secret = context.getVariable("local_secret");
context.setVariable("request.header.Authorization","Basic "+CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1
                                      .parse(client_id + ':' + client_secret)));

راجِع أيضًا "ترميز بيانات اعتماد المصادقة الأساسية".

مرجع العناصر

يصف مرجع السياسة عناصر وسمات سياسة OAuthV2.

ويُعدّ نموذج السياسة المعروض أدناه من بين العديد من الإعدادات المحتملة. يعرض هذا النموذج سياسة OAuthV2 التي تم ضبطها لعملية generateAccessToken. ويتضمن ذلك العناصر المطلوبة والاختيارية. يمكنك الرجوع إلى أوصاف العناصر في هذا القسم لمعرفة التفاصيل.

<OAuthV2 name="GenerateAccessToken">
  <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
  <Operation>GenerateAccessToken</Operation>
  <!-- This is in millseconds, so expire in an hour -->
  <ExpiresIn>3600000</ExpiresIn>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <GenerateResponse/>
</OAuthV2>

سمات <OAuthV2>

<OAuthV2 async="false" continueOnError="false" enabled="true" name="MyOAuthPolicy">

يصف الجدول التالي السمات الشائعة لجميع العناصر الرئيسية للسياسة:

عنصر <DisplayName>

يمكنك استخدام هذه السمة بالإضافة إلى السمة name لتصنيف السياسة في محرّر الخادم الوكيل لواجهة المستخدم الخاصة بالإدارة باستخدام اسم بلغة مختلفة.

<DisplayName>Policy Display Name</DisplayName>

عنصر <AccessToken>

<AccessToken>request.header.access_token</AccessToken>

بشكل تلقائي، تتوقع خدمة AccessAccessToken إرسال رمز الدخول في عنوان Authorization. يمكنك تغيير هذا الإعداد التلقائي باستخدام هذا العنصر. على سبيل المثال، يشير request.queryparam.access_token إلى أنّ رمز الدخول يجب أن يكون متوفّرًا كمَعلمة طلب بحث باسم access_token.

curl https://myorg-myenv.apigee.net/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"

curl "https://myorg-myenv.apigee.net/oauth2/validate?access_token:Rft3dqrs56Blirls56a"

عنصر <AccessTokenPrefix>

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

بشكل تلقائي، تتوقّع الملكية AccessAccessToken إرسال رمز الدخول في عنوان تفويض كرمز مميّز لحامل. على سبيل المثال:

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

حاليًا، يمثّل Bearer البادئة الوحيدة المسموح بها.

عنصر <AppEndUser>

<AppEndUser>request.queryparam.app_enduser</AppEndUser>

في الحالات التي يجب فيها إرسال رقم تعريف المستخدم النهائي للتطبيق إلى خادم التفويض، يتيح لك هذا العنصر تحديد المكان الذي يجب أن يبحث فيه Edge عن رقم تعريف المستخدم النهائي. على سبيل المثال، يمكن إرساله كمَعلمة طلب بحث أو في عنوان HTTP.

على سبيل المثال، يشير request.queryparam.app_enduser إلى أن AppEndUser يجب أن تكون موجودة كمَعلمة طلب البحث، على سبيل المثال، ?app_enduser=ntesla@theramin.com. لطلب AppAppUser في عنوان HTTP مثلاً، اضبط هذه القيمة على request.header.app_enduser.

يتيح لك هذا الإعداد تضمين رقم تعريف المستخدم النهائي للتطبيق في رمز الدخول. وهذه الميزة مفيدة إذا أردت أن تتمكّن من استرداد رموز الدخول عبر بروتوكول OAuth 2.0 أو إبطالها من خلال رقم تعريف المستخدم النهائي. لمزيد من المعلومات، يمكنك الاطّلاع على مقالة تفعيل استرداد رموز الدخول عبر OAuth 2.0 وإبطالها حسب رقم تعريف المستخدم النهائي أو رقم تعريف التطبيق أو كليهما.

<السمات/السمة>

<Attributes>
    <Attribute name="attr_name1" ref="flow.variable" display="true|false">value1</Attribute>
    <Attribute name="attr_name2" ref="flow.variable" display="true|false">value2</Attribute>
</Attributes>

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

يتيح لك هذا العنصر تحديد قيمة في متغيّر تدفق أو من سلسلة حرفية. إذا حدّدت متغيّرًا وسلسلة، يتم استخدام القيمة المحدّدة في متغيّر التدفق. إذا تعذّر حلّ المتغيّر، ستكون السلسلة هي القيمة التلقائية.

لمزيد من المعلومات حول استخدام هذا العنصر، اطّلِع على تخصيص الرموز المميّزة ورموز التفويض.

عرض سمات مخصّصة أو إخفاؤها في الرد

تذكّر أنّه في حال ضبط عنصر generateResponse لهذه السياسة على true، سيتم عرض تمثيل JSON الكامل للرمز المميّز في الاستجابة، بما في ذلك أي سمات مخصّصة تضبطها. في بعض الحالات، قد تحتاج إلى إخفاء بعض السمات المخصّصة أو جميعها في الردّ بحيث لا تظهر لتطبيقات العميل.

تظهر السمات المخصّصة في الردّ تلقائيًا. وإذا كنت تريد إخفاءها، يمكنك ضبط المعلَمة display على false. على سبيل المثال:

<Attributes>
    <Attribute name="employee_id" ref="employee.id" display="false"/>
    <Attribute name="employee_name" ref="employee.name" display="false"/>
</Attributes>

لا يتم استخدام قيمة السمة display. لنفترض أنك أنشأت رمز دخول مميزًا بسمات مخصّصة تريد إخفاءها في الردّ الذي تم إنشاؤه. تحقيق display=false يؤدي إلى تحقيق هذا الهدف. إذا تم إنشاء رمز دخول جديد لاحقًا باستخدام رمز مميّز لإعادة التحميل، ستظهر السمات المخصّصة الأصلية من رمز الدخول في استجابة الرمز المميّز لإعادة التحميل. ويعود السبب في ذلك إلى أنّ محرّك بحث Edge لا يذكر أنّه تم ضبط السمة display في الأصل على القيمة false في سياسة إنشاء رمز الدخول، أمّا السمة المخصّصة، فهي ببساطة جزء من البيانات الوصفية لرمز الوصول.

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

لإخفاء السمات المخصّصة في هذه الحالات، تتوفّر لك الخيارات التالية:

• إعادة ضبط السمات المخصّصة صراحةً في سياسة الرمز المميّز لإعادة التحميل وضبط العرض على "خطأ" في هذه الحالة، قد تحتاج إلى استرداد القيم المخصّصة الأصلية من رمز الدخول الأصلي باستخدام سياسة GetOAuthV2Info.
• استخدِم سياسة JavaScript بعد المعالجة لاستخراج أي سمات مخصّصة لا تريد رؤيتها في الرد.

راجِع أيضًا تخصيص الرموز المميّزة ورموز التفويض.

عنصر <ClientId>

<ClientId>request.formparam.client_id</ClientId>

وفي كثير من الحالات، يجب أن يرسل تطبيق العميل معرِّف العميل إلى خادم التفويض. يتيح لك هذا العنصر تحديد المكان الذي يجب أن يبحث فيه Edge عن معرِّف العميل. ويكون الموقع الجغرافي الوحيد الذي يمكنك ضبطه هو الموقع الجغرافي التلقائي، وهو متغيّر التدفق request.formparam.client_id. لا يمكن ضبط إعدادات ClientId على أي متغيّر آخر. يمكنك أيضًا الاطّلاع على طلب رموز الدخول ورموز الدخول.

عنصر <Code>

<Code>request.queryparam.code</Code>

في مسار نوع منح التفويض، على العميل إرسال رمز تفويض إلى خادم التفويض (Apigee Edge). يتيح لك هذا العنصر تحديد المكان الذي يجب أن يبحث فيه Edge عن رمز التفويض. على سبيل المثال، يمكن إرساله كمَعلمة طلب بحث أو عنوان HTTP أو مَعلمة نموذج (الخيار التلقائي).

ويشير المتغيّر request.queryparam.auth_code إلى أنّ رمز التفويض يجب أن يكون متوفّرًا كمعلَمة طلب بحث، على سبيل المثال ?auth_code=AfGlvs9. على سبيل المثال، لطلب رمز التفويض في عنوان HTTP، اضبط هذه القيمة على request.header.auth_code. راجِع أيضًا طلب رموز الدخول ورموز التفويض.

عنصر<تاريخ انتهاء الصلاحية>

<ExpiresIn>10000</ExpiresIn> 

يفرض وقت انتهاء صلاحية رموز الدخول ورموز التفويض بالملي ثانية. (بالنسبة إلى الرموز المميّزة لإعادة التحميل، استخدِم <RefreshTokenExpiresIn>. وتكون قيمة وقت انتهاء الصلاحية هي قيمة من إنشاء النظام بالإضافة إلى القيمة <ExpiresIn>. إذا تم ضبط <ExpiresIn> على -1، تنتهي صلاحية الرمز المميَّز أو الرمز وفقًا لالحد الأقصى لانتهاء صلاحية رمز الدخول عبر OAuth. وإذا لم يتم تحديد السياسة <ExpiresIn>، سيطبّق النظام قيمة تلقائية تم ضبطها على مستوى النظام.

يمكن أيضًا تحديد وقت انتهاء الصلاحية في وقت التشغيل باستخدام قيمة تلقائية غير ثابتة أو من خلال الإشارة إلى متغيّر التدفق. على سبيل المثال، يمكنك تخزين قيمة انتهاء صلاحية الرمز المميّز في خريطة قيمة أساسية واستردادها وتحديدها إلى متغيّر والإشارة إليها في السياسة. مثلاً: kvm.oauth.expires_in

باستخدام Apigee Edge for Public Cloud، يحتفظ Edge بالكيانات التالية في ذاكرة التخزين المؤقت لمدة 180 ثانية على الأقل بعد الوصول إلى الكيانات.

• رموز الدخول عبر OAuth. يعني ذلك أنّ الرمز المميّز الذي تم إبطاله قد يستمر في العمل لمدة تصل إلى ثلاث دقائق إلى أن تنتهي صلاحية الحدّ الأقصى لذاكرة التخزين المؤقت.
• كيانات خدمة إدارة المفاتيح (KMS) (التطبيقات ومطوّرو البرامج ومنتجات واجهة برمجة التطبيقات)
• سمات مخصَّصة للرموز المميَّزة لبروتوكول OAuth وعلى كيانات KMS

يحدد المقطع التالي متغير تدفق وقيمة تلقائية أيضًا. يُرجى العِلم أنّ قيمة متغيّر التدفّق تحظى بالأولوية على القيمة التلقائية المحدّدة.

<ExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</ExpiresIn>

لا يتيح Edge طريقة لفرض انتهاء صلاحية الرمز المميَّز بعد إنشائه. إذا كنت بحاجة إلى فرض انتهاء صلاحية الرمز المميّز (على سبيل المثال، استنادًا إلى شرط)، يمكنك الاطّلاع على حلّ محتمل في هذه المشاركة في منتدى Apigee.

تتم إزالة رموز الدخول المنتهية الصلاحية تلقائيًا من نظام Apigee Edge بعد 3 أيام من انتهاء صلاحيتها. يمكنك أيضًا الاطّلاع على إزالة الرموز المميزة لإزالة إمكانية الوصول.

سحابة إلكترونية خاصة: بالنسبة إلى تثبيت Edge الخاص للسحابة الإلكترونية، يتم ضبط القيمة التلقائية من خلال السمة conf_keymanagement_oauth_auth_code_expiry_time_in_millis. لإعداد هذا الموقع:

1. افتح الملف message-processor.properties في محرِّر. إذا لم يكن الملف متاحًا، أنشئه:

   vi /opt/apigee/customer/application/message-processor.properties

2. اضبط السمة على النحو المطلوب:

   conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000

3. تأكَّد من أن ملف المواقع مملوك لمستخدم "apigee":

   chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

4. أعِد تشغيل معالج الرسائل.

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

العنصر <ExternalAccessToken>

<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>

تخبر Apigee Edge بمكان العثور على رمز الدخول الخارجي (رمز الدخول الذي لم يتم إنشاؤه من خلال Apigee Edge).

يوضّح المتغيّر request.queryparam.external_access_token أنّه يجب توفُّر رمز الدخول الخارجي كمَعلمة طلب البحث، على سبيل المثال ?external_access_token=12345678. على سبيل المثال، لطلب رمز الدخول الخارجي في عنوان HTTP، يجب ضبط هذه القيمة على request.header.external_access_token. راجِع أيضًا استخدام الرموز المميزة لبروتوكول OAuth من طرف ثالث.

عنصر <ExternalAuthentication>

<ExternalAuthorization>true</ExternalAuthorization>

إذا كان هذا العنصر غير صحيح أو غير متوفّر، تتحقّق Edge من client_id وclient_secret عادةً من مخزن تفويض Apigee Edge. استخدِم هذا العنصر عندما تريد العمل مع رموز OAuth المميزة التابعة لجهات خارجية. للحصول على تفاصيل عن استخدام هذا العنصر، يُرجى الاطّلاع على استخدام الرموز المميزة لبروتوكول OAuth التابعة لجهات خارجية.

عنصر <ExternalAuthenticationCode>

<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>

يتم استخدام Apigee Edge للعثور على رمز المصادقة الخارجي (رمز المصادقة الذي لم يتم إنشاؤه من خلال Apigee Edge).

يوضّح المتغيّر request.queryparam.external_auth_code أنّه يجب توفّر رمز المصادقة الخارجي كمَعلمة طلب بحث، كما هو الحال مع ?external_auth_code=12345678. على سبيل المثال، لطلب رمز المصادقة الخارجية في عنوان HTTP، اضبط هذه القيمة على request.header.external_auth_code. راجِع أيضًا استخدام الرموز المميزة لبروتوكول OAuth من طرف ثالث.

العنصر <ExternalإعادةToken>>

<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>

تخبر Apigee Edge بمكان العثور على رمز مميّز خارجي لإعادة التحميل (رمز مميز لإعادة التحميل لم يتم إنشاؤه من خلال Apigee Edge).

يشير المتغيّر request.queryparam.external_refresh_token إلى أنّ الرمز المميّز لإعادة التحميل الخارجي يجب أن يكون معلَمة عن طلب البحث، كما هو الحال على سبيل المثال ?external_refresh_token=12345678. على سبيل المثال، لطلب الرمز المميّز الخارجي لإعادة التحميل في عنوان HTTP، اضبط هذه القيمة على request.header.external_refresh_token. راجِع أيضًا استخدام الرموز المميزة لبروتوكول OAuth من طرف ثالث.

عنصر <CreateResponse>

<GenerateResponse enabled='true'/>

في حال ضبط هذه السياسة على true، ستنشئ السياسة ردًا وتعرضه. على سبيل المثال، بالنسبة إلى CreateAccessToken، قد تكون الاستجابة على النحو التالي:

{
  "issued_at" : "1467841035013",
  "scope" : "read",
  "application_name" : "e31b8d06-d538-4f6b-9fe3-8796c11dc930",
  "refresh_token_issued_at" : "1467841035013",
  "status" : "approved",
  "refresh_token_status" : "approved",
  "api_product_list" : "[Product1, nhl_product]",
  "expires_in" : "1799",
  "developer.email" : "edward@slalom.org",
  "token_type" : "BearerToken",
  "refresh_token" : "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "client_id" : "Adfsdvoc7KX5Gezz9le745UEql5dDmj",
  "access_token" : "AnoHsh2oZ6EFWF4h0KrA0gC5og3a",
  "organization_name" : "cerruti",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

وإذا تم إرسال false، لن يتم إرسال أي رد. وبدلاً من ذلك، تتم تعبئة مجموعة من متغيّرات التدفق بقيم ذات صلة بوظيفة السياسة. على سبيل المثال، تتم تعبئة متغيّر تدفق بيانات يُسمّى oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code باستخدام رمز المصادقة الذي تم إنشاؤه حديثًا. يُرجى العِلم أنّه يتم التعبير عن expires_in بالثواني في الاستجابة.

العنصر <CreateErrorResponse>

<GenerateErrorResponse enabled='true'/>

وفي حال ضبط السياسة على true، يتم إنشاء استجابة وعرضها في حال ضبط سمة FollowOnError على "صحيح". وإذا كان false (الخيار التلقائي)، لن يتم إرسال أي ردّ. وبدلاً من ذلك، تتم تعبئة مجموعة من متغيّرات التدفق بقيم ذات صلة بوظيفة السياسة.

<GrantType>

<GrantType>request.queryparam.grant_type</GrantType>

تخبر السياسة مكان العثور على مَعلمة نوع المِنح التي تم تمريرها في طلب. وفقًا لمواصفات OAuth 2.0، يجب تقديم نوع المِنح مع طلبات رموز الدخول ورموز التفويض. ويمكن أن يكون المتغيّر عنوانًا أو معلّمة طلب بحث أو معلّمة نموذج (تلقائي).

على سبيل المثال، يشير request.queryparam.grant_type إلى أن كلمة المرور يجب أن تكون معلّمة لطلب البحث، على سبيل المثال، ?grant_type=password. على سبيل المثال، لطلب نوع منح الإذن في عنوان HTTP، اضبط هذه القيمة على request.header.grant_type. يمكنك أيضًا الاطّلاع على طلب رموز الدخول ورموز الدخول.

عنصر <Operation>

<Operation>GenerateAuthorizationCode</Operation>

عملية OAuth 2.0 التي تم تنفيذها من خلال السياسة

عنصر <PassWord>

<PassWord>request.queryparam.password</PassWord>

يتم استخدام هذا العنصر مع نوع منح كلمة المرور فقط. بالنسبة إلى نوع منح كلمة المرور، يجب إتاحة بيانات اعتماد المستخدم (كلمة المرور واسم المستخدم) لسياسة OAuthV2. يتم استخدام العنصرين <PassWord> و<UserName> لتحديد المتغيرات حيث يمكن لتطبيق Edge العثور على هذه القيم. وإذا لم يتم تحديد هذه العناصر، من المتوقّع أن تعثر السياسة على القيم (تلقائيًا) في معلّمات النموذج باسم username وpassword. وفي حال عدم العثور على القيم، تعرض السياسة خطأً. يمكنك استخدام العنصرين <PassWord> و<UserName> للإشارة إلى أي متغيّر مسار يحتوي على بيانات الاعتماد.

على سبيل المثال، يمكنك تمرير كلمة المرور في طلب رمز مميّز باستخدام معلَمة طلب بحث وضبط العنصر على النحو التالي: <PassWord>request.queryparam.password</PassWord>. لطلب إدخال كلمة المرور في عنوان HTTP، عليك ضبط هذه القيمة على request.header.password.

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

يمكنك أيضًا الاطّلاع على طلب رموز الدخول ورموز التفويض.

عنصر <RedirectUri>

<RedirectUri>request.queryparam.redirect_uri</RedirectUri>

تحدِّد هذه السمة مكان البحث عن Edge في المَعلمة redirect_uri في الطلب.

لمحة عن معرّفات الموارد المنتظمة (URI) لإعادة التوجيه

يتم استخدام معرِّفات الموارد المنتظمة (URI) مع رمز التفويض وأنواع المنح الضمنية. يحدّد معرّف الموارد المنتظم (URI) لخادم إعادة التوجيه (Edge) المكان الذي يجب إرسال رمز التفويض إليه (لنوع منح رمز التفويض) أو رمز الدخول (لنوع منح الإذن الضمني). ومن المهم معرفة الحالات التي تكون فيها هذه المعلّمة مطلوبة ووقت استخدامها وكيفية استخدامها:

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

• (اختياري) في حال تسجيل عنوان URL لمعاودة الاتصال ولم يكن redirect_uri متوفرًا في الطلب، يعيد متصفّح Edge التوجيه إلى عنوان URL المسجّل لمعاودة الاتصال.
• (مطلوب) إذا لم يكن عنوان URL لمعاودة الاتصال مسجّلاً، يجب استخدام السمة redirect_uri. يُرجى العِلم أنّ Edge في هذه الحالة ستقبل أي عنوان URL. يمكن أن تمثل هذه الحالة مشكلة أمان، وبالتالي يجب عدم استخدامها إلا مع تطبيقات العملاء الموثوق بها. إذا لم تكن تطبيقات العميل موثوقة، يجب دائمًا تسجيل عنوان URL لمعاودة الاتصال.

يمكنك إرسال هذه المعلمة في معلمة طلب البحث أو في عنوان الصفحة. يوضّح المتغيّر request.queryparam.redirect_uri أنّه يجب تقديم معلّمة RedirectUri كمَعلمة طلب بحث، كما على سبيل المثال ?redirect_uri=login.myapp.com. على سبيل المثال، لطلب إعادة التوجيه في عنوان HTTP، اضبط هذه القيمة على request.header.redirect_uri. راجِع أيضًا طلب رموز الدخول ورموز التفويض.

عنصر <RelaunchToken>

<RefreshToken>request.queryparam.refreshtoken</RefreshToken>

عند طلب رمز دخول مميز باستخدام رمز مميّز لإعادة التحميل، عليك تقديم رمز مميّز لإعادة التحميل في الطلب. يتيح لك هذا العنصر تحديد المكان الذي يجب أن يبحث فيه Edge عن الرمز المميّز لإعادة التحميل. على سبيل المثال، يمكن إرساله كمَعلمة طلب بحث أو عنوان HTTP أو مَعلمة نموذج (الإعداد التلقائي).

يوضّح المتغيّر request.queryparam.refreshtoken أنّه يجب توفُّر الرمز المميّز لإعادة التحميل كمعلَمة طلب بحث، على سبيل المثال، ?refresh_token=login.myapp.com. على سبيل المثال، لطلب إضافة الرمز المميّز في عنوان HTTP، اضبط هذه القيمة على request.header.refresh_token. راجِع أيضًا طلب رموز الدخول ورموز التفويض.

عنصر <RelaunchTokenExpirationIn>

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

يفرض وقت انتهاء صلاحية الرموز المميزة لإعادة التحميل بالمللي ثانية. قيمة وقت انتهاء الصلاحية هي قيمة من إنشاء النظام بالإضافة إلى قيمة <RefreshTokenExpiresIn>. إذا تم ضبط <RefreshTokenExpiresIn> على -1، تنتهي صلاحية الرمز المميّز لإعادة التحميل وفقًا لالحد الأقصى لانتهاء صلاحية الرمز المميّز لإعادة تحميل OAuth. وإذا لم يتم تحديد السمة <RefreshTokenExpiresIn>، تكون صلاحية صلاحيتها غير محدّدة بشكل تلقائي.

يمكن أيضًا تحديد وقت انتهاء الصلاحية في وقت التشغيل باستخدام قيمة تلقائية غير ثابتة أو من خلال الإشارة إلى متغيّر التدفق. على سبيل المثال، يمكنك تخزين قيمة انتهاء صلاحية الرمز المميّز في خريطة قيمة أساسية واستردادها وتحديدها إلى متغيّر والإشارة إليها في السياسة. مثلاً: kvm.oauth.expires_in.

يحدد المقطع التالي متغير تدفق وقيمة تلقائية أيضًا. يُرجى العِلم أنّ قيمة متغيّر التدفق لها الأولوية على القيمة التلقائية المحدّدة.

<RefreshTokenExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</RefreshTokenExpiresIn>

سحابة إلكترونية خاصة: بالنسبة إلى تثبيت Edge الخاص للسحابة الإلكترونية، يتم ضبط القيمة التلقائية من خلال السمة conf_keymanagement_oauth_refresh_token_expiry_time_in_millis. لإعداد هذا الموقع:

1. افتح الملف message-processor.properties في محرِّر. إذا لم يكن الملف متاحًا، أنشئه:

   vi /opt/apigee/customer/application/message-processor.properties

2. اضبط السمة على النحو المطلوب:

   conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000

3. تأكَّد من أن ملف المواقع مملوك لمستخدم "apigee":

   chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

4. أعِد تشغيل معالج الرسائل.

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

عنصر <ResponseType>

<ResponseType>request.queryparam.response_type</ResponseType>

يُعلِم هذا العنصر Edge الذي يمنحه تطبيق العميل. ولا يُستخدم إلا مع رمز التفويض وخطوات نوع منح الإذن الضمني.

تبحث تلقائيًا شبكة Edge عن قيمة نوع الاستجابة في معلَمة طلب البحث response_type. إذا كنت تريد إلغاء هذا السلوك التلقائي، استخدِم العنصر <ResponseType> لضبط متغيّر التدفق الذي يحتوي على قيمة نوع الاستجابة. على سبيل المثال، إذا ضبطت هذا العنصر على request.header.response_type، يبحث تطبيق Edge عن نوع الاستجابة الذي سيتم تمريره في عنوان الطلب. يمكنك أيضًا الاطّلاع على طلب رموز الدخول ورموز الدخول.

عنصر <Reuse RefreshToken>

<ReuseRefreshToken>true</ReuseRefreshToken>

وعند ضبط السياسة على true، تتم إعادة استخدام الرمز المميّز الحالي لإعادة التحميل إلى أن تنتهي صلاحيته. إذا تم استخدام false، يتم إصدار رمز مميّز جديد لإعادة التحميل من خلال Apigee Edge عندما يتم تقديم رمز مميّز صالح لإعادة التحميل.

عنصر <النطاق>

<Scope>request.queryparam.scope</Scope>

إذا كان هذا العنصر متوفّرًا في إحدى سياسات generateAccessToken أو CreateAuthorizeCode، يتم استخدامه لتحديد النطاقات التي ستُمنَح الرمز المميّز أو الرمز. يتم عادةً تمرير هذه القيم إلى السياسة في الطلب الوارد من تطبيق عميل. ويمكنك ضبط العنصر لتتغير متغيّر التدفق، ما يمنحك خيار تحديد كيفية تمرير النطاقات في طلب. في المثال التالي، يشير request.queryparam.scope إلى أن النطاق يجب أن يكون معلَمة عن طلب البحث، على سبيل المثال، ?scope=READ. لطلب النطاق في عنوان HTTP، على سبيل المثال، اضبط هذه القيمة على request.header.scope.

إذا ظهر هذا العنصر في سياسة "VerifyAccessToken"، يتم استخدامه لتحديد النطاقات التي يجب أن تفرضها السياسة. بالنسبة إلى هذا النوع من السياسات، يجب أن تكون القيمة اسم نطاق "مشفّر" ولا يمكنك استخدام المتغيّرات. على سبيل المثال:

<Scope>A B</Scope>

يمكنك أيضًا الاطِّلاع على العمل باستخدام نطاقات OAuth2 وطلب رموز الدخول ورموز المصادقة.

عنصر <State>

<State>request.queryparam.state</State>

وفي الحالات التي يجب أن يرسل فيها تطبيق العميل معلومات الحالة إلى خادم التفويض، يتيح لك هذا العنصر تحديد المكان الذي يجب أن يبحث فيه Edge عن قيم الحالة. على سبيل المثال، يمكن إرساله كمعلمة طلب بحث أو في عنوان HTTP. وعادةً ما يتم استخدام قيمة الحالة كإجراء أمني لمنع هجمات CSRF.

على سبيل المثال، يشير request.queryparam.state إلى أنّ الحالة يجب أن تكون متوفّرة كمَعلمة طلب بحث، على سبيل المثال ?state=HjoiuKJH32. لطلب الحالة في عنوان HTTP مثلاً، يمكنك ضبط هذه القيمة على request.header.state. يمكنك أيضًا الاطّلاع على طلب رموز الدخول ورموز الدخول.

عنصر <StoreToken>

 <StoreToken>true</StoreToken> 

اضبط هذا العنصر على true عندما يكون العنصر <ExternalAuthorization> هو true. يطلب العنصر <StoreToken> من واجهة Apigee Edge تخزين رمز الوصول الخارجي. بخلاف ذلك، لن يستمر.

العنصر <supportedGrantType>>/<GrantType>

<SupportedGrantTypes>
    <GrantType>authorization_code</GrantType>
    <GrantType>client_credentials</GrantType>
    <GrantType>implicit</GrantType>
    <GrantType>password</GrantType>
</SupportedGrantTypes>

تحدِّد هذه السياسة أنواع المنح التي تتوافق مع نقطة نهاية رمز OAuth المميّز في Apigee Edge. ويمكن أن تدعم نقطة النهاية أنواعًا متعددة من المِنح (أي يمكن ضبط نقطة نهاية واحدة لتوزيع رموز الدخول لأنواع متعددة من المِنح). لمزيد من المعلومات حول نقاط النهاية، يُرجى الاطّلاع على فهم نقاط نهاية OAuth. يتم تمرير نوع المنح في طلبات الرموز المميّزة في المعلَمة grant_type.

في حال عدم تحديد أي من أنواع المِنح المتوافقة، تكون أنواع المِنح الوحيدة المسموح بها هي authorization_code وimplicit. راجِع أيضًا العنصر <GrantType> (وهو عنصر مستوى أعلى يتم استخدامه لتحديد مكان البحث عن Apigee Edge عن المعلَمة grant_type التي يتم تمريرها في طلب عميل). ستتأكّد شبكة Edge من أن قيمة المعلَمة grant_type تتطابق مع أحد أنواع المِنح المتوافقة.

العنصر <Tokens>/<Token>

يتم استخدامه مع عمليّتَي VerifyToken وinvalidateToken. يمكنك أيضًا الاطّلاع على الموافقة على رموز الدخول وإبطالها. يحدّد العنصر <Token> متغيّر التدفق الذي يحدّد مصدر الرمز المميّز الذي سيتم إبطاله. على سبيل المثال، إذا كان من المتوقّع أن يرسل مطوّرو البرامج رموز الدخول كمعلمات طلب بحث تحمل الاسم access_token، استخدِم request.queryparam.access_token مثلاً.

عنصر <UserName>

<UserName>request.queryparam.user_name</UserName>

يتم استخدام هذا العنصر مع نوع منح كلمة المرور فقط. بالنسبة إلى نوع منح كلمة المرور، يجب إتاحة بيانات اعتماد المستخدم (كلمة المرور واسم المستخدم) لسياسة OAuthV2. يتم استخدام العنصرين <PassWord> و<UserName> لتحديد المتغيرات حيث يمكن لتطبيق Edge العثور على هذه القيم. وإذا لم يتم تحديد هذه العناصر، من المتوقّع أن تعثر السياسة على القيم (تلقائيًا) في معلّمات النموذج باسم username وpassword. وفي حال عدم العثور على القيم، تعرض السياسة خطأً. يمكنك استخدام العنصرين <PassWord> و<UserName> للإشارة إلى أي متغيّر مسار يحتوي على بيانات الاعتماد.

على سبيل المثال، يمكنك تمرير اسم المستخدم في معلَمة طلب بحث وضبط العنصر <UserName> على النحو التالي: <UserName>request.queryparam.username</UserName>.لطلب اسم المستخدم في عنوان HTTP، اضبط هذه القيمة على request.header.username.

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

يمكنك أيضًا الاطّلاع على طلب رموز الدخول ورموز التفويض.

التحقق من رموز الدخول

بعد إعداد نقطة نهاية الرمز المميّز للخادم الوكيل لواجهة برمجة التطبيقات، يتم إرفاق سياسة OAuthV2 المقابلة التي تحدِّد العملية VerifyAccessToken بالتدفق الذي يعرِض المورد المحمي.

على سبيل المثال، لضمان أنّ جميع الطلبات الموجّهة إلى واجهة برمجة تطبيقات مسموح بها، تفرض السياسة التالية إثبات ملكية رمز الدخول:

<OAuthV2 name="VerifyOAuthAccessToken">
  <Operation>VerifyAccessToken</Operation>
</OAuthV2>

تم إرفاق السياسة بمورد واجهة برمجة التطبيقات المطلوب حمايته. للتأكّد من التحقّق من صحة جميع الطلبات المُرسَلة إلى واجهة برمجة تطبيقات، أرفِق السياسة بالطلب المسبق ProxyEndpoint من خلال الخطوات التالية:

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthAccessToken</Name></Step>
  </Request>
</PreFlow>

يمكن استخدام العناصر الاختيارية التالية لإلغاء الإعدادات التلقائية لعملية AccessAccessToken.

<OAuthV2 name="ValidateOauthScopePolicy">
  <Operation>VerifyAccessToken</Operation>
  <Scope>READ WRITE</Scope>
</OAuthV2>

يمكنك أيضًا الاطِّلاع على التحقُّق من رموز الدخول وطلب رموز الدخول ورموز التفويض.

تحديد مواقع متغيّرات الطلبات

وبالنسبة إلى كل نوع مِنح، تضع السياسة افتراضات حول الموقع الجغرافي أو المعلومات المطلوبة في رسائل الطلبات. تستند هذه الافتراضات إلى مواصفات OAuth 2.0. إذا كانت تطبيقاتك تحتاج إلى الانحراف عن مواصفات OAuth 2.0، يمكنك تحديد المواقع الجغرافية المتوقّعة لكل معلّمة. على سبيل المثال، عند التعامل مع رمز التفويض، يمكنك تحديد موقع رمز التفويض ومعرّف العميل ومعرّف الموارد المنتظم (URI) لإعادة التوجيه والنطاق. ويمكن تحديد هذه العناوين على أنها عناوين HTTP أو معلَمات طلب البحث أو معلّمات النموذج.

يوضّح المثال التالي كيفية تحديد موقع معلمات رمز التفويض المطلوبة على أنها عناوين HTTP:

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.header.client_id</ClientId>
  <RedirectUri>request.header.redirect_uri</RedirectUri>
  <Scope>request.header.scope</Scope>
  ...

أو إذا لزم الأمر لدعم قاعدة تطبيق العميل، يمكنك المزج بين العناوين ومَعلمات طلب البحث ومطابقتها:

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.queryparam.client_id</ClientId>
  <RedirectUri>request.queryparam.redirect_uri</RedirectUri>
  <Scope>request.queryparam.scope</Scope>
  ...

يمكن ضبط موقع واحد فقط لكل معلّمة.

متغيّرات التدفق

وتتم تعبئة متغيّرات التدفق المحدّدة في هذا الجدول عند تنفيذ سياسات OAuth المعنيّة، وبالتالي تكون متاحة للسياسات الأخرى أو للتطبيقات التي يتم تنفيذها في مسار الخادم الوكيل لواجهة برمجة التطبيقات.

عملية CheckAccessToken

يتم تنفيذ عملية CheckAccessToken، وتتم تعبئة عدد كبير من متغيّرات التدفق في سياق تنفيذ الخادم الوكيل. توفّر لك هذه المتغيّرات خصائص ذات صلة برمز الدخول وتطبيق المطوّرين ومطوّر البرامج والشركة. يمكنك استخدام سياسة "تخصيص الرسائل" أو JavaScript، على سبيل المثال، لقراءة أي من هذه المتغيّرات واستخدامها حسب الحاجة في وقت لاحق من خطوات العملية. ويمكن أن تكون هذه المتغيّرات مفيدة أيضًا لأغراض تصحيح الأخطاء.

المتغيّرات الخاصة بالرمز المميّز

المتغيّرات الخاصة بالتطبيقات

ترتبط هذه المتغيّرات بتطبيق المطوّر المرتبط بالرمز المميّز.

المتغيّرات الخاصة بمطوّر البرامج

وإذا كان app.appType هو "Company"، تتم تعبئة سمات الشركة وإذا كان app.appType هو "Developer"، يعني ذلك أن سمات مطوّر البرامج تتم تعبئتها.

المتغيّرات الخاصة بالشركة

وإذا كان app.appType هو "Company"، تتم تعبئة سمات الشركة وإذا كان app.appType هو "Developer"، يعني ذلك أن سمات مطوّر البرامج تتم تعبئتها.

عملية إنشاء رمز الإنشاء

يتم ضبط هذه المتغيّرات عند تنفيذ عملية generateتخويلCode بنجاح:

البادئة: oauthv2authcode.{policy_name}.{variable_name}

مثال: oauthv2authcode.GenerateCodePolicy.code

عمليات الإنشاء - AccessAccessToken وUpdate_Token

يتم إعداد هذه المتغيّرات عند تنفيذ عمليتَي CREATEAccessAccessToken وUpdateAccessToken بنجاح. يُرجى العِلم أنّ متغيّرات الرمز المميّز لإعادة التحميل لا تنطبق على مسار نوع منح بيانات اعتماد العميل.

البادئة: oauthv2accesstoken.{policy_name}.{variable_name}

مثال: oauthv2accesstoken.GenerateTokenPolicy.access_token

إنشاء رمز دخول مميز

يتم ضبط هذه المتغيّرات عند تنفيذ عملية CREATEAccessAccessImplicit بنجاح تدفق نوع المنح الضمني.

البادئة: oauthv2accesstoken.{policy_name}.{variable_name}

مثال: oauthv2accesstoken.RefreshTokenPolicy.access_token

مرجع الخطأ

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

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

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

أخطاء النشر

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

متغيّرات الخطأ

يتم ضبط هذه المتغيّرات عندما تؤدي هذه السياسة إلى حدوث خطأ في وقت التشغيل.

مثال على استجابة الخطأ

ويتم إرسال هذه الاستجابات مرة أخرى إلى العميل إذا كان العنصر <GenerateResponse> صحيحًا.

إذا كانت قيمة <GenerateResponse> true، ستعرض السياسة الأخطاء بهذا التنسيق للعمليات التي تنشئ رموزًا مميّزة ورموزًا. للحصول على قائمة كاملة، راجِع مرجع استجابة خطأ HTTP OAuth.

{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}

إذا كانت السياسة <GenerateResponse> هي true، ستعرض السياسة الأخطاء بهذه التنسيق للتحقق من صحة العمليات أو التحقّق منها. للحصول على قائمة كاملة، راجِع مرجع استجابة HTTP باستخدام بروتوكول OAuth.

{  
   {  
      "fault":{  
         "faultstring":"Invalid Access Token",
         "detail":{  
            "errorcode":"keymanagement.service.invalid_access_token"
         }
      }
   }

مثال على قاعدة خطأ

<FaultRule name=OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientResponse</Name>
        <Condition>(fault.name = "invalid_client") OR (fault.name = "InvalidClientIdentifier")</Condition>
    </Step>
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
        <Condition>(fault.name = "invalid_access_token")</Condition>
    </Step>
    <Condition>(oauthV2.failed = true) </Condition>
</FaultRule>

مخطط السياسة

يتم تحديد كل نوع من أنواع السياسات من خلال مخطط XML (.xsd). يمكنك الرجوع إلى مخططات السياسات على GitHub.

استخدام إعدادات OAuth التلقائية

يتم توفير كل مؤسسة (حتى مؤسسة تجريبية مجانية) على Apigee Edge باستخدام نقطة نهاية للرمز المميّز OAuth. يتم ضبط نقطة النهاية مسبقًا باستخدام السياسات في الخادم الوكيل لواجهة برمجة التطبيقات الذي يُسمى oauth. يمكنك البدء في استخدام نقطة نهاية الرمز المميّز فور إنشاء حساب على Apigee Edge. لمعرفة التفاصيل، يُرجى الاطّلاع على فهم نقاط نهاية OAuth.

إزالة رموز الدخول نهائيًا

تتم إزالة الرموز المميزة لبروتوكول OAuth2 تلقائيًا من نظام Apigee Edge بعد 3 أيام (259200 ثانية)، بعد انتهاء صلاحية كل من رمز الدخول والرمز المميَّز لإعادة التحميل (إذا كان متوفّرًا). وفي بعض الحالات، قد تحتاج إلى تغيير هذا الخيار التلقائي. على سبيل المثال، قد ترغب في تقليل وقت الإزالة النهائية لتوفير مساحة على القرص في حال إنشاء عدد كبير من الرموز المميّزة.

إذا كنت تستخدم Edge for Private Cloud، يمكنك تغيير الإعداد التلقائي من خلال ضبط خصائص المؤسسة كما هو موضَّح في هذا القسم. (تنطبق الإزالة النهائية للرموز المميّزة المنتهية الصلاحية لمدة 3 أيام على متصفِّح Edge المخصَّص للإصدار 4.19.01 من Cloud الخاص والإصدارات الأحدث). أما في الإصدارات الأقدم، تكون الفاصل الزمني التلقائي لإزالة البيانات هو 180 يومًا.)

تعديل إعدادات الإزالة النهائية لإصدار Edge الخاص على Cloud 4.16.01 والإصدارات الأحدث

ملاحظة: لن تتأثر سوى الرموز المميزة التي تم إنشاؤها بعد تطبيق هذه الإعدادات، ولا تنطبق الإعدادات على الرموز المميزة التي تم إنشاؤها سابقًا.

تعديل إعدادات الإزالة النهائية لـ Edge 4.15.07 من Edge الخاص

ملاحظة: لن تتأثر سوى الرموز المميزة التي تم إنشاؤها بعد هذه الإعدادات، ولا تنطبق الإعدادات على الرموز المميزة التي تم إنشاؤها سابقًا.

سلوك لا يتوافق مع معايير RFC

تعرض سياسة OAuthV2 استجابة للرمز المميّز تحتوي على سمات معيّنة غير متوافقة مع RFC. يعرض الجدول التالي السمات غير المتوافقة التي عرضتها سياسة OAuthV2 والخصائص المتوافقة معها.

بالإضافة إلى ذلك، تشير استجابة الخطأ للرمز المميّز لإعادة التحميل إلى أنّ grant_type = refresh_token:

{"ErrorCode" : "invalid_request", "Error" :"Refresh Token expired"}

ومع ذلك، فإن الاستجابة المتوافقة مع معيار RFC هي:

{"error" : "invalid_grant", "error_description" :"refresh token expired"}

مواضيع ذات صلة

• مقدّمة عن OAuth 2.0