Activer ou désactiver le contrôle d’accès en fonction du rôle dans Recherche Azure AI

Si vous voulez utiliser le contrôle d’accès en fonction du rôle Azure pour les connexions à Recherche Azure AI, cet article vous explique comment l’activer pour votre service de recherche.

L’accès en fonction du rôle pour les opérations de plan de données est facultatif, mais recommandé. L’alternative est l’authentification par clé, qui est la valeur par défaut.

Les rôles d’administration de service (plan de contrôle) sont intégrés et ne peuvent être ni activés, ni désactivés.

Remarque

Le plan de données fait référence aux opérations sur le point de terminaison du service de recherche, comme l’indexation ou les requêtes, ou toute autre opération spécifiée dans l'API REST Recherche ou les bibliothèques clientes du kit de développement logiciel (SDK) équivalentes.

Prérequis

• Propriétaire ou Administrateur d’accès utilisateur ou rôle personnalisé avec des autorisations Microsoft.Authorization/roleAssignments/write.

• Un service de recherche dans n’importe quelle région, sur n’importe quel niveau, y compris le niveau gratuit.

Activer le contrôle d’accès en fonction du rôle pour les opérations de plan de données

Lorsque vous activez les rôles pour le plan de données, la modification est effective immédiatement, mais attendez quelques secondes avant d’attribuer des rôles.

Le mode d’échec par défaut est http401WithBearerChallenge. Vous pouvez également définir le mode d’échec sur http403.

Une fois l’accès en fonction du rôle activé, le service de recherche reconnaît un en-tête d’autorisation sur les requêtes de plan de données qui fournissent un jeton d’accès OAuth2.

Azure portal

1. Connectez-vous au portail Azure et ouvrez la page du service de recherche.

2. Sélectionnez Paramètres, puis sélectionnez Clés dans le volet de navigation gauche.

   

3. Choisissez Contrôle en fonction du rôle ou Les deux si vous utilisez actuellement des clés et avez besoin de temps pour passer des clients vers le contrôle d’accès en fonction du rôle.

   Option	Description
   Clé API	(Valeur par défaut.) Nécessite des clés API dans l’en-tête de demande pour l’autorisation.
   Contrôle d’accès en fonction du rôle	Nécessite l’appartenance à une attribution de rôle pour terminer la tâche. Nécessite aussi un en-tête d’autorisation dans la demande.
   Les deux	Les demandes sont valides aussi bien avec une clé API qu’un contrôle d’accès en fonction du rôle. Cependant, si vous fournissez les deux dans la même demande, la clé API est utilisée.

4. En tant qu’administrateur, si vous choisissez une approche de rôle uniquement, attribuez des rôles du plan de données à votre compte d’utilisateur pour restaurer un accès administratif complet sur les opérations du plan de données dans le Portail Azure. Les rôles comprennent le Contributeur de service de recherche, le Contributeur de données d’index de recherche et le Lecteur de données d’index de recherche. Vous avez besoin des trois rôles si vous souhaitez disposer d’un accès équivalent.

   Cinq à dix minutes peuvent être nécessaires pour que les attributions de rôles prennent effet. En attendant, le message suivant s’affiche dans les pages du portail utilisées pour les opérations du plan de données.

   

Azure CLI

Exécutez ce script pour prendre en charge les rôles uniquement :

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --disable-local-auth

Ou exécutez ce script pour prendre en charge à la fois les clés et les rôles :

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --aad-auth-failure-mode http401WithBearerChallenge `
  --auth-options aadOrApiKey

Pour plus d’informations, consultez Gérer votre service Recherche Azure AI avec l’interface de ligne de commande Azure.

Azure PowerShell

Exécutez cette commande pour définir le type d’authentification sur les rôles uniquement :

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -DisableLocalAuth 1

Ou exécutez cette commande pour prendre en charge à la fois les clés et les rôles :

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -AuthOption AadOrApiKey

Pour plus d’informations, consultez Gérer votre service Recherche Azure AI avec PowerShell.

REST API

Utilisez l’API REST de gestion Créer ou mettre à jour le service pour configurer votre service pour le contrôle d’accès en fonction du rôle (RBAC).

Tous les appels à l’API REST de gestion sont authentifiés avec Microsoft Entra ID. Pour obtenir de l’aide sur la configuration des requêtes authentifiées, consultez Gérer recherche Azure AI à l’aide de REST.

1. 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
   

2. 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"
               }
           }
       }
   }
   

Désactiver le contrôle d’accès en fonction du rôle

Il est possible de désactiver le contrôle d’accès en fonction du rôle pour les opérations de plan de données et d’utiliser l’authentification basée sur des clés à la place. Vous pourriez faire ainsi dans le cadre d’un flux de travail de test, par exemple pour exclure les problèmes d’autorisation.

Inversez les étapes que vous avez suivies précédemment pour activer l’accès en fonction du rôle.

1. Connectez-vous au portail Azure et ouvrez la page du service de recherche.

2. Sélectionnez Paramètres, puis sélectionnez Clés dans le volet de navigation gauche.

3. Sélectionnez API Keys (Clés API).

Désactiver l'authentification par clé API

L’accès par clé, ou authentification locale, peut être désactivé sur votre service si vous utilisez exclusivement les rôles intégrés et l’authentification Microsoft Entra. La désactivation des clés API entraîne le refus par le service de recherche de toutes les requêtes liées aux données qui passent une clé API dans l’en-tête.

Les clés API d’administration peuvent être désactivées, mais pas supprimées. Vous pouvez supprimer des clés API de requête.

Des autorisations Propriétaire ou Contributeur sont requises pour désactiver les fonctionnalités de sécurité.

Azure portal

1. Dans le portail Azure, accédez à votre service de recherche.

2. Dans le volet de navigation gauche, sélectionnez Clés.

3. Sélectionnez Contrôle d’accès en fonction du rôle.

La modification est effective immédiatement, mais attendez quelques secondes avant de tester. Si vous êtes autorisé à attribuer des rôles en tant que membre Propriétaire, Administrateur de service ou Coadministrateur, vous pouvez utiliser les fonctionnalités du portail pour tester l’accès en fonction du rôle.

Azure CLI

Pour désactiver l’authentification par clé, définissez - disableLocalAuth sur true. Il s’agit de la même syntaxe que le script « Activer les rôles uniquement » présenté dans la section précédente.

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --disable-local-auth

Pour réactiver l’authentification par clé, définissez -disableLocalAuth sur false. Le service de recherche recommence à accepter automatiquement les clés API sur la requête (en supposant qu'elles soient spécifiées).

Pour plus d’informations, consultez Gérer votre service Recherche Azure AI avec l’interface de ligne de commande Azure.

Azure PowerShell

Pour désactiver l’authentification par clé, définissez DisableLocalAuth sur true. Il s’agit de la même syntaxe que le script « Activer les rôles uniquement » présenté dans la section précédente.

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -DisableLocalAuth 1

Pour réactiver l’authentification par clé, définissez DisableLocalAuth sur false. Le service de recherche recommence à accepter automatiquement les clés API sur la requête (en supposant qu'elles soient spécifiées).

Pour plus d’informations, consultez Gérer votre service Recherche Azure AI avec PowerShell.

REST API

Pour désactiver l’authentification basée sur des clés, définissez « disableLocalAuth » sur true.

1. 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
   

2. Utilisez PATCH pour mettre à jour la configuration du service. La modification suivante définit « authOptions » sur Null.

   PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
   {
       "properties": {
           "disableLocalAuth": true
       }
   }
   

Pour réactiver l’authentification par clé, définissez « disableLocalAuth » sur false. Le service de recherche recommence à accepter automatiquement les clés API sur la requête (en supposant qu'elles soient spécifiées).

Limites

• Le contrôle d’accès en fonction du rôle peut augmenter la latence de certaines demandes. Chaque combinaison unique de ressource de service (index, indexeur, etc.) et de principal de service déclenche une vérification d’autorisation. Ces vérifications d’autorisation peuvent ajouter jusqu’à 200 millisecondes de latence par demande.

• Dans de rares cas où les demandes proviennent d’un grand nombre de principaux de service différents, ciblant différentes ressources de service (index, indexeurs, etc.), il est possible que les vérifications d’autorisation entraînent une limitation. La limitation se produit uniquement si des centaines de combinaisons uniques de chaque ressource du service de recherche et du principal de service ont été utilisées en une seconde.

---

Étapes suivantes

Configurer des rôles pour l’accès à un service de recherche