كيفية تأمين واجهات برمجة التطبيقات باستخدام مصادقة شهادة العميل في إدارة API

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

توفر APIM القدرة على تأمين الوصول إلى واجهات برمجة التطبيقات (أي العميل إلى APIM) باستخدام شهادات العميل ومصادقة TLS المتبادلة. يمكنك التحقق من صحة الشهادات المقدمة من قبل العميل المعيّن والتحقق من خصائص الشهادة مقابل القيم المطلوبة باستخدام تعبيرات النهج.

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

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

خيارات الشهادة

للتحقق من صحة الشهادة، يمكن لإدارة واجهة برمجة التطبيقات التحقق من الشهادات المدارة في مثيل APIM الخاص بك. إذا اخترت استخدام إدارة واجهة برمجة التطبيقات لإدارة شهادات العميل، فلديك الخيارات التالية:

• الرجوع إلى شهادة تمت إدارتها في Azure Key Vault
• إضافة ملف شهادة مباشرة في إدارة API

يوصى باستخدام شهادات key vault لأنها تساعد على تحسين أمان إدارة API:

• يمكن إعادة استخدام الشهادات المخزنة في key vaults عبر الخدمات
• يمكن تطبيق نهج الوصول الدقيق على الشهادات المخزنة في key vaults
• يتم تدوير الشهادات المحدثة في key vault تلقائيًا في إدارة API. بعد التحديث في key vault، يتم تحديث شهادة في إدارة API في غضون 4 ساعات. يمكنك أيضًا تحديث الشهادة يدويًا باستخدام مدخل Azure أو عبر إدارة REST API.

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

• إذا لم تنشئ بعد مثيل خدمة إدارة API، راجع إنشاء مثيل خدمة إدارة API.

• تحتاج إلى الوصول إلى الشهادة وكلمة المرور للإدارة في Azure key vault أو تحميله إلى خدمة إدارة API. يجب أن تكون الشهادة بتنسيق CER أو PFX. يسمح بالشهادات الموقعة ذاتيًا.

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

  إشعار

  شهادات المرجع المصدق للتحقق من صحة الشهادة غير مدعومة في مستوى الاستهلاك.

المتطلبات الأساسية لدمج key vault الرئيسية

1. إذا لم يكن لديك مخزن مفاتيح بالفعل، فبادر بإنشاء مخزن. لمعرفة خطوات إنشاء مخزن مفاتيح، راجع التشغيل السريع: إنشاء مخزن مفاتيح باستخدام مدخل Microsoft Azure.

   لإنشاء شهادة أو استيرادها إلى مخزن المفاتيح، راجع التشغيل السريع: تعيين شهادة واستردادها من Azure Key Vault باستخدام مدخل Microsoft Azure.

2. تمكين managed identity معينة من قبل النظام أو المعينة من قبل المستخدم في مثيل APIM.

تكوين الوصول إلى key vault

1. في المدخل، انتقل إلى key vault.

2. في القائمة اليسرى، حدد Access configuration، ولاحظ نموذج الإذن الذي تم تكوينه.

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

   لإضافة نهج الوصول إلى مخزن المفاتيح:
   

   1. في القائمة اليسرى، حدد Access policies.
   2. في صفحة Access policies ، حدد + Create.
   3. في علامة التبويب أذونات، ضمن أذونات سرية، حدد الحصول على وقائمة، ثم حدد التالي.
   4. في علامة التبويب Principal ، حدد principal، وابحث عن اسم المورد للهوية المدارة، ثم حدد Next. إذا كنت تستخدم هوية معينة من قِبل النظام، فإن الأساسي هو اسم مثيل إدارة API الخاص بك.
   5. حدد التالي مرة أخرى. حدد Review + create من علامة التبويب، حدد Create.

   لتكوين الوصول إلى Azure RBAC:
   

   1. على الجانب الأيسر، حدد التحكم بالوصول (IAM).
   2. في صفحة Access control (IAM)، حدد Add role assignment.
   3. في علامة التبويب Role ، حدد Key Vault Certificate User.
   4. في علامة التبويب Members ، حدد Managed identity>+ Select members.
   5. في صفحة تحديد الهوية المدارة، حدد الهوية المدارة المعينة من قبل النظام أو الهوية المدارة المعينة من قبل المستخدم المقترنة بمثيل إدارة واجهة برمجة التطبيقات، ثم حدد تحديد.
   6. حدد مراجعة + تعيين.

متطلبات جدار الحماية Key Vault

إذا تم تمكين جدار الحماية Key Vault على مخزن المفاتيح الخاص بك، فيما يلي متطلبات إضافية:

• يجب عليك استخدام الهوية المُدارة المعينة من قبل النظام لمثيل إدارة APIM للوصول إلى مخزن المفاتيح.

• في جدار الحماية Key Vault، قم بتمكين الخيار Allow Trusted Microsoft Services to bypass this firewall.

• تأكد من أن عنوان IP للعميل المحلي لديك مسموح له بالوصول إلى مخزن المفاتيح مؤقتاً خلال تحديد شهادة أو سر لإضافته إلى Azure API M. للحصول على مزيدٍ من المعلومات، راجع تكوين إعدادات شبكة Azure Key Vault.

  بعد إكمال التكوين، يمكنك حظر عنوان العميل الخاص بك في جدار حماية مخزن المفاتيح.

متطلبات الشبكة الافتراضية

إذا تم توزيع مثيل إدارة APIM في شبكة ظاهرية، فقم أيضاً بتكوين إعدادات الشبكة التالية:

• قم بتمكين نقطة نهاية الخدمة في Azure Key Vault على الشبكة الفرعية لإدارة APIM.
• قم بتكوين قاعدة مجموعة أمان الشبكة (NSG) للسماح بنسبة استخدام الشبكة الصادرة إلى علامات خدمة AzureKeyVault وAzureActiveDirectory service tags.

للتفاصيل راجع تكوين الشبكة عند إعداد إدارة واجهة برمجة التطبيقات Azure في VNET.

إضافة شهادة key vault

راجع Prerequisites for key vault integration.

هام

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

تنبيه

عند استخدام شهادة key vault في إدارة API، احرص على عدم حذف الشهادة أو key vault أو الهوية المُدارة المستخدمة للوصول إلى key vault.

لإضافة شهادة key vault إلى إدارة API:

1. في مدخل Azure، انتقل إلى مثيل API Management الخاص بك.

2. ضمن System، حدد Certificates.

3. حدد شهادات>+ إضافة.

4. في المعرف، أدخل اسمًا من اختيارك.

5. في الشهادة، حدد Key vault.

6. أدخل معرف شهادة key vault، أو اختر تحديد لتحديد شهادة من key vault.

   هام

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

7. في Client identity، حدد هوية مُدارة معينة من قِبل النظام أو هوية مُدارة معينة من قِبل المستخدم. تعرف على كيفية إضافة أو تعديل الهويات المُدارة في خدمة API Management.

   إشعار

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

8. حدد إضافة.

   

9. حدد حفظ.

تحميل شهادة

لتحميل شهادة عميل إلى إدارة API:

1. في مدخل Azure، انتقل إلى مثيل API Management الخاص بك.

2. ضمن System، حدد Certificates.

3. حدد شهادات>+ إضافة.

4. في المعرف، أدخل اسمًا من اختيارك.

5. في الشهادة، حدد Key vault.

6. استعرض لتحديد ملف الشهادة .pfx، وأدخل كلمة المرور الخاصة به.

7. حدد إضافة.

   

8. حدد حفظ.

إشعار

إذا كنت ترغب فقط في استخدام الشهادة لمصادقة العميل باستخدام APIM، يمكنك تحميل ملف CER.

تمكين مثيل APIM لتلقي شهادات العميل والتحقق منها

مستوى المطور أو الأساسي أو القياسي أو المتميز

لتلقي شهادات العميل والتحقق منها عبر HTTP/2 في المستويات Developer أو Basic أو Basic v2 أو Standard أو Standard v2 أو Premium، يجب تمكين إعداد التفاوض على شهادة العميل على شفرة المجال المخصص كما هو موضح أدناه.

مُستوى الاستهلاك

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

نهج للتحقق من صحة الشهادات الخاصة بالعميل

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

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

التحقق من صحة الشهادة مع المتغيرات الخاصة بالسياق

يمكنك أيضًا إعداد تعبيرات النهج مع context المتغير للتحقق من شهادات العميل. تظهر الأمثلة في المقاطع التالية التعبيرات من خلال استخدام context.Request.Certificate الخاصية context وخصائص أخرى.

إشعار

قد لا تعمل مصادقة الشهادة المتبادلة بشكل صحيح عند عرض نقطة نهاية بوابة إدارة واجهة برمجة التطبيقات من خلال بوابة التطبيق. وذلك لأن بوابة التطبيق تعمل كموازن تحميل الطبقة 7، وإنشاء اتصال SSL مميز مع خدمة إدارة واجهة برمجة التطبيقات الخلفية. وبالتالي، لن تتم إعادة توجيه الشهادة المرفقة من قبل العميل في طلب HTTP الأولي إلى APIM. ومع ذلك، كحل بديل، يمكنك إرسال الشهادة باستخدام خيار متغيرات الخادم. للحصول على إرشادات مفصلة، راجع متغيرات خادم المصادقة المتبادلة.

هام

• بدءًا من مايو 2021،context.Request.Certificateتطلب الشهادة فقط عندما يتم تعيين الخاصية من قِبل مثيل APIM إلىhostnameConfigurationnegotiateClientCertificateTrue. negotiateClientCertificate يتم تعيين إلى خطأ بصفة افتراضية.
• إذا تم تعطيل إعادة التفاوض على TLS في العميل الخاص بك، فقد ترى أخطاء TLS عند طلب الشهادة باستخدام الخاصية context.Request.Certificate. في حالة حدوث ذلك، قم بتمكين إعدادات إعادة التفاوض على TLS في العميل.
• إعادة التفاوض على الشهادة غير مدعومة في مستويات API Management v2.

التحقق من المُصدّر والموضوع

يمكن تكوين النهج أدناه للتحقق من المُصدّر وموضوع شهادة العميل:

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify() || context.Request.Certificate.Issuer != "trusted-issuer" || context.Request.Certificate.SubjectName.Name != "expected-subject-name")" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

إشعار

لتعطيل التحقق من قائمة إبطال الشهادة، استخدم context.Request.Certificate.VerifyNoRevocation() بدلا من context.Request.Certificate.Verify(). إذا كانت شهادة العميل موقعة ذاتيا، يجب تحميل شهادة (شهادات) CA الجذر (أو المتوسط) إلى APIM من أجل context.Request.Certificate.Verify() وcontext.Request.Certificate.VerifyNoRevocation() للعمل.

إمكانية التحقق من بصمة الإبهام

يمكن تكوين النهج أدناه للتحقق من بصمة الإبهام الخاصة بشهادة عميل:

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify() || context.Request.Certificate.Thumbprint != "DESIRED-THUMBPRINT-IN-UPPER-CASE")" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

إشعار

لتعطيل التحقق من قائمة إبطال الشهادة، استخدم context.Request.Certificate.VerifyNoRevocation() بدلا من context.Request.Certificate.Verify(). إذا كانت شهادة العميل موقعة ذاتيا، يجب تحميل شهادة (شهادات) CA الجذر (أو المتوسط) إلى APIM من أجل context.Request.Certificate.Verify() وcontext.Request.Certificate.VerifyNoRevocation() للعمل.

التحقق من بصمة الإبهام مقابل الشهادات التي تم تحميلها إلى APIM

يوضح المثال التالي كيفية التحقق من بصمة الإبهام الخاصة بشهادة عميل مقابل الشهادات التي تم تحميلها إلى APIM:

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify()  || !context.Deployment.Certificates.Any(c => c.Value.Thumbprint == context.Request.Certificate.Thumbprint))" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

إشعار

لتعطيل التحقق من قائمة إبطال الشهادة، استخدم context.Request.Certificate.VerifyNoRevocation() بدلا من context.Request.Certificate.Verify(). إذا كانت شهادة العميل موقعة ذاتيا، يجب تحميل شهادة (شهادات) CA الجذر (أو المتوسط) إلى APIM من أجل context.Request.Certificate.Verify() وcontext.Request.Certificate.VerifyNoRevocation() للعمل.

تلميح

يمكن أن تظهر مشكلة حالة التوقف التام لشهادة العميل الموضحة في هذهالمقالة نفسها بعدة طرق، مثل تجميد الطلبات، الطلبات التي تؤدي403 Forbiddenإلى حالة تعليمة برمجية بعد انتهاء المهلة،context.Request.Certificateهوnull. تؤثر هذه المشكلة عادة POST على PUT الطلبات مع محتوى يبلغ طوله حوالي 60 كيلوبايت أو أكبر. لمنع حدوث هذه المشكلة قم بتشغيل إعداد "التفاوض على شهادة العميل" من اجل أسماء المضيفين المطلوبة على نصل "المجالات المخصصة" كما هو موضح في الصورة الأولى من هذا المستند. لا تتوفر هذه الميزة في مستوى الاستهلاك.

الخطوات التالية

• كيفية تأمين خدمات الواجهة الخلفية باستخدام مصادقة شهادة العميل
• كيفية إضافة شهادة CA مخصصة في Azure API Management
• تعرف على النهج المتبع في API Management