Partager via

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

  • Article

Cet article explique comment configurer une connexion d’indexeur à une base de données Azure Cosmos DB en utilisant une identité managée au lieu de fournir des informations d’identification dans la 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 managé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 appliquer l’accès en fonction du rôle comme seule méthode d’authentification pour les connexions de données en définissant disableLocalAuth sur true pour votre compte Azure Cosmos DB for NoSQL.

Prérequis

Approches prises en charge pour l’authentification par 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 héritée 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 moderne 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 for NoSQL prennent en charge l’approche héritée et moderne : l’approche moderne est fortement recommandée.

Limites

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

Se connecter à Azure Cosmos DB for NoSQL

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

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

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

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

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

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

  5. Cliquez sur Suivant.

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

  7. Filtrez selon les identités managées affectées par le système ou les 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é une mais qu’elle n’est pas disponible, patientez 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 for NoSQL.

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

L’identité managée doit attribuer un rôle pour lire à partir du 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 qu’à l’aide d’Azure CLI pour le moment.

Définir les 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-00000000000"
$scope=$(az cosmosdb show --name $cosmosdbname --resource-group $resourcegroup --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 $cosmosdbname --resource-group $resourcegroup --role-definition-id $readOnlyRoleDefinitionId --principal-id $sys_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 for NoSQL

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

Une fois que vous avez configuré à la fois les attributions de rôle de plan de contrôle et de plan de données sur le compte Azure Cosmos DB for NoSQL, vous pouvez configurer une connexion à celle-ci qui fonctionne sous ce rôle.

Les indexeurs utilisent un objet source de données pour les connexions à une source de données externe. Cette section explique comment spécifier une identité managée affectée par le système ou une identité managée affectée par l’utilisateur dans une chaîne de connexion de source de données. Vous trouverez d’autres exemples de 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 la chaîne de connexion est formulée.

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

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

Quand 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 qui n’a pas de clé de compte ou de mot de passe. Le ResourceId doit inclure l’ID d’abonnement d’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 met en œuvre l’approche moderne.

POST https://[service name].search.windows.net/datasources?api-version=2024-11-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];IdentityAuthType=AccessToken"
    },
    "container": { "name": "[my-cosmos-collection]" }
}

Remarque

Si la propriété IdentityAuthType ne fait pas partie de la chaîne de connexion, Recherche Azure AI utilise par défaut l’approche héritée pour garantir la compatibilité descendante.

Se connecter via l’identité affecté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é affectée par l’utilisateur via l’approche moderne.

POST https://[service name].search.windows.net/datasources?api-version=2024-11-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];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 héritée.

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 d’Azure Cosmos DB pour Gremlin/MongoDB.

Définir la chaîne de connexion

  • Pour les collections MongoDB, ajoutez « ApiKind=MongoDb » à la chaîne de connexion et utilisez une API REST en préversion.
  • Pour les graphiques Gremlin, ajoutez « ApiKind = Gremlin » à la 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 que la seule chaîne de connexion valide est IdentityAuthType=AccountKey ou son omission totale.

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=2024-11-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=2024-11-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 for NoSQL, vérifiez si l’accès du compte aux réseaux sélectionnés est restreint. Vous pouvez éliminer les problèmes de pare-feu en essayant la connexion sans restrictions en place. Reportez-vous à Accès de l’indexeur au contenu protégé par les fonctionnalités de sécurité réseau Azure pour plus d’informations

  • Pour Azure Cosmos DB for NoSQL, si l’indexeur échoue en raison de problèmes d’authentification, vérifiez que les attributions de rôle ont été effectuées à la fois 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 alterné vos clés de compte Azure Cosmos DB, vous devez attendre jusqu’à 15 minutes pour que la chaîne de connexion de l’identité managée fonctionne.

Voir aussi