مشاركة عبر

مصادقة الوصول إلى واجهات برمجة تطبيقات Azure OpenAI وتخويله باستخدام Azure API Management

  • مقالة

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

في هذه المقالة، ستتعرف على طرق المصادقة والتخويل لنقاط نهاية Azure OpenAI API التي تتم إدارتها باستخدام Azure API Management. توضح هذه المقالة الطرق الشائعة التالية:

  • المصادقة - المصادقة على واجهة برمجة تطبيقات Azure OpenAI باستخدام النهج التي تصادق باستخدام مفتاح API أو هوية مدارة لمعرف Microsoft Entra.

  • التخويل - لمزيد من التحكم في الوصول الدقيق، قم بالمصادقة المسبقة على الطلبات التي تمرر رموز OAuth 2.0 المميزة التي تم إنشاؤها بواسطة موفر هوية مثل معرف Microsoft Entra.

للحصول على الخلفية، راجع:

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

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

المصادقة باستخدام مفتاح API

الطريقة الافتراضية للمصادقة على واجهة برمجة تطبيقات Azure OpenAI هي باستخدام مفتاح API. بالنسبة لهذا النوع من المصادقة، يجب أن تتضمن جميع طلبات واجهة برمجة التطبيقات مفتاح API صالحا api-key في رأس HTTP.

  • يمكن لإدارة واجهة برمجة التطبيقات إدارة مفتاح API بطريقة آمنة، باستخدام قيمة مسماة.
  • يمكن بعد ذلك الرجوع إلى القيمة المسماة في نهج واجهة برمجة التطبيقات لتعيين api-key العنوان في الطلبات إلى واجهة برمجة تطبيقات Azure OpenAI. نقدم مثالين لكيفية القيام بذلك: أحدهما يستخدم النهج set-backend-service ، والآخر يستخدم النهج set-header .

تخزين مفتاح API بقيمة مسماة

  1. الحصول على مفتاح API من مورد Azure OpenAI. في مدخل Microsoft Azure، ابحث عن مفتاح في صفحة Keys and Endpoint لمورد Azure OpenAI.
  2. انتقل إلى مثيل API Management، وحدد القيم المسماة في القائمة اليمنى.
  3. حدد + إضافة، وأضف القيمة كبيانات سرية، أو بشكل اختياري لمزيد من الأمان، استخدم مرجع key vault.

تمرير مفتاح واجهة برمجة التطبيقات في طلبات واجهة برمجة التطبيقات - تعيين نهج الخدمة الخلفية

  1. إنشاء خلفية تشير إلى واجهة برمجة تطبيقات Azure OpenAI.

    1. في القائمة اليسرى لمثيل API Management، حدد Backends.
    2. حدد + إضافة، وأدخل اسما وصفيا للواجهة الخلفية. مثال: openai-backend.
    3. ضمن النوع، حدد مخصص، وأدخل عنوان URL لنقطة نهاية Azure OpenAI. مثال:https://contoso.openai.azure.com/openai.
    4. ضمن Authorization credentials، حدد Headers، وأدخل api-key كاسم العنوان والقيمة المسماة كقيمة.
    5. حدد إنشاء.

  2. أضف مقتطف النهج التالي set-backend-service في inbound قسم النهج لتمرير مفتاح API في الطلبات إلى واجهة برمجة تطبيقات Azure OpenAI.

    في هذا المثال، مورد الواجهة الخلفية هو openai-backend.

    <set-backend-service backend-id="openai-backend" />

تمرير مفتاح واجهة برمجة التطبيقات في طلبات واجهة برمجة التطبيقات - نهج رأس المجموعة

بدلا من ذلك، أضف مقتطف النهج التالي set-header في inbound قسم النهج لتمرير مفتاح API في الطلبات إلى واجهة برمجة تطبيقات Azure OpenAI. تقوم قصاصة النهج هذه بتعيين api-key العنوان بالقيمة المسماة التي قمت بإعدادها.

في هذا المثال، القيمة المسماة في APIM هي openai-api-key.

<set-header name="api-key" exists-action="override">
    <value>{{openai-api-key}}</value>
</set-header>

المصادقة باستخدام هوية مدارة

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

فيما يلي خطوات لتكوين مثيل API Management لاستخدام هوية مدارة لمصادقة الطلبات إلى واجهة برمجة تطبيقات Azure OpenAI.

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

  2. قم بتعيين الهوية المدارة دور مستخدم OpenAI للخدمات المعرفية، المحدد في نطاق المورد المناسب. على سبيل المثال، قم بتعيين الهوية المدارة المعينة من قبل النظام دور مستخدم OpenAI للخدمات المعرفية على مورد Azure OpenAI. للحصول على خطوات مفصلة، راجع التحكم في الوصول المستند إلى الدور لخدمة Azure OpenAI.

  3. أضف مقتطف النهج التالي في inbound قسم النهج لمصادقة الطلبات إلى واجهة برمجة تطبيقات Azure OpenAI باستخدام الهوية المدارة.

    في هذا المثال:

    • يحصل النهج authentication-managed-identity على رمز مميز للوصول للهوية المدارة.
    • يعين Authorization النهج set-header رأس الطلب مع رمز الوصول المميز.
    <authentication-managed-identity resource="https://cognitiveservices.azure.com" output-token-variable-name="managed-id-access-token" ignore-error="false" /> 
<set-header name="Authorization" exists-action="override"> 
    <value>@("Bearer " + (string)context.Variables["managed-id-access-token"])</value> 
</set-header>

تخويل OAuth 2.0 باستخدام موفر الهوية

لتمكين وصول أكثر دقة إلى واجهات برمجة تطبيقات OpenAPI من قبل مستخدمين أو عملاء معينين، يمكنك المصادقة المسبقة على الوصول إلى واجهة برمجة تطبيقات Azure OpenAI باستخدام تخويل OAuth 2.0 مع معرف Microsoft Entra أو موفر هوية آخر. للحصول على خلفية، راجع حماية واجهة برمجة تطبيقات في Azure API Management باستخدام تخويل OAuth 2.0 مع معرف Microsoft Entra.

إشعار

استخدم تفويض OAuth 2.0 كجزء من استراتيجية دفاعية متعمقة. إنه ليس بديلا لمصادقة مفتاح API أو مصادقة الهوية المدارة إلى واجهة برمجة تطبيقات Azure OpenAI.

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

  1. أنشئ تطبيقا في موفر الهوية الخاص بك لتمثيل OpenAI API في Azure API Management. إذا كنت تستخدم معرف Microsoft Entra، فسجل تطبيقا في مستأجر معرف Microsoft Entra. سجل تفاصيل مثل معرف التطبيق وURI للجمهور.

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

  2. أضف مقتطف inbound نهج في مثيل APIM للتحقق من صحة الطلبات التي تقدم رمز ويب JSON المميز (JWT) في Authorization العنوان. ضع هذه القصاصة البرمجية قبل النهج الأخرى inbound التي قمت بتعيينها للمصادقة على واجهة برمجة تطبيقات Azure OpenAI.

    إشعار

    توضح الأمثلة التالية البنية العامة للنهج للتحقق من صحة JWT. قم بتخصيصها لموفر الهوية ومتطلبات التطبيق وواجهة برمجة التطبيقات.

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

      <validate-azure-ad-token tenant-id={{TENANT_ID}} header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <client-application-ids>
            <application-id>{{CLIENT_APP_ID}}</application-id>
    </client-application-ids>
   <audiences>
        <audience>...</audience> 
    </audiences>
    <required-claims>
        <claim name=...>
            <value>...</value>
        </claim>
    </required-claims>
</validate-azure-ad-token>

    • validate-jwt - إذا كنت تستخدم موفر هوية آخر، فكون validate-jwt النهج للتحقق من صحة الجمهور والمطالبات في JWT. للحصول على التفاصيل، راجع مرجع النهج.

      <validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url={{OPENID_CONFIGURATION_URL}} />
    <issuers>
        <issuer>{{ISSUER_URL}}</issuer>
    </issuers>
    <audiences>
        <audience>...</audience> 
    </audiences>
    <required-claims>
        <claim name=...>
            <value>...</value>
        </claim>
    </required-claims>
</validate-jwt>

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