سياسة 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>

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

وفقًا للإعدادات التلقائية، تتوقّع ميزة CheckAccessToken إرسال رمز الدخول في عنوان "التفويض" على أنّه رمز الحامل المميز. مثال:

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

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

العنصر <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 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. راجِع أيضًا طلب رموز الدخول ورموز التفويض.

عنصر<expirationIn>

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

عنصر <ExternalAuth>

<ExternalAuthorization>true</ExternalAuthorization>

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

العنصر <ExternalAuthCode>

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

العنصر <ExternalPreviewToken>

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

العنصر <DELETEToken>

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

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

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

العنصر <refreshTokenديسمبرIn>

<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 عن نوع الاستجابة ليتم تمريره في عنوان الطلب. راجِع أيضًا طلب رموز الدخول ورموز التفويض.

العنصر <ReuserefreshToken>

<ReuseRefreshToken>true</ReuseRefreshToken>

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

عنصر <Scope>

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

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

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

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

تُستخدَم مع عمليتَي التحقّق المتقدّم (التحقّق بخطوتين) ونموذج غير صالح للرمز المميّز. راجِع أيضًا الموافقة على رموز الدخول وإبطالها. يحدد العنصر <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 كما يلي:

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

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

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

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

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

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

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

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

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

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

عملية GenerateتفويضCode

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

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

مثال: ‎oauthv2authcode.GenerateCodePolicy.code

عمليات إنشاء GenerateAccessToken و منطقة ActivateAccessToken

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

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

مثال: ‎oauthv2accesstoken.GenerateTokenPolicy.access_token

GenerateAccessTokenImplicitGrant

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

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

مثال: ‎oauthv2accesstoken.RefreshTokenPolicy.access_token

مرجع الخطأ

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

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

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

أخطاء النشر

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

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

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

مثال على الردّ على الخطأ

يتم إرسال هذه الاستجابات إلى العميل إذا كان العنصر <GenerateResponse> true.

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

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

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

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

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

تحديث إعدادات الإزالة النهائية للإصدار 4.15.07 من Edge Private Cloud

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

سلوك غير متوافق مع 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