Povolení nebo zakázání řízení přístupu na základě role ve službě Azure AI Search

Azure AI Search ve výchozím nastavení používá ověřování založené na klíčích, ale plně podporuje ověřování a autorizaci Microsoft Entra ID pro všechny operace roviny řízení a roviny dat prostřednictvím řízení přístupu na základě role (RBAC).

Než budete moct přiřadit role pro autorizovaný přístup k rovině dat ke službě Azure AI Search, musíte ve vyhledávací službě povolit řízení přístupu na základě role. Role pro správu služeb (řídicí rovina) jsou integrované a není možné je povolit ani zakázat.

Poznámka:

Rovina dat odkazuje na operace s koncovým bodem vyhledávací služby, jako je indexování nebo dotazy nebo jakákoli jiná operace zadaná v rozhraních REST API vyhledávací služby nebo ekvivalentních klientských knihovnách Azure SDK. Řídicí rovina odkazuje na správu prostředků Azure, jako je vytvoření nebo konfigurace vyhledávací služby.

Požadavky

• Vyhledávací služba v libovolné oblasti, na libovolné úrovni, včetně bezplatné.

• Vlastník, Správce uživatelských přístupů nebo vlastní role s oprávněními Microsoft.Authorization/roleAssignments/write

Povolení přístupu na základě role pro operace roviny dat

Nakonfigurujte vyhledávací službu tak, aby rozpoznala autorizační hlavičku u žádostí o data, která poskytují přístupový token OAuth2.

Když povolíte role pro rovinu dat, změna se projeví okamžitě, ale před přiřazením rolí počkejte několik sekund.

Výchozí režim selhání pro neoprávněné požadavky je http401WithBearerChallenge. Případně můžete režim selhání nastavit na http403hodnotu .

Azure Portal

1. Přihlaste se k webu Azure Portal a otevřete stránku vyhledávací služby.

2. Vyberte Nastavení a pak v levém navigačním podokně vyberte Klíče .

   

3. Pokud aktuálně používáte klíče a potřebujete čas na převod klientů na řízení přístupu na základě role, zvolte řízení na základě role nebo obojí .

   Možnost	Popis
   Klíč rozhraní API	(výchozí). Vyžaduje klíče rozhraní API v hlavičce požadavku pro autorizaci.
   Řízení přístupu na základě role	K dokončení úkolu vyžaduje členství v přiřazení role. Vyžaduje také autorizační hlavičku požadavku.
   Oba	Požadavky jsou platné pomocí klíče rozhraní API nebo řízení přístupu na základě role, ale pokud zadáte obojí ve stejném požadavku, použije se klíč rozhraní API.

4. Pokud jako správce zvolíte přístup jen pro role, přiřaďte k vašemu uživatelskému účtu role roviny dat, abyste obnovili úplný přístup pro správu operací roviny dat na webu Azure Portal. Mezi role patří Přispěvatel vyhledávací služby, Přispěvatel dat indexu vyhledávání a Čtenář dat indexu vyhledávání. Pokud chcete ekvivalentní přístup, potřebujete první dvě role.

   Někdy může trvat pět až deset minut, než se přiřazení rolí projeví. Do té doby se na stránkách webu Azure Portal, která se používá pro operace roviny dat, zobrazí následující zpráva.

   

Azure CLI

Spusťte tento skript, který podporuje pouze role:

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

Nebo spusťte tento skript, který podporuje klíče i role:

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

Další informace najdete v tématu Správa Search Azure AI pomocí Azure CLI.

Azure PowerShell

Spuštěním tohoto příkazu nastavte typ ověřování jenom na role:

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

Nebo spusťte tento příkaz, který podporuje klíče i role:

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

Další informace najdete v tématu Správa Search Azure AI pomocí PowerShellu.

REST API

Pomocí rozhraní REST API pro správu vytvořte nebo aktualizujte službu ke konfiguraci služby pro řízení přístupu na základě role.

Všechna volání rozhraní REST API pro správu se ověřují prostřednictvím ID Microsoft Entra. Nápovědu k nastavení ověřených požadavků najdete v tématu Správa služby Azure AI Search pomocí REST.

1. Získejte nastavení služby, abyste mohli zkontrolovat aktuální konfiguraci.

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

2. Pomocí funkce PATCH aktualizujte konfiguraci služby. Následující úpravy umožňují přístup na základě rolí i klíčů. Pokud chcete konfiguraci jen pro role, přečtěte si téma Zakázání klíčů rozhraní API.

   V části "properties" nastavte "authOptions" na "aadOrApiKey". Vlastnost disableLocalAuth musí být false, aby bylo možné nastavit "authOptions".

   Volitelně můžete nastavit "aadAuthFailureMode" a určit, zda se 401 vrátí místo 403 při selhání ověřování. Platné hodnoty jsou http401WithBearerChallenge nebo 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"
               }
           }
       }
   }
   

Zakázání řízení přístupu na základě role

Řízení přístupu na základě role je možné zakázat pro operace roviny dat a místo toho použít ověřování založené na klíči. Můžete to udělat jako součást testovacího pracovního postupu, například k vyloučíte problémy s oprávněními.

Obrácení kroků, které jste použili dříve, abyste povolili přístup na základě role.

1. Přihlaste se k webu Azure Portal a otevřete stránku vyhledávací služby.

2. Vyberte Nastavení a pak v levém navigačním podokně vyberte Klíče .

3. Vyberte klíče rozhraní API.

Zakázání ověřování pomocí klíče rozhraní API

Přístup ke klíči nebo místní ověřování můžete ve službě zakázat, pokud používáte výhradně předdefinované role a ověřování Microsoft Entra. Zakázání klíčů rozhraní API způsobí, že vyhledávací služba odmítne všechny požadavky související s daty, které předávají klíč rozhraní API v hlavičce.

Klíče rozhraní API pro správu je možné zakázat, ale neodstranit. Klíče rozhraní API pro dotazy je možné odstranit.

K zakázání funkcí zabezpečení se vyžadují oprávnění vlastníka nebo přispěvatele.

Azure Portal

1. Na webu Azure Portal přejděte do vyhledávací služby.

2. V levém navigačním podokně vyberte Klíče.

3. Vyberte řízení přístupu na základě role.

Změna je efektivní okamžitě, ale před testováním počkejte několik sekund. Za předpokladu, že máte oprávnění přiřazovat role jako člen vlastníka, správce služeb nebo spolusprávce, můžete pomocí funkcí portálu otestovat přístup na základě role.

Azure CLI

Pokud chcete zakázat ověřování založené na klíči, nastavte -disableLocalAuth na true. Jedná se o stejnou syntaxi jako skript "povolit pouze role" uvedený v předchozí části.

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

Pokud chcete znovu povolit ověřování pomocí klíče, nastavte -disableLocalAuth na false. Vyhledávací služba obnoví přijetí klíčů rozhraní API na požadavku automaticky (za předpokladu, že jsou zadané).

Další informace najdete v tématu Správa Search Azure AI pomocí Azure CLI.

Azure PowerShell

Pokud chcete zakázat ověřování založené na klíčích, nastavte DisableLocalAuth na hodnotu true. Jedná se o stejnou syntaxi jako skript "povolit pouze role" uvedený v předchozí části.

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

Pokud chcete znovu povolit ověřování pomocí klíče, nastavte DisableLocalAuth na false. Vyhledávací služba obnoví přijetí klíčů rozhraní API na požadavku automaticky (za předpokladu, že jsou zadané).

Další informace najdete v tématu Správa Search Azure AI pomocí PowerShellu.

REST API

Pokud chcete zakázat ověřování založené na klíči, nastavte možnost disableLocalAuth na hodnotu true.

1. Získejte nastavení služby, abyste mohli zkontrolovat aktuální konfiguraci.

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

2. Pomocí funkce PATCH aktualizujte konfiguraci služby. Následující úpravy nastaví "authOptions" na hodnotu 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
       }
   }
   

Pokud chcete znovu povolit ověřování pomocí klíče, nastavte disableLocalAuth na false. Vyhledávací služba obnoví přijetí klíčů rozhraní API na požadavku automaticky (za předpokladu, že jsou zadané).

Účinky řízení přístupu na základě role

• Řízení přístupu na základě role může zvýšit latenci některých požadavků. Každá jedinečná kombinace prostředku služby (index, indexer, sady dovedností atd.) a instanční objekty aktivují kontrolu autorizace. Tyto kontroly autorizace můžou na požadavek přidat až 200 milisekund latence.

• Ve výjimečných případech, kdy požadavky pocházejí z velkého počtu různých instančních objektů, všechny cílení na různé prostředky služby (indexy, indexery atd.), je možné, aby autorizace kontrol měla za následek omezování. Omezování by se stalo pouze v případě, že se během sekundy použily stovky jedinečných kombinací prostředků vyhledávací služby a instančního objektu.

Další kroky

Nastavení rolí pro přístup k vyhledávací službě