Autenticare i client per gli endpoint online

  • Articolo

SI APPLICA A:Estensione ML dell'interfaccia della riga di comando di Azure v2 (corrente)Python SDK azure-ai-ml v2 (corrente)

Questo articolo illustra come autenticare i client per l'esecuzione di operazioni del piano di controllo e del piano dati su endpoint online.

Un'operazione del piano di controllo controlla un endpoint e lo cambia. Queste operazioni includono creazione, lettura, aggiornamento ed eliminazione (CRUD) su endpoint online e distribuzioni online.

Un'operazione del piano dati usa i dati per interagire con un endpoint online senza cambiarlo. Ad esempio, un'operazione dal piano dati potrebbe consistere nell'invio di una richiesta di assegnazione dei punteggi a un endpoint online e nella ricezione di una risposta.

Prerequisiti

Prima di seguire la procedura descritta in questo articolo, assicurarsi di disporre dei prerequisiti seguenti:

Preparare un'identità utente

Per eseguire le operazioni del piano di controllo (CRUD) e del piano dati (invio di richieste di assegnazione dei punteggi) sugli endpoint online, è necessaria un'identità utente. È possibile usare la stessa identità utente o diverse per le operazioni del piano di controllo e del piano dati. In questo articolo viene usata la stessa identità utente per le operazioni del piano di controllo e del piano dati.

Per creare un'identità utente in Microsoft Entra ID, vedere Configurare l'autenticazione. L'ID identità sarà necessario in un secondo momento.

Assegnare autorizzazioni all'identità

In questa sezione si assegnano le autorizzazioni all'identità utente da usare per interagire con l'endpoint. Per iniziare, usare un ruolo predefinito o creare un ruolo personalizzato. Successivamente, assegnare il ruolo all'identità utente.

Usare un ruolo predefinito

Il AzureML Data Scientistruolo predefinito può essere usato per gestire e usare endpoint e distribuzioni e usa caratteri jolly per includere le azioni seguenti di controllo degli accessi in base al ruolo del piano di controllo:

  • 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

e per includere l'azione seguente di controllo degli accessi in base al ruolo del piano dati:

  • Microsoft.MachineLearningServices/workspaces/onlineEndpoints/score/action

Facoltativamente, il ruolo predefinito Azure Machine Learning Workspace Connection Secrets Reader può essere usato per accedere ai segreti delle connessioni all'area di lavoro e include le azioni di controllo degli accessi in base al ruolo seguenti del piano di controllo:

  • Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action
  • Microsoft.MachineLearningServices/workspaces/metadata/secrets/read

Se si usano questi ruoli predefiniti, non è necessaria alcuna azione in questo passaggio.

(Facoltativo) Creare un ruolo personalizzato

È possibile ignorare questo passaggio se si usano ruoli predefiniti o altri ruoli personalizzati predefiniti.

  1. Definire l'ambito e le azioni per i ruoli personalizzati creando le relative definizioni JSON. Ad esempio, la definizione del ruolo seguente consente all'utente di eseguire operazioni CRUD su un endpoint online, in un'area di lavoro specificata.

    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 definizione del ruolo seguente consente all'utente di inviare richieste di assegnazione dei punteggi a un endpoint online, in un'area di lavoro specificata.

    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. Usare le definizioni JSON per creare ruoli personalizzati:

    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>

    Nota

    Per creare ruoli personalizzati è necessario uno di questi tre ruoli:

    • owner
    • Amministratore Accesso utente
    • Un ruolo personalizzato con autorizzazione Microsoft.Authorization/roleDefinitions/write (per creare/aggiornare/eliminare ruoli personalizzati) e un'autorizzazione Microsoft.Authorization/roleDefinitions/read (per visualizzare ruoli personalizzati).

    Per altre informazioni sulla creazione di ruoli personalizzati, vedere Ruoli personalizzati di Azure.

  3. Verificare la definizione del ruolo:

    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 '"')`

Assegnare il ruolo all'identità

  1. Se si usa il ruolo predefinito AzureML Data Scientist, usare il codice seguente per assegnarlo all'identità utente.

    az role assignment create --assignee <identityId> --role "AzureML Data Scientist" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>

  2. Facoltativamente, se si usa il ruolo predefinito Azure Machine Learning Workspace Connection Secrets Reader, usare il codice seguente per assegnarlo all'identità utente.

    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. Se si usa un ruolo personalizzato, usare il codice seguente per assegnarlo all'identità utente.

    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>

    Nota

    Per assegnare ruoli personalizzati all'identità utente, è necessario uno dei tre ruoli seguenti:

    • owner
    • Amministratore Accesso utente
    • Un ruolo personalizzato che consente l'autorizzazione Microsoft.Authorization/roleAssignments/write (per assegnare ruoli personalizzati) e Microsoft.Authorization/roleAssignments/read (per visualizzare le assegnazioni di ruolo).

    Per altre informazioni sui diversi ruoli di Azure e sulle relative autorizzazioni, vedere Ruoli di Azure e Assegnazione di ruoli di Azure tramite il portale di Azure.

  4. Creare l'assegnazione di ruolo:

    az role assignment list --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>

Ottenere il token di Microsoft Entra per le operazioni del piano di controllo

Eseguire questo passaggio se si prevede di eseguire operazioni del piano di controllo con l'API REST, che userà direttamente il token.

Se si prevede di usare altri modi, ad esempio l'interfaccia della riga di comando di Azure Machine Learning (v2), Python SDK (v2) o lo studio di Azure Machine Learning, non è necessario ottenere manualmente il token di Microsoft Entra. Durante l'accesso, invece, l'identità utente sarà già stata autenticata e il token sarà stato recuperato e passato automaticamente.

È possibile recuperare il token di Microsoft Entra per le operazioni del piano di controllo dall'endpoint della risorsa di Azure: https://management.azure.com.

  1. Accedere ad Azure.

    az login

  2. Se si vuole usare un'identità specifica, usare il codice seguente per accedere con l'identità:

    az login --identity --username <identityId>

  3. Usare questo contesto per ottenere il token.

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

(Facoltativo) Verificare l'endpoint della risorsa e l'ID client per individuare il token di Microsoft Entra

Dopo aver recuperato il token di Microsoft Entra, è possibile verificare che sia quello per l'endpoint della risorsa di Azure corretto management.azure.com e l'ID client corretto decodificando il token tramite jwt.ms, che restituirà una risposta JSON con le informazioni seguenti:

{
    "aud": "https://management.azure.com",
    "oid": "<your-object-id>"
}

Creare un endpoint

L'esempio seguente crea un endpoint con un'identità assegnata dal sistema (SAI). SAI è il tipo di identità predefinito dell'identità gestita per gli endpoint. Alcuni ruoli di base vengono assegnati automaticamente per SAI. Per altre informazioni sull'assegnazione di ruolo per un'identità assegnata dal sistema, vedere Assegnazione di ruolo automatica per l'identità dell'endpoint.

L'interfaccia della riga di comando non richiede di fornire esplicitamente il token del piano di controllo. Al contrario, l'interfaccia della riga di comando az login esegue l'autenticazione durante l'accesso e il token viene recuperato e passato automaticamente.

  1. Creare un file YAML di definizione dell'endpoint.

    endpoint.yml:

    $schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: my-endpoint
auth_mode: aad_token

  2. È possibile sostituire auth_mode con key per l'autenticazione della chiave o con aml_token per l'autenticazione del token di Azure Machine Learning. In questo esempio si usa aad_token per l'autenticazione del token di Microsoft Entra.

    az ml online-endpoint create -f endpoint.yml

  3. Controllare lo stato dell'endpoint:

    az ml online-endpoint show -n my-endpoint

  4. Se si vuole eseguire l'override del valore di auth_mode (ad esempio sostituendolo con aad_token) durante la creazione di un endpoint, eseguire il codice seguente:

    az ml online-endpoint create -n my-endpoint --auth_mode aad_token

  5. Se si vuole aggiornare l'endpoint esistente e specificare auth_mode (ad esempio su aad_token), eseguire il codice seguente:

    az ml online-endpoint update -n my-endpoint --set auth_mode=aad_token

Creare una distribuzione

Per creare una distribuzione, vedere Distribuire un modello di Machine Learning con un endpoint online o Usare REST per distribuire un modello come endpoint online. Non esiste alcuna differenza nel modo in cui si creano distribuzioni per le diverse modalità di autenticazione.

Il codice seguente è un esempio di come creare una distribuzione. Per altre informazioni sulla distribuzione di endpoint online, vedere Distribuire un modello di Machine Learning con un endpoint online (tramite interfaccia della riga di comando)

  1. Creare un file YAML di definizione della distribuzione.

    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. Creare la distribuzione usando il file YAML. Per questo esempio, impostare tutto il traffico sulla nuova distribuzione.

    az ml online-deployment create -f blue-deployment.yml --all-traffic

Ottenere l'URI di assegnazione dei punteggi per l'endpoint

Se si prevede di usare l'interfaccia della riga di comando per richiamare l'endpoint, non è necessario ottenere esplicitamente l'URI di assegnazione dei punteggi, perché l'interfaccia della riga di comando gestisce questo aspetto automaticamente. Tuttavia, è comunque possibile usare l'interfaccia della riga di comando per ottenere l'URI di assegnazione dei punteggi in modo da poterlo usare con altri canali, ad esempio l'API REST.

scoringUri=$(az ml online-endpoint show -n my-endpoint --query "scoring_uri")

Ottenere la chiave o il token per le operazioni del piano dati

È possibile usare una chiave o un token per le operazioni del piano dato, anche se il processo per ottenerli è un'operazione del piano di controllo. In altre parole, si usa un token del piano di controllo per ottenere la chiave o il token che viene usato in un secondo momento per eseguire le operazioni del piano dati.

Per ottenere la chiave o il token di Azure Machine Learning, è necessario che sia assegnato il ruolo corretto all'identità utente che lo richiede, come descritto in Autorizzazione per le operazioni del piano di controllo. Per ottenere il token di Microsoft Entranon sono richiesti ruoli aggiuntivi per l'identità utente.

Se si prevede di usare l'interfaccia della riga di comando per richiamare l'endpoint, non è necessario ottenere le chiavi o il token per le operazioni del piano dati in modo esplicito, perché l'interfaccia della riga di comando gestisce questo aspetto automaticamente. Tuttavia, è comunque possibile usare l'interfaccia della riga di comando per ottenere le chiavi o il token per l'operazione del piano dati in modo da poterli usare con altri canali, ad esempio l'API REST.

Per ottenere le chiavi o il token per le operazioni del piano dati, usare il comando az ml online-endpoint get-credentials. Questo comando restituisce un output JSON che contiene chiavi, token e/o informazioni aggiuntive.

Suggerimento

Per estrarre informazioni specifiche dall'output JSON, viene usato come esempio il parametro --query del comando dell'interfaccia della riga di comando. Tuttavia, è possibile usare qualsiasi strumento adatto a questo scopo.

Quando auth_mode dell'endpoint è key

  • Le chiavi vengono restituite nei campi primaryKey e 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)

Quando auth_mode dell'endpoint è aml_token

  • Il token viene restituito nel campo accessToken.
  • L'ora di scadenza del token viene restituita nel campo expiryTimeUtc.
  • L'ora di aggiornamento del token viene restituita nel campo 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)

Quando auth_mode dell'endpoint è aad_token

  • Il token viene restituito nel campo accessToken.
  • L'ora di scadenza del token viene restituita nel campo 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)

Verificare l'endpoint della risorsa e l'ID client per individuare il token di Microsoft Entra

Dopo aver recuperato il token di Microsoft Entra, è possibile verificare che sia quello per l'endpoint della risorsa di Azure corretto ml.azure.com e l'ID client corretto decodificando il token tramite jwt.ms, che restituirà una risposta JSON con le informazioni seguenti:

{
    "aud": "https://ml.azure.com",
    "oid": "<your-object-id>"
}

Assegnare punteggi ai dati tramite la chiave o il token

È possibile usare az ml online-endpoint invoke per gli endpoint con una chiave, un token di Azure Machine Learning o un token Microsoft Entra. L'interfaccia della riga di comando gestisce automaticamente la chiave o il token, quindi non è necessario passarlo in modo esplicito.

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

Registrazione e monitoraggio del traffico

Per abilitare la registrazione del traffico nelle impostazioni di diagnostica per l'endpoint, seguire la procedura descritta in Come abilitare/disabilitare i log.

Se l'impostazione di diagnostica è abilitata, è possibile controllare la tabella AmlOnlineEndpointTrafficLogs per visualizzare la modalità di autenticazione e l'identità utente.

Contenuto correlato