Freigeben über

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.

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 integrierte Rolle AzureML Data Scientist kann für die Verwaltung und Nutzung von Endpunkten und Bereitstellungen verwendet werden und nutzt Platzhalter, um die folgenden RBAC-Aktionen auf 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 az login 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. Zum Abrufen des Microsoft Entra-Tokens sind keine zusätzlichen Rollen für die Benutzeridentität erforderlich.

Wenn Sie beabsichtigen, die CLI zum Aufrufen des Endpunkts zu verwenden, müssen Sie die Schlüssel oder das Token für Vorgänge auf der Datenebene nicht explizit abrufen, da die CLI dies für Sie erledigt. Sie können jedoch weiterhin die CLI verwenden, um die Schlüssel oder das Token für Vorgänge auf der Datenebene abzurufen, damit Sie es mit anderen Kanälen wie der REST-API verwenden können.

Verwenden Sie den Befehl az ml online-endpoint get-credentials, um die Schlüssel oder das Token für Vorgänge auf der Datenebene abzurufen. Dieser Befehl gibt eine JSON-Ausgabe zurück, die die Schlüssel, das Token und/oder zusätzliche Informationen enthält.

Tipp

Um eine bestimmte Information aus der JSON-Ausgabe zu extrahieren, wird beispielsweise der Parameter --query des CLI-Befehls verwendet. Sie können jedoch jedes geeignete Tool für diesen Zweck verwenden.

Wenn auth_mode des Endpunkts key ist

  • Schlüssel werden in den Feldern primaryKey und secondaryKey zurückgegeben.
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)

Wenn auth_mode des Endpunkts aml_token ist

  • Das Token wird im Feld accessToken zurückgegeben.
  • Die Tokenablaufzeit wird im Feld expiryTimeUtc zurückgegeben.
  • Die Tokenaktualisierungszeit wird im Feld refreshAfterTimeUtc 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)
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)

Wenn auth_mode des Endpunkts aad_token ist

  • Das Token wird im Feld accessToken zurückgegeben.
  • Die Tokenablaufzeit wird im Feld expiryTimeUtc 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)
export EXPIRY_TIME_UTC=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query expiryTimeUtc)

Ü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

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

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

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