سياسة 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 name="attr_name1" ref="flow.variable" display="true|false">value1</Attribute>
    <Attribute name="attr_name2" ref="flow.variable" display="true|false">value2</Attribute>
</Attributes>

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

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

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

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

تذكَّر أنّه في حال ضبط عنصر 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 وعناصر "إدارة مفاتيح التشفير"

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

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

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

يتم تلقائيًا محو الرموز المميَّزة للوصول المنتهية الصلاحية من نظام 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>

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

عنصر <ExternalAuthorizationCode>

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

عنصر <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 على true. إذا كان الخيار 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>

تُحدِّد مكان البحث عن المَعلمة redirect_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. راجِع أيضًا مقالة طلب الرموز المميّزة للوصول ورموز التفويض.

عنصر <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.

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

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

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

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

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

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

عملية VerifyAccessToken

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

المتغيّرات المتعلّقة بالرمز المميّز

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

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

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

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

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

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

عملية GenerateAuthorizationCode

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

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

إذا كنت تستخدم Edge for Private Cloud، يمكنك تغيير هذا الإعداد التلقائي من خلال ضبط سمات المؤسسة كما هو موضّح في هذا القسم. (ينطبق الحذف خلال 3 أيام للعناصر التي انتهت صلاحيتها على الإصدار 4.19.01 من Edge for Private Cloud والإصدارات الأحدث. وبالنسبة إلى الإصدارات الأقدم، تبلغ الفاصل الزمني التلقائي للإزالة النهائية 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