سياسة OAuthV2

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

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

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

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

&lt;DisplayName&gt; عنصر

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

<DisplayName>Policy Display Name</DisplayName>

العنصر <AccessToken>

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

تتوقّع الدالة VerifyAccessToken تلقائيًا إرسال رمز الدخول في العنوان 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>

تتوقّع الدالة VerifyAccessToken تلقائيًا إرسال رمز الدخول في عنوان Authorization كرمز Bearer. على سبيل المثال:

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

في الوقت الحالي، Bearer هو البادئة الوحيدة المتاحة.

عنصر <AppEndUser>

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

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

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

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

<Attributes/Attribute>

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

في عدة حالات، يجب أن يرسل تطبيق العميل معرّف العميل إلى خادم التفويض. يحدّد هذا العنصر أنّ Apigee يجب أن يبحث عن معرّف العميل في متغيّر التدفق 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>

<ExpiresIn>10000</ExpiresIn>

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

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

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

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

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

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

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

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

السحابة الإلكترونية الخاصة: عند تثبيت Edge for Private Cloud، يتم ضبط القيمة التلقائية من خلال السمة 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 التابع لجهات خارجية.

العنصر <ExternalAuthorization>

<ExternalAuthorization>true</ExternalAuthorization>

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

العنصر <ExternalAuthorizationCode>

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

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

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

العنصر <ExternalRefreshToken>

<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 التابع لجهات خارجية.

العنصر <GenerateResponse>

<GenerateResponse enabled='true'/>

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

{
  "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 يتم التعبير عنها بالثواني في الرد.

العنصر <GenerateErrorResponse>

<GenerateErrorResponse enabled='true'/>

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

<GrantType>

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

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

على سبيل المثال، يشير 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) الخاصة بإعادة التوجيه

يتم استخدام معرّفات الموارد المنتظمة لإعادة التوجيه مع رمز التفويض وأنواع منح الإذن الضمني. يحدّد معرّف الموارد المنتظم لإعادة التوجيه الخادم المفوّض (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. لفرض استخدام RedirectUri في عنوان HTTP، مثلاً، اضبط هذه القيمة على request.header.redirect_uri. راجِع أيضًا طلب رموز الدخول ورموز التفويض.

العنصر <RefreshToken>

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

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

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

العنصر <RefreshTokenExpiresIn>

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

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

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

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

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

السحابة الإلكترونية الخاصة: عند تثبيت Edge for Private Cloud، يتم ضبط القيمة التلقائية من خلال السمة 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 عن نوع الاستجابة المطلوب تمريره في عنوان الطلب. راجِع أيضًا طلب رموز مميّزة للوصول ورموز تفويض.

العنصر <ReuseRefreshToken>

<ReuseRefreshToken>true</ReuseRefreshToken>

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

العنصر <Scope>

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

إذا كان هذا العنصر متوفّرًا في إحدى سياستي GenerateAccessToken أو GenerateAuthorizationCode، يتم استخدامه لتحديد النطاقات التي سيتم منح الرمز المميّز أو الرمز لها. يتم عادةً تمرير هذه القيم إلى السياسة في الطلب من تطبيق عميل. يمكنك ضبط العنصر لقبول متغيّر سير العمل، ما يتيح لك اختيار طريقة تمرير النطاقات في الطلب. في المثال التالي، يشير 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 بتخزين رمز الدخول الخارجي. وإلا لن يتم الاحتفاظ بها.

العنصر <SupportedGrantTypes>/<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>

يُستخدَم مع عمليتَي ValidateToken و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>

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

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

يمكن استخدام العناصر الاختيارية التالية لتجاوز الإعدادات التلقائية لعملية VerifyAccessToken.

<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 المعنية، وبالتالي تكون متاحة للسياسات أو التطبيقات الأخرى التي يتم تنفيذها في تدفق خادم وكيل API.

عملية VerifyAccessToken

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

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

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

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

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

إذا كانت قيمة app.appType هي "Company"، سيتم ملء سمات الشركة، وإذا كانت قيمة app.appType هي "Developer"، سيتم ملء سمات المطوّر.

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

إذا كانت قيمة app.appType هي "Company"، سيتم ملء سمات الشركة، وإذا كانت قيمة app.appType هي "Developer"، سيتم ملء سمات المطوّر.

عملية GenerateAuthorizationCode

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

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

مثال: oauthv2authcode.GenerateCodePolicy.code

عمليتَي GenerateAccessToken وRefreshAccessToken

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

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

مثال: oauthv2accesstoken.GenerateTokenPolicy.access_token

GenerateAccessTokenImplicitGrant

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

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

مثال: oauthv2accesstoken.RefreshTokenPolicy.access_token

مرجع الأخطاء

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

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

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

أخطاء النشر

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

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

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

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

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

إذا كانت قيمة <GenerateResponse> هي صحيح، تعرض السياسة أخطاء بهذا التنسيق للعمليات التي تُنشئ الرموز المميّزة والرموز. للحصول على قائمة كاملة، يُرجى الاطّلاع على مرجع استجابة خطأ بروتوكول 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 التلقائية

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

إزالة رموز الدخول

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

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

تعديل إعدادات الحذف في Edge Private Cloud 4.16.01 والإصدارات الأحدث

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

تعديل إعدادات الحذف في Edge Private Cloud 4.15.07

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

السلوك غير المتوافق مع طلب التعليقات (RFC)

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

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

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

ومع ذلك، فإنّ الرد المتوافق مع RFC هو:

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

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

• مقدّمة حول بروتوكول OAuth 2.0