Azure AI Search'te yönetilen kimlik kullanarak bağlanmak için arama hizmeti yapılandırma

Makale
07/25/2024

Önemli

Kullanıcı tarafından atanan yönetilen kimlik ataması, Ek Kullanım Koşulları altında genel önizleme aşamasındadır. Yönetim önizleme REST API'sinde Azure AI Search için kullanıcı tarafından atanan yönetilen kimlik ataması sağlanır. Sistem tarafından atanan yönetilen kimlik desteği genel olarak kullanılabilir.

Azure AI Search'ten dizin oluşturma veya sorgular sırasında veri sağlayan, uygulanan yapay zeka veya vektörleştirme sağlayan kaynaklara giden bağlantılar için Microsoft Entra Kimliğini ve rol atamalarını kullanabilirsiniz.

Giden bağlantıda rol kullanmak için, önce arama hizmetinizi bir Microsoft Entra kiracısında arama hizmetinizin güvenlik ilkesi olarak sistem tarafından atanan veya kullanıcı tarafından atanan yönetilen kimliği kullanacak şekilde yapılandırın. Yönetilen bir kimliğe sahip olduktan sonra, yetkili erişim için roller atayabilirsiniz. Yönetilen kimlikler ve rol atamaları, gizli dizileri ve kimlik bilgilerini bağlantı dizesi veya koda geçirme gereksinimini ortadan kaldırır.

Önkoşullar

Temel katmanda veya daha yüksek bir bölgede, herhangi bir bölgede bir arama hizmeti.
Geçerli bir rol ataması olan bir Microsoft Entra güvenlik sorumlusundan gelen istekleri kabul eden bir Azure kaynağı.

Desteklenen senaryolar

Azure AI Search, sistem tarafından atanan veya kullanıcı tarafından atanan yönetilen kimliği altında diğer Azure kaynaklarına bağlanabilir.

Sistem tarafından atanan yönetilen kimliğin Arama hizmeti yapılandırması genel olarak kullanılabilir.
Kullanıcı tarafından atanan yönetilen kimliğin Arama hizmeti yapılandırması, ek kullanım koşulları altında genel önizleme aşamasındadır.
Sistem veya kullanıcı tarafından atanan yönetilen kimliğin veri düzlemi kullanımı genel olarak kullanılabilir. Örneğin, dizin oluşturucu veri kaynağı bağlantısında, anahtar kasasında, hata ayıklama oturumunda veya zenginleştirme önbelleğinde kullanıcı tarafından atanan bir yönetilen kimlik istiyorsanız, kullandığınız özelliğin de genel olarak kullanılabildiğini varsayarak bağlantıyı oluşturmak için genel olarak kullanılabilir bir REST API sürümü kullanabilirsiniz.

Sistem tarafından yönetilen kimlik, bir bağlantı dizesi Microsoft Entra Kimliği kullanan bir hizmet veya uygulamanın benzersiz kaynak kimliği olduğunda belirtilir. Kullanıcı tarafından atanan yönetilen kimlik bir "identity" özelliği aracılığıyla belirtilir.

Arama hizmeti azure depolamayı dizin oluşturucu veri kaynağı olarak ve hata ayıklama oturumları, zenginleştirme önbelleğe alma ve bilgi deposu için veri havuzu olarak kullanır. Depolama alanına geri yazan arama özellikleri için, yönetilen kimliğin "Rol atama" bölümünde açıklandığı gibi katkıda bulunan rolü ataması gerekir.

Senaryo	Sistem	Kullanıcı tarafından atanan
Desteklenen Azure veri kaynaklarına ^{dizin oluşturucu bağlantıları 1}	Yes	Yes
Müşteri tarafından yönetilen anahtarlar için Azure Key Vault	Yes	Yes
Hata ayıklama oturumları (Azure Depolama'da barındırılıyor)¹	Yes	Hayır
Zenginleştirme önbelleği (Azure Depolama'da barındırılıyor) 1,^²	Yes	Yes
Bilgi Deposu (Azure Depolama'da barındırılıyor) ¹	Yes	Yes
Azure OpenAI veya Azure AI ^{3 bağlantıları}	Yes	Yes

¹ Arama ve depolama arasındaki bağlantı için ağ güvenlik yapılandırmanız, hangi yönetilen kimlik türünü kullanabileceğiniz konusunda kısıtlamalar uygular. Güvenilen hizmet özel durumu veya kaynak örneği kuralı aracılığıyla depolamaya aynı bölge bağlantısı için yalnızca sistem tarafından yönetilen kimlik kullanılabilir. Ayrıntılar için bkz . Ağ korumalı depolama hesabına erişim.

² Yapay zeka arama hizmeti şu anda paylaşılan anahtar erişiminin kapalı olduğu bir depolama hesabındaki tablolara bağlanamıyor.

³ Azure OpenAI veya Azure AI bağlantıları şunlardır: Özel beceri, Özel vektörleştirici, Azure OpenAI ekleme becerisi, Azure OpenAI vektörleştiricisi, AML becerisi, Azure AI Studio model kataloğu vektörleştiricisi, Azure AI Vision çok modüllü ekleme becerisi, Azure AI Vision vektörleştiricisi.

Sistem tarafından yönetilen kimlik oluşturma

Sistem tarafından atanan yönetilen kimliği etkinleştirdiğinizde, Microsoft Entra ID arama hizmetiniz için aynı kiracıdaki diğer Azure hizmetlerinde kimlik doğrulaması yapmak için kullanılabilecek bir kimlik oluşturur. Daha sonra bu kimliği, verilere ve modellere erişmek için rol atamalarında kullanabilirsiniz.

Sistem tarafından atanan yönetilen kimlik, arama hizmetinize özgüdür ve kullanım ömrü boyunca hizmete bağlıdır. Arama hizmeti yalnızca bir sistem tarafından atanan yönetilen kimliğe sahip olabilir.

Azure portalında oturum açın ve arama hizmetinizi bulun.
Ayarlar'ın altında Kimlik'i seçin.
Sistem tarafından atanan sekmesinde, Durum'un altında Açık'ı seçin.
Kaydet'i seçin.

Ayarları kaydettikten sonra sayfa, arama hizmetinize atanmış bir nesne tanımlayıcısını gösterecek şekilde güncelleştirilir.

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -IdentityType SystemAssigned

Daha fazla bilgi için bkz . Sistem tarafından atanan yönetilen kimlikle (Azure PowerShell) arama hizmeti oluşturma.

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --identity-type SystemAssigned

Daha fazla bilgi için bkz . Sistem tarafından atanan yönetilen kimlikle (Azure CLI) arama hizmeti oluşturma.

Arama hizmeti oluşturma veya güncelleştirme isteğini formüle etme.

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2023-11-01
{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "SystemAssigned"
  }
}

Onay ve sistem tarafından yönetilen kimlik için bir nesne tanımlayıcısı yanıtta döndürülür.

Daha fazla bilgi için bkz . Hizmet Oluşturma veya Güncelleştirme (Yönetim REST API'si).

Kullanıcı tarafından atanan yönetilen kimlik oluşturma

Önemli

Bu senaryonun bir bölümü, Ek Kullanım Koşulları altında genel önizleme aşamasındadır. Yönetim önizlemeSI REST API'sinde Azure AI Search için kullanıcı tarafından atanan yönetilen kimlik yapılandırması sağlanır.

Kullanıcı tarafından atanan yönetilen kimlik, Azure'da bulunan bir kaynaktır. Rol atamalarında daha fazla ayrıntı düzeyi istiyorsanız, kullanıcı tarafından atanan birden çok yönetilen kimlik oluşturabilirsiniz. Örneğin, farklı uygulamalar ve senaryolar için ayrı kimlikler isteyebilirsiniz.

Adımlar şunlardır:

Azure aboneliğinizde kullanıcı tarafından atanan bir yönetilen kimlik oluşturun.
Arama hizmetinizde, kullanıcı tarafından atanan yönetilen kimliği etkinleştirmek için hizmet tanımını güncelleştirin (bu adım önizleme aşamasındadır).
Bağlanmak istediğiniz diğer Azure hizmetlerinde kimlik için bir rol ataması oluşturun.
Dizin oluşturucu veri kaynağı gibi Azure AI Search'teki veri kaynağı bağlantılarında, bağlantı ayrıntılarında kullanıcı tarafından yönetilen kimliğe başvurun (özellik için destek genel kullanıma sunulduysa bu adım genel olarak kullanılabilir).

Kullanıcı tarafından atanan yönetilen kimliğin kapsamı abonelikler, kaynak grupları veya kaynak türleri olarak ayarlanabilir.

Kullanıcı tarafından atanan yönetilen kimliği ilişkilendirme, Azure portalında, Yönetim REST API'lerinin önizleme sürümlerinde ve özelliği sağlayan beta SDK paketlerinde desteklenir.

Azure portalı
REST API

Azure portalda oturum açma
Kaynak oluştur’u seçin.
"Arama hizmeti s ve market" arama çubuğunda "Kullanıcı Tarafından Atanan Yönetilen Kimlik" araması yapın ve Oluştur'u seçin.
Aboneliği, kaynak grubunu ve bölgeyi seçin. Kimliğe açıklayıcı bir ad verin.
Oluştur'u seçin ve kaynağın dağıtımı tamamlanmasını bekleyin.

Kimliği kullanabilmeniz birkaç dakika sürer.
Arama hizmeti sayfanızdaki Ayarlar'ın altında Kimlik'i seçin.
Kullanıcı tarafından atanan sekmesinde Ekle'yi seçin.
Aboneliği seçin ve ardından önceki adımda oluşturduğunuz kullanıcı tarafından atanan yönetilen kaynağı seçin.

Kullanıcı tarafından atanan yönetilen kimlik atamak için portal yerine önizleme Yönetimi REST API'sini kullanabilirsiniz. API sürümlerini veya sonraki sürümleri 2021-04-01-preview kullanın. Bu örnekte 2024-06-01-preview kullanılmıştır.

Arama hizmetini GÜNCELLEŞTIRMEK için bir istek formüle edin.

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2024-06-01-preview
{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/[subscription ID]/resourcegroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[name of managed identity]": {}
    }
  }
}

Tam yönetilen kimlik belirtmek için "identity" özelliğini ayarlayın:
- "type" kimlik türüdür. Geçerli değerler her ikisi için de "SystemAssigned", "UserAssigned" veya "SystemAssigned, UserAssigned" değerleridir. "Hiçbiri" değeri, arama hizmetinden daha önce atanmış tüm kimlikleri temizler.
- "userAssignedIdentities", kullanıcı tarafından atanan yönetilen kimliğin ayrıntılarını içerir. Güncelleştirme Hizmeti isteğinde belirtebilmeniz için önce bu kimliğin zaten mevcut olması gerekir.

Rol atama

Yönetilen bir kimliğe sahip olduktan sonra, Azure kaynağında arama hizmeti izinlerini belirleyen roller atayın.

Dizin oluşturucu veri bağlantıları ve Azure Key Vault'ta müşteri tarafından yönetilen bir anahtara erişmek için okuma izinleri gereklidir.
Bir bilgi deposunda hata ayıklama oturumu verilerini barındırmak, zenginleştirme önbelleği ve uzun süreli içerik depolaması için Azure Depolama'yı kullanan yapay zeka zenginleştirme özellikleri için yazma izinleri gereklidir.

Aşağıdaki adımlarda rol ataması iş akışı gösterilmektedir. Bu örnek Azure OpenAI içindir. Diğer Azure kaynakları için bkz . Azure Depolama'ya bağlanma, Azure Cosmos DB'ye bağlanma veya Azure SQL'e bağlanma.

Azure hesabınızla Azure portalında oturum açın ve Azure OpenAI kaynağınıza gidin.
Soldaki menüden Erişim denetimi'ni seçin.
Ekle'yi ve ardından Rol ataması ekle'yi seçin.
İş işlevi rolleri'nin altında Bilişsel Hizmetler OpenAI Kullanıcısı'nın ardından İleri'yi seçin.
Üyeler'in altında Yönetilen kimlik'i ve ardından Üyeler'i seçin.
Aboneliğe ve kaynak türüne (Arama hizmeti) göre filtreleyin ve ardından arama hizmetinizin yönetilen kimliğini seçin.
Gözden geçir + ata'yı seçin.

Bağlantı dizesi örnekleri

Arama hizmeti için yönetilen kimlik tanımlanıp bir rol ataması verildikten sonra, giden bağlantılar diğer Azure kaynağının benzersiz kaynak kimliğini kullanacak şekilde değiştirilebilir. Çeşitli senaryolar için bazı bağlantı dizesi örnekleri aşağıda verilmiştir.

Bu bağlantılar için genel kullanıma sunulan REST API sürümlerini ve Azure SDK paketlerini kullanabilirsiniz.

İpucu

Bu nesnelerin çoğunu Azure portalında oluşturabilir, sistem veya kullanıcı tarafından atanan yönetilen kimliği belirtebilir ve ardından bağlantı dizesi almak için JSON tanımını görüntüleyebilirsiniz.

Blob veri kaynağı (sistem):

Dizin oluşturucu veri kaynağı, veri kaynağına bağlantının nasıl yapıldığını belirleyen bir "credentials" özelliği içerir. Aşağıdaki örnekte, depolama hesabının benzersiz kaynak kimliğini belirten bir bağlantı dizesi gösterilmektedir.

Microsoft Entra Id, arama hizmetinin sistem tarafından yönetilen kimliğini kullanarak isteğin kimliğini doğrular. bağlantı dizesi kapsayıcı içermediğini fark edin. Veri kaynağı tanımında, kapsayıcı adı bağlantı dizesi değil "container" özelliğinde (gösterilmez) belirtilir.

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    }

Blob veri kaynağı (kullanıcı):

Azure Depolama'ya arama isteği, kullanıcı tarafından atanan yönetilen kimlik altında da yapılabilir. Arama hizmeti kullanıcı kimliği "identity" özelliğinde belirtilir.

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    },
  . . .
"identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
  }

Bilgi deposu:

Bilgi deposu tanımı, Azure Depolama'ya yönelik bir bağlantı dizesi içerir. bağlantı dizesi, depolama hesabınızın benzersiz kaynak kimliğidir. Dizenin yolda kapsayıcılar veya tablolar içermediğini fark edin. Bunlar, bağlantı dizesi değil, eklenmiş projeksiyon tanımında tanımlanır.

"knowledgeStore": {
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/storage-account-name};"
}

Zenginleştirme önbelleği:

Dizin oluşturucu önbelleğe alınmış zenginleştirmeler için kullanılan kapsayıcıyı oluşturur, kullanır ve hatırlar. Kapsayıcının önbellek bağlantı dizesi dahil edilmesi gerekmez. Nesne kimliğini portalda arama hizmetinizin Kimlik sayfasında bulabilirsiniz.

"cache": {
  "enableReprocessing": true,
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}

Hata ayıklama oturumu:

Hata ayıklama oturumu portalda çalışır ve oturumu başlattığınızda bir bağlantı dizesi alır. Aşağıdaki örneğe benzer bir dize yapıştırabilirsiniz.

"ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name}/{container-name};",

Özel beceri:

Özel beceri, özel kodu barındıran bir Azure işlevinin veya uygulamanın uç noktasını hedefler. Uç nokta özel beceri tanımında belirtilir. "authResourceId" varlığının olması, arama hizmetine yönetilen bir kimlik kullanarak bağlanmasını ve özellikteki hedef işlevin veya uygulamanın uygulama kimliğini geçirmesini söyler.

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "authResourceId": "<Azure-AD-registered-application-ID>",
  "batchSize": 4,
  "context": "/document",
  "inputs": [ ... ],
  "outputs": [ ...]
}

Azure OpenAI ekleme becerisi ve Azure OpenAI vektörleştiricisi:

AI Search'teki Azure OpenAI ekleme becerisi ve vektörleştiricisi, ekleme modelini barındıran bir Azure OpenAI hizmetinin uç noktasını hedefler. Uç nokta, Azure OpenAI ekleme beceri tanımında ve/veya Azure OpenAI vektörleştirici tanımında belirtilir. Sistem tarafından yönetilen kimlik yapılandırıldıysa ve "apikey" ve "authIdentity" boşsa kullanılır. "authIdentity" özelliği yalnızca kullanıcı tarafından atanan yönetilen kimlik için kullanılır.

Sistem tarafından yönetilen kimlik örneği:

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://url.openai.azure.com/",
  "deploymentId": "text-embedding-ada-002",
  "modelName": "text-embedding-ada-002",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ]
}

 "vectorizers": [
    {
      "name": "my_azure_open_ai_vectorizer",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://url.openai.azure.com",
        "deploymentId": "text-embedding-ada-002",
        "modelName": "text-embedding-ada-002"
      }
    }
  ]

Kullanıcı tarafından atanan yönetilen kimlik örneği:

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://url.openai.azure.com/",
  "deploymentId": "text-embedding-ada-002",
  "modelName": "text-embedding-ada-002",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ],
  "authIdentity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
   }
}

 "vectorizers": [
    {
      "name": "my_azure_open_ai_vectorizer",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://url.openai.azure.com",
        "deploymentId": "text-embedding-ada-002",
        "modelName": "text-embedding-ada-002"
        "authIdentity": {
            "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
            "userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
          }
      }
    }
  ]

Güvenlik duvarı erişimini denetleme

Azure kaynağınız bir güvenlik duvarının arkasındaysa, arama hizmetinizden gelen istekleri kabul eden bir gelen kuralı olduğundan emin olun.

Azure Blob Depolama veya Azure Data Lake Storage 2. Nesil ile aynı bölge bağlantıları için sistem tarafından yönetilen bir kimlik ve güvenilen hizmet özel durumu kullanın. İsteğe bağlı olarak, istekleri kabul etmek için bir kaynak örneği kuralı yapılandırabilirsiniz.
Diğer tüm kaynaklar ve bağlantılar için, Arama'dan gelen istekleri kabul eden bir IP güvenlik duvarı kuralı yapılandırın. Ayrıntılar için bkz . Azure ağ güvenliği özellikleri tarafından korunan içeriğe dizin oluşturucu erişimi.

Aracılığıyla paylaş