Microsoft Entra Id kullanarak bir arama uygulamasına erişim yetkisi verme

  • Makale

Azure AI Search üzerinde oluşturulan arama uygulamaları artık kimliği doğrulanmış ve yetkili erişim için Microsoft kimlik platformu kullanabilir. Azure'da kimlik sağlayıcısı Microsoft Entra Id'dir. Microsoft Entra Id kullanmanın önemli avantajlarından biri, kimlik bilgilerinizin ve API anahtarlarınızın artık kodunuzda depolanması gerek olmamasıdır. Microsoft Entra, uygulamayı çalıştıran güvenlik sorumlusunun (kullanıcı, grup veya hizmet) kimliğini doğrular. Kimlik doğrulaması başarılı olursa, Microsoft Entra ID uygulamaya erişim belirtecini döndürür ve uygulama erişim belirtecini kullanarak Azure AI Search'e yönelik istekleri yetkileyebilir.

Bu makalede, istemcinizi Microsoft Entra Id için nasıl yapılandırabileceğiniz gösterilmektedir:

  • Kimlik doğrulaması için uygulamanız için bir yönetilen kimlik oluşturun. Farklı türde bir güvenlik sorumlusu nesnesi kullanabilirsiniz, ancak kimlik bilgilerini yönetme gereksinimini ortadan kaldırdığı için bu makalede yönetilen kimlikler kullanılır.

  • Yetkilendirme için, yönetilen kimliğe sorguları çalıştırma veya dizin oluşturma işlerini yönetme izinleri veren bir Azure rolü atayın.

  • İstemci kodunuzu çağıracak TokenCredential()şekilde güncelleştirin. Örneğin, Azure.Identity kullanarak bir Microsoft Entra Kimliği aracılığıyla kimlik doğrulaması yapmak için yeni SearchClient(uç nokta, yeni DefaultAzureCredential()) kullanmaya başlayabilirsiniz.

Veri düzlemi için rol tabanlı erişimi yapılandırma

Şunlar için geçerlidir: Arama Dizini Veri Katkıda Bulunanı, Arama Dizini Veri Okuyucusu, Arama Hizmeti Katkıda Bulunanı

Bu adımda, arama hizmetinizi OAuth2 erişim belirteci sağlayan veri isteklerindeki yetkilendirme üst bilgisini tanıyacak şekilde yapılandırın.

  1. Azure portalında oturum açın ve arama hizmeti sayfasını açın.

  2. Sol gezinti bölmesinde Tuşlar'ı seçin.

    Kimlik doğrulama seçeneklerini içeren anahtarlar sayfasının ekran görüntüsü.

  3. BIR API erişim denetimi seçeneği belirleyin. Esneklik istiyorsanız veya uygulamaları geçirmeniz gerekiyorsa her ikisini de öneririz.

    Seçenek Açıklama
    API Anahtarı (varsayılan) Yetkilendirme için istek üst bilgisinde bir yönetici veya sorgu API anahtarları gerektirir. Hiçbir rol kullanılmaz.
    Rol tabanlı erişim denetimi Bir sonraki adımda açıklanan görevi tamamlamak için rol atamasında üyelik gerektirir. Ayrıca bir yetkilendirme üst bilgisi gerektirir.
    Her ikisi İstekler API anahtarı veya rol tabanlı erişim denetimi kullanılarak geçerlidir.

Değişiklik hemen geçerli olur, ancak test etmeden önce birkaç saniye bekleyin.

Arama hizmeti işlemleri için tüm ağ çağrıları ve içerik seçtiğiniz seçeneğe uygundur: API anahtarları, taşıyıcı belirteci veya Her İkisi'ni seçerseniz bunlardan biri.

Portalda rol tabanlı erişim denetimini etkinleştirdiğinizde, yetkilendirme başarısız olursa hata modu "http401WithBearerChallenge" olur.

Yönetilen kimlik oluşturma

Bu adımda, istemci uygulamanız için bir yönetilen kimlik oluşturun.

  1. Azure Portal’ında oturum açın.

  2. Yönetilen Kimlikler'i arayın.

  3. Oluştur'u belirleyin.

  4. Yönetilen kimliğinize bir ad verin ve bir bölge seçin. Ardından Oluştur’u seçin.

    Yönetilen Kimlik Oluşturma sihirbazının ekran görüntüsü.

Yönetilen kimliğe rol atama

Ardından, istemcinizin yönetilen kimliğine arama hizmetinize erişim vermeniz gerekir. Azure AI Search'te çeşitli yerleşik roller vardır. Özel bir rol de oluşturabilirsiniz.

En düşük izinleri vermek en iyi yöntemdir. Uygulamanızın yalnızca sorguları işlemesi gerekiyorsa, Arama Dizini Veri Okuyucusu rolünü atamanız gerekir. Alternatif olarak, istemcinin arama dizininde hem okuma hem de yazma erişimine ihtiyacı varsa, Arama Dizini Veri Katkıda Bulunanı rolünü kullanmanız gerekir.

  1. Azure Portal’ında oturum açın.

  2. Arama hizmetinize gidin.

  3. Sol gezinti bölmesinde Erişim denetimi (IAM) öğesini seçin.

  4. + Ekle>Rol ataması ekle’yi seçin.

    Rol ataması ekle menüsünün açık olduğu Erişim denetimi (IAM) sayfasının ekran görüntüsü.

  5. Uygun bir rol seçin:

    • Sahip

    • Katılımcı

    • Okuyucu

    • Arama Hizmeti Katkıda Bulunanı

    • Arama Dizini Veri Katkıda Bulunanı

    • Arama Dizini Veri Okuyucusu

      Not

      Sahip, Katkıda Bulunan, Okuyucu ve Arama Hizmeti Katkıda Bulunanı, denetim düzlemi rolleridir ve arama dizinindeki verilere erişmenize izin vermez. Veri erişimi için Arama Dizini Veri Katkıda Bulunanı veya Arama Dizini Veri Okuyucusu rolünü seçin. Her rolün kapsamı ve amacı hakkında daha fazla bilgi için bkz . Arama'da kullanılan yerleşik roller.

  6. Üyeler sekmesinde, arama hizmetinize erişim vermek istediğiniz yönetilen kimliği seçin.

  7. Gözden geçirme + atama sekmesinde Gözden geçir + ata’yı seçerek rolü atayın.

Uygulamanızın arama hizmetlerine, nesnelerine ve içeriğe kapsamlı erişime ihtiyacı varsa Arama Hizmeti Katkıda Bulunanı ve Arama Dizini Veri Katkıda Bulunanı gibi birden çok rol atayabilirsiniz.

PowerShell'i kullanarak da rol atayabilirsiniz.

İstemcinizde Microsoft Entra kimlik doğrulamayı ayarlama

Arama hizmetinde yönetilen bir kimliğe ve rol atamasına sahip olduktan sonra, güvenlik sorumlusunun kimliğini doğrulamak ve bir OAuth 2.0 belirteci almak için uygulamanıza kod eklemeye hazırsınız demektir.

Rol tabanlı erişim denetimi için aşağıdaki istemci kitaplıklarını kullanın:

Not

Microsoft Entra ID tarafından kullanılan OAuth 2.0 kod verme akışı hakkında daha fazla bilgi edinmek için bkz . OAuth 2.0 kod verme akışını kullanarak Microsoft Entra web uygulamalarına erişimi yetkilendirme.

Aşağıdaki yönergeler, kod değişikliklerini göstermek için mevcut bir C# örneğine başvurur.

  1. Başlangıç noktası olarak, Azure SDK'larını kullanarak Hızlı Başlangıç: Tam metin araması'nın C# bölümünün kaynak kodunu klonlayın.

    Örnek şu anda ve oluşturmak SearchClientSearchIndexClient için anahtar tabanlı kimlik doğrulamasını AzureKeyCredential kullanır, ancak rol tabanlı kimlik doğrulamasına geçmek için küçük bir değişiklik yapabilirsiniz.

  2. Azure.Search.Documents NuGet paketini 11.4 veya sonraki bir sürüme güncelleştirin.

  3. Diğer kimlik doğrulama tekniklerine erişmek için Azure.Identity kitaplığını içeri aktarın.

  4. Program.cs içinde öğesinin Main() başında kullanmak AzureKeyCredential yerine aşağıdaki kod parçacığında gibi kullanınDefaultAzureCredential:

    // Create a SearchIndexClient to send create/delete index commands
SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, new DefaultAzureCredential());
// Create a SearchClient to load and query documents
SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, new DefaultAzureCredential());

Yerel ortamda test etme

Kullanıcı tarafından atanan yönetilen kimlikler yalnızca Azure ortamlarında çalışır. Bu kodu yerel olarak çalıştırırsanız kimlik DefaultAzureCredential bilgilerinizle kimlik doğrulamasına geri döner. Kodu yerel olarak çalıştırmayı planlıyorsanız, kendinize arama hizmetine gerekli erişimi verdiğinizden emin olun.

  1. Hızlı başlangıç örneğindeki tüm işlemleri çalıştırmak için hesabınızın rol atamaları olduğunu doğrulayın. Hem dizin oluşturmak hem de sorgulamak için "Dizin Veri Okuyucusu Ara" ve "Dizin Verileri Katkıda Bulunanı Ara" kullanın.

  2. Azure oturum açma hesabınızı seçmek için Araçlar>Seçenekleri>Azure Hizmet Kimlik Doğrulaması'na gidin.

Artık yetkilendirme için rol tabanlı erişim denetimini kullanarak projeyi yerel sisteminizde Visual Studio'dan çalıştırabilmeniz gerekir.

Not

Azure.Identity belgelerinde .NET için Azure SDK ile Microsoft Entra kimlik doğrulaması hakkında DefaultAzureCredential daha fazla ayrıntı bulunur. DefaultAzureCredential , makul varsayılan davranışlarla yaygın senaryoları işleyerek SDK ile çalışmaya başlamayı basitleştirmeye yöneliktir. Daha fazla denetim isteyen veya senaryosu varsayılan ayarlar tarafından sunulmayan geliştiriciler diğer kimlik bilgileri türlerini kullanmalıdır.

Ayrıca bkz.