مشاركة عبر

كيفية تأمين واجهات برمجة التطبيقات باستخدام مصادقة شهادة العميل في إدارة 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

للحصول على التفاصيل، راجع تكوين الشبكة عند إعداد APIM في شبكة ظاهرية.

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

راجع Prerequisites for key vault integration.

هام

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

تنبيه

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

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

  1. في مدخل Microsoft Azure، انتقل إلى مثيل APIM.

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

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

  4. في المعرف، أدخل اسما.

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

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

    هام

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

  7. في Client identity، حدد هوية معينة من قبل النظام أو هوية مدارة معينة من قبل المستخدم. لمزيد من المعلومات، راجع استخدام الهويات المدارة في Azure API Management.

    إشعار

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

  8. حدد إضافة.

    لقطة شاشة توضح كيفية إضافة شهادة key vault إلى APIM في المدخل.

  9. حدد حفظ.

تحميل شهادة

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

  1. في مدخل Microsoft Azure، انتقل إلى مثيل APIM.

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

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

  4. في المعرف، أدخل اسما.

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

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

  7. حدد إضافة.

    لقطة شاشة لتحميل شهادة عميل إلى APIM في المدخل.

  8. حدد حفظ.

إشعار

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

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

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

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

التفاوض على الشهادة الخاصة بالعميل

مستوى الاستهلاك أو الإصدار 2 الأساسي أو الإصدار القياسي 2 أو Premium v2

لتلقي شهادات العميل والتحقق منها في مستوى Consumption أو Basic v2 أو Standard v2 أو Premium v2، يجب تمكين إعداد طلب شهادة العميل على جزء Custom domains كما هو موضح أدناه.

طلب الشهادة الخاصة بالعميل

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

استخدم نهج التحقق من صحة شهادة العميل للتحقق من صحة سمات واحدة أو أكثر من شهادة عميل المستخدمة للوصول إلى واجهات برمجة التطبيقات المستضافة في مثيل 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 كيلوبايت أو أكبر. لمنع حدوث هذه المشكلة قم بتشغيل إعداد "التفاوض على شهادة العميل" من اجل أسماء المضيفين المطلوبة على نصل "المجالات المخصصة" كما هو موضح في الصورة الأولى من هذا المستند. لا تتوفر هذه الميزة في مستوى الاستهلاك.

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