Autentisera klienter för onlineslutpunkter
GÄLLER FÖR:Azure CLI ml extension v2 (current)Python SDK azure-ai-ml v2 (aktuell)
Den här artikeln beskriver hur du autentiserar klienter för att utföra kontrollplans- och dataplansåtgärder på onlineslutpunkter.
En kontrollplansåtgärd styr en slutpunkt och ändrar den. Kontrollplansåtgärder omfattar åtgärder för att skapa, läsa, uppdatera och ta bort (CRUD) på onlineslutpunkter och onlinedistributioner.
En dataplansåtgärd använder data för att interagera med en onlineslutpunkt utan att ändra slutpunkten. En dataplansåtgärd kan till exempel bestå av att skicka en bedömningsbegäran till en onlineslutpunkt och få ett svar.
Förutsättningar
Innan du följer stegen i den här artikeln kontrollerar du att du har följande förutsättningar:
En Azure Machine Learning-arbetsyta. Om du inte har någon använder du stegen i artikeln Snabbstart: Skapa arbetsyteresurser för att skapa en.
Azure CLI och
ml
tillägget eller Azure Machine Learning Python SDK v2:Information om hur du installerar Azure CLI och tillägget finns i Installera, konfigurera och använda CLI (v2).
Viktigt!
CLI-exemplen i den här artikeln förutsätter att du använder Bash-gränssnittet (eller det kompatibla). Till exempel från ett Linux-system eller Windows-undersystem för Linux.
Om du vill installera Python SDK v2 använder du följande kommando:
pip install azure-ai-ml azure-identity
Om du vill uppdatera en befintlig installation av SDK:et till den senaste versionen använder du följande kommando:
pip install --upgrade azure-ai-ml azure-identity
Mer information finns i Installera Python SDK v2 för Azure Machine Learning.
Begränsningar
Slutpunkter med autentiseringsläge för Microsoft Entra-token (aad_token
) stöder inte bedömning med hjälp av flikarna CLIaz ml online-endpoint invoke
, SDK ml_client.online_endpoints.invoke()
eller Test eller Consume i Azure Machine Learning-studio. Använd i stället en allmän Python SDK eller använd REST API för att skicka kontrollplanstoken. Mer information finns i Poängsätta data med hjälp av nyckeln eller token.
Förbereda en användaridentitet
Du behöver en användaridentitet för att utföra kontrollplansåtgärder (d.v.s. CRUD-åtgärder) och dataplansåtgärder (dvs. skicka bedömningsbegäranden) på onlineslutpunkten. Du kan använda samma användaridentitet eller olika användaridentiteter för kontrollplanets och dataplanets åtgärder. I den här artikeln använder du samma användaridentitet för både kontrollplans- och dataplansåtgärder.
Information om hur du skapar en användaridentitet under Microsoft Entra-ID finns i Konfigurera autentisering. Du behöver identitets-ID senare.
Tilldela behörigheter till identiteten
I det här avsnittet tilldelar du behörigheter till den användaridentitet som du använder för att interagera med slutpunkten. Du börjar med att antingen använda en inbyggd roll eller genom att skapa en anpassad roll. Därefter tilldelar du rollen till din användaridentitet.
Använda en inbyggd roll
Den AzureML Data Scientist
inbyggda rollen kan användas för att hantera och använda slutpunkter och distributioner och den använder jokertecken för att inkludera följande RBAC-åtgärder för kontrollplanet :
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
och för att inkludera följande RBAC-åtgärd för dataplanet :
Microsoft.MachineLearningServices/workspaces/onlineEndpoints/score/action
Du kan också använda den Azure Machine Learning Workspace Connection Secrets Reader
inbyggda rollen för att komma åt hemligheter från arbetsyteanslutningar och den innehåller följande RBAC-åtgärder för kontrollplanet :
Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action
Microsoft.MachineLearningServices/workspaces/metadata/secrets/read
Om du använder de här inbyggda rollerna behövs ingen åtgärd i det här steget.
(Valfritt) Skapa en anpassad roll
Du kan hoppa över det här steget om du använder inbyggda roller eller andra färdiga anpassade roller.
Definiera omfånget och åtgärderna för anpassade roller genom att skapa JSON-definitioner av rollerna. Med följande rolldefinition kan användaren till exempel CRUD en onlineslutpunkt under en angiven arbetsyta.
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>" ] }
Med följande rolldefinition kan användaren skicka bedömningsbegäranden till en onlineslutpunkt under en angiven arbetsyta.
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>" ] }
Använd JSON-definitionerna för att skapa anpassade roller:
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>
Kommentar
Om du vill skapa anpassade roller behöver du en av tre roller:
- ägare
- administratör för användaråtkomst
- en anpassad roll med
Microsoft.Authorization/roleDefinitions/write
behörighet (för att skapa/uppdatera/ta bort anpassade roller) ochMicrosoft.Authorization/roleDefinitions/read
behörighet (för att visa anpassade roller).
Mer information om hur du skapar anpassade roller finns i Anpassade Azure-roller.
Verifiera rolldefinitionen:
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 '"')`
Tilldela rollen till identiteten
Om du använder den
AzureML Data Scientist
inbyggda rollen använder du följande kod för att tilldela rollen till din användaridentitet.az role assignment create --assignee <identityId> --role "AzureML Data Scientist" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>
Om du använder den
Azure Machine Learning Workspace Connection Secrets Reader
inbyggda rollen kan du använda följande kod för att tilldela rollen till din användaridentitet.az role assignment create --assignee <identityId> --role "Azure Machine Learning Workspace Connection Secrets Reader" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>
Om du använder en anpassad roll använder du följande kod för att tilldela rollen till din användaridentitet.
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>
Kommentar
Om du vill tilldela anpassade roller till användaridentiteten behöver du en av tre roller:
- ägare
- administratör för användaråtkomst
- en anpassad roll som tillåter
Microsoft.Authorization/roleAssignments/write
behörighet (för att tilldela anpassade roller) ochMicrosoft.Authorization/roleAssignments/read
(för att visa rolltilldelningar).
Mer information om de olika Azure-rollerna och deras behörigheter finns i Azure-roller och Tilldela Azure-roller med Hjälp av Azure-portalen.
Bekräfta rolltilldelningen:
az role assignment list --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>
Hämta Microsoft Entra-token för kontrollplansåtgärder
Utför det här steget om du planerar att utföra kontrollplansåtgärder med REST API, som använder token direkt.
Om du planerar att använda andra sätt som Azure Machine Learning CLI (v2), Python SDK (v2) eller Azure Machine Learning-studio behöver du inte hämta Microsoft Entra-token manuellt. I stället skulle användaridentiteten redan autentiseras under inloggningen och token hämtas och skickas automatiskt åt dig.
Du kan hämta Microsoft Entra-token för kontrollplansåtgärder från Azure-resursslutpunkten: https://management.azure.com
.
Logga in på Azure.
az login
Om du vill använda en specifik identitet använder du följande kod för att logga in med identiteten:
az login --identity --username <identityId>
Använd den här kontexten för att hämta token.
export CONTROL_PLANE_TOKEN=`(az account get-access-token --resource https://management.azure.com --query accessToken | tr -d '"')`
(Valfritt) Verifiera resursslutpunkten och klient-ID:t för Microsoft Entra-token
När du har hämtat Microsoft Entra-token kan du kontrollera att token är för rätt Azure-resursslutpunkt management.azure.com
och rätt klient-ID genom att avkoda token via jwt.ms, vilket returnerar ett json-svar med följande information:
{
"aud": "https://management.azure.com",
"oid": "<your-object-id>"
}
Skapa en slutpunkt
I följande exempel skapas slutpunkten med en systemtilldelad identitet (SAI) som slutpunktsidentitet. SAI är standardidentitetstypen för den hanterade identiteten för slutpunkter. Vissa grundläggande roller tilldelas automatiskt för SAI. Mer information om rolltilldelning för en systemtilldelad identitet finns i Automatisk rolltilldelning för slutpunktsidentitet.
CLI kräver inte att du uttryckligen anger kontrollplanstoken. I stället autentiserar CLI dig under inloggningen och token hämtas och skickas automatiskt åt dig.
Skapa en YAML-fil för slutpunktsdefinition.
endpoint.yml:
$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json name: my-endpoint auth_mode: aad_token
Du kan ersätta
auth_mode
medkey
för nyckelautentisering elleraml_token
för Azure Machine Learning-tokenautentisering. I det här exemplet använderaad_token
du för Microsoft Entra-tokenautentisering.az ml online-endpoint create -f endpoint.yml
Kontrollera slutpunktens status:
az ml online-endpoint show -n my-endpoint
Om du vill åsidosätta
auth_mode
(till exempel tillaad_token
) när du skapar en slutpunkt kör du följande kod:az ml online-endpoint create -n my-endpoint --auth_mode aad_token
Om du vill uppdatera den befintliga slutpunkten och ange
auth_mode
(till exempel tillaad_token
) kör du följande kod:az ml online-endpoint update -n my-endpoint --set auth_mode=aad_token
Skapa en distribution
Information om hur du skapar en distribution finns i Distribuera en ML-modell med en onlineslutpunkt eller Använd REST för att distribuera en modell som en onlineslutpunkt. Det finns ingen skillnad i hur du skapar distributioner för olika autentiseringslägen.
Följande kod är ett exempel på hur du skapar en distribution. Mer information om hur du distribuerar onlineslutpunkter finns i Distribuera en ML-modell med en onlineslutpunkt (via CLI)
Skapa en YAML-fil för distributionsdefinition.
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
Skapa distributionen med YAML-filen. I det här exemplet anger du all trafik till den nya distributionen.
az ml online-deployment create -f blue-deployment.yml --all-traffic
Hämta bedömnings-URI:n för slutpunkten
Om du planerar att använda CLI för att anropa slutpunkten behöver du inte hämta bedömnings-URI:n explicit, eftersom CLI hanterar den åt dig. Du kan dock fortfarande använda CLI för att hämta bedömnings-URI:n så att du kan använda den med andra kanaler, till exempel REST API.
scoringUri=$(az ml online-endpoint show -n my-endpoint --query "scoring_uri")
Hämta nyckeln eller token för dataplansåtgärder
En nyckel eller token kan användas för dataplansåtgärder, även om processen med att hämta nyckeln eller token är en kontrollplansåtgärd. Med andra ord använder du en kontrollplanstoken för att hämta nyckeln eller token som du senare använder för att utföra dina dataplansåtgärder.
För att hämta nyckeln eller Azure Machine Learning-token krävs att rätt roll tilldelas till användaridentiteten som begär den, enligt beskrivningen i auktorisering för kontrollplansåtgärder. Användaridentiteten behöver inga extra roller för att hämta Microsoft Entra-token.
Nyckel- eller Azure Machine Learning-token
Om du planerar att använda CLI för att anropa slutpunkten, och om slutpunkten har konfigurerats för att använda ett autentiseringsläge för nyckel eller Azure Machine Learning-token (aml_token
), behöver du inte hämta dataplanstoken explicit, eftersom CLI hanterar den åt dig. Du kan dock fortfarande använda CLI för att hämta dataplanstoken så att du kan använda den med andra kanaler, till exempel REST API.
Om du vill hämta nyckeln eller Azure Machine Learning-token (aml_token
) använder du kommandot az ml online-endpoint get-credentials . Det här kommandot returnerar ett JSON-dokument som innehåller nyckeln eller Azure Machine Learning-token.
Nycklar returneras i fälten primaryKey
och secondaryKey
. I följande exempel visas hur du använder parametern --query
för att endast returnera primärnyckeln:
export DATA_PLANE_TOKEN=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query primaryKey)
Azure Machine Learning-token returneras i fältet accessToken
:
export DATA_PLANE_TOKEN=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query accessToken)
Fälten expiryTimeUtc
och refreshAfterTimeUtc
innehåller också förfallo- och uppdateringstiderna för token.
Microsoft Entra-token
Om du vill hämta Microsoft Entra-token (aad_token
) med CLI använder du kommandot az account get-access-token . Det här kommandot returnerar ett JSON-dokument som innehåller Microsoft Entra-token.
Microsoft Entra-token returneras i fältet accessToken
:
export DATA_PLANE_TOKEN=`(az account get-access-token --resource https://ml.azure.com --query accessToken | tr -d '"')`
Kommentar
- CLI-tillägget
ml
stöder inte hämtar Microsoft Entra-token. Användaz account get-access-token
i stället enligt beskrivningen i föregående kod. - Token för dataplansåtgärder hämtas från Azure-resursslutpunkten
ml.azure.com
i stället förmanagement.azure.com
, till skillnad från token för kontrollplansåtgärder.
Verifiera resursslutpunkten och klient-ID:t för Microsoft Entra-token
När du har hämtat Entra-token kan du kontrollera att token är för rätt Azure-resursslutpunkt ml.azure.com
och rätt klient-ID genom att avkoda token via jwt.ms, vilket returnerar ett json-svar med följande information:
{
"aud": "https://ml.azure.com",
"oid": "<your-object-id>"
}
Poängsätta data med hjälp av nyckeln eller token
Nyckel- eller Azure Machine Learning-token
Du kan använda az ml online-endpoint invoke
för slutpunkter med en nyckel eller Azure Machine Learning-token. CLI hanterar nyckeln eller Azure Machine Learning-token automatiskt så att du inte behöver skicka den explicit.
az ml online-endpoint invoke -n my-endpoint -r request.json
Microsoft Entra-token
Det går inte att använda az ml online-endpoint invoke
för slutpunkter med en Microsoft Entra-token. Använd REST API i stället och använd slutpunktens bedömnings-URI för att anropa slutpunkten.
Logga och övervaka trafik
Om du vill aktivera trafikloggning i diagnostikinställningarna för slutpunkten följer du stegen i Aktivera/inaktivera loggar.
Om diagnostikinställningen är aktiverad kan du kontrollera AmlOnlineEndpointTrafficLogs
tabellen för att se autentiseringsläget och användaridentiteten.