Autentisera klienter för onlineslutpunkter

  • Artikel

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:

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 Scientistinbyggda 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.

  1. 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>"
    ]
}

  2. 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) och Microsoft.Authorization/roleDefinitions/read behörighet (för att visa anpassade roller).

    Mer information om hur du skapar anpassade roller finns i Anpassade Azure-roller.

  3. 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

  1. 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>

  2. 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>

  3. 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) och Microsoft.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.

  4. 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.

  1. Logga in på Azure.

    az login

  2. 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>

  3. 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.

  1. 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

  2. Du kan ersätta auth_mode med key för nyckelautentisering eller aml_token för Azure Machine Learning-tokenautentisering. I det här exemplet använder aad_token du för Microsoft Entra-tokenautentisering.

    az ml online-endpoint create -f endpoint.yml

  3. Kontrollera slutpunktens status:

    az ml online-endpoint show -n my-endpoint

  4. Om du vill åsidosätta auth_mode (till exempel till aad_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

  5. Om du vill uppdatera den befintliga slutpunkten och ange auth_mode (till exempel till aad_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)

  1. 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

  2. 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änd az 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ör management.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.

Relaterat innehåll