Authentifier les clients pour les points de terminaison en ligne

  • Article

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 :

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 rôle intégré AzureML Data Scientist 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.

  1. 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>"
    ]
}

  2. 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’autorisation Microsoft.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.

  3. 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é

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

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

  3. 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) et Microsoft.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.

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

  1. connectez-vous à Azure.

    az login

  2. Si vous souhaitez utiliser une identité spécifique, utilisez le code suivant pour vous connecter avec l’identité :

    az login --identity --username <identityId>

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

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

  2. Vous pouvez remplacer auth_mode par key pour l’authentification par clé ou aml_token pour l’authentification par jeton Azure Machine Learning. Dans cet exemple, vous utilisez aad_token pour l’authentification par jeton Microsoft Entra.

    az ml online-endpoint create -f endpoint.yml

  3. Vérifiez l’état du point de terminaison :

    az ml online-endpoint show -n my-endpoint

  4. Si vous souhaitez remplacer auth_mode (par exemple, par aad_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

  5. Si vous souhaitez mettre à jour le point de terminaison existant et spécifier auth_mode (par exemple, sur aad_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)

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

  2. 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 et secondaryKey.
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.

Contenu connexe