حماية واجهة برمجة تطبيقات في Azure API Management باستخدام تخويل OAuth 2.0 مع معرف Microsoft Entra

ينطبق على: جميع مستويات إدارة واجهة برمجة التطبيقات

في هذه المقالة، ستتعلم خطوات عالية المستوى لتكوين مثيل إدارة واجهة برمجة تطبيقات Azure لحماية واجهة برمجة التطبيقات، باستخدام بروتوكول OAuth 2.0 مع معرف Microsoft Entra.

للحصول على نظرة عامة تصورية حول تخويل واجهة برمجة التطبيقات، راجع المصادقة والتخويل لواجهات برمجة التطبيقات في APIM.

المتطلبات الأساسية

قبل اتباع الخطوات الواردة في هذه المقالة، يجب أن يكون لديك:

• مثيل إدارة API
• واجهة برمجة تطبيقات منشورة باستخدام مثيل إدارة واجهة برمجة التطبيقات API
• مستأجر Microsoft Entra

نظرة عامة

اتبع هذه الخطوات لحماية واجهة برمجة تطبيقات في APIM، باستخدام تخويل OAuth 2.0 مع معرف Microsoft Entra.

1. قم بتسجيل تطبيق (يسمى backend-app في هذه المقالة) في معرف Microsoft Entra.

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

2. قم بتكوين نهج validate-jwt في إدارة واجهة برمجة التطبيقات. تتحقق هذه السياسة من صحة الرمز المميز OAuth المقدم في كل طلب واجهة برمجة تطبيقات وارد. يمكن تمرير الطلبات الصالحة إلى واجهة برمجة التطبيقات.

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

تسجيل تطبيق في معرف Microsoft Entra لتمثيل واجهة برمجة التطبيقات

باستخدام مدخل Microsoft Azure، قم بحماية واجهة برمجة التطبيقات باستخدام معرف Microsoft Entra عن طريق تسجيل تطبيق يمثل واجهة برمجة التطبيقات أولا.

للحصول على تفاصيل حول تسجيل التطبيق، راجع التشغيل السريع: تكوين تطبيق لعرض واجهة برمجة تطبيقات الويب.

1. في مدخل Microsoft Azure، ابحث عن App registrations وحددها.

2. حدد تسجيل جديد.

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

   • في قسم الاسم ، أدخل اسم تطبيق ذي معنى، مثل backend-app. يتم عرض هذا الاسم لمستخدمي التطبيق.
   • في قسم أنواع الحسابات المدعومة، حدد خيارا يناسب السيناريو الخاص بك.

4. اترك قسم Redirect URI فارغا.

5. حدد Register لإنشاء التطبيق.

6. في صفحة نظرة عامة على التطبيق، ابحث عن قيمة معرف التطبيق (العميل) وسجلها لاحقا.

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

8. حدد الزر Add a scope لعرض صفحة Add a scope:

   1. أدخل اسم نطاق جديدا واسم عرض موافقة المسؤول ووصف موافقة المسؤول.
   2. تأكد من تحديد حالة النطاق الممكن .

9. حدد الزر Add scope لإنشاء النطاق.

10. تكرار الخطوتين السابقتين لإضافة كافة النطاقات التي يدعمها API الخاصة بك.

11. بمجرد إنشاء النطاقات، قم بتدوينها لاستخدامها لاحقًا.

قم بتكوين صورة التحقق من صحة JWT للمصادقة المسبقة على الطلبات

يتحقق نهج المثال التالي، عند إضافته إلى <inbound> قسم النهج، من قيمة مطالبة الجمهور في رمز وصول تم الحصول عليه من معرف Microsoft Entra الذي يتم تقديمه في عنوان التخويل. تقوم بإرجاع رسالة الخطأ إذا كان الرمز المميز غير صالح. تكوين هذا النهج في نطاق نهج مناسب للسيناريو الخاص بك.

• في openid-config عنوان URL، aad-tenant هو معرف المستأجر في معرف Microsoft Entra. ابحث عن هذه القيمة في مدخل Microsoft Azure، على سبيل المثال، في صفحة نظرة عامة لمورد Microsoft Entra. يفترض المثال الموضح تطبيق Microsoft Entra أحادي المستأجر ونقطة نهاية تكوين v2.
• قيمة claim هي معرف العميل للتطبيق الخلفي الذي قمت بتسجيله في معرف Microsoft Entra.

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/{aad-tenant}/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>{audience-value - (ex:api://guid)}</audience>
    </audiences>
    <issuers>
        <issuer>{issuer-value - (ex: https://sts.windows.net/{tenant id}/)}</issuer>
    </issuers>
    <required-claims>
        <claim name="aud">
            <value>{backend-app-client-id}</value>
        </claim>
    </required-claims>
</validate-jwt>

إشعار

يصنف عنوان URL openid-config يتوافق مع نقطة نهاية الإصدار 2. بالنسبة لنقطة النهاية v1 openid-config ، استخدم https://login.microsoftonline.com/{aad-tenant}/.well-known/openid-configuration.

للحصول على معلومات حول كيفية تكوين النهج، راجع تعيين أو تحرير النهج. راجع مرجع validate-jwt لمزيد من التخصيص على عمليات التحقق من صحة JWT. للتحقق من صحة JWT التي تم توفيرها بواسطة خدمة Microsoft Entra، توفر APIM أيضا النهج validate-azure-ad-token .

سير عمل التفويض

1. يحصل المستخدم أو التطبيق على رمز مميز من معرف Microsoft Entra مع أذونات تمنح حق الوصول إلى تطبيق الخلفية. إذا كنت تستخدم نقطة نهاية v2، فتأكد من تعيين الخاصية accessTokenAcceptedVersion إلى 2 في بيان التطبيق لتطبيق الواجهة الخلفية وأي تطبيق عميل تقوم بتكوينه.

2. تتم إضافة الرمز المميز في رأس التفويض لطلبات واجهة برمجة التطبيقات إلى APIM.

3. تتحقق APIM من صحة الرمز المميز باستخدام النهج validate-jwt.

   • إذا كان الطلب لا يحتوي على رمز مميز صالح، فإن APIM تحظره.

   • إذا كان الطلب يحتوي على رمز مميز صالح، يمكن للبوابة إعادة توجيه الطلب إلى واجهة برمجة التطبيقات.

المحتوى ذو الصلة

• لمعرفة المزيد حول كيفية إنشاء تطبيق وتنفيذ OAuth 2.0، راجع نماذج التعليمات البرمجية ل Microsoft Entra.

• للحصول على مثال شامل لتكوين تخويل مستخدم OAuth 2.0 في مدخل مطور APIM، راجع كيفية تخويل وحدة تحكم الاختبار لمدخل المطور عن طريق تكوين تخويل المستخدم OAuth 2.0.

• تعرف على المزيد حول معرف Microsoft Entra وOAuth2.0.

• للحصول على طرق أخرى لتأمين الخدمة الخلفية، راجع مصادقة الشهادة المتبادلة.