Se connecter à Azure Cosmos DB à l’aide d’une identité managée (Recherche Azure AI)

Note

Recherche Azure AI est disponible via le portail Azure, les API REST et les SDK Azure. Il sous-tend également Foundry IQ, la couche de connaissances managée qui transforme le contenu d’entreprise en bases de connaissances réutilisables et prenant en charge les autorisations pour les agents dans le portail Microsoft Foundry.

Cet article explique comment configurer une connexion d'indexeur à une base de données Azure Cosmos DB à l'aide d'une identité managée au lieu de fournir des informations d'identification dans le chaîne de connexion.

Vous pouvez utiliser une identité managée affectée par le système ou une identité managée affectée par l’utilisateur. Les identités gérées sont des connexions Microsoft Entra et nécessitent des attributions de rôles Azure pour accéder aux données dans Azure Cosmos DB. Vous pouvez éventuellement enforcer l’accès en fonction du rôle en tant que seule méthode d’authentification pour les connexions de données en définissant disableLocalAuth sur true pour votre Azure Cosmos DB pour NoSQL compte.

Conditions préalables

Limitations

  • Les indexeurs qui se connectent à Azure Cosmos DB pour Gremlin et MongoDB (actuellement en préversion) prennent uniquement en charge l’approche legacy.

Approches prises en charge pour l’authentification d’identité managée

Recherche Azure AI prend en charge deux mécanismes pour se connecter à Azure Cosmos DB à l’aide d’une identité managée.

  • L’approche legacy nécessite la configuration de l’identité managée pour disposer d’autorisations de lecteur sur le plan de contrôle du compte Azure Cosmos DB cible. Recherche Azure AI utilise cette identité pour récupérer les clés de compte du compte Cosmos DB en arrière-plan pour accéder aux données. Cette approche ne fonctionnera pas si le compte Cosmos DB a "disableLocalAuth": true.

  • L’approche modern nécessite la configuration des rôles appropriés d’identité managée sur le plan de contrôle et de données du compte Azure Cosmos DB cible. Recherche Azure AI demande ensuite un jeton d’accès pour accéder aux données dans le compte Cosmos DB. Cette approche fonctionne même si le compte Cosmos DB a "disableLocalAuth": true.

Les indexeurs qui se connectent à Azure Cosmos DB pour NoSQL prennent en charge l’approche legacy et l’approche modern - l’approche modern est recommandée.

Se connecter à Azure Cosmos DB pour NoSQL

Cette section décrit les étapes de configuration de la connexion à Azure Cosmos DB pour NoSQL via l’approche modern.

Configurer les attributions de rôles de plan de contrôle

  1. Connectez-vous au portail Azure et recherchez votre compte Cosmos DB pour NoSQL.

  2. Sélectionnez Contrôle d’accès (IAM).

  3. Sélectionnez Ajouter , puis sélectionnez Attribution de rôle.

  4. Dans la liste des rôles de fonction de travail, sélectionnez Lecteur de compte Cosmos DB.

  5. Sélectionnez Suivant.

  6. Sélectionnez Identité managée , puis sélectionnez Membres.

  7. Filtrez par identités managées affectées par le système ou par identités managées affectées par l’utilisateur. Vous devez voir l’identité managée que vous avez créée précédemment pour votre service de recherche. Si vous n’en avez pas, consultez Configurer la recherche pour utiliser une identité managée. Si vous en avez déjà configuré un mais qu’il n’est pas disponible, donnez-lui quelques minutes.

  8. Sélectionnez l’identité et enregistrez l’attribution de rôle.

Pour plus d’informations, consultez Utiliser le contrôle d’accès en fonction du rôle du plan de contrôle avec Azure Cosmos DB pour NoSQL.

Configurer des attributions de rôles de plan de données

L’identité managée doit se voir attribuer un rôle pour accéder au plan de données du compte Cosmos DB. L'ID d'objet (principal) de l'identité affectée par le système/l'utilisateur du service de recherche se trouve sous l'onglet « Identité » du service de recherche. Cette étape ne peut être effectuée que via Azure CLI à l’instant.

Définir des variables :

$cosmosdb_acc_name = <cosmos db account name>
$resource_group = <resource group name>
$subsciption = <subscription ID>
$system_assigned_principal = <Object (principal) ID for the search service's system/user assigned identity>
$readOnlyRoleDefinitionId = "00000000-0000-0000-0000-000000000001"
$scope=$(az cosmosdb show --name $cosmosdb_acc_name --resource-group $resource_group --query id --output tsv)

Définissez une attribution de rôle pour l’identité affectée par le système :

az cosmosdb sql role assignment create --account-name $cosmosdb_acc_name --resource-group $resource_group --role-definition-id $readOnlyRoleDefinitionId --principal-id $system_assigned_principal --scope $scope

Pour plus d’informations, consultez Utiliser le contrôle d’accès en fonction du rôle du plan de données avec Azure Cosmos DB pour NoSQL

Configurer la définition de la source de données

Une fois que vous avez configuré les deux attributions de rôles du plan de contrôle et du plan de données sur le compte Azure Cosmos DB pour NoSQL, vous pouvez configurer une connexion à elle qui fonctionne selon ce rôle.

Les indexeurs utilisent un objet de source de données pour les connexions à une source de données externe. Cette section explique comment spécifier une identité gérée attribuée par le système ou une identité gérée attribuée par l'utilisateur dans une chaîne de connexion de source de données. Vous trouverez d’autres exemples chaîne de connexion dans l’article sur l’identité managée.

Conseil

Vous pouvez créer une connexion de source de données à Cosmos DB dans le portail Azure, en spécifiant une identité managée affectée par le système ou par l’utilisateur, puis afficher la définition JSON pour voir comment le chaîne de connexion est formulé.

L’API REST, le portail Azure et le sdk .NET prennent en charge l’utilisation d’une identité managée affectée par le système ou affectée par l’utilisateur.

Se connecter via l’identité affectée par le système

Lorsque vous vous connectez avec une identité managée affectée par le système, la seule modification apportée à la définition de la source de données est le format de la propriété « credentials ». Fournissez un nom de base de données et un ResourceId sans clé de compte ni mot de passe. ResourceId doit inclure l’ID d’abonnement de Azure Cosmos DB, le groupe de ressources et le nom du compte Azure Cosmos DB.

Voici un exemple utilisant l’API REST Créer une source de données qui exerce l’approche moderne .

POST https://[service name].search.windows.net/datasources?api-version=2026-04-01
{
    "name": "my-cosmosdb-ds",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];IdentityAuthType=AccessToken"
    },
    "container": { "name": "[my-cosmos-collection]" }
}

Note

Si la propriété IdentityAuthType ne fait pas partie de la chaîne de connexion, Recherche Azure AI utilise par défaut l'approche legacy pour garantir la compatibilité avec les versions précédentes.

Se connecter par l’identité assignée par l’utilisateur

Vous devez ajouter une propriété « identity » à la définition de source de données, où vous spécifiez l’identité spécifique (sur plusieurs qui peuvent être affectées au service de recherche), qui sera utilisée pour se connecter au compte Azure Cosmos DB.

Voici un exemple utilisant l'identité assignée par l'utilisateur via l'approche moderne.

POST https://[service name].search.windows.net/datasources?api-version=2026-04-01
{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];IdentityAuthType=AccessToken"
    },
    "container": { "name": "[my-cosmos-collection]"},
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    }
}

Se connecter à Azure Cosmos DB pour Gremlin/MongoDB (préversion)

Cette section décrit les étapes de configuration de la connexion à Azure Cosmos DB pour Gremlin/Mongo via l’approche legacy.

Configurer les attributions de rôles de plan de contrôle

Suivez les mêmes étapes que précédemment pour attribuer les rôles appropriés sur le plan de contrôle de la Azure Cosmos DB pour Gremlin/MongoDB.

Définir la chaîne de connexion

  • Pour les collections MongoDB, ajoutez « ApiKind=MongoDb » au chaîne de connexion et utilisez une API REST en préversion.
  • Pour les graphiques Gremlin, ajoutez « ApiKind=Gremlin » au chaîne de connexion et utilisez une API REST en préversion.
  • Pour les deux types, seule l’approche héritée est prise en charge ; c’est-à-dire, IdentityAuthType=AccountKey ou l’omettre entièrement est la seule option valide pour la chaîne de connexion.

Voici un exemple de connexion aux collections MongoDB à l’aide de l’identité affectée par le système via l’API REST

POST https://[service name].search.windows.net/datasources?api-version=2026-08-01-preview
{
    "name": "my-cosmosdb-ds",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];ApiKind=MongoDb"
    },
    "container": { "name": "[my-cosmos-collection]", "query": null },
    "dataChangeDetectionPolicy": null
}

Voici un exemple de connexion aux graphiques Gremlin à l’aide de l’identité affectée par l’utilisateur.

POST https://[service name].search.windows.net/datasources?api-version=2026-08-01-preview
{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];ApiKind=Gremlin"
    },
    "container": { "name": "[my-cosmos-collection]"},
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    }
}

Exécuter l’indexeur pour vérifier les autorisations

Les informations de connexion et les autorisations sur le service distant sont validées au moment de l’exécution de l’indexeur. Si l’indexeur réussit, la syntaxe de connexion et les attributions de rôles sont valides. Pour plus d’informations, consultez Exécuter ou réinitialiser des indexeurs, des compétences ou des documents.

Résoudre les problèmes de connexion

  • Pour Azure Cosmos DB pour NoSQL, vérifiez si le compte dispose de son accès restreint pour sélectionner des réseaux. Vous pouvez exclure tous les problèmes de pare-feu en essayant la connexion sans restrictions en place. Pour plus d’informations, consultez Accès de l’indexeur au contenu protégé par la sécurité réseau d’Azure

  • Pour Azure Cosmos DB pour NoSQL, si l’indexeur échoue en raison de problèmes d’authentification, vérifiez que les attributions de rôles ont été effectuées both sur le plan de contrôle et le plan de données du compte Cosmos DB.

  • Pour Gremlin ou MongoDB, si vous avez récemment modifié vos clés de compte Azure Cosmos DB, vous devez attendre jusqu'à 15 minutes avant que la chaîne de connexion d'identité gérée fonctionne.

Voir aussi

  • Last updated on