Поделиться через


Проверка подлинности клиентов для сетевых конечных точек

ОБЛАСТЬ ПРИМЕНЕНИЯ:Расширение машинного обучения Azure CLI версии 2 (current)Python SDK azure-ai-ml версии 2 (current)

В этой статье описывается, как аутентифицировать клиентов для выполнения операций контрольного плана и плана данных на сетевых конечных точках.

Операция плоскости управления управляет конечной точкой и изменяет ее. К операциям уровня управления относятся операции создания, чтения, обновления и удаления (CRUD) в сетевых конечных точках и развертываниях в сети.

Операция плоскости данных использует данные для взаимодействия с интернет-конечной точкой без изменения конечной точки. Например, операция плоскости данных может состоять из отправки запроса оценки в конечную точку в Сети и получения ответа.

Необходимые компоненты

  • Рабочая область Машинного обучения Azure. Инструкции по созданию рабочей области см. в разделе "Создание рабочей области".

  • Интерфейс командной строки Azure и расширение ml или Python SDK v2 для Azure Machine Learning:

    Чтобы установить Azure CLI и расширение, см. статью ml".

    Примеры в этой статье предполагают, что вы используете оболочку Bash или совместимую с ней. Например, можно использовать оболочку в системе Linux или подсистеме Windows для Linux.

  • Учетная запись пользователя в Microsoft Entra ID. Сведения о создании удостоверения пользователя см. в разделе "Настройка проверки подлинности". Позже вам потребуется идентификатор удостоверения.
  • Необходимая роль RBAC для операций уровня управления и данных: назначьте одну из следующих ролей для идентификации пользователя на уровне рабочей области:
    • Специалист по обработке и анализу данных AzureML (встроенный) — включает разрешения для операций CRUD в конечных точках и оценке. См . роль "Специалист по обработке и анализу данных AzureML".
    • Владелец или участник — полный доступ к управлению конечными точками.
    • Пользовательская роль с Microsoft.MachineLearningServices/workspaces/onlineEndpoints/* действиями.
  • (Необязательно) Средство чтения секретов подключений рабочей области машинного обучения Azure — обязательно только в случае, если вам необходимо получить доступ к секретам из подключений рабочей области.

Проверка настройки

Запустите этот фрагмент кода, чтобы убедиться, что учетные данные и разрешения RBAC настроены правильно:

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

Ожидаемые выходные данные: массив JSON конечных точек (пустой [] , если конечные точки еще не существуют).

Справочник: az ml online-endpoint list

Назначение разрешений удостоверению

Если у вас уже назначена требуемая роль RBAC (как указано в предварительных требованиях), перейдите к разделу "Создание конечной точки". В этом разделе содержатся сведения о создании пользовательских ролей при необходимости.

Просмотр встроенных сведений о роли

AzureML Data Scientist роль включает следующие действия RBAC уровня управления:

  • 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

И это действие уровня данных RBAC:

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

Встроенная Azure Machine Learning Workspace Connection Secrets Reader роль включает:

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

(Необязательно) Создание настраиваемой роли

Этот шаг можно пропустить, если вы используете встроенные роли или другие предварительно созданные пользовательские роли.

  1. Определите область и действия для пользовательских ролей, создав определения JSON ролей. Например, следующее определение роли ,custom-role-for-control-plane.json, позволяет пользователю выполнять операции CRUD в сетевой конечной точке в указанной рабочей области.

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

    Следующее определение роли 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. Используйте определения 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>
    

    Примечание.

    Чтобы создать пользовательские роли, вам потребуется одна из трех ролей:

    • Владелец
    • Администратор доступа пользователей
    • Пользовательская роль с Microsoft.Authorization/roleDefinitions/write разрешением (для создания, обновления и удаления пользовательских ролей) и Microsoft.Authorization/roleDefinitions/read разрешением (для просмотра пользовательских ролей).

    Дополнительные сведения о создании пользовательских ролей см. в статье о пользовательских ролях Azure.

  3. Проверьте определение роли:

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

Назначение роли удостоверению

  1. Если вы используете AzureML Data Scientist встроенную роль, используйте следующий код, чтобы назначить роль идентификатору пользователя.

    az role assignment create --assignee <identityID> --role "AzureML Data Scientist" --scope /subscriptions/<subscriptionID>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>
    
  2. При необходимости, если вы используете Azure Machine Learning Workspace Connection Secrets Reader встроенную роль, используйте следующий код, чтобы назначить роль удостоверению пользователя.

    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. Если вы используете пользовательскую роль, используйте следующий код, чтобы назначить роль идентификатору пользователя.

    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>
    

    Примечание.

    Чтобы назначить пользовательские роли удостоверению пользователя, вам потребуется одна из трех ролей:

    • Владелец
    • Администратор доступа пользователей
    • Пользовательская роль, которая предоставляет Microsoft.Authorization/roleAssignments/write разрешение (назначать пользовательские роли) и Microsoft.Authorization/roleAssignments/read (просматривать назначения ролей).

    Дополнительные сведения о ролях Azure и их разрешениях см. в статье "Роли Azure" и "Назначение ролей Azure" с помощью портала Azure.

  4. Подтвердите назначение роли:

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

Получение маркера Microsoft Entra для операций плоскости управления

Выполните этот шаг, если планируется выполнять операции управления с помощью REST API, который напрямую использует токен.

Если вы планируете использовать другие методы, такие как Azure CLI с расширением ml версии 2, пакетом SDK для Python версии 2 или студией машинного обучения Azure, вам не нужно вручную получить маркер Microsoft Entra. Ваша учетная запись будет аутентифицирована при входе, и токен будет автоматически получен и передан для вас.

Токен Microsoft Entra для операций в плоскости управления можно получить из конечной точки ресурса Azure: https://management.azure.com.

  1. войдите в Azure.

    az login
    
  2. Если вы хотите использовать определенное удостоверение, используйте следующий код для входа с помощью удостоверения:

    az login --identity --username <identityID>
    
  3. Используйте этот контекст для получения маркера:

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

Референс: az login, az account get-access-token

(Необязательно) Проверьте конечную точку ресурса и идентификатор клиента для токена Microsoft Entra

После получения маркера Microsoft Entra можно убедиться, что маркер предназначен для правильной конечной точки ресурса Azure (management.azure.com) и правильного идентификатора клиента, декодируя маркер с помощью jwt.ms, который возвращает ответ JSON со следующими сведениями:

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

Создание конечной точки

В следующем примере создается конечная точка с системно назначаемым удостоверением в качестве идентификатора конечной точки. Удостоверение, назначенное системой, является типом удостоверения по умолчанию для управляемого удостоверения конечных точек. Некоторые базовые роли автоматически назначаются для системно назначенной идентичности. Дополнительные сведения о назначении ролей для удостоверения, назначаемого системой, см. в разделе "Автоматическое назначение ролей" для удостоверения конечной точки.

Интерфейс командной строки не требует явного предоставления маркера плоскости управления. Вместо этого команда CLI az login выполняет проверку подлинности во время входа, а маркер автоматически извлекается и передается для вас.

  1. Создайте файл YAML определения конечной точки с именем endpoint.yml:

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

    Вы можете установить auth_mode для проверки подлинности ключа или key для проверки подлинности токена в Azure Machine Learning. В этом примере используется aad_token аутентификация токена Microsoft Entra.

  2. Создание конечной точки:

    az ml online-endpoint create -f endpoint.yml
    
  3. Проверьте состояние конечной точки:

    az ml online-endpoint show -n my-endpoint
    
  4. Если вы хотите переопределить auth_mode (например, на aad_token) при создании конечной точки, выполните следующий код:

    az ml online-endpoint create -n my-endpoint --auth-mode aad_token
    
  5. Если вы хотите обновить существующую конечную точку и указать auth_mode (например, как aad_token), выполните следующий код:

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

Справочник: az ml online-endpoint create, az ml online-endpoint show, az ml online-endpoint update

Создание развертывания

Сведения о создании развертывания см. в статье "Развертывание модели машинного обучения с помощью веб-конечной точки " или "Использование REST" для развертывания модели в качестве сетевой конечной точки. Нет разницы в том, как создавать развертывания для различных режимов проверки подлинности.

Следующий код является примером создания развертывания. Дополнительные сведения о развертывании сетевых конечных точек см. в статье "Развертывание модели машинного обучения с помощью сетевой конечной точки(через CLI)".

  1. Создайте файл YAML определения развертывания с именем 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. Создайте развертывание с помощью YAML-файла. В этом примере задайте для нового развертывания весь трафик.

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

Справочник: az ml online-deployment create

Получение URI оценки для конечной точки

Если вы используете az ml online-endpoint invoke для вызова конечной точки, интерфейс командной строки автоматически разрешает URI обработки, поэтому его не нужно извлекать вручную.

Однако если вам нужен универсальный код ресурса (URI) оценки для использования с другими инструментами (например, REST API или пользовательскими HTTP-клиентами), его можно получить с помощью следующей команды:

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

Справочник: az ml online-endpoint show

Получение ключа или маркера для операций плоскости данных

Ключ или маркер можно использовать для операций плоскости данных, даже если процесс получения ключа или маркера является операцией плоскости управления. Другими словами, маркер плоскости управления используется для получения ключа или маркера, который позже используется для выполнения операций плоскости данных.

Чтобы получить ключ или токен Azure Machine Learning, идентификатор пользователя, запрашивающего его, должен иметь назначенную правильную роль, как описано в разделе "Авторизация для операций плоскости управления". Пользователю не нужны дополнительные роли для получения токена Microsoft Entra.

Если вы планируете использовать интерфейс командной строки для вызова конечной точки, вам не нужно явно получать ключи или маркер для операций плоскости данных, так как интерфейс командной строки предоставляет его для вас. Однако вы по-прежнему можете использовать командную строку для получения ключей или токена для операций плоскости данных, чтобы использовать его с другими каналами, такими как REST API.

Чтобы получить ключи или маркер для операций плоскости данных, используйте команду az ml online-endpoint get-credentials . Эта команда возвращает выходные данные JSON, содержащие ключи, маркер и/или дополнительные сведения.

Совет

В следующей команде --query параметр используется для извлечения определенных сведений из выходных данных JSON. Однако для этой цели можно использовать любое подходящее средство.

Когда конечная auth_mode точка находится key

  • Ключи возвращаются в primaryKey полях и 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 точка находится aml_token

  • Маркер возвращается в поле accessToken.

  • Время истечения срока действия маркера возвращается в поле expiryTimeUtc.

  • Время обновления токена возвращается в поле 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 точка находится aad_token

  • Маркер возвращается в поле accessToken.

  • Время истечения срока действия маркера возвращается в поле 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)
    

Референция: az ml online-endpoint get-credentials

Проверка конечной точки ресурса и идентификатора клиента для маркера Microsoft Entra

После получения маркера Entra можно убедиться, что маркер предназначен для правильной конечной точки ресурса Azure, ml.azure.comа также правильный идентификатор клиента, декодируя маркер с помощью jwt.ms, который возвращает ответ JSON со следующими сведениями:

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

Оценка данных с помощью ключа или маркера

Для конечных точек можно использовать az ml online-endpoint invoke ключ, маркер Машинное обучение Azure или токен Microsoft Entra. Интерфейс командной строки автоматически предоставляет ключ или маркер, поэтому не нужно явно передавать его.

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

Справочник: az ml online-endpoint invoke

Журнал и мониторинг трафика

Чтобы включить ведение журнала трафика в параметрах диагностики конечной точки, выполните действия, описанные в разделе "Включение журналов".

Если параметр диагностики включен, вы можете просмотреть таблицу AmlOnlineEndpointTrafficLogs, чтобы увидеть режим проверки подлинности и удостоверение пользователя.