Condividi tramite


Autenticare client per gli endpoint online

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

Questo articolo illustra come autenticare i client per gli endpoint online di Azure Machine Learning. È possibile configurare le autorizzazioni, creare un endpoint, recuperare token o chiavi e assegnare un punteggio ai dati usando una delle tre modalità di autenticazione: chiave, token di Azure Machine Learning (aml_token) o token Microsoft Entra (aad_token).

L'autenticazione degli endpoint online prevede due tipi di operazioni:

  • Un'operazione del piano di controllo controlla un endpoint e lo modifica. 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 modificarlo. Ad esempio, un'operazione del piano dati consiste nell'inviare una richiesta di assegnazione dei punteggi a un endpoint online e ottenere una risposta.

Scegliere una modalità di autenticazione

Gli endpoint online supportano tre modalità di autenticazione per le operazioni del piano dati. Scegliere la modalità più adatta ai requisiti di sicurezza e al tipo di endpoint.

Chiave Token di Azure Machine Learning (aml_token) Token Microsoft Entra (aad_token)
Livello di sicurezza Più basso: le chiavi statiche non scadono Medio : breve durata, aggiornamento automatico Massimo — basato sull'identità, con ambito determinato dal ruolo
Tipi di endpoint Servizi Gestiti e Kubernetes Servizi gestiti e Kubernetes Solo gestito
RBAC richiesto per il punteggio No No Sì (score/action ruolo)
Durata dei token Nessuna scadenza (ruotare manualmente) Breve durata con aggiornamento Breve durata (per i criteri di Microsoft Entra)
Ideale per Sviluppo e test Pipeline automatizzate Carichi di lavoro di produzione

Per i carichi di lavoro di produzione negli endpoint online gestiti, usare l'autenticazione token Microsoft Entra (aad_token) per la sicurezza più avanzata. Per gli endpoint di sviluppo o Kubernetes, l'autenticazione basata su chiave è l'opzione più semplice.

Importante

L'autenticazione del token Microsoft Entra (aad_token) è supportata solo per gli endpoint online gestiti. Per gli endpoint online Kubernetes, usare l'autenticazione con chiave o token di Azure Machine Learning (aml_token). Per altre informazioni, vedere Autenticazione e autorizzazione per gli endpoint online.

Prerequisiti

  • Python SDK: azure-ai-ml e azure-identity pacchetti (pip install azure-ai-ml azure-identity)
  • Interfaccia della riga di comando di Azure: estensione ml (az extension add -n ml)
  • Identità utente in Microsoft Entra ID. Per informazioni sulla creazione di un'identità utente, vedere Configurare l'autenticazione. È necessario l'ID identità in un passaggio successivo.
  • Ruolo di controllo degli accessi in base al ruolo necessario per le operazioni del piano di controllo e del piano dati: assegnare uno dei ruoli seguenti all'identità utente nell'ambito dell'area di lavoro:
    • Data Scientist di AzureML (predefinito): include le autorizzazioni per le operazioni CRUD sugli endpoint e l'assegnazione dei punteggi. Vedere Ruolo data scientist di AzureML.
    • Proprietario o Collaboratore : accesso completo per gestire gli endpoint.
    • Ruolo personalizzato con Microsoft.MachineLearningServices/workspaces/onlineEndpoints/* azioni.
  • (Facoltativo) Lettore segreti connessione dell'area di lavoro di Azure Machine Learning : obbligatorio solo se è necessario accedere ai segreti dalle connessioni all'area di lavoro.

Verificare la configurazione

Esegui questo snippet per verificare che le credenziali e le autorizzazioni RBAC (controllo degli accessi basato sui ruoli) siano configurate correttamente:

az login
az ml online-endpoint list --resource-group <RESOURCE_GROUP> --workspace-name <WORKSPACE_NAME>

Output previsto: matrice JSON di endpoint (vuota [] se non esistono ancora endpoint).

Riferimento: az ml online-endpoint list

Assegnare autorizzazioni all'identità

Se hai già assegnato il ruolo RBAC richiesto (come indicato in Prerequisiti), procedi a Crea un endpoint. Questa sezione fornisce informazioni dettagliate sulla creazione di ruoli personalizzati, se necessario.

Visualizzare i dettagli del ruolo predefiniti

Il AzureML Data Scientistruolo predefinito include queste azioni 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 questa azione di controllo degli accessi in base al ruolo del piano dati:

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

Il Azure Machine Learning Workspace Connection Secrets Reader ruolo predefinito include:

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

(Facoltativo) Creare un ruolo personalizzato

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 di ruolo seguente ,custom-role-for-control-plane.json, consente all'utente di eseguire operazioni CRUD su un endpoint online in un'area di lavoro specificata.

    {
        "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 di ruolo seguente ,custom-role-for-scoring.json, consente all'utente di inviare richieste di assegnazione dei punteggi a un endpoint online in un'area di lavoro specificata.

    {
        "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>
    

    Note

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

    • Proprietario
    • Amministratore dell'accesso utente
    • Un ruolo personalizzato con Microsoft.Authorization/roleDefinitions/write autorizzazione (per creare/aggiornare/eliminare ruoli personalizzati) e Microsoft.Authorization/roleDefinitions/read l'autorizzazione (per visualizzare i 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>
    

    Note

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

    • Proprietario
    • Amministratore dell'accesso utente
    • 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 ruoli di Azure e sulle relative autorizzazioni, vedere Ruoli di Azure e Assegnare ruoli di Azure tramite il portale di Azure.

  4. Confermare l'assegnazione del ruolo:

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

Ottenere un token del control plane

Completare questo passaggio se si prevede di eseguire operazioni del piano di controllo usando l'API REST, che usa direttamente il token.

Se si prevede di usare altri metodi, ad esempio l'interfaccia della riga di comando di Azure con l'estensione ml v2, Python SDK v2 o Azure Machine Learning Studio, non è necessario ottenere manualmente il token Microsoft Entra. L'identità utente viene autenticata durante l'accesso e il token viene recuperato e passato automaticamente.

È possibile recuperare dall'endpoint della risorsa di Azure il token Microsoft Entra per le operazioni del piano di controllo: 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 -o tsv)
    

Riferimento: az login, az account get-access-token

Verificare il token del piano di controllo (facoltativo)

Dopo aver recuperato il token Microsoft Entra, è possibile verificare che il token sia per l'endpoint di risorsa di Azure corretto (management.azure.com) e l'ID client corretto decodificando il token tramite jwt.ms.

Suggerimento

Il sito jwt.ms è uno strumento di proprietà di Microsoft che decodifica completamente i token nel browser. Nessun dato viene inviato a un server. Non incollare mai i token in strumenti di decodifica non attendibili.

Il token decodificato restituisce una risposta JSON contenente le informazioni seguenti:

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

Creare un endpoint

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

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

  1. Creare un file YAML di definizione dell'endpoint denominato endpoint.yml:

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

    È possibile impostare auth_mode su key per l'autenticazione della chiave o aml_token per l'autenticazione del token di Azure Machine Learning. Questo esempio usa aad_token per l'autenticazione del token Microsoft Entra.

    Note

    La aad_token modalità di autenticazione è supportata solo per gli endpoint online gestiti. Per gli endpoint online Kubernetes, impostare auth_mode su key o aml_token.

  2. Creare l'endpoint:

    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, come aad_token), eseguire il codice seguente:

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

Riferimento: az ml online-endpoint create, az ml online-endpoint show, az ml online-endpoint update

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 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 l'interfaccia della riga di comando).

  1. Creare un file YAML di definizione della distribuzione denominato 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-ubuntu22.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
    

Riferimento: az ml online-deployment create

Ottenere l'URI di assegnazione dei punteggi

Se si usa az ml online-endpoint invoke per chiamare l'endpoint, l'interfaccia della riga di comando risolve automaticamente l'URI di assegnazione dei punteggi, quindi non è necessario recuperarlo manualmente.

Tuttavia, se è necessario l'URI di assegnazione dei punteggi per l'uso con altri strumenti ,ad esempio l'API REST o i client HTTP personalizzati, è possibile recuperarlo con il comando seguente:

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

Riferimento: az ml online-endpoint show

Ottenere una chiave o un token per il piano dati

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

La durata dei token varia in base alla modalità di autenticazione:

  • Chiave: le chiavi non scadono ma devono essere ruotate regolarmente per la sicurezza. Usare l'azione regenerateKeys per ruotare le chiavi.
  • Token di Azure Machine Learning (aml_token): token di breve durata che includono un refreshAfterTimeUtc campo. Richiedere un nuovo token dopo questa volta per evitare la scadenza.
  • Token Microsoft Entra (aad_token): segue i criteri di durata del token ID di Microsoft Entra (in genere da 60 a 90 minuti). Aggiornare il token prima di expiryTimeUtc.

Per ottenere la chiave o il token di Azure Machine Learning, l'identità utente che la richiede deve avere il ruolo corretto assegnato, come descritto in Autorizzazione per le operazioni del piano di controllo. L'identità utente non richiede ruoli aggiuntivi per ottenere il token Microsoft Entra.

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 lo fornisce automaticamente. Tuttavia, è comunque possibile usare l'interfaccia della riga di comando per ottenere le chiavi o il token per le operazioni del piano dati in modo che sia possibile usarlo 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 l'output JSON che contiene chiavi, token e/o informazioni aggiuntive.

Suggerimento

Nel comando seguente il --query parametro viene usato per estrarre informazioni specifiche dall'output JSON. Tuttavia, è possibile usare qualsiasi strumento adatto a tale scopo.

Quando l'oggetto 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 l'oggetto auth_mode dell'endpoint è aml_token

  • Il token viene restituito nel accessToken campo .

  • L'ora di scadenza del expiryTimeUtc token viene restituita nel campo .

  • 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 l'oggetto auth_mode dell'endpoint è aad_token

  • Il token viene restituito nel accessToken campo .

  • L'ora di scadenza del expiryTimeUtc token viene restituita nel campo .

    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)
    

Riferimento: az ml online-endpoint get-credentials

Verificare il token del piano dati (facoltativo)

Dopo aver ottenuto il token Entra, è possibile verificare che il token sia per l'endpoint di risorsa di Azure corretto, ml.azure.come l'ID client corretto decodificando il token tramite jwt.ms, che restituisce una risposta JSON con le informazioni seguenti:

Suggerimento

Il sito jwt.ms è uno strumento di proprietà di Microsoft che decodifica completamente i token nel browser. Nessun dato viene inviato a un server. Non incollare mai i token in strumenti di decodifica non attendibili.

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

Assegnare un punteggio ai dati

È 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 fornisce automaticamente la chiave o il token, quindi non è necessario passarlo in modo esplicito.

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

Riferimento: az ml online-endpoint invoke

Monitorare il traffico degli endpoint

Per abilitare la registrazione del traffico nelle impostazioni di diagnostica per l'endpoint, completare i passaggi descritti in Attivare i log.

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

Risolvere gli errori di autenticazione

Nella tabella seguente sono elencati gli errori di autenticazione comuni e le relative risoluzioni.

Error Causa possibile Resolution
401 - Non autorizzato Token del pubblico mancante, scaduto o errato Verificare che il gruppo di destinatari del token corrisponda al tipo di endpoint: management.azure.com per il piano di controllo, ml.azure.com per il piano dati. Aggiornare i token scaduti.
403 Vietato L'identità utente non dispone del ruolo RBAC richiesto Assegnare AzureML Data Scientist o un ruolo personalizzato con l'autorizzazione score/action nell'ambito dell'endpoint. Vedere Assegnare autorizzazioni all'identità.
aad_token non accettato Utilizzare aad_token su un endpoint Kubernetes Passa a key o aml_token. L'autenticazione del token Microsoft Entra è supportata solo per gli endpoint online gestiti.
AADSTS700016 o errore di Entra simile Risorsa o gruppo di destinatari errato nella richiesta di token Verificare che il parametro della risorsa corrisponda al tipo di operazione: https://management.azure.com per il piano di controllo, https://ml.azure.com per il piano dati.