تنفيذ نوع منح بيانات اعتماد العميل

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

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

معلومات عن هذا الموضوع

يقدّم هذا الموضوع وصفًا عامًا لنوع منح بيانات اعتماد عميل OAuth 2.0 ويناقش كيفية تنفيذ هذا الإجراء على Apigee Edge.

حالات الاستخدام

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

الأدوار

تحدد الأدوار "الممثلين" الذين يشاركون في عملية OAuth. لنلقِ نظرة سريعة على أدوار بيانات اعتماد العميل لتوضيح الدور الذي يؤديه Apigee Edge. للحصول على مناقشة كاملة بشأن أدوار OAuth 2.0، يمكنك الاطّلاع على مواصفات ITF OAuth 2.0.

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

عيّنة تعليمات برمجية

يمكنك العثور على نموذج لتنفيذ نوع منح بيانات اعتماد العميل كامل وفعّال على GitHub. يمكنك الاطّلاع على المراجع الإضافية أدناه للحصول على روابط إلى مزيد من الأمثلة.

مخطط التدفق

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

الخطوات في تدفق بيانات اعتماد العميل

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

شرط أساسي: يجب تسجيل تطبيق العميل في Apigee Edge للحصول على معرِّف العميل ومفاتيح سر العميل. يُرجى الاطّلاع على تسجيل تطبيقات العميل للحصول على مزيد من التفاصيل.

1- يطلب العميل رمز دخول.

لاستلام رمز الدخول، يرسل العميل POST طلب بيانات من واجهة برمجة التطبيقات إلى Edge مع قيم معرّف العميل وسر العميل التي تم الحصول عليها من تطبيق مطوّر برامج مسجَّل. بالإضافة إلى ذلك، يجب تمرير المعلَمة agent_type=client_credentials كمَعلمة طلب بحث. (ومع ذلك، يمكنك ضبط سياسة OAuthV2 لقبول هذه المعلَمة في عنوان الطلب أو نصه، لذا يُرجى الاطّلاع على سياسة OAuthV2 لمعرفة التفاصيل).

مثلاً:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials&client_id=ns4fQc14Zg4hKFCNaSzArVuwszX95X&client_secret=ZIjFyTsNgQNyxI'

ملاحظة: مع أنّه يمكنك تمرير قيمتَي client_id وclient_secret كمَعلمتَي طلب بحث كما هو موضّح أعلاه، يفضَّل تمريرهما كسلسلة عنوان URL بترميز base64 في عنوان التفويض. لإجراء ذلك، عليك استخدام أداة أو أداة ترميز base64 لترميز القيمتَين مع نقطتَين للفصل بينهما. على النحو التالي: aBase64EncodeFunction(clientidvalue:clientsecret). لذلك، سيتم ترميز المثال أعلاه على النحو التالي:

النتيجة = aBase64EncodeFunction(ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI) // لاحظ النقطتين التي تفصل بين القيمتين.

نتيجة ترميز base64 للسلسلة أعلاه هي: bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==

بعد ذلك، قم بإجراء طلب الرمز المميز على النحو التالي:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials' -H 'Authorization: Basic bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg=='

2. يتحقّق Edge من بيانات الاعتماد

لاحظ أنه يتم إرسال طلب واجهة برمجة التطبيقات إلى نقطة النهاية /accesstoken. تحتوي نقطة النهاية هذه على سياسة مرتبطة بها للتحقُّق من بيانات اعتماد التطبيق. ويعني ذلك أنّ السياسة تقارن بين المفاتيح التي تم إرسالها والمفاتيح التي أنشأها Apigee Edge عندما تم تسجيل التطبيق. لمعرفة المزيد من المعلومات حول نقاط نهاية OAuth على Edge، يُرجى الاطّلاع على ضبط نقاط نهاية OAuth وسياساته.

3. يعرض Edge استجابة

إذا كانت بيانات الاعتماد جيدة، يعرض Edge رمز الدخول للعميل. وإذا لم يكُن مطابقًا، سيتم عرض رسالة خطأ.

4. يستدعي العميل واجهة برمجة التطبيقات المحمية

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

ضبط المسارات والسياسات

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

تهيئة التدفق المخصص

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

<Flows>
  <Flow name="GetAccessToken">
         <!-- This policy flow is triggered when the URI path suffix
         matches /oauth/accesstoken. Publish this URL to app developers 
         to use when obtaining an access token using an auth code   
         -->
    <Condition>proxy.pathsuffix == "/oauth/accesstoken"</Condition>
    <Request>
        <Step><Name>GetAccessToken</Name></Step>
    </Request>
  </Flow>
</Flows>

ضبط المسار باستخدام سياسة

يجب إرفاق سياسة بنقطة النهاية على النحو التالي. راجِع إعداد نقاط نهاية وسياسات OAuth لإلقاء نظرة عامة سريعة على الخطوات اللازمة لإضافة سياسة OAuthV2 إلى نقطة نهاية الخادم الوكيل.

الحصول على رمز الدخول

يتم إرفاق هذه السياسة بمسار /accesstoken. ويستخدِم سياسة OAuthV2 مع عملية GenerateAccessToken المحدّدة.

<OAuthV2 name="GetAccessToken">
  <Operation>GenerateAccessToken</Operation>
  <ExpiresIn>3600000</ExpiresIn>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GenerateResponse/>
</OAuthV2>

إنّ طلب البيانات من واجهة برمجة التطبيقات للحصول على رمز الدخول هو طلب POST ويشتمل على عنوان تفويض يتضمّن Client_id + client+secret base64 ومَعلمة طلب البحث sitemap=client_credentials. يمكن أن تتضمن أيضًا معلمات اختيارية للنطاق والحالة. على سبيل المثال:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials' -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVgT1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ'

إرفاق سياسة رمز الدخول المميّز لإثبات الملكية

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

<OAuthV2 async="false" continueOnError="false" enabled="true" name="VerifyAccessToken">
    <DisplayName>VerifyAccessToken</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <SupportedGrantTypes/>
    <GenerateResponse enabled="true"/>
    <Tokens/>
</OAuthV2>

استدعاء واجهة برمجة التطبيقات المحمية

لطلب واجهة برمجة تطبيقات محمية باستخدام أمان OAuth 2.0، يجب تقديم رمز دخول صالح. النمط الصحيح هو تضمين الرمز المميز في عنوان التفويض، على النحو التالي: يُشار إلى رمز الدخول أيضًا باسم "رمز الحامل المميز".

$ curl -H "Authorization: Bearer UAj2yiGAcMZGxfN2DhcUbl9v8WsR" \
  http://myorg-test.apigee.net/v0/weather/forecastrss?w=12797282 

راجِع أيضًا إرسال رمز الدخول.

مراجع إضافية

• تقدِّم Apigee تدريبًا على الإنترنت لمطوّري واجهات برمجة التطبيقات، بما في ذلك دورة تدريبية حول أمان واجهة برمجة التطبيقات، بما في ذلك بروتوكول OAuth.
• سياسة OAuthV2 -- تتضمّن الكثير من الأمثلة التي تعرض كيفية إرسال طلبات إلى خادم التفويض وكيفية ضبط سياسة OAuthV2.