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

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

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

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

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

فيديو

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

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

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

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

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

مخطط المسار

يوضّح مخطط المسار التالي مسار OAuth لرمز التفويض مع استخدام Apigee Edge كخادم تفويض.

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

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

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

المتطلبات الأساسية: يجب تسجيل تطبيق العميل في Apigee Edge للحصول على معرّف العميل ومفاتيح سر العميل. لمعرفة التفاصيل، يُرجى الاطّلاع على تسجيل تطبيقات العميل لـ.

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

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

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

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

3- يمنح المستخدم الموافقة

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

4- يرسل تطبيق تسجيل الدخول طلبًا إلى Apigee Edge

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

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

عندما يتلقّى Edge طلب POST من تطبيق تسجيل الدخول على نقطة نهاية ‎ /authorizationcode، يحدث أمران. أولاً، يحدّد Edge أنّ تسجيل الدخول قد تم بنجاح (من خلال التحقّق من مَعلمات الطلب أو العناوين بحثًا عن مؤشر نجاح). بعد ذلك، يتحقّق Edge للتأكّد من أنّ عنوان URI لإعادة التوجيه الذي تم إرساله من تطبيق تسجيل الدخول يطابق عنوان URI لإعادة التوجيه الذي تم تحديده عند تسجيل التطبيق في Apigee Edge. إذا كان كل شيء على ما يرام، ينشئ Edge رمز تفويض.

{redirect_uri}?code={authorization_code}&state={some_string}

6- يستردّ العميل رمز التفويض ويطلب رمز دخول من 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'

7- يتلقّى العميل رمز دخول

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

8- يطلب العميل واجهة برمجة التطبيقات المحمية

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

$ 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 تم تحديد عملية GenerateAuthorizationCode لها).

أسهل طريقة لعرض إعداد المسار هي استخدام مثال 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 وscope وstate.

$ 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 مع تحديد عملية GenerateAuthorizationCode.

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

طلب البيانات من واجهة برمجة التطبيقات للحصول على رمز التفويض هو طلب POST ويتطلّب تمرير الـ client_id وresponse_type وredirect_uri، بالإضافة إلى scope وstate اختياريًا، في نص الطلب كمعلَمات نموذج، كما هو موضّح في هذا المثال:

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

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

هذه السياسة مرفقة بالمسار ‎/oauth/accesstoken. يستخدم سياسة OAuthV2 مع تحديد عملية GenerateAccessToken. في هذه الحالة، من المتوقّع أن تكون المَعلمة grant_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=authorization_code وscope اختياريًا. على سبيل المثال:

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

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

إرفاق سياسة التحقّق من رمز الدخول

أرفِق سياسة VerifyAccessToken (سياسة OAuthV2 مع تحديد عملية VerifyAccessToken ) ببداية أي مسار يصل إلى واجهة برمجة تطبيقات محمية، بحيث يتم تنفيذها في كل مرة يتم فيها تلقّي طلب لموارد محمية. يتحقّق 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

يمكنك أيضًا الاطّلاع على إرسال رمز دخول.