Azure AI Search'te rol tabanlı erişim denetimini etkinleştirme veya devre dışı bırakma

Makale
06/18/2024

Azure AI Search'e yetkili erişim rolleri atayabilmeniz için önce arama hizmetinizde rol tabanlı erişim denetimini etkinleştirin.

Veri düzlemi işlemleri için rol tabanlı erişim isteğe bağlıdır, ancak daha güvenli bir seçenek olarak önerilir. Alternatif olarak , varsayılan olan anahtar tabanlı kimlik doğrulaması kullanılır.

Hizmet yönetimi (denetim düzlemi) rolleri yerleşik olarak bulunur ve etkinleştirilemiyor veya devre dışı bırakılamaz.

Not

Veri düzlemi, dizin oluşturma veya sorgular gibi arama hizmeti uç noktasına yönelik işlemleri ya da Arama REST API'sinde veya eşdeğer Azure SDK istemci kitaplıklarında belirtilen diğer işlemleri ifade eder.

Önkoşullar

Ücretsiz dahil olmak üzere herhangi bir bölgede, herhangi bir katmanda bir arama hizmeti.
Sahip, Kullanıcı Erişimi Yöneticisi veya Microsoft.Authorization/roleAssignments/write izinlerine sahip özel bir rol.

Veri düzlemi işlemleri için rol tabanlı erişimi etkinleştirme

Arama hizmetinizi OAuth2 erişim belirteci sağlayan veri isteklerinde yetkilendirme üst bilgisini tanıyacak şekilde yapılandırın.

Veri düzlemi için rolleri etkinleştirdiğinizde, değişiklik hemen geçerli olur, ancak rolleri atamadan önce birkaç saniye bekleyin.

Yetkisiz istekler için varsayılan hata modu şeklindedir http401WithBearerChallenge. Alternatif olarak, hata modunu olarak http403ayarlayabilirsiniz.

Azure portalında oturum açın ve arama hizmeti sayfasını açın.
Ayarlar'ı ve ardından sol gezinti bölmesinde Anahtarlar'ı seçin.

Şu anda anahtar kullanıyorsanız ve istemcileri rol tabanlı erişim denetimine geçirmeniz için zamana ihtiyacınız varsa Rol tabanlı denetim veya Her İkisi'ni seçin.

Seçenek	Açıklama
API Anahtarı	(varsayılan). Yetkilendirme için istek üst bilgisinde API anahtarları gerektirir.
Rol tabanlı erişim denetimi	Görevi tamamlamak için rol atamasında üyelik gerektirir. Ayrıca istekte bir yetkilendirme üst bilgisi gerektirir.
Her ikisi	İstekler API anahtarı veya rol tabanlı erişim denetimi kullanılarak geçerlidir, ancak ikisini de aynı istekte sağlarsanız API anahtarı kullanılır.

Yönetici olarak, yalnızca rollere yönelik bir yaklaşım seçerseniz, Azure portalında veri düzlemi işlemleri üzerinden tam yönetim erişimini geri yüklemek için kullanıcı hesabınıza veri düzlemi rolleri atayın. Roller arasında Arama Hizmeti Katkıda Bulunanı, Arama Dizini Veri Katkıda Bulunanı ve Arama Dizini Veri Okuyucusu yer alır. Eşdeğer erişim istiyorsanız üç rolü de kullanmanız gerekir.

Bazen rol atamalarının etkili olması beş ile on dakika sürebilir. Bu gerçekleşene kadar, veri düzlemi işlemleri için kullanılan portal sayfalarında aşağıdaki ileti görüntülenir.

Yalnızca rolleri desteklemek için bu betiği çalıştırın:

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

Ya da hem anahtarları hem de rolleri desteklemek için bu betiği çalıştırın:

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

Daha fazla bilgi için bkz. Azure CLI ile Azure AI Arama hizmeti yönetme.

Kimlik doğrulama türünü yalnızca rollere ayarlamak için şu komutu çalıştırın:

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

Ya da hem anahtarları hem de rolleri desteklemek için şu komutu çalıştırın:

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

Daha fazla bilgi için bkz. PowerShell ile Azure AI Arama hizmeti yönetme.

Hizmetinizi rol tabanlı erişim denetimi için yapılandırmak için Yönetim REST API'sini Oluşturma veya Güncelleştirme Hizmeti'ni kullanın.

Yönetim REST API'sine yapılan tüm çağrıların kimliği Microsoft Entra Kimliği aracılığıyla doğrulanır. Kimliği doğrulanmış istekleri ayarlama konusunda yardım için bkz . REST kullanarak Azure AI Arama'yı yönetme.

Geçerli yapılandırmayı gözden geçirebilmeniz için hizmet ayarlarını alın.

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

Hizmet yapılandırmasını güncelleştirmek için PATCH kullanın. Aşağıdaki değişiklikler hem anahtarlara hem de rol tabanlı erişime olanak tanır. Yalnızca roller yapılandırması istiyorsanız bkz . API anahtarlarını devre dışı bırakma.

"özellikler" bölümünde "authOptions" değerini "aadOrApiKey" olarak ayarlayın. "authOptions" ayarlamak için "disableLocalAuth" özelliği false olmalıdır.

İsteğe bağlı olarak, kimlik doğrulaması başarısız olduğunda 403 yerine 401'in döndürülip döndürülmeyeceğini belirtmek için "aadAuthFailureMode" değerini ayarlayın. Geçerli değerler :"http401WithBearerChallenge" veya "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"
            }
        }
    }
}
```

Rol tabanlı erişim denetimini devre dışı bırakma

Bunun yerine veri düzlemi işlemleri için rol tabanlı erişim denetimini devre dışı bırakmak ve anahtar tabanlı kimlik doğrulaması kullanmak mümkündür. Bunu bir test iş akışının parçası olarak, örneğin izin sorunlarını eleyebilirsiniz.

Rol tabanlı erişimi etkinleştirmek için daha önce izlediğiniz adımları tersine çevirin.

Azure portalında oturum açın ve arama hizmeti sayfasını açın.
Ayarlar'ı ve ardından sol gezinti bölmesinde Anahtarlar'ı seçin.
API Anahtarları'nı seçin.

API anahtarı kimlik doğrulamayı devre dışı bırakma

Yalnızca yerleşik rolleri ve Microsoft Entra kimlik doğrulamasını kullanıyorsanız, hizmetinizde anahtar erişimi veya yerel kimlik doğrulaması devre dışı bırakılabilir. API anahtarlarının devre dışı bırakılması, arama hizmetinin üst bilgide bir API anahtarı geçiren verilerle ilgili tüm istekleri reddetmesine neden olur.

Yönetici API anahtarları devre dışı bırakılabilir, ancak silinemez. Sorgu API anahtarları silinebilir.

Güvenlik özelliklerini devre dışı bırakmak için sahip veya Katkıda Bulunan izinleri gereklidir.

Azure portalında arama hizmetinize gidin.
Sol gezinti bölmesinde Anahtarlar'ı seçin.
Rol tabanlı erişim denetimi'ni seçin.

Değişiklik hemen geçerli olur, ancak test etmeden önce birkaç saniye bekleyin. Rolleri Sahip, hizmet yöneticisi veya ortak yönetici olarak atama izniniz olduğunu varsayarsak, rol tabanlı erişimi test etmek için portal özelliklerini kullanabilirsiniz.

Anahtar tabanlı kimlik doğrulamasını devre dışı bırakmak için -disableLocalAuth değerini true olarak ayarlayın. Bu, önceki bölümde sunulan "yalnızca rolleri etkinleştir" betiğiyle aynı söz dizimidir.

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

Anahtar kimlik doğrulamasını yeniden etkinleştirmek için -disableLocalAuth değerini false olarak ayarlayın. Arama hizmeti, istekte API anahtarlarının kabul edilmesini otomatik olarak sürdürür (belirtildiği varsayılarak).

Daha fazla bilgi için bkz. Azure CLI ile Azure AI Arama hizmeti yönetme.

Anahtar tabanlı kimlik doğrulamasını devre dışı bırakmak için DisableLocalAuth değerini true olarak ayarlayın. Bu, önceki bölümde sunulan "yalnızca rolleri etkinleştir" betiğiyle aynı söz dizimidir.

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

Anahtar kimlik doğrulamasını yeniden etkinleştirmek için DisableLocalAuth değerini false olarak ayarlayın. Arama hizmeti, istekte API anahtarlarının kabul edilmesini otomatik olarak sürdürür (belirtildiği varsayılarak).

Daha fazla bilgi için bkz. PowerShell ile Azure AI Arama hizmeti yönetme.

Anahtar tabanlı kimlik doğrulamasını devre dışı bırakmak için "disableLocalAuth" değerini true olarak ayarlayın.

Geçerli yapılandırmayı gözden geçirebilmeniz için hizmet ayarlarını alın.

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

Hizmet yapılandırmasını güncelleştirmek için PATCH kullanın. Aşağıdaki değişiklik "authOptions" değerini null olarak ayarlar.

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
    }
}

Anahtar kimlik doğrulamasını yeniden etkinleştirmek için "disableLocalAuth" değerini false olarak ayarlayın. Arama hizmeti, istekte API anahtarlarının kabul edilmesini otomatik olarak sürdürür (belirtildiği varsayılarak).

Sınırlamalar

Rol tabanlı erişim denetimi bazı isteklerin gecikme süresini artırabilir. Hizmet kaynağı (dizin, dizin oluşturucu vb.) ve hizmet sorumlusunun her benzersiz bileşimi bir yetkilendirme denetimi tetikler. Bu yetkilendirme denetimleri, istek başına 200 milisaniyeye kadar gecikme süresi ekleyebilir.
İsteklerin çok sayıda farklı hizmet sorumlusundan kaynaklandığı nadir durumlarda, tümü farklı hizmet kaynaklarını (dizinler, dizin oluşturucular vb.) hedefleyen durumlarda, yetkilendirme denetimlerinin azaltmaya neden olması mümkündür. Azaltma yalnızca arama hizmeti kaynağı ve hizmet sorumlusunun yüzlerce benzersiz bileşimi bir saniye içinde kullanıldığında gerçekleşir.

Sonraki adımlar

Arama hizmetine erişim için rolleri ayarlama

Aracılığıyla paylaş