تمكين أو تعطيل التحكم في الوصول المستند إلى الدور في Azure الذكاء الاصطناعي Search

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

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

أدوار إدارة الخدمة (وحدة التحكم) مضمنة ولا يمكن تمكينها أو تعطيلها.

إشعار

يشير مستوى البيانات إلى العمليات مقابل نقطة نهاية خدمة البحث، مثل الفهرسة أو الاستعلامات، أو أي عملية أخرى محددة في Search REST API أو مكتبات عميل Azure SDK المكافئة.

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

• خدمة بحث في أي منطقة، على أي مستوى، بما في ذلك مجانا.

• المالك أو مسؤول وصول المستخدم أو دور مخصص مع أذونات Microsoft.Authorization/roleAssignments/write .

تمكين الوصول المستند إلى الدور لعمليات مستوى البيانات

قم بتكوين خدمة البحث الخاصة بك للتعرف على عنوان تخويل على طلبات البيانات التي توفر رمز وصول OAuth2.

عند تمكين الأدوار لمستوى البيانات، يكون التغيير فعالا على الفور، ولكن انتظر بضع ثوان قبل تعيين الأدوار.

وضع الفشل الافتراضي للطلبات غير المصرح بها هو http401WithBearerChallenge. بدلا من ذلك، يمكنك تعيين وضع الفشل إلى http403.

مدخل Microsoft Azure

1. سجل الدخول إلى مدخل Microsoft Azure وافتح صفحة خدمة البحث.

2. حدد الإعدادات ثم حدد المفاتيح في جزء التنقل الأيمن.

   

3. اختر التحكم المستند إلى الدور أو كلاهما إذا كنت تستخدم المفاتيح حاليا وتحتاج إلى وقت لانتقال العملاء إلى التحكم في الوصول المستند إلى الدور.

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

4. كمسؤول، إذا اخترت نهج الأدوار فقط، فقم بتعيين أدوار مستوى البيانات إلى حساب المستخدم الخاص بك لاستعادة الوصول الإداري الكامل عبر عمليات مستوى البيانات في مدخل Microsoft Azure. تتضمن الأدوار "مساهم خدمة البحث" و"مساهم بيانات فهرس البحث" و"قارئ بيانات فهرس البحث". تحتاج إلى جميع الأدوار الثلاثة إذا كنت تريد الوصول المكافئ.

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

   

Azure CLI

قم بتشغيل هذا البرنامج النصي لدعم الأدوار فقط:

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --disable-local-auth

أو قم بتشغيل هذا البرنامج النصي لدعم كل من المفاتيح والأدوار:

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --aad-auth-failure-mode http401WithBearerChallenge `
  --auth-options aadOrApiKey

لمزيد من المعلومات، راجع إدارة الذكاء الاصطناعي خدمة البحث Azure باستخدام Azure CLI.

Azure PowerShell

قم بتشغيل هذا الأمر لتعيين نوع المصادقة إلى أدوار فقط:

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -DisableLocalAuth 1

أو قم بتشغيل هذا الأمر لدعم كل من المفاتيح والأدوار:

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -AuthOption AadOrApiKey

لمزيد من المعلومات، راجع إدارة الذكاء الاصطناعي خدمة البحث Azure باستخدام PowerShell.

واجهة برمجة التطبيقات REST

استخدم Management REST API Create or Update Service لتكوين الخدمة الخاصة بك للتحكم في الوصول المستند إلى الدور.

تتم مصادقة جميع الاستدعاءات إلى Management REST API من خلال معرف Microsoft Entra. للحصول على تعليمات حول إعداد الطلبات المصادق عليها، راجع إدارة Azure الذكاء الاصطناعي Search باستخدام REST.

1. احصل على إعدادات الخدمة بحيث يمكنك مراجعة التكوين الحالي.

   GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
   

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

   ضمن "properties"، قم بتعيين "authOptions" إلى "aadOrApiKey". يجب أن تكون الخاصية "disableLocalAuth" خاطئة لتعيين "authOptions".

   اختياريا، قم بتعيين "aadAuthFailureMode" لتحديد ما إذا كان يتم إرجاع 401 بدلا من 403 عند فشل المصادقة. القيم الصالحة هي "http401WithBearerChallenge" أو "http403".

   PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
   {
       "properties": {
           "disableLocalAuth": false,
           "authOptions": {
               "aadOrApiKey": {
                   "aadAuthFailureMode": "http401WithBearerChallenge"
               }
           }
       }
   }
   

تعطيل التحكم في الوصول المستند إلى الدور

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

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

1. سجل الدخول إلى مدخل Microsoft Azure وافتح صفحة خدمة البحث.

2. حدد الإعدادات ثم حدد المفاتيح في جزء التنقل الأيمن.

3. حدد API Keys.

تعطيل مصادقة مفتاح API

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

يمكن تعطيل مفاتيح واجهة برمجة تطبيقات المسؤول، ولكن لا يمكن حذفها. يمكن حذف مفاتيح واجهة برمجة تطبيقات الاستعلام.

أذونات المالك أو المساهم مطلوبة لتعطيل ميزات الأمان.

مدخل Microsoft Azure

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

2. في جزء التنقل الأيسر، حدد Keys.

3. حدد التحكم في الوصول المستند إلى الدور.

التغيير فعال على الفور، ولكن انتظر بضع ثوان قبل الاختبار. بافتراض أن لديك الإذن لتعيين الأدوار كعضو في المالك أو مسؤول الخدمة أو المسؤول المشترك، يمكنك استخدام ميزات المدخل لاختبار الوصول المستند إلى الدور.

Azure CLI

لتعطيل المصادقة المستندة إلى المفتاح، قم بتعيين -disableLocalAuth إلى true. هذا هو نفس بناء الجملة مثل البرنامج النصي "تمكين الأدوار فقط" المعروض في القسم السابق.

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --disable-local-auth

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

لمزيد من المعلومات، راجع إدارة الذكاء الاصطناعي خدمة البحث Azure باستخدام Azure CLI.

Azure PowerShell

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

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -DisableLocalAuth 1

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

لمزيد من المعلومات، راجع إدارة الذكاء الاصطناعي خدمة البحث Azure باستخدام PowerShell.

واجهة برمجة التطبيقات REST

لتعطيل المصادقة المستندة إلى المفتاح، قم بتعيين "disableLocalAuth" إلى true.

1. احصل على إعدادات الخدمة بحيث يمكنك مراجعة التكوين الحالي.

   GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
   

2. استخدم PATCH لتحديث تكوين الخدمة. يعين التعديل التالي "authOptions" إلى null.

   PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
   {
       "properties": {
           "disableLocalAuth": true
       }
   }
   

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

القيود

• يمكن أن يزيد التحكم في الوصول المستند إلى الدور من زمن انتقال بعض الطلبات. تؤدي كل مجموعة فريدة من مورد الخدمة (الفهرس والمفهرس وما إلى ذلك) ومدير الخدمة إلى إجراء فحص للتخويل. يمكن أن تضيف عمليات التحقق من التخويل هذه ما يصل إلى 200 مللي ثانية من زمن الانتقال لكل طلب.

• في حالات نادرة حيث تنشأ الطلبات من عدد كبير من أساسيات الخدمة المختلفة، وجميعها تستهدف موارد خدمة مختلفة (الفهارس، والمفهرسات، وما إلى ذلك)، من الممكن أن تؤدي عمليات التحقق من التخويل إلى تقييد. لن يحدث التقييد إلا إذا تم استخدام مئات المجموعات الفريدة من مورد خدمة البحث ومدير الخدمة في غضون ثانية.

---

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

إعداد أدوار للوصول إلى خدمة بحث