Authentifizieren von Clients für Onlineendpunkte

  • Artikel

GILT FÜR:Azure CLI ML-Erweiterung v2 (aktuell)Python SDK azure-ai-ml v2 (aktuell)

In diesem Artikel wird beschrieben, wie Clients authentifiziert werden, um Steuerebenen- und Datenebenenvorgänge auf Onlineendpunkten durchzuführen.

Ein Steuerungsebenenvorgang steuert einen Endpunkt und ändert ihn. Steuerungsebenenvorgänge umfassen Erstellungs-, Lese-, Aktualisierungs- und Löschvorgänge (CRUD) auf Onlineendpunkten und Onlinebereitstellungen.

Ein Datenebenenvorgang verwendet Daten, um mit einem Onlineendpunkt zu interagieren, ohne den Endpunkt zu ändern. Beispielsweise kann ein Datenebenenvorgang aus dem Senden einer Bewertungsanforderung an einen Onlineendpunkt und dem Abrufen einer Antwort bestehen.

Voraussetzungen

Stellen Sie vor dem Ausführen der Schritte in diesem Artikel sicher, dass Sie über die folgenden erforderlichen Komponenten verfügen:

  • Ein Azure Machine Learning-Arbeitsbereich. Wenn keiner vorliegt, führen Sie die Schritte unter Schnellstart: Erstellen von Arbeitsbereichsressourcen aus, um einen Arbeitsbereich zu erstellen.

  • Die Azure CLI und die ml-Erweiterung oder das Azure Machine Learning Python SDK v2:

    • Informationen zum Installieren der Azure CLI und der Erweiterung finden Sie unter Installieren, Einrichten und Verwenden der CLI (v2).

      Wichtig

      In den CLI-Beispielen in diesem Artikel wird davon ausgegangen, dass Sie die Bash-Shell (oder eine kompatible Shell) verwenden, beispielsweise über ein Linux-System oder ein Windows-Subsystem für Linux.

    • Verwenden Sie zum Installieren des Python SDK v2 den folgenden Befehl:

      pip install azure-ai-ml azure-identity

      Verwenden Sie den folgenden Befehl, um eine vorhandene Installation des SDK auf die neueste Version zu aktualisieren:

      pip install --upgrade azure-ai-ml azure-identity

      Weitere Informationen finden Sie unter Installieren des Python SDK v2 für Azure Machine Learning.

Begrenzungen

Endpunkte mit Microsoft Entra-Token (aad_token)-Authentifizierungsmodus unterstützen keine Bewertung mithilfe der CLI az ml online-endpoint invoke, des SDK ml_client.online_endpoints.invoke() oder der Registerkarten Testen oder Nutzen des Azure Machine Learning-Studios. Verwenden Sie stattdessen ein generisches Python SDK oder die REST-API, um das Steuerelementebenentoken zu übergeben. Weitere Informationen finden Sie unter Score-Daten mithilfe des Schlüssels oder Tokens.

Vorbereiten einer Benutzeridentität

Sie benötigen eine Benutzeridentität, um Steuerungsebenenvorgänge (d. h. CRUD-Vorgänge) und Datenebenenvorgänge (d. h. Bewertungsanforderungen senden) auf dem Onlineendpunkt durchzuführen. Sie können dieselbe Benutzeridentität oder unterschiedliche Benutzeridentitäten für die Steuerungsebenen- und Datenebenenvorgänge verwenden. In diesem Artikel verwenden Sie die gleiche Benutzeridentität für Vorgänge der Steuerungsebene und der Datenebene.

Informationen zum Erstellen einer Benutzeridentität unter Microsoft Entra-ID finden Sie unter Einrichten der Authentifizierung. Sie benötigen die Identitäts-ID später.

Zuweisen der Berechtigung an die Identität

In diesem Abschnitt weisen Sie der Benutzeridentität, die Sie für die Interaktion mit dem Endpunkt verwenden, Berechtigungen zu. Sie beginnen mit der Verwendung einer integrierten Rolle oder durch Erstellen einer benutzerdefinierten Rolle. Anschließend weisen Sie der Benutzeridentität die Rolle zu.

Verwenden einer integrierten Rolle

Die AzureML Data Scientistintegrierte Rollekann für die Verwaltung und Nutzung von Endpunkten und Bereitstellungen verwendet werden und nutzt Platzhalter, um die folgenden RBAC-Aktionen der Steuerungsebene einzuschließen:

  • 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

und um die folgende RBAC-Aktion der Datenebene einzuschließen:

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

Optional kann die integrierte Rolle Azure Machine Learning Workspace Connection Secrets Reader verwendet werden, um auf Geheimnisse aus Arbeitsbereichsverbindungen zuzugreifen und die folgenden RBAC-Aktionen der Steuerungsebene einzuschließen:

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

Wenn Sie diese integrierten Rollen verwenden, ist in diesem Schritt keine Aktion erforderlich.

(Optional) Erstellen einer benutzerdefinierten Rolle

Sie können diesen Schritt überspringen, wenn Sie integrierte Rollen oder andere vordefinierte benutzerdefinierte Rollen verwenden.

  1. Definieren Sie den Bereich und die Aktionen für benutzerdefinierte Rollen, indem Sie JSON-Definitionen der Rollen erstellen. Mit der folgenden Rollendefinition kann der Benutzer z. B. einen Onlineendpunkt unter einem angegebenen Arbeitsbereich in CRUD erstellen.

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

    Mit der folgenden Rollendefinition kann der Benutzer Bewertungsanforderungen an einen Onlineendpunkt unter einem bestimmten Arbeitsbereich senden.

    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. Verwenden Sie die JSON-Definitionen, um benutzerdefinierte Rollen zu erstellen:

    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>

    Hinweis

    Zum Erstellen benutzerdefinierter Rollen benötigen Sie eine von drei Rollen:

    • owner
    • Benutzerzugriffsadministrator
    • eine benutzerdefinierte Rolle mit Microsoft.Authorization/roleDefinitions/write-Berechtigung (zum Erstellen/Aktualisieren/Löschen benutzerdefinierter Rollen) und Microsoft.Authorization/roleDefinitions/read-Berechtigung (zum Anzeigen benutzerdefinierter Rollen).

    Weitere Informationen zum Erstellen benutzerdefinierter Rollen finden Sie unter benutzerdefinierte Azure-Rollen.

  3. Überprüfen Sie die Rollendefinition:

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

Zuweisen der Rolle zur Identität

  1. Wenn Sie die integrierte Rolle AzureML Data Scientist verwenden, nutzen Sie den folgenden Code, um ihrer Benutzeridentität die Rolle zuzuweisen.

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

  2. Wenn Sie alternativ die integrierte Rolle Azure Machine Learning Workspace Connection Secrets Reader verwenden, nutzen Sie den folgenden Code, um ihrer Benutzeridentität die Rolle zuzuweisen.

    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. Wenn Sie eine benutzerdefinierte Rolle verwenden, verwenden Sie den folgenden Code, um ihrer Benutzeridentität die Rolle zuzuweisen.

    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>

    Hinweis

    Um der Benutzeridentität benutzerdefinierte Rollen zuzuweisen, benötigen Sie eine von drei Rollen:

    • owner
    • Benutzerzugriffsadministrator
    • eine benutzerdefinierte Rolle, welche die Microsoft.Authorization/roleAssignments/write-Berechtigung (zum Zuweisen benutzerdefinierter Rollen) und Microsoft.Authorization/roleAssignments/read (zum Anzeigen von Rollenzuweisungen) zulässt.

    Weitere Informationen zu den verschiedenen Azure-Rollen und deren Berechtigungen finden Sie unter Azure-Rollen und Zuweisen von Azure-Rollen mithilfe des Azure-Portals.

  4. Bestätigen Sie die Rollenzuweisung:

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

Abrufen des Microsoft Entra-Tokens für Steuerungsebenenvorgänge

Führen Sie diesen Schritt aus, wenn Sie die Steuerungsebenenoperationen mit der REST-APIausführen möchten, die das Token direkt verwenden.

Wenn Sie andere Möglichkeiten wie Azure Machine Learning CLI (v2), Python SDK (v2) oder das Azure Machine Learning Studio verwenden möchten, müssen Sie das Microsoft Entra-Token nicht manuell abrufen. Stattdessen wurde ihre Benutzeridentität bei der Anmeldung bereits authentifiziert, und das Token wird automatisch abgerufen und für Sie übergeben.

Sie können das Microsoft Entra-Token für Steuerungsebenenvorgänge vom Azure-Ressourcenendpunkt abrufen: https://management.azure.com.

  1. Melden Sie sich bei Azure an.

    az login

  2. Wenn Sie eine bestimmte Identität verwenden möchten, verwenden Sie den folgenden Code, um sich mit der Identität anzumelden:

    az login --identity --username <identityId>

  3. Verwenden Sie diesen Kontext, um das Token abzurufen.

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

(Optional) Überprüfen des Ressourcenendpunkts und der Client-ID für das Microsoft Entra-Token

Nachdem Sie das Microsoft Entra-Token abgerufen haben, können Sie überprüfen, ob das Token für den richtigen Azure-Ressourcenendpunkt management.azure.com und die richtige Client-ID gilt, indem Sie das Token über jwt.ms decodieren, wodurch eine JSON-Antwort mit den folgenden Informationen zurückgegeben wird:

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

Erstellen eines Endpunkts

Im folgenden Beispiel wird der Endpunkt mit einer vom System zugewiesenen Identität (SAI) als Endpunktidentität erstellt. Das SAI ist der Standardidentitätstyp der verwalteten Identität für Endpunkte. Einige Grundlegende Rollen werden automatisch für das SAI zugewiesen. Weitere Informationen zur Rollenzuweisung für eine vom System zugewiesene Identität finden Sie unter Automatische Rollenzuweisung für Endpunktidentitäten.

Die CLI erfordert nicht, dass Sie explizit das Steuerelementebenentoken bereitstellen. Stattdessen authentifiziert die CLI Sie während der Anmeldung, und das Token wird automatisch abgerufen und für Sie übergeben.

  1. Erstellen Sie eine YAML-Endpunktdefinitionsdatei.

    endpoint.yml:

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

  2. Sie können auth_mode für die Schlüsselauthentifizierung durch key oder aml_token für die Azure Machine Learning-Tokenauthentifizierung ersetzen. In diesem Beispiel verwenden Sie aad_token für die Authentifizierung des Microsoft Entra-Tokens.

    az ml online-endpoint create -f endpoint.yml

  3. Überprüfen Sie den Status des Endpunkts:

    az ml online-endpoint show -n my-endpoint

  4. Wenn Sie beim Erstellen eines Endpunkts auth_mode außer Kraft setzen möchten (z. B. durch aad_token), führen Sie den folgenden Code aus:

    az ml online-endpoint create -n my-endpoint --auth_mode aad_token

  5. Wenn Sie den vorhandenen Endpunkt aktualisieren und auth_mode angeben möchten (z. B. durch aad_token), führen Sie den folgenden Code aus:

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

Erstellen einer Bereitstellung

Informationen zum Erstellen einer Bereitstellung finden Sie unter Bereitstellen eines ML-Modells mit einem Onlineendpunkt oder Verwenden von REST zum Bereitstellen eines Modells als Onlineendpunkt. Es gibt keinen Unterschied bei der Erstellung von Bereitstellungen für verschiedene Authentifizierungsmodi.

Der folgende Code ist ein Beispiel für das Erstellen einer Bereitstellung. Weitere Informationen zum Bereitstellen von Onlineendpunkten finden Sie unter Bereitstellen eines ML-Modells mit einem Onlineendpunkt (über CLI)

  1. Erstellen Sie eine YAML-Bereitstellungsdefinitionsdatei.

    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. Erstellen Sie die Bereitstellung mithilfe der YAML-Datei. Legen Sie in diesem Beispiel den gesamten Datenverkehr auf die neue Bereitstellung fest.

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

Abrufen des Bewertungs-URI für den Endpunkt

Wenn Sie beabsichtigen, die CLI zum Aufrufen des Endpunkts zu verwenden, müssen Sie den Bewertungs-URI nicht explizit abrufen, da die CLI ihn für Sie verarbeitet. Sie können jedoch weiterhin die CLI verwenden, um den Bewertungs-URI abzurufen, damit Sie ihn mit anderen Kanälen wie der REST-API verwenden können.

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

Abrufen des Schlüssels oder Token für Datenebenenvorgänge

Ein Schlüssel oder Token kann für Datenebenenvorgänge verwendet werden, obwohl der Vorgang zum Abrufen des Schlüssels oder Tokens ein Steuerungsebenenvorgang ist. Mit anderen Worten: Sie verwenden ein Steuerebenentoken, um den Schlüssel oder das Token abzurufen, den Sie später zum Ausführen Ihrer Datenebenenvorgänge verwenden.

Zum Abrufen des Schlüssels oder des Azure Machine Learning-Tokens muss der Benutzeridentität die richtige, von ihr angeforderte Rolle zugewiesen werden, wie in der Autorisierung für Steuerungsebenenvorgänge beschrieben. Die Benutzeridentität benötigt keine zusätzlichen Rollen, um das Microsoft Entra-Token abzurufen.

Schlüssel- oder Azure Machine Learning-Token

Wenn Sie beabsichtigen, die CLI zum Aufrufen des Endpunkts zu verwenden, und wenn der Endpunkt für die Verwendung eines Authentifizierungsmodus von Schlüsseln oder Azure Machine Learning-Token (aml_token) eingerichtet ist, müssen Sie das Datenebenentoken nicht explizit abrufen, da die CLI es für Sie verarbeitet. Sie können jedoch weiterhin die CLI verwenden, um das Datenebenentoken abzurufen, damit Sie es mit anderen Kanälen wie der REST-API verwenden können.

Verwenden Sie zum Abrufen des Schlüssels oder des Azure Machine Learning-Tokens (aml_token) den Befehl az ml online-endpoint get-credentials. Dieser Befehl gibt ein JSON-Dokument zurück, das den Schlüssel oder das Azure Machine Learning-Token enthält.

Schlüssel werden in den Feldern primaryKey und secondaryKey zurückgegeben. Das folgende Beispiel zeigt, wie Sie den --query-Parameter verwenden, um nur den Primärschlüssel zurückzugeben:

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 werden im Feld accessToken zurückgegeben:

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

Darüber hinaus enthalten die Felder expiryTimeUtc und refreshAfterTimeUtc die Ablauf- und Aktualisierungszeiten des Tokens.

Microsoft Entra-Token

Verwenden Sie zum Abrufen des Microsoft Entra-Tokens (aad_token) mithilfe der CLI den Befehl az account get-access-token. Dieser Befehl gibt ein JSON-Dokument zurück, welches das Microsoft Entra-Token enthält.

Das Microsoft Entra-Token wird im Feld accessToken zurückgegeben:

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

Hinweis

  • Die CLI-Erweiterung ml unterstützt nicht das Abrufen des Microsoft Entra-Tokens. Verwenden Sie stattdessen az account get-access-token, wie im vorherigen Code beschrieben.
  • Das Token für Datenebenenvorgänge wird vom Azure-Ressourcenendpunkt ml.azure.com statt, wie das Token für Steuerungsebenenvorgänge, von management.azure.com abgerufen.

Überprüfen des Ressourcenendpunkts und der Client-ID für das Microsoft Entra-Token

Nachdem Sie das Entra-Token abgerufen haben, können Sie überprüfen, ob das Token für den richtigen Azure-Ressourcenendpunkt ml.azure.com und die richtige Client-ID ist, indem Sie das Token über jwt.msdecodieren, wodurch eine JSON-Antwort mit den folgenden Informationen zurückgegeben wird:

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

Bewerten von Daten mithilfe des Schlüssels oder Tokens

Schlüssel- oder Azure Machine Learning-Token

Sie können az ml online-endpoint invoke für Endpunkte mit einem Schlüssel oder Azure Machine Learning-Token verwenden. Die CLI verarbeitet den Schlüssel oder das Azure Machine Learning-Token automatisch, sodass Sie es nicht explizit übergeben müssen.

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

Microsoft Entra-Token

Die Verwendung von az ml online-endpoint invoke für Endpunkte mit einem Microsoft Entra-Token wird nicht unterstützt. Verwenden Sie stattdessen die REST-API und den Bewertungs-URI des Endpunkts, um den Endpunkt aufzurufen.

Protokollieren und Überwachen des Datenverkehrs

Um die Datenverkehrsprotokollierung in den Diagnoseeinstellungen für den Endpunkt zu aktivieren, führen Sie die Schritte zum Aktivieren/Deaktivieren von Protokollen aus.

Wenn die Diagnoseeinstellung aktiviert ist, können Sie die AmlOnlineEndpointTrafficLogs-Tabelle überprüfen, um den Authentifizierungsmodus und die Benutzeridentität anzuzeigen.

Zugehöriger Inhalt