Autoriser l’accès à une application de recherche à l’aide de Microsoft Entra ID

Article
04/25/2024

Les applications de recherche basées sur Recherche Azure AI peuvent désormais utiliser la plateforme d’identités Microsoft pour l’accès authentifié et autorisé. Sur Azure, le fournisseur d’identité est Microsoft Entra ID. L’un des avantages clés de Microsoft Entra ID est qu’il élimine la nécessité de stocker vos informations d’identification et vos clés API dans le code. Microsoft Entra authentifie le principal de sécurité (un utilisateur, un groupe ou un service) qui exécute l’application. Si l’authentification réussit, Microsoft Entra ID retourne le jeton d’accès à l’application, qui peut ensuite l’utiliser pour autoriser les requêtes adressées à Recherche Azure AI.

Cet article explique comment configurer votre client pour Microsoft Entra ID :

Pour l'authentification, créez une identité gérée pour votre application. Vous pouvez utiliser un autre type d’objet principal de sécurité, mais cet article utilise des identités managées, car elles éliminent la nécessité de gérer les informations d’identification.
Pour l’autorisation, attribuez un rôle Azure à l’identité managée qui accorde des autorisations pour exécuter des requêtes ou gérer des travaux d’indexation.
Mettez à jour votre code client pour appeler TokenCredential(). Par exemple, vous pouvez commencer à utiliser le nouveau SearchClient(endpoint, new DefaultAzureCredential()) pour vous authentifier via Microsoft Entra ID à l’aide d’Azure.Identity.

Configurer l’accès en fonction du rôle pour le plan de données

S’applique à : Recherche dans l’index de données Contributeur, Lecteur de données d’index de recherche, Contributeur du Service de recherche

Dans cette étape, configurez votre service de recherche afin qu’il reconnaisse un en-tête d’autorisation sur les demandes de données qui fournissent un jeton d’accès OAuth2.

Azure portal
REST API

Connectez-vous au portail Azure et ouvrez la page du service de recherche.
Sélectionnez Clés dans le volet de navigation de gauche.

Choisissez une option de contrôle d’accès à l’API. Nous vous recommandons de choisir l’option Les deux si vous souhaitez une flexibilité ou si vous avez besoin de migrer des applications.

Option	Description
Clé API	(par défaut) Nécessite des clés API de requête ou administrateur dans l’en-tête de la requête pour l’autorisation. Aucun rôle n’est utilisé.
Contrôle d’accès en fonction du rôle	Nécessite l’appartenance à une attribution de rôle pour terminer la tâche, décrite dans l’étape suivante. Chaque requête nécessite un en-tête d’autorisation.
Les deux	Les requêtes sont valides à l’aide d’une clé API ou du contrôle d’accès en fonction du rôle (RBAC).

La modification est effective immédiatement, mais attendez quelques secondes avant de tester.

Tous les appels réseau pour les opérations de service de recherche et le contenu respectent l’option que vous sélectionnez : clés API, jeton du porteur ou les deux si vous sélectionnez Les deux.

Lorsque vous activez le contrôle d’accès en fonction du rôle dans le portail, le mode d’échec est « http401WithBearerChallenge » si l’autorisation échoue.

Utilisez l’API REST de gestion Créer ou mettre à jour le service pour configurer votre service.

Tous les appels à l’API REST de gestion sont authentifiés via Microsoft Entra ID, avec les autorisations Contributeur ou Propriétaire. Pour obtenir de l'aide sur la configuration des requêtes authentifiées dans un client REST, consultez Gérer Azure AI Search à l'aide de REST.

Obtenez les paramètres de service pour pouvoir passer en revue la configuration actuelle.

GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01

Utilisez PATCH pour mettre à jour la configuration du service. Les modifications suivantes activent à la fois les clés et l’accès en fonction du rôle. Si vous souhaitez une configuration de rôles uniquement, consultez Désactiver les clés API.

Sous « Propriétés », définissez « authOptions » sur « aadOrApiKey ». La propriété « disableLocalAuth » doit être false pour définir « authOptions ».

Si vous le souhaitez, définissez « aadAuthFailureMode » pour spécifier si 401 est retourné à la place de 403 lorsque l’authentification échoue. Les valeurs valides sont « http401WithBearerChallenge » ou « 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"
            }
        }
    }
}
```

Créer une identité managée

Au cours de cette étape, créez une identité managée pour votre application cliente.

Connectez-vous au portail Azure.
Recherchez Identités managées.
Sélectionnez Créer.
Donnez un nom à votre identité managée et sélectionnez une région. Sélectionnez ensuite Create (Créer).

Attribuer un rôle à l’identité managée

Ensuite, vous devez accorder l’accès de l’identité managée de votre client à votre service de recherche. Recherche Azure AI intègre plusieurs rôles. Vous pouvez également créer un rôle personnalisé.

Il est recommandé d’accorder des autorisations minimales. Si votre application doit uniquement gérer les requêtes, vous devez attribuer le rôle Lecteur de données d’index de recherche. Alternativement, si le client a besoin d'un accès en lecture et en écriture sur un index de recherche, vous devez utiliser le rôle Contributeur de données d'index de recherche.

Connectez-vous au portail Azure.
Accéder à votre service de recherche.
Sélectionnez Contrôle d’accès (IAM) dans le menu de navigation de gauche.
Sélectionnez + Ajouter>Ajouter une attribution de rôle.
Sélectionnez un rôle applicable :
- Propriétaire
- Contributeur
- Lecteur
- Contributeur du service de recherche
- Contributeur de données d’index de la Recherche
- Lecteur de données d’index de la Recherche
  
  Remarque
  
  Le propriétaire, le contributeur, le lecteur et le contributeur du service de recherche sont des rôles de plan de contrôle et ne vous donnent pas accès aux données dans un index de recherche. Pour l’accès aux données, choisissez le rôle Contributeur aux données d’index de recherche ou Lecteur de données d’index de recherche. Pour plus d'informations sur la portée et l'objectif de chaque rôle, consultez Rôles intégrés utilisés dans la recherche.
Sous l’onglet Membres, sélectionnez l’identité managée à laquelle vous souhaitez octroyer l’accès à votre service de recherche.
Dans l’onglet Passer en revue + affecter, sélectionnez Passer en revue + affecter pour affecter le rôle.

Vous pouvez attribuer plusieurs rôles, tels que Contributeur du service de recherche et Contributeur de données d’index de recherche, si votre application a besoin d’un accès complet aux services de recherche, aux objets et au contenu.

Vous pouvez également attribuer des rôles à l’aide de PowerShell.

Configurer l’authentification Microsoft Entra dans votre client

Une fois que vous avez une identité managée et une attribution de rôle sur le service de recherche, vous êtes prêt à ajouter du code à votre application pour authentifier le principal de sécurité et acquérir un jeton OAuth 2.0.

Utilisez les bibliothèques de client suivantes pour le contrôle d’accès en fonction du rôle :

Remarque

Pour en savoir plus sur le flux d’octroi de code OAuth 2.0 utilisé par Microsoft Entra ID, consultez Autoriser l’accès aux applications web Microsoft Entra à l’aide du flux d’octroi de code OAuth 2.0.

Kit de développement logiciel (SDK) .NET
REST API

Les instructions suivantes font référence à un exemple C# existant pour illustrer les modifications de code.

En guise de point de départ, clonez le code source de la section C# de Démarrage rapide : recherche en texte intégral à l’aide des kits SDK Azure.

L’exemple utilise actuellement l’authentification par clé et le AzureKeyCredential pour créer les SearchClient et SearchIndexClient, mais vous pouvez apporter une petite modification pour passer à l’authentification par rôle.
Mettez à jour le package NuGet Azure.Search.Documents vers la version 11.4 ou ultérieure.
Importez la bibliothèque Azure.Identity pour accéder à d’autres techniques d’authentification.

Au lieu d’utiliser AzureKeyCredential au début de Main() dans Program.cs, utilisez DefaultAzureCredential comme dans l’extrait de code ci-dessous :

// 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());

Test local

Les identités managées affectées par l’utilisateur fonctionnent uniquement dans les environnements Azure. Si vous exécutez ce code localement, DefaultAzureCredential revient à s’authentifier avec vos informations d’identification. Veillez à vous donner l’accès requis au service de recherche si vous envisagez d’exécuter le code localement.

Vérifiez que votre compte dispose d’attributions de rôles pour exécuter toutes les opérations dans l’exemple de démarrage rapide. Pour créer et interroger un index, utilisez « Lecteur de données d’index de recherche » et « Contributeur aux données d’index de recherche ».
Accédez à Outils>Options>Authentication par le service Azure pour choisir votre compte d’authentification Azure.

Vous devez maintenant être en mesure d’exécuter le projet à partir de Visual Studio sur votre système local, en utilisant le contrôle d’accès en fonction du rôle pour l’autorisation.

Remarque

La documentation d’Azure.Identity contient des détails supplémentaires sur DefaultAzureCredential et l’utilisation de l’authentification Microsoft Entra avec le kit SDK Azure pour .NET. DefaultAzureCredential vise à simplifier la prise en main du Kit de développement logiciel (SDK) en gérant des scénarios courants avec des comportements par défaut raisonnables. Les développeurs qui souhaitent davantage de contrôle ou dont le scénario n’est pas pris en charge par les paramètres par défaut doivent utiliser d’autres types d’informations d’identification.

L’utilisation d’un Kit de développement logiciel (SDK) Azure simplifie le flux OAuth 2.0, mais vous pouvez également programmer directement dans le protocole de votre application. Tous les détails sont disponibles dans Plateforme d’identités Microsoft et flux d’informations d’identification du client OAuth 2.0.

Commencez par obtenir un jeton auprès de la plateforme d’identités Microsoft :

POST /[tenant id]/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=[client id]
&scope=https%3A%2F%2Fsearch.azure.com%2F.default
&client_secret=[client secret]
&grant_type=client_credentials

L’étendue requise est "https://search.azure.com/.default".

Maintenant que vous avez un jeton, vous êtes prêt à envoyer une demande au service de recherche.

GET https://[service name].search.windows.net/indexes/[index name]/docs?[query parameters]
Content-Type: application/json   
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...