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

Makale
01/18/2025

Azure AI Search, tüm denetim düzlemi ve veri düzlemi işlemleri için anahtarsız ve anahtar tabanlı kimlik doğrulamasını destekler. Azure rol tabanlı erişim denetimi (RBAC) aracılığıyla tüm denetim düzlemi ve veri düzlemi işlemleri için Microsoft Entra Id kimlik doğrulaması ve yetkilendirmesini kullanabilirsiniz.

Önemli

Arama hizmeti oluşturduğunuzda, anahtar tabanlı kimlik doğrulaması varsayılandır, ancak en güvenli seçenek değildir. Bu makalede açıklandığı gibi rol tabanlı erişimle değiştirmenizi öneririz.

Azure AI Search'e yetkili veri düzlemi erişimi için roller atayabilmeniz için önce arama hizmetinizde rol tabanlı erişim denetimini etkinleştirmeniz gerekir. 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 Hizmeti REST API'lerinde veya eşdeğer Azure SDK istemci kitaplıklarında belirtilen diğer işlemleri ifade eder. Denetim düzlemi , arama hizmeti oluşturma veya yapılandırma gibi Azure kaynak yönetimini 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 hizmetinize gidin.
Ayarlar'ı ve ardından sol gezinti bölmesinde Anahtarlar'ı seçin.

Rol tabanlı denetim'i seçin. Yalnızca şu anda anahtar kullanıyorsanız ve istemcileri rol tabanlı erişim denetimine geçirmeniz için zamana ihtiyacınız varsa Her İkisi seçeneğini belirleyin.

Seçenek	Açıklama
API Anahtarı (varsayılan)	Yetkilendirme için istek üst bilgisinde API anahtarları gerektirir.
Rol tabanlı erişim denetimi (önerilir)	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 ilk iki rol 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 Azure 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.

Azure portalında rol tabanlı erişim denetimini devre dışı bırakmak için:

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

Sonraki adımlar

Arama hizmetine erişim için rolleri ayarlama

Aracılığıyla paylaş