تنفيذ نوع منح رمز التفويض

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

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

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

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

حملة فيديو

يمكنك مشاهدة فيديو قصير لمعرفة كيفية استخدام نوع منح تفويض OAuth 2.0 لتأمين واجهات برمجة التطبيقات.

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

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

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

يمكنك العثور على نموذج كامل وفعّال لتنفيذ نوع منح رمز التفويض على Apigee Edge في مستودع api-platform-samples على GitHub. يمكنك الاطّلاع على نموذج oauth-advanced في دليل api-platform- sample/sample-proxies. راجِع ملف README للحصول على تفاصيل عن النموذج.

مخطط التدفق

يوضِّح الرسم البياني التالي للتدفق تدفق OAuth لرمز التفويض مع تشغيل Apigee Edge كخادم تفويض.

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

الخطوات في مسار رمز التفويض

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

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

1- يبدأ المستخدم التدفق

عندما يحتاج التطبيق إلى الوصول إلى موارد المستخدم المحمية من خادم موارد (على سبيل المثال، قائمة جهات الاتصال على موقع إلكتروني على وسائل التواصل الاجتماعي)، يُرسِل التطبيق طلب بيانات من واجهة برمجة التطبيقات إلى Apigee Edge، ما يتحقّق من صحة رقم تعريف العميل ويعيد توجيه متصفّح المستخدم، إذا كان صالحًا، إلى صفحة تسجيل دخول حيث سيُدخِل المستخدم بيانات اعتماده. ويتضمن طلب البيانات من واجهة برمجة التطبيقات المعلومات التي حصل عليها تطبيق العميل عند تسجيله: معرّف العميل ومعرّف الموارد المنتظم (URI) لإعادة التوجيه.

2. إدخال المستخدم لبيانات الاعتماد

يرى المستخدم الآن صفحة تسجيل دخول يُطلب منه إدخال بيانات اعتماد تسجيل الدخول. إذا تم تسجيل الدخول بنجاح، سننتقل إلى الخطوة التالية.

3. يمنح المستخدم موافقته.

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

4. يرسل تطبيق تسجيل الدخول طلب Apigee Edge

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

5. ينشئ Apigee Edge رمز تفويض

عندما يتلقى Edge طلب GET من تطبيق تسجيل الدخول على نقطة نهاية /Authorizecode (رمز التفويض)، يحدث أمران. أولاً، يحدّد متصفّح Edge أنّ عملية تسجيل الدخول تمت بنجاح (من خلال التحقّق من حالة HTTP أو وسائل أخرى). يتحقّق Next Edge من أنّ معرّف الموارد المنتظم (URI) لإعادة التوجيه، والذي تم إرساله من تطبيق تسجيل الدخول، يتطابق مع معرّف الموارد المنتظم (URI) لإعادة التوجيه الذي تم تحديده عند تسجيل التطبيق في Apigee Edge. إذا كان كل شيء على ما يرام، سينشئ Edge رمز تفويض. مثال:

http://myorg-test.apigee.net/oauth/authorizationcode?client_id={consumer_key}&response_type=code&redirect_uri={redirect_uri}&scope=scope1%20scope2&state={some_string}

6. يرسل Edge رمز التفويض مرة أخرى إلى العميل

يرسل Edge إلى العميل عملية إعادة التوجيه 302 مع رمز المصادقة المرفق كمعلَمة طلب بحث.

7. يسترد العميل رمز التفويض ويطلب رمز دخول من Edge.

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

$ curl https://{org_name}-test.apigee.net/my_oauth_proxy/accesstoken?code=Xyz123&grant_type=authorization_code -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpKNhGar6K&client_secret=hAr4GngA9vAyvI4'

8. يتلقى العميل رمز دخول

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

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

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

$ curl -H "Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

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

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

• إنشاء تدفقات مخصّصة
• إضافة سياسات OAuthV2 وإعدادها

ضبط التدفق المخصَّص

يمكنك عادةً إعداد مسار نوع المنحة هذا بحيث يتم تحديد كل خطوة أو "خطوة" من التدفق من خلال التدفق في الخادم الوكيل Apigee Edge. يتضمن كل مسار نقطة نهاية وسياسة تؤدي المهمة الخاصة ببروتوكول OAuth المطلوبة، مثل إنشاء رمز تفويض أو رمز دخول. على سبيل المثال، كما هو موضّح في ملف XML أدناه، تحتوي نقطة نهاية /oauth/authorizationcode على سياسة مرتبطة تُسمى GenerateAuthCode (وهي سياسة OAuthV2 لها عملية GenerateUsageCode محددة).

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

راجِع أيضًا مثال على التنفيذ على GitHub.

<Flows>
  <Flow name="RedirectToLoginApp">
         <!-- 
         Publish this URI to developers to use for their 'login' link 
         -->
    <Condition>proxy.pathsuffix == "/oauth/authorize"</Condition>
    <Request>
        <Step><Name>RedirectToLoginPage</Name></Step>
    </Request>
  </Flow>
  <Flow name="GetAuthCode">
         <!-- 
         Call this URL from your Login app after you authenticate the user.
         The policy will automatically return the auth code in the response to the 
         redirect_uri registered by the calling app 
         -->
    <Condition>proxy.pathsuffix == "/oauth/authorizationcode"</Condition>
    <Request>
        <Step><Name>GenerateAuthCode</Name></Step>
    </Request>
  </Flow>
  <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>GenerateAccessToken</Name></Step>
    </Request>
  </Flow>
</Flows>

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

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

إعادة توجيه تسجيل الدخول

هذا هو مسار /oauth/authorize. تكون السياسة المرفقة مسؤولة عن إعادة توجيه المستخدم إلى تطبيق تسجيل دخول، حيث يمكن للمستخدم النهائي إجراء مصادقة وتفويض لتطبيق العميل للوصول إلى موارده المحمية بدون الكشف عن اسم المستخدم وكلمة المرور لتطبيق العميل. ويمكنك إجراء ذلك باستخدام سياسة وسيلة شرح الخدمة أو JavaScript أو Node.js أو وسائل أخرى.

إنّ طلب البيانات من واجهة برمجة التطبيقات لتنفيذ الطلب هو GET ويتطلب معلَمات طلب البحث client_id وResponse_type وredirect_uri والنطاق والحالة.

$ curl http://myorg-test.apigee.net/oauth/authorize?client_id={consumer_key}&response_type=code&redirect_uri={redirect_uri}&scope=scope1%20scope2&state={some_string}

الحصول على رمز المصادقة

هذا هو مسار /oauth/authorizationcode. ويستخدِم سياسة OAuthV2 مع تحديد عملية GenerateAuthorizeCode (رمز التفويض).

<OAuthV2 async="false" continueOnError="false" enabled="true" name="GetAuthCode">
    <DisplayName>GetAuthCode</DisplayName>
    <Operation>GenerateAuthorizationCode</Operation>
    <ExpiresIn>600000</ExpiresIn>
    <GenerateResponse/>
</OAuthV2>

إنّ طلب البيانات من واجهة برمجة التطبيقات للحصول على رمز التفويض هو GET ويتطلب معلَمات طلب البحث client_id وResponse_type بالإضافة إلى النطاق والحالة اختياريًا، كما هو موضّح في المثال التالي:

$curl http://myorg-test.apigee.net/oauth/authorizationcode?client_id={consumer_key}&response_type=code&scope=scope1%20scope2&state={some_string}

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

يتم إرفاق هذه السياسة بمسار /oauth/accesstoken. ويستخدِم سياسة OAuthV2 مع عملية GenerateAccessCode المحدّدة. في هذه الحالة، يكون من المتوقّع أن تكون المَعلمة custom_type كمَعلمة طلب بحث:

<OAuthV2 name="GetAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>360000000</ExpiresIn> 
    <SupportedGrantTypes> 
        <GrantType>authorization_code</GrantType> 
    </SupportedGrantTypes> 
    <GrantType>request.queryparam.grant_type</GrantType> 
    <GenerateResponse/> 
</OAuthV2>

إنّ طلب البيانات من واجهة برمجة التطبيقات للحصول على رمز الدخول هو طلب POST ويجب أن يتضمّن client_id وclient_secret وGrant_type=authorized_code بالإضافة إلى النطاق اختياريًا. مثال:

$ curl https://{org_name}-test.apigee.net/oauth/accesstoken?grant_type=authorization_code -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K&client_secret=hAr4Gn0gA9vAyvI4'

هذا مجرد ملخّص أساسي. يتضمن مثال الإنتاج العديد من السياسات الأخرى لإنشاء عناوين URL وإجراء عمليات تحويل وتنفيذ مهام أخرى. يمكنك الرجوع إلى العيّنة على GitHub للاطّلاع على مشروع كامل ومكتمل.

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

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

<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 

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