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

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

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

حول هذا الموضوع

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

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

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

الأدوار

تحدّد الأدوار "الجهات الفاعلة" التي تشارك في عملية OAuth. لنلقِ نظرة سريعة على أدوار بيانات اعتماد العميل للمساعدة في توضيح مكان Apigee Edge. للحصول على مناقشة كاملة حول أدوار OAuth 2.0، راجِع مواصفات IETF 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 مع قيم معرّف العميل وسر العميل اللذين تم الحصول عليهما من تطبيق مطوّر مسجّل. بالإضافة إلى ذلك، يجب تمرير المَعلمة grant_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 في عنوان Authorization. لإجراء ذلك، عليك استخدام أداة أو برنامج ترميز base64 لترميز القيمتَين معًا مع الفصل بينهما بنقطتَين رأسيتَين. على سبيل المثال: aBase64EncodeFunction(clientidvalue:clientsecret). وبالتالي، سيتم ترميز المثال أعلاه على النحو التالي:

result = 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 ويتضمّن عنوان Authorization مع client_id + client+secret بترميز base64 ومعلمة طلب البحث grant_type=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 مع عملية VerifyAccessToken. تتحقّق هذه السياسة من أنّ الطلبات الواردة تتضمّن رمز دخول صالحًا. إذا كان الرمز المميز صالحًا، يعالج 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، عليك تقديم رمز دخول صالح. النمط الصحيح هو تضمين الرمز المميّز في عنوان Authorization، كما يلي: ملاحظة يُشار أيضًا إلى رمز الدخول باسم "رمز حامل مميّز".

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

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

مراجع إضافية

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