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 che siano stati soddisfati i prerequisiti seguenti:

Limiti

Gli endpoint con la modalità di autenticazione tramite token di Microsoft Entra (aad_token) non supportano l'assegnazione dei punteggi usando az ml online-endpoint invoke dell'interfaccia della riga di comando, ml_client.online_endpoints.invoke() dell'SDK o le schede Test o Utilizzo dello studio di Azure Machine Learning. Usare invece un SDK Python generico o l'API REST per passare il token del piano di controllo. Per altre informazioni, vedere Assegnare punteggi ai dati usando la chiave o il token.

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 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. L'identità utente non necessita di ruoli aggiuntivi per ottenere il token di Microsoft Entra.

Chiave o token di Azure Machine Learning

Se si prevede di usare l'interfaccia della riga di comando per richiamare l'endpoint, e se l'endpoint è configurato per usare una modalità di autenticazione di tipo chiave o token di Azure Machine Learning (aml_token), non è necessario ottenere esplicitamente il token del piano dati, perché l'interfaccia della riga di comando gestisce automaticamente questo aspetto. Tuttavia, è comunque possibile usare l'interfaccia della riga di comando per ottenere il token del piano dati in modo da poterlo usare con altri canali, ad esempio l'API REST.

Per ottenere la chiave o il token di Azure Machine Learning (aml_token), usare il comando az ml online-endpoint get-credentials. Questo comando restituisce un documento JSON che contiene l'ID della chiave o del token di Azure Machine Learning.

Le chiavi vengono restituite nei campi primaryKey e secondaryKey. L'esempio seguente illustra come usare il parametro --query per restituire solo la chiave primaria:

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

I token di Azure Machine Learning vengono restituiti nel campo accessToken:

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

Inoltre, i campi expiryTimeUtc e refreshAfterTimeUtc contengono gli orari di scadenza e di aggiornamento del token.

Token di Microsoft Entra

Per ottenere il token di Microsoft Entra (aad_token) usando l'interfaccia della riga di comando, usare il comando az account get-access-token. Questo comando restituisce un documento JSON che contiene il token di Microsoft Entra.

Il token di Microsoft Entra viene restituito nel campo accessToken:

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

Nota

  • L'estensione ml dell'interfaccia della riga di comando non supporta l'acquisizione del token di Microsoft Entra. Usare invece az account get-access-token, come descritto nel codice precedente.
  • Il token per le operazioni del piano dati viene recuperato dall'endpoint della risorsa di Azure ml.azure.com invece che da management.azure.com, a differenza del token per le operazioni del piano di controllo.

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

Chiave o token di Azure Machine Learning

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

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

Token di Microsoft Entra

L'uso di az ml online-endpoint invoke per gli endpoint con un token di Microsoft Entra non è supportato. Usare invece l'API REST e usare l'URI di assegnazione dei punteggi dell'endpoint per richiamare l'endpoint.

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