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 :

Limites

Les points de terminaison avec le mode d’authentification par jeton Microsoft Entra (aad_token) ne prennent pas en charge le scoring à l’aide de l’interface CLI az ml online-endpoint invoke, du kit de développement logiciel (SDK) ml_client.online_endpoints.invoke() ou des onglets Test ou Consommation d’Azure Machine Learning studio. Utilisez plutôt un kit de développement logiciel (SDK) Python générique ou utilisez l’API REST pour passer le jeton du plan de contrôle. Pour plus d’informations, consultez Scoring des données à l’aide de la clé ou du jeton.

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 Scientistrô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.

  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 vous authentifie pendant la connexion, et le jeton est automatiquement récupéré et transmis pour vous.

  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’identité utilisateur n’a pas besoin de rôles supplémentaires pour obtenir le jeton Microsoft Entra.

Clé ou jeton Azure Machine Learning

Si vous envisagez d’utiliser l’interface CLI pour appeler le point de terminaison et si le point de terminaison est configuré pour utiliser un mode d’authentification par clé ou jeton Azure Machine Learning (aml_token), vous n’êtes pas obligé d’obtenir explicitement le jeton de plan de données, car l’interface CLI le gère pour vous. Toutefois, vous pouvez toujours utiliser l’interface CLI pour obtenir le jeton de plan de données afin de pouvoir l’utiliser avec d’autres canaux, tels que l’API REST.

Pour obtenir la clé ou le jeton Azure Machine Learning (aml_token), utilisez la commande az ml online-endpoint get-credentials. Cette commande retourne un document JSON qui contient la clé ou le jeton Azure Machine Learning.

Les clés sont retournées dans les champs primaryKey et secondaryKey. L’exemple suivant montre comment utiliser le paramètre --query pour retourner uniquement la clé primaire :

export DATA_PLANE_TOKEN=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query primaryKey)

Les jetons Azure Machine Learning sont retournés dans le champ accessToken :

export DATA_PLANE_TOKEN=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query accessToken)

Par ailleurs, les champs expiryTimeUtc et refreshAfterTimeUtc contiennent les heures d’expiration et d’actualisation du jeton.

Jeton Microsoft Entra

Pour obtenir le jeton Microsoft Entra (aad_token) à l’aide de l’interface CLI, utilisez la commande az account get-access-token. Cette commande retourne un document JSON qui contient le jeton Microsoft Entra.

Le jeton Microsoft Entra est retourné dans le champ accessToken :

export DATA_PLANE_TOKEN=`(az account get-access-token --resource https://ml.azure.com --query accessToken | tr -d '"')`

Remarque

  • L’extension CLI ml ne prend pas en charge l’obtention du jeton Microsoft Entra. Utilisez az account get-access-token à la place, comme décrit dans le code précédent.
  • Le jeton pour les opérations de plan de données est récupéré à partir du point de terminaison de ressource Azure ml.azure.com au lieu de management.azure.com, contrairement au jeton pour les opérations de plan de contrôle.

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

Clé ou jeton Azure Machine Learning

Vous pouvez utiliser az ml online-endpoint invoke pour les points de terminaison avec une clé ou un jeton Azure Machine Learning. L’interface CLI gère automatiquement la clé ou le jeton Azure Machine Learning. Vous n’avez donc pas besoin de le transmettre explicitement.

az ml online-endpoint invoke -n my-endpoint -r request.json

Jeton Microsoft Entra

L’utilisation de az ml online-endpoint invoke pour les points de terminaison avec un jeton Microsoft Entra n’est pas prise en charge. Utilisez plutôt l’API REST et utilisez l’URI de scoring du point de terminaison pour appeler le point de terminaison.

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