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

Note

Azure AI Vyhledávač je k dispozici prostřednictvím portálu Azure, rozhraní REST API a Sady Azure SDK. Podporuje také Foundry IQ, spravovanou znalostní vrstvu, která transformuje podnikový obsah na opakovaně použitelné znalostní báze s podporou oprávnění pro agenty na portálu Microsoft Foundry.

Tento článek vysvětluje, jak povolit řízení přístupu na základě role (RBAC) pro operace roviny dat ve službě Azure AI Vyhledávač. Pokud je povoleno řízení přístupu na základě role, můžete místo klíčů rozhraní API použít ověřování Microsoft Entra ID.

Důležité

Při vytváření vyhledávací služby je výchozí ověřování založené na klíčích, ale není to nejbezpečnější možnost. Doporučujeme, abyste ho nahradili přístupem na základě role, jak je popsáno v tomto článku.

Je možné zakázat pouze role data plane. Role pro správu služeb (řídicí rovina) jsou integrované a není možné je povolit ani zakázat.

Pokud v protokolu aktivit vyhledávací služby určené pouze pro role zaznamenáte aktivitu související s klíči, jako je získání administrátorských klíčů, tyto akce jsou zahájeny v řídicí vrstvě a neovlivní váš obsah ani operace s ním spojené.

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 pro povolení RBAC
Po povolení RBAC potřebujete role roviny dat pro přístup k obsahu: Přispěvatel vyhledávací služby, Přispěvatel dat indexu vyhledávání a Čtenář dat indexu vyhledávání. Podrobnosti najdete v tématu Přiřazení rolí .

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 http403.

Na webu Azure Portal přejděte do vyhledávací služby.
Vyberte Nastavení a pak v levém podokně vyberte Klíče .

Zvolte řízení na základě role. 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 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 (doporučeno)	K dokončení úkolu je vyžadováno členství v přidělené roli. 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.

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.

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

Reference:aktualizace služby az search

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

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

Reference:Set-AzSearchService

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

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 Vyhledávač pomocí REST.

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

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

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=2025-05-01
{
    "properties": {
        "disableLocalAuth": false,
        "authOptions": {
            "aadOrApiKey": {
                "aadAuthFailureMode": "http401WithBearerChallenge"
            }
        }
    }
}
```
Úspěšná žádost se vrátí 200 OK s aktualizovanou konfigurací služby.

Referenční informace:Služby – Vytvoření nebo aktualizace

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čení problémů s oprávněními.

Zakázání řízení přístupu na základě role na webu Azure Portal:

Na webu Azure Portal přejděte do vyhledávací služby.
Vyberte Nastavení a pak v levém podokně vyberte Klíče .
Vyberte klíče rozhraní API.

Zakázat ověřování pomocí klíče 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.

Na webu Azure Portal přejděte do vyhledávací služby.
V levém navigačním podokně vyberte Klíče.
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.

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.

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.

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

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

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

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=2025-05-01
{
    "properties": {
        "disableLocalAuth": true
    }
}

Úspěšná žádost se vrátí 200 OK s aktualizovanou konfigurací služby.

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é).

Referenční informace:Služby – Vytvoření nebo aktualizace

Další kroky

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

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-01-24