Udostępnij za pośrednictwem


Uwierzytelnianie klientów dla punktów końcowych online

DOTYCZY: Rozszerzenie interfejsu wiersza polecenia platformy Azure w wersji 2 (current)Zestaw PYTHON SDK azure-ai-ml v2 (bieżąca)

W tym artykule opisano sposób uwierzytelniania klientów w celu wykonywania operacji płaszczyzny sterowania i płaszczyzny danych w punktach końcowych online.

Operacja płaszczyzny sterowania kontroluje punkt końcowy i zmienia go. Operacje płaszczyzny sterowania obejmują operacje tworzenia, odczytu, aktualizacji i usuwania (CRUD) w punktach końcowych online i wdrożeniach online.

Operacja płaszczyzny danych używa danych do interakcji z punktem końcowym online bez zmiany punktu końcowego. Na przykład operacja płaszczyzny danych może składać się z wysyłania żądania oceniania do punktu końcowego online i uzyskiwania odpowiedzi.

Wymagania wstępne

Przed wykonaniem kroków opisanych w tym artykule upewnij się, że masz następujące wymagania wstępne:

Przygotowywanie tożsamości użytkownika

Tożsamość użytkownika jest potrzebna do wykonywania operacji płaszczyzny sterowania (czyli operacji CRUD) i operacji płaszczyzny danych (czyli wysyłania żądań oceniania) w punkcie końcowym online. W przypadku operacji płaszczyzny sterowania i płaszczyzny danych można użyć tej samej tożsamości użytkownika lub różnych tożsamości użytkowników. W tym artykule używasz tej samej tożsamości użytkownika zarówno dla operacji płaszczyzny sterowania, jak i płaszczyzny danych.

Aby utworzyć tożsamość użytkownika w obszarze Microsoft Entra ID, zobacz Konfigurowanie uwierzytelniania. Później będzie potrzebny identyfikator tożsamości.

Przypisywanie uprawnień do tożsamości

W tej sekcji przypiszesz uprawnienia do tożsamości użytkownika używanej do interakcji z punktem końcowym. Zaczynasz od użycia wbudowanej roli lub przez utworzenie roli niestandardowej. Następnie przypiszesz rolę do tożsamości użytkownika.

Używanie wbudowanej roli

Wbudowana AzureML Data Scientist rola może służyć do zarządzania punktami końcowymi i wdrożeniami oraz używania ich oraz używania symboli wieloznacznych w celu uwzględnienia następujących akcji kontroli RBAC płaszczyzny sterowania:

  • 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

i uwzględnić następującą akcję kontroli dostępu opartej na rolach płaszczyzny danych:

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

Opcjonalnie wbudowana Azure Machine Learning Workspace Connection Secrets Reader rola może służyć do uzyskiwania dostępu do wpisów tajnych z połączeń obszaru roboczego i obejmuje następujące akcje kontroli RBAC płaszczyzny sterowania:

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

Jeśli używasz tych wbudowanych ról, w tym kroku nie jest wymagana żadna akcja.

(Opcjonalnie) Tworzenie roli niestandardowej

Ten krok można pominąć, jeśli używasz wbudowanych ról lub innych wstępnie utworzonych ról niestandardowych.

  1. Zdefiniuj zakres i akcje dla ról niestandardowych, tworząc definicje JSON ról. Na przykład poniższa definicja roli umożliwia użytkownikowi cruD punkt końcowy online w ramach określonego obszaru roboczego.

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

    Poniższa definicja roli umożliwia użytkownikowi wysyłanie żądań oceniania do punktu końcowego online w określonym obszarze roboczym.

    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. Użyj definicji JSON, aby utworzyć role niestandardowe:

    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>
    

    Uwaga

    Aby utworzyć role niestandardowe, potrzebujesz jednej z trzech ról:

    • owner
    • administrator dostępu użytkowników
    • rola niestandardowa z Microsoft.Authorization/roleDefinitions/write uprawnieniem (aby utworzyć/zaktualizować/usunąć role niestandardowe) i Microsoft.Authorization/roleDefinitions/read uprawnienie (aby wyświetlić role niestandardowe).

    Aby uzyskać więcej informacji na temat tworzenia ról niestandardowych, zobacz Role niestandardowe platformy Azure.

  3. Sprawdź definicję roli:

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

Przypisywanie roli do tożsamości

  1. Jeśli używasz wbudowanej roli, użyj następującego AzureML Data Scientist kodu, aby przypisać rolę do tożsamości użytkownika.

    az role assignment create --assignee <identityId> --role "AzureML Data Scientist" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>
    
  2. Opcjonalnie, jeśli używasz wbudowanej roli, użyj następującego Azure Machine Learning Workspace Connection Secrets Reader kodu, aby przypisać rolę do tożsamości użytkownika.

    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. Jeśli używasz roli niestandardowej, użyj następującego kodu, aby przypisać rolę do tożsamości użytkownika.

    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>
    

    Uwaga

    Aby przypisać role niestandardowe do tożsamości użytkownika, potrzebujesz jednej z trzech ról:

    • owner
    • administrator dostępu użytkowników
    • rola niestandardowa, która zezwala na Microsoft.Authorization/roleAssignments/write uprawnienia (do przypisywania ról niestandardowych) i Microsoft.Authorization/roleAssignments/read (w celu wyświetlania przypisań ról).

    Aby uzyskać więcej informacji na temat różnych ról platformy Azure i ich uprawnień, zobacz Role platformy Azure i Przypisywanie ról platformy Azure przy użyciu witryny Azure Portal.

  4. Potwierdź przypisanie roli:

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

Uzyskiwanie tokenu Microsoft Entra dla operacji płaszczyzny sterowania

Wykonaj ten krok , jeśli planujesz wykonywać operacje płaszczyzny sterowania za pomocą interfejsu API REST, który będzie bezpośrednio używać tokenu.

Jeśli planujesz używać innych sposobów, takich jak interfejs wiersza polecenia usługi Azure Machine Learning (wersja 2), zestaw PYTHON SDK (wersja 2) lub usługa Azure Machine Learning Studio, nie musisz ręcznie pobierać tokenu entra firmy Microsoft. Zamiast tego podczas logowania tożsamość użytkownika zostałaby już uwierzytelniona, a token zostanie automatycznie pobrany i przekazany.

Token entra firmy Microsoft dla operacji płaszczyzny sterowania można pobrać z punktu końcowego zasobu platformy Azure: https://management.azure.com.

  1. Zaloguj się do Azure.

    az login
    
  2. Jeśli chcesz użyć określonej tożsamości, użyj następującego kodu, aby zalogować się przy użyciu tożsamości:

    az login --identity --username <identityId>
    
  3. Użyj tego kontekstu, aby uzyskać token.

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

(Opcjonalnie) Weryfikowanie punktu końcowego zasobu i identyfikatora klienta dla tokenu entra firmy Microsoft

Po pobraniu tokenu Firmy Microsoft Entra możesz sprawdzić, czy token jest odpowiedni dla odpowiedniego punktu końcowego management.azure.com zasobu platformy Azure i odpowiedniego identyfikatora klienta, dekodując token za pośrednictwem jwt.ms, co spowoduje zwrócenie odpowiedzi json z następującymi informacjami:

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

Tworzenie punktu końcowego

Poniższy przykład tworzy punkt końcowy z tożsamością przypisaną przez system (SAI) jako tożsamością punktu końcowego. Sai jest domyślnym typem tożsamości zarządzanej dla punktów końcowych. Niektóre podstawowe role są automatycznie przypisywane dla sai. Aby uzyskać więcej informacji na temat przypisywania roli dla tożsamości przypisanej przez system, zobacz Automatyczne przypisywanie roli dla tożsamości punktu końcowego.

Interfejs wiersza polecenia nie wymaga jawnego podania tokenu płaszczyzny sterowania. Zamiast tego interfejs wiersza polecenia az login uwierzytelnia Cię podczas logowania, a token jest automatycznie pobierany i przekazywany.

  1. Utwórz plik YAML definicji punktu końcowego.

    endpoint.yml:

    $schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
    name: my-endpoint
    auth_mode: aad_token
    
  2. Możesz zastąpić auth_mode ciąg ciągiem key dla uwierzytelniania klucza lub aml_token uwierzytelniania tokenu usługi Azure Machine Learning. W tym przykładzie używasz aad_token uwierzytelniania tokenu Entra firmy Microsoft.

    az ml online-endpoint create -f endpoint.yml
    
  3. Sprawdź stan punktu końcowego:

    az ml online-endpoint show -n my-endpoint
    
  4. Jeśli chcesz przesłonić auth_mode (na przykład do aad_token) podczas tworzenia punktu końcowego, uruchom następujący kod:

    az ml online-endpoint create -n my-endpoint --auth_mode aad_token
    
  5. Jeśli chcesz zaktualizować istniejący punkt końcowy i określić auth_mode (na przykład do aad_token), uruchom następujący kod:

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

Tworzenie wdrożenia

Aby utworzyć wdrożenie, zobacz Deploy an ML model with an online endpoint (Wdrażanie modelu uczenia maszynowego przy użyciu punktu końcowego online) lub Use REST to deploy an model as an online endpoint (Wdrażanie modelu uczenia maszynowego przy użyciu punktu końcowego online) lub Use REST to deploy an model as an online endpoint (Wdrażanie modelu w trybie online). Nie ma różnicy w sposobie tworzenia wdrożeń dla różnych trybów uwierzytelniania.

Poniższy kod to przykład tworzenia wdrożenia. Aby uzyskać więcej informacji na temat wdrażania punktów końcowych online, zobacz Wdrażanie modelu uczenia maszynowego przy użyciu punktu końcowego online (za pośrednictwem interfejsu wiersza polecenia)

  1. Utwórz plik YAML definicji wdrożenia.

    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. Utwórz wdrożenie przy użyciu pliku YAML. W tym przykładzie ustaw cały ruch na nowe wdrożenie.

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

Uzyskiwanie identyfikatora URI oceniania dla punktu końcowego

Jeśli planujesz wywołać punkt końcowy przy użyciu interfejsu wiersza polecenia, nie musisz jawnie uzyskać identyfikatora URI oceniania, ponieważ interfejs wiersza polecenia obsługuje go za Ciebie. Jednak nadal możesz użyć interfejsu wiersza polecenia, aby uzyskać identyfikator URI oceniania, aby można było go używać z innymi kanałami, takimi jak interfejs API REST.

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

Pobieranie klucza lub tokenu dla operacji płaszczyzny danych

Klucz lub token może służyć do operacji płaszczyzny danych, mimo że proces pobierania klucza lub tokenu jest operacją płaszczyzny sterowania. Innymi słowy, używasz tokenu płaszczyzny sterowania, aby uzyskać klucz lub token, którego później używasz do wykonywania operacji płaszczyzny danych.

Uzyskanie klucza lub tokenu usługi Azure Machine Learning wymaga, aby prawidłowa rola została przypisana do żądanej tożsamości użytkownika, zgodnie z opisem w temacie Autoryzacja dla operacji płaszczyzny sterowania. Pobieranie tokenu Microsoft Entra nie wymaga żadnych dodatkowych ról dla tożsamości użytkownika.

Jeśli planujesz używać interfejsu wiersza polecenia do wywoływania punktu końcowego, nie musisz jawnie pobierać kluczy ani tokenu dla operacji płaszczyzny danych, ponieważ interfejs wiersza polecenia je obsługuje. Jednak nadal możesz użyć interfejsu wiersza polecenia, aby uzyskać klucze lub token operacji płaszczyzny danych, aby można było go używać z innymi kanałami, takimi jak interfejs API REST.

Aby uzyskać klucze lub token dla operacji płaszczyzny danych, użyj polecenia az ml online-endpoint get-credentials . To polecenie zwraca dane wyjściowe JSON zawierające klucze, token i/lub dodatkowe informacje.

Napiwek

Aby wyodrębnić określone informacje z danych wyjściowych JSON, --query parametr polecenia interfejsu wiersza polecenia jest używany jako przykład. Jednak w tym celu można użyć dowolnego odpowiedniego narzędzia.

Kiedy auth_mode punkt końcowy jest key

  • Klucze są zwracane w polach primaryKey i 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)

Kiedy auth_mode punkt końcowy jest aml_token

  • Token jest zwracany w accessToken polu.
  • Czas wygaśnięcia tokenu expiryTimeUtc jest zwracany w polu.
  • Czas odświeżania tokenu refreshAfterTimeUtc jest zwracany w polu.
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)

Kiedy auth_mode punkt końcowy jest aad_token

  • Token jest zwracany w accessToken polu.
  • Czas wygaśnięcia tokenu expiryTimeUtc jest zwracany w polu.
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)

Weryfikowanie punktu końcowego zasobu i identyfikatora klienta tokenu entra firmy Microsoft

Po otrzymaniu tokenu Entra możesz sprawdzić, czy token jest odpowiedni dla odpowiedniego punktu końcowego ml.azure.com zasobu platformy Azure i odpowiedniego identyfikatora klienta, dekodując token za pośrednictwem jwt.ms, co spowoduje zwrócenie odpowiedzi json z następującymi informacjami:

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

Ocenianie danych przy użyciu klucza lub tokenu

Możesz użyć dla az ml online-endpoint invoke punktów końcowych z kluczem, tokenem usługi Azure Machine Learning lub tokenem firmy Microsoft Entra. Interfejs wiersza polecenia automatycznie obsługuje klucz lub token, aby nie trzeba było przekazywać go jawnie.

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

Rejestrowanie i monitorowanie ruchu

Aby włączyć rejestrowanie ruchu w ustawieniach diagnostycznych punktu końcowego, wykonaj kroki opisane w temacie Jak włączyć/wyłączyć dzienniki.

Jeśli ustawienie diagnostyczne jest włączone, możesz sprawdzić tabelę AmlOnlineEndpointTrafficLogs , aby wyświetlić tryb uwierzytelniania i tożsamość użytkownika.