Autentizace klientů pro online síťové koncové body

PLATÍ PRO:Rozšíření Azure CLI ml v2 (aktuální)Python SDK azure-ai-ml v2 (aktuální)

V tomto článku se dozvíte, jak ověřovat klienty pro online koncové body služby Azure Machine Learning. Nastavíte oprávnění, vytvoříte koncový bod, načtete tokeny nebo klíče a vyhodnotíte data pomocí jednoho ze tří režimů ověřování: klíč, token Služby Azure Machine Learning (aml_token) nebo token Microsoft Entra (aad_token).

Online ověřování koncových bodů zahrnuje dva typy operací:

  • Operace řídicí roviny řídí koncový bod a mění ho. Operace řídicí roviny zahrnují operace vytvoření, čtení, aktualizace a odstranění (CRUD) u online koncových bodů a online nasazení.
  • Operace v datové rovině používá data k interakci s online koncovým bodem, aniž by se změnil koncový bod. Operace roviny dat se například skládá z odeslání žádosti o bodování do online koncového bodu a získání odpovědi.

Výběr režimu ověřování

Online koncové body podporují tři režimy ověřování pro operace roviny dat. Zvolte režim, který nejlépe vyhovuje vašim požadavkům na zabezpečení a typu koncového bodu.

Klíč Token služby Azure Machine Learning (aml_token) Token Microsoft Entra (aad_token)
Úroveň zabezpečení Nejnižší – platnost statických klíčů nevyprší Střední – krátkodobé, automaticky aktualizované Nejvyšší – na základě identity, v rozsahu role
Typy koncových bodů Řízené a Kubernetes Řízené a Kubernetes Pouze spravované
RBAC je vyžadováno pro hodnocení Ne Ne Ano (score/action role)
Životnost tokenu Bez vypršení platnosti (ruční otočení) Krátkodobé s možností obnovy Krátkodobé (podle zásad Microsoft Entra)
Nejlepší pro Vývoj a testování Automatizované kanály Produkční úlohy

Pro produkční úlohy ve spravovaných online koncových bodech použijte ověřování tokenů Microsoft Entra (aad_token) pro nejsilnější zabezpečení. Pro vývoj nebo koncové body Kubernetes je nejjednodušší možností ověřování na základě klíčů.

Důležité

Ověřování pomocí tokenu Microsoft Entra jeaad_token podporováno pouze pro spravované online koncové body. V případě online koncových bodů Kubernetes použijte ověřování pomocí klíče nebo tokenuaml_token Azure Machine Learning. Další informace najdete v tématu Ověřování a autorizace pro online koncové body.

Požadavky

  • Python SDK: azure-ai-ml a azure-identity balíčky (pip install azure-ai-ml azure-identity)
  • Azure CLI: Rozšíření ml (az extension add -n ml)
  • Identita uživatele v Microsoft Entra ID. Informace o vytvoření identity uživatele najdete v tématu Nastavení ověřování. Id identity budete potřebovat v pozdějším kroku.
  • Požadovaná role RBAC pro operace řídicí roviny a roviny dat: Přiřaďte k identitě uživatele v rozsahu pracovního prostoru jednu z následujících rolí:
    • Datový vědec AzureML (integrovaný) – zahrnuje oprávnění k operacím CRUD v koncových bodech a vyhodnocování. Podívejte se na roli datového vědce AzureML.
    • Vlastník nebo Přispěvatel – Úplný přístup ke správě koncových bodů
    • Vlastní role s akcemi Microsoft.MachineLearningServices/workspaces/onlineEndpoints/* .
  • (Volitelné) Čtečka tajných kódů připojení pracovního prostoru Azure Machine Learning – Vyžaduje se jenom v případě, že potřebujete získat přístup k tajným kódům z připojení pracovních prostorů.

Ověření nastavení

Spuštěním tohoto fragmentu kódu ověřte, že jsou vaše přihlašovací údaje a oprávnění RBAC správně nakonfigurované:

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

Očekávaný výstup: Pole koncových bodů JSON (prázdné [] , pokud ještě neexistují žádné koncové body).

Referenční informace: az ml online-endpoint list

Přiřazení oprávnění k identitě

Pokud už máte přiřazenou požadovanou roli RBAC (jak je uvedeno v části Požadavky), přeskočte na Vytvoření koncového bodu. Tato část obsahuje podrobnosti o vytvoření vlastní role v případě potřeby.

Zobrazení podrobností o předdefinované roli

AzureML Datoví vědci zahrnuje tyto akce RBAC řídicí roviny:

  • 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

Tato akce RBAC pro datovou rovinu:

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

Předdefinovaná Azure Machine Learning Workspace Connection Secrets Reader role zahrnuje:

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

(Volitelné) Vytvoření vlastní role

Tento krok přeskočte, pokud používáte předdefinované role nebo jiné předem vytvořené vlastní role.

  1. Definujte obor a akce pro vlastní role vytvořením definic JSON rolí. Například následující definice role ,custom-role-for-control-plane.json, umožňuje uživateli provádět operace CRUD na online koncovém bodu v zadaném pracovním prostoru.

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

    Následující definice role custom-role-for-scoring.jsonumožňuje uživateli odesílat žádosti o bodování do online koncového bodu v zadaném pracovním prostoru.

    {
    "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. K vytvoření vlastních rolí použijte definice JSON:

    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>

    Poznámka:

    K vytváření vlastních rolí potřebujete jednu ze tří rolí:

    • Vlastník
    • Správce uživatelských přístupů
    • Vlastní role s oprávněním Microsoft.Authorization/roleDefinitions/write (k vytvoření, aktualizaci nebo odstranění vlastních rolí) a Microsoft.Authorization/roleDefinitions/read oprávnění (k zobrazení vlastních rolí).

    Další informace o vytváření vlastních rolí najdete v tématu Vlastní role Azure.

  3. Ověřte definici role:

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

Přiřaďte roli k identitě

  1. Pokud používáte AzureML Datoví vědci předdefinované role, přiřaďte roli identitě uživatele pomocí následujícího kódu.

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

  2. Pokud používáte Azure Machine Learning Workspace Connection Secrets Reader předdefinované role, můžete k přiřazení role k identitě uživatele použít následující kód.

    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. Pokud používáte vlastní roli, přiřaďte k identitě uživatele následující kód.

    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>

    Poznámka:

    Pokud chcete přiřadit vlastní role identitě uživatele, potřebujete jednu ze tří rolí:

    • Vlastník
    • Správce uživatelských přístupů
    • Vlastní role, která uděluje oprávnění k přiřazení vlastních rolí (Microsoft.Authorization/roleAssignments/write) a ke zobrazení přiřazení rolí (Microsoft.Authorization/roleAssignments/read).

    Další informace o rolích Azure a jejich oprávněních najdete v tématu Role Azure a Přiřazení rolí Azure pomocí webu Azure Portal.

  4. Potvrďte přiřazení role:

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

Získejte token řídicího panelu

Tento krok dokončete, pokud plánujete provádět operace řídicí roviny pomocí rozhraní REST API, které token používá přímo.

Pokud plánujete používat jiné metody, jako je Azure CLI s rozšířením ml v2, sadou Python SDK v2 nebo nástrojem Azure Machine Learning Studio, nemusíte token Microsoft Entra získat ručně. Vaše identita uživatele se ověřuje při přihlášení a token se automaticky načte a předá vám.

Můžete načíst token Microsoft Entra pro operace řídicí roviny z koncového bodu prostředku Azure: https://management.azure.com.

  1. Přihlaste se do Azure.

    az login

  2. Pokud chcete použít konkrétní identitu, přihlaste se pomocí následujícího kódu:

    az login --identity --username <identityID>

  3. K získání tokenu použijte tento kontext:

    export CONTROL_PLANE_TOKEN=$(az account get-access-token \
    --resource https://management.azure.com \
    --query accessToken -o tsv)

Referenční informace: az login, az account get-access-token

Ověření tokenu řídicí roviny (volitelné)

Po načtení tokenu Microsoft Entra můžete ověřit, že je token pro správný koncový bod prostředku Azure (management.azure.com) a správné ID klienta dekódováním tokenu pomocí jwt.ms.

Návod

Web jwt.ms je nástroj vlastněný Microsoftem, který dekóduje tokeny zcela v prohlížeči – na server se neposílají žádná data. Nikdy nevkládejte tokeny do nedůvěryhodných dekódovacích nástrojů.

Dekódovaný token vrátí odpověď JSON obsahující následující informace:

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

Vytvoření koncového bodu

Následující příklad vytvoří koncový bod s identitou přiřazenou systémem (SAI) jako identitou koncového bodu. Sai je výchozí typ identity pro koncové body a některé základní role se automaticky přiřazují. Další informace najdete v tématu Automatické přiřazení role pro identitu koncového bodu.

Rozhraní příkazového řádku nevyžaduje explicitní zadání tokenu řídicí roviny. Místo toho vás příkaz rozhraní příkazového řádku az login ověří během přihlašování a token se automaticky načte a předá vám.

  1. Vytvořte soubor YAML definice koncového bodu s názvem endpoint.yml:

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

    Můžete nastavit auth_mode na key pro ověřování pomocí klíče nebo aml_token pro ověřování tokenů služby Microsoft Azure Machine Learning. Tento příklad používá aad_token k ověřování tokenu Microsoft Entra.

    Poznámka:

    Režim aad_token ověřování se podporuje jenom pro spravované online koncové body. U online koncových bodů Kubernetes nastavte hodnotu auth_mode na key nebo aml_token.

  2. Vytvořte koncový bod:

    az ml online-endpoint create -f endpoint.yml

  3. Zkontrolujte stav koncového bodu:

    az ml online-endpoint show -n my-endpoint

  4. Pokud chcete při vytváření koncového bodu přepsat auth_mode (například na aad_token) následující kód:

    az ml online-endpoint create -n my-endpoint --auth-mode aad_token

  5. Pokud chcete aktualizovat existující koncový bod a zadat auth_mode (například jako aad_token), spusťte následující kód:

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

Referenční informace: az ml online-endpoint create, az ml online-endpoint show, az ml online-endpoint update

Vytvořte nasazení

Pokud chcete vytvořit nasazení, přečtěte si téma Nasazení modelu strojového učení s online koncovým bodem nebo nasadit model pomocí REST jako online koncový bod. V tom, jak vytváříte nasazení pro různé režimy ověřování, není žádný rozdíl.

Následující kód je příkladem, jak vytvořit nasazení. Další informace o nasazení online koncových bodů najdete v tématu Nasazení modelu strojového učení pomocí online koncového bodu (prostřednictvím rozhraní příkazového řádku).

  1. Vytvořte soubor YAML definice nasazení s názvem 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. Vytvořte nasazení pomocí souboru YAML. V tomto příkladu nastavte veškerý provoz na nové nasazení.

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

Referenční informace: az ml online-deployment create

Získání hodnoticího identifikátoru URI

Pokud použijete az ml online-endpoint invoke k volání koncového bodu, CLI automaticky přeloží URI pro hodnocení, takže ho nemusíte načítat ručně.

Pokud ale potřebujete identifikátor URI bodování pro použití s jinými nástroji (například s rozhraním REST API nebo vlastními klienty HTTP), můžete ho načíst pomocí následujícího příkazu:

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

Referenční informace: az ml online-endpoint show

Získejte klíč nebo token datové vrstvy

Klíč nebo token můžete použít pro operace roviny dat, i když proces získání klíče nebo tokenu je operace řídicí roviny. Jinými slovy, pomocí tokenu řídicí roviny získáte klíč nebo token, který později použijete pro operace roviny dat.

Životnost tokenů se liší podle režimu ověřování:

  • Klíč: Platnost klíčů nevyprší, ale měla by se pravidelně obměňovat kvůli zabezpečení. Pomocí akce regenerateKeys můžete otočit klíče.
  • Token Služby Azure Machine Learning (aml_token): Krátkodobé tokeny, které obsahují refreshAfterTimeUtc pole. Po této době požádejte o nový token, abyste se vyhnuli vypršení platnosti.
  • Token Microsoft Entra (aad_token): Řídí se zásadami životnosti tokenu ID Microsoft Entra (obvykle 60–90 minut). Aktualizujte token před expiryTimeUtc.

K získání klíče nebo tokenu Azure Machine Learning musí mít identita uživatele, která žádá, správnou roli přiřazenou, jak je popsáno v dokumentu Autorizace pro operace řídicí roviny. Identita uživatele k získání tokenu Microsoft Entra nepotřebuje žádné další role.

Pokud chcete k vyvolání koncového bodu použít rozhraní příkazového řádku, nemusíte klíče ani tokeny pro operace roviny dat explicitně získat, protože rozhraní příkazového řádku ho poskytuje za vás. Pomocí rozhraní příkazového řádku ale můžete získat klíče nebo token pro operace roviny dat, abyste ho mohli použít s jinými kanály, jako je rozhraní REST API.

Pokud chcete získat klíče nebo token pro operace datové roviny, použijte příkaz az ml online-endpoint get-credentials. Tento příkaz vrátí výstup JSON, který obsahuje klíče, token a/nebo další informace.

Návod

V následujícím příkazu --query se parametr používá k extrahování konkrétních informací z výstupu JSON. Pro tento účel však můžete použít jakýkoli vhodný nástroj.

auth_mode Když je koncový bodkey

  • Klíče jsou vráceny v polích primaryKey a 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)

auth_mode Když je koncový bodaml_token

  • Token se vrátí v poli accessToken.

  • V poli se vrátí čas vypršení platnosti tokenu expiryTimeUtc .

  • V poli se vrátí čas aktualizace tokenu 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)

auth_mode Když je koncový bodaad_token

  • Token se vrátí v poli accessToken.

  • V poli se vrátí čas vypršení platnosti tokenu 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)

Referenční informace: az ml online-endpoint get-credentials

Ověření tokenu roviny dat (volitelné)

Po získání tokenu Entra můžete ověřit, že token je určený pro správný koncový bod ml.azure.comprostředku Azure, a správné ID klienta dekódováním tokenu prostřednictvím jwt.ms, který vrátí odpověď JSON s následujícími informacemi:

Návod

Web jwt.ms je nástroj vlastněný Microsoftem, který dekóduje tokeny zcela v prohlížeči – na server se neposílají žádná data. Nikdy nevkládejte tokeny do nedůvěryhodných dekódovacích nástrojů.

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

Skóre dat

Můžete použít az ml online-endpoint invoke pro koncové body s klíčem, tokenem služby Azure Machine Learning nebo tokenem Microsoft Entra. Rozhraní příkazového řádku poskytuje klíč nebo token automaticky, takže ho nemusíte explicitně předávat.

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

Referenční informace: az ml online-endpoint invoke

Monitorování provozu koncových bodů

Pokud chcete povolit protokolování provozu v nastavení diagnostiky pro koncový bod, proveďte kroky v části Zapnutí protokolů.

Pokud je nastavení diagnostiky povolené, můžete zobrazit AmlOnlineEndpointTrafficLogs tabulku a zobrazit režim ověřování a identitu uživatele.

Řešení chyb ověřování

Následující tabulka uvádí běžné chyby ověřování a jejich řešení.

Error Pravděpodobná příčina Resolution
401 Neautorizováno Chybějící, prošlý nebo token pro nesprávnou cílovou skupinu Ověřte, že cílová skupina tokenů odpovídá typu koncového bodu: management.azure.com pro řídicí rovinu ml.azure.com pro rovinu dat. Obnovte tokeny s vypršenou platností.
403 – Zakázáno Identita uživatele nemá požadovanou roli RBAC. Přiřaďte AzureML Datoví vědci nebo vlastní roli s oprávněním score/action v oboru koncového bodu. Viz Přiřazení oprávnění k identitě.
aad_token nepřijato Použití aad_token na koncovém bodu Kubernetes Přepněte na key nebo aml_token. Ověřování tokenu Microsoft Entra je podporováno pouze pro spravované online koncové body.
AADSTS700016 nebo podobná chyba Entra Nesprávný prostředek nebo cílová skupina v žádosti o token Ujistěte se, že parametr prostředku odpovídá typu operace: https://management.azure.com pro řídicí rovinu, https://ml.azure.com pro rovinu dat.

Související obsah

  • Last updated on