Authentifier les clients pour les points de terminaison en ligne
S’APPLIQUE À :Extension Azure ML CLI v2 (actuelle)
Kit de développement logiciel (SDK) Python azure-ai-ml v2 (préversion)
Cet article explique comment authentifier les clients pour effectuer des opérations de plan de contrôle et de plan de données sur des points de terminaison en ligne.
Une opération de plan de contrôle permet de contrôler un point de terminaison et de le modifier. Les opérations de plan de contrôle incluent les opérations de création, lecture, mise à jour et suppression (CRUD) sur les points de terminaison en ligne et les déploiements en ligne.
Une opération de plan de données utilise des données pour interagir avec un point de terminaison en ligne sans modifier le point de terminaison. Par exemple, une opération de plan de données peut consister à envoyer une demande de scoring à un point de terminaison en ligne et à obtenir une réponse.
Prérequis
Avant de suivre les étapes décrites dans cet article, vérifiez que vous disposez des composants requis suivants :
Un espace de travail Azure Machine Learning. Si vous n’en avez pas, procédez comme suit dans le Guide de démarrage rapide : Créer des ressources d’espace de travail pour en créer un.
Azure CLI et l’extension
ml
ou le Kit de développement logiciel (SDK) Python Azure Machine Learning v2 :Pour installer Azure CLI et l’extension, consultez Installer, configurer et utiliser l’interface CLI (v2).
Important
Les exemples CLI de cet article supposent que vous utilisez l’interpréteur de commandes Bash (ou compatible). Par exemple, à partir d’un système Linux ou d’un sous-système Windows pour Linux.
Pour installer le kit SDK Python v2, utilisez la commande suivante :
pip install azure-ai-ml azure-identity
Pour mettre à jour une installation existante du Kit de développement logiciel (SDK) vers la version la plus récente, utilisez la commande suivante :
pip install --upgrade azure-ai-ml azure-identity
Pour plus d’informations, consultez Installer le kit SDK Python v2 pour Azure Machine Learning.
Préparer une identité utilisateur
Vous avez besoin d’une identité utilisateur pour effectuer des opérations de plan de contrôle (c’est-à-dire des opérations CRUD) et des opérations de plan de données (autrement dit, envoyer des demandes de scoring) sur le point de terminaison en ligne. Vous pouvez utiliser la même identité utilisateur ou différentes identités utilisateur pour les opérations du plan de contrôle et du plan de données. Dans cet article, vous utilisez la même identité utilisateur pour les opérations de plan de contrôle et de plan de données.
Pour créer une identité d’utilisateur sous Microsoft Entra ID, consultez Configurer l’authentification. Vous aurez besoin de l’ID d’identité ultérieurement.
Attribuer des autorisations à l’identité
Dans cette section, vous attribuez des autorisations à l’identité utilisateur que vous utilisez pour interagir avec le point de terminaison. Vous commencez en utilisant un rôle intégré ou en créant un rôle personnalisé. Ensuite, vous attribuez le rôle à votre identité utilisateur.
Utiliser un rôle intégré
Le AzureML Data Scientist
rôle intégré peut être utilisé pour gérer et utiliser des points de terminaison et des déploiements, et il utilise des caractères génériques pour inclure les actions de RBAC du plan de contrôle suivantes :
Microsoft.MachineLearningServices/workspaces/onlineEndpoints/write
Microsoft.MachineLearningServices/workspaces/onlineEndpoints/delete
Microsoft.MachineLearningServices/workspaces/onlineEndpoints/read
Microsoft.MachineLearningServices/workspaces/onlineEndpoints/token/action
Microsoft.MachineLearningServices/workspaces/onlineEndpoints/listKeys/action
Microsoft.MachineLearningServices/workspaces/onlineEndpoints/regenerateKeys/action
et pour inclure l’action RBAC du plan de données suivante :
Microsoft.MachineLearningServices/workspaces/onlineEndpoints/score/action
Si vous le souhaitez, le rôle intégré Azure Machine Learning Workspace Connection Secrets Reader
peut être utilisé pour accéder aux secrets à partir des connexions de l’espace de travail et inclure les actions de RBAC du plan de contrôle suivantes :
Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action
Microsoft.MachineLearningServices/workspaces/metadata/secrets/read
Si vous utilisez ces rôles intégrés, aucune action n’est nécessaire à cette étape.
(Facultatif) Créer un rôle personnalisé
Vous pouvez ignorer cette étape si vous utilisez des rôles intégrés ou d’autres rôles personnalisés prédéfinis.
Définissez l’étendue et les actions des rôles personnalisés en créant des définitions JSON des rôles. Par exemple, la définition de rôle suivante permet à l’utilisateur d’effectuer une opération CRUD sur un point de terminaison en ligne, sous un espace de travail spécifié.
custom-role-for-control-plane.json :
{ "Name": "Custom role for control plane operations - online endpoint", "IsCustom": true, "Description": "Can CRUD against online endpoints.", "Actions": [ "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/write", "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/delete", "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/read", "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/token/action", "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/listKeys/action", "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/regenerateKeys/action" ], "NotActions": [ ], "AssignableScopes": [ "/subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>" ] }
La définition de rôle suivante permet à l’utilisateur d’envoyer des demandes de scoring à un point de terminaison en ligne, sous un espace de travail spécifié.
custom-role-for-scoring.json :
{ "Name": "Custom role for scoring - online endpoint", "IsCustom": true, "Description": "Can score against online endpoints.", "Actions": [ "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/*/action" ], "NotActions": [ ], "AssignableScopes": [ "/subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>" ] }
Utilisez les définitions JSON pour créer des rôles personnalisés :
az role definition create --role-definition custom-role-for-control-plane.json --subscription <subscriptionId> az role definition create --role-definition custom-role-for-scoring.json --subscription <subscriptionId>
Remarque
Pour créer des rôles personnalisés, vous avez besoin d’un des trois rôles suivants :
- Propriétaire
- administrateur de l’accès utilisateur
- un rôle personnalisé avec l’autorisation
Microsoft.Authorization/roleDefinitions/write
(pour créer/mettre à jour/supprimer des rôles personnalisés) et l’autorisationMicrosoft.Authorization/roleDefinitions/read
(pour afficher les rôles personnalisés).
Pour plus d’informations sur la création des rôles personnalisés, consultez Rôles personnalisés Azure.
Vérifiez la définition de rôle :
az role definition list --custom-role-only -o table az role definition list -n "Custom role for control plane operations - online endpoint" az role definition list -n "Custom role for scoring - online endpoint" export role_definition_id1=`(az role definition list -n "Custom role for control plane operations - online endpoint" --query "[0].id" | tr -d '"')` export role_definition_id2=`(az role definition list -n "Custom role for scoring - online endpoint" --query "[0].id" | tr -d '"')`
Attribuez le rôle à l’identité
Si vous utilisez le rôle intégré
AzureML Data Scientist
, utilisez le code suivant pour attribuer le rôle à votre identité utilisateur.az role assignment create --assignee <identityId> --role "AzureML Data Scientist" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>
Le cas échéant, si vous utilisez le rôle intégré
Azure Machine Learning Workspace Connection Secrets Reader
, utilisez le code suivant pour attribuer le rôle à votre identité utilisateur.az role assignment create --assignee <identityId> --role "Azure Machine Learning Workspace Connection Secrets Reader" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>
Si vous utilisez un rôle personnalisé, utilisez le code suivant pour attribuer le rôle à votre identité utilisateur.
az role assignment create --assignee <identityId> --role "Custom role for control plane operations - online endpoint" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName> az role assignment create --assignee <identityId> --role "Custom role for scoring - online endpoint" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>
Remarque
Pour affecter des rôles personnalisés à l’identité utilisateur, vous avez besoin de l’un des trois rôles suivants :
- Propriétaire
- administrateur de l’accès utilisateur
- un rôle personnalisé qui autorise l’autorisation
Microsoft.Authorization/roleAssignments/write
(pour attribuer des rôles personnalisés) etMicrosoft.Authorization/roleAssignments/read
(pour afficher les attributions de rôles).
Pour plus d’informations sur les différents rôles Azure et leurs autorisations, consultez Rôles Azure et Attribution de rôles Azure à l’aide du portail Azure.
Confirmez l’attribution de rôle :
az role assignment list --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>
Obtenir le jeton Microsoft Entra pour les opérations de plan de contrôle
Effectuez cette étape si vous envisagez d’effectuer des opérations de plan de contrôle avec l’API REST, qui utilisera directement le jeton.
Si vous envisagez d’utiliser d’autres méthodes telles que l’interface CLI Azure Machine Learning (v2), le kit de développement logiciel (SDK) Python (v2) ou Azure Machine Learning studio, vous n’avez pas besoin d’obtenir manuellement le jeton Microsoft Entra. Au lieu de cela, pendant la connexion, votre identité utilisateur est déjà authentifiée, et le jeton est automatiquement récupéré et transmis pour vous.
Vous pouvez récupérer le jeton Microsoft Entra pour les opérations de plan de contrôle à partir du point de terminaison de ressource Azure : https://management.azure.com
.
connectez-vous à Azure.
az login
Si vous souhaitez utiliser une identité spécifique, utilisez le code suivant pour vous connecter avec l’identité :
az login --identity --username <identityId>
Utilisez ce contexte pour obtenir le jeton.
export CONTROL_PLANE_TOKEN=`(az account get-access-token --resource https://management.azure.com --query accessToken | tr -d '"')`
(Facultatif) Vérifier le point de terminaison de ressource et l’ID client pour le jeton Microsoft Entra
Après avoir récupéré le jeton Microsoft Entra, vous pouvez vérifier que le jeton est destiné au point de terminaison de ressource Azure management.azure.com
approprié et à l’ID client approprié en décodant le jeton via jwt.ms, ce qui renvoie une réponse json avec les informations suivantes :
{
"aud": "https://management.azure.com",
"oid": "<your-object-id>"
}
Créer un point de terminaison
L’exemple suivant crée le point de terminaison avec une identité affectée par le système (SAI) comme identité de point de terminaison. La SAI est le type d’identité par défaut de l’identité managée pour les points de terminaison. Certains rôles de base sont automatiquement attribués pour la SAI. Pour plus d’informations sur l’attribution de rôle pour une identité affectée par le système, consultez Attribution automatique de rôle pour l’identité de point de terminaison.
L’interface CLI ne vous oblige pas à fournir explicitement le jeton du plan de contrôle. Au lieu de cela, l’interface CLI az login
vous authentifie pendant la connexion, et le jeton est automatiquement récupéré et transmis.
Créez un fichier YAML de définition de point de terminaison.
endpoint.yml :
$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json name: my-endpoint auth_mode: aad_token
Vous pouvez remplacer
auth_mode
parkey
pour l’authentification par clé ouaml_token
pour l’authentification par jeton Azure Machine Learning. Dans cet exemple, vous utilisezaad_token
pour l’authentification par jeton Microsoft Entra.az ml online-endpoint create -f endpoint.yml
Vérifiez l’état du point de terminaison :
az ml online-endpoint show -n my-endpoint
Si vous souhaitez remplacer
auth_mode
(par exemple, paraad_token
) lors de la création d’un point de terminaison, exécutez le code suivant :az ml online-endpoint create -n my-endpoint --auth_mode aad_token
Si vous souhaitez mettre à jour le point de terminaison existant et spécifier
auth_mode
(par exemple, suraad_token
), exécutez le code suivant :az ml online-endpoint update -n my-endpoint --set auth_mode=aad_token
Créer un déploiement
Pour créer un déploiement, consultez Déployer un modèle ML avec un point de terminaison en ligne ou Utiliser REST pour déployer un modèle en tant que point de terminaison en ligne. Il n’existe aucune différence dans la façon dont vous créez des déploiements pour différents modes d’authentification.
Le code suivant est un exemple de création d’un déploiement. Pour plus d’informations sur le déploiement de points de terminaison en ligne, consultez Déployer un modèle ML avec un point de terminaison en ligne (via l’interface CLI)
Créez un fichier YAML de définition de déploiement.
blue-deployment.yml :
$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json name: blue endpoint_name: my-aad-auth-endp1 model: path: ../../model-1/model/ code_configuration: code: ../../model-1/onlinescoring/ scoring_script: score.py environment: conda_file: ../../model-1/environment/conda.yml image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest instance_type: Standard_DS3_v2 instance_count: 1
Créez le déploiement en utilisant le fichier YAML. Pour cet exemple, définissez tout le trafic vers le nouveau déploiement.
az ml online-deployment create -f blue-deployment.yml --all-traffic
Obtenir l’URI de scoring pour le point de terminaison
Si vous envisagez d’utiliser l’interface CLI pour appeler le point de terminaison, vous n’êtes pas obligé d’obtenir explicitement l’URI de scoring, car l’interface CLI le gère pour vous. Toutefois, vous pouvez toujours utiliser l’interface CLI pour obtenir l’URI de scoring afin de pouvoir l’utiliser avec d’autres canaux, tels que l’API REST.
scoringUri=$(az ml online-endpoint show -n my-endpoint --query "scoring_uri")
Obtenir la clé ou le jeton pour les opérations de plan de données
Une clé ou un jeton peut être utilisé pour les opérations de plan de données, même si le processus d’obtention de la clé ou du jeton est une opération de plan de contrôle. En d’autres termes, vous utilisez un jeton de plan de contrôle pour obtenir la clé ou le jeton que vous utilisez ultérieurement pour effectuer vos opérations de plan de données.
L’obtention de la clé ou du jeton Azure Machine Learning nécessite que le rôle approprié soit affecté à l’identité utilisateur qui la demande, comme décrit dans Autorisation pour les opérations du plan de contrôle. L’obtention du jeton Microsoft Entra ne nécessite pas de rôles supplémentaires pour l’identité utilisateur.
Si vous envisagez d’utiliser l’interface CLI pour appeler le point de terminaison, vous n’avez pas besoin d’obtenir explicitement les clés ou le jeton pour les opérations de plan de données, car l’interface CLI s’en charge à votre place. Cependant, vous pouvez toujours utiliser l’interface CLI pour obtenir les clés ou le jeton pour l’opération de plan de données pour pouvoir les utiliser avec d’autres canaux, tels que l’API REST.
Pour obtenir les clés ou le jeton pour des opérations de plan de données, utilisez la commande az ml online-endpoint get-credentials. Cette commande retourne une sortie JSON qui contient les clés, le jeton et/ou des informations supplémentaires.
Conseil
Pour extraire des informations spécifiques de la sortie JSON, le paramètre --query
de la commande CLI est utilisé comme exemple. Toutefois, vous pouvez utiliser n’importe quel outil approprié à cet effet.
Quand auth_mode
du point de terminaison est key
- Les clés sont retournées dans les champs
primaryKey
etsecondaryKey
.
export DATA_PLANE_TOKEN=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query primaryKey)
export DATA_PLANE_TOKEN2=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query secondaryKey)
Quand auth_mode
du point de terminaison est aml_token
- Le jeton est retourné dans le champ
accessToken
. - L’heure d’expiration du jeton est retournée dans le champ
expiryTimeUtc
. - L’heure d’actualisation du jeton est retournée dans le champ
refreshAfterTimeUtc
.
export DATA_PLANE_TOKEN=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query accessToken)
export EXPIRY_TIME_UTC=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query expiryTimeUtc)
export REFRESH_AFTER_TIME_UTC=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query refreshAfterTimeUtc)
Quand auth_mode
du point de terminaison est aad_token
- Le jeton est retourné dans le champ
accessToken
. - L’heure d’expiration du jeton est retournée dans le champ
expiryTimeUtc
.
export DATA_PLANE_TOKEN=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query accessToken)
export EXPIRY_TIME_UTC=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query expiryTimeUtc)
Vérifier le point de terminaison de ressource et l’ID client du jeton Microsoft Entra
Après avoir obtenu le jeton Entra, vous pouvez vérifier que le jeton est destiné au point de terminaison de ressource Azure ml.azure.com
approprié et à l’ID client approprié en décodant le jeton via jwt.ms, qui retourne une réponse json avec les informations suivantes :
{
"aud": "https://ml.azure.com",
"oid": "<your-object-id>"
}
Scorer les données en utilisant la clé ou le jeton
Vous pouvez utiliser az ml online-endpoint invoke
pour les points de terminaison avec une clé, un jeton Azure Machine Learning ou un jeton Microsoft Entra. L’interface CLI gère automatiquement la clé ou le jeton. Vous n’avez donc pas besoin de le transmettre explicitement.
az ml online-endpoint invoke -n my-endpoint -r request.json
Journaliser et surveiller le trafic
Pour activer la journalisation du trafic dans les paramètres de diagnostic du point de terminaison, suivez les étapes décrites dans Comment activer/désactiver les journaux.
Si le paramètre de diagnostic est activé, vous pouvez vérifier la table AmlOnlineEndpointTrafficLogs
pour afficher le mode d’authentification et l’identité utilisateur.