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


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

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

Из этой статьи вы узнаете, как проверить подлинность клиентов для конечных точек Машинного обучения Azure. Вы настраиваете разрешения, создаете конечную точку, извлекаете маркеры или ключи и оцениваете данные с помощью одного из трех режимов проверки подлинности: ключ, маркер машинного обучения Azure (aml_token) или токен Microsoft Entra (aad_token).

Проверка подлинности конечной точки в Сети включает два типа операций:

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

Выбор режима проверки подлинности

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

Ключ Токен машинного обучения Azure (aml_token) Токен Microsoft Entra (aad_token)
Уровень безопасности Наименьший — срок действия статических ключей не истекает Средний: кратковременный, автоматически обновляемый Самый высокий — на основе идентификации, в рамках ролей
Типы конечных точек Управляемые и Kubernetes Управляемые и Kubernetes Только управляемое
Для оценки требуется RBAC Нет Нет Да (score/action роль)
Время существования токена Срок действия не истек (поворот вручную) Краткосрочное с обновлением Краткосрочная (согласно политике Microsoft Entra)
лучше всего подходит для Разработка и тестирование Автоматизированные конвейеры Нагрузки в производственной среде

Для рабочих нагрузок в управляемых сетевых конечных точках используйте проверку подлинности маркера Microsoft Entra (aad_token) для обеспечения надежной безопасности. Для разработки или конечных точек Kubernetes проверка подлинности на основе ключей является самым простым вариантом.

Внимание

Проверка подлинности токенаaad_token Microsoft Entra поддерживается только для управляемых конечных точек в Интернете. Для сетевых конечных точек Kubernetes используйте ключ или аутентификацию с помощью токенаaml_token для Azure Machine Learning. Дополнительные сведения см. в статье "Проверка подлинности и авторизация для сетевых конечных точек".

Требуемые условия

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

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

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

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

  • Пакет SDK для Python: azure-ai-ml и azure-identity пакеты (pip install azure-ai-ml azure-identity)
  • Azure CLI: ml расширение (az extension add -n ml)
  • Учетная запись пользователя в 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>
    

Получение токена контрольной плоскости

Выполните этот шаг, если планируется выполнять операции управления с помощью 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 можно убедиться, что маркер предназначен для правильной конечной точки ресурса Azure (management.azure.com) и правильного идентификатора клиента, декодируя маркер с помощью jwt.ms.

Совет

Сайт jwt.ms — это инструмент, принадлежащий Microsoft, который полностью декодирует токены в браузере — данные не отправляются на сервер. Никогда не вставлять маркеры в ненадежные средства декодирования.

Декодированные маркеры возвращают ответ JSON, содержащий следующие сведения:

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

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

В следующем примере создается конечная точка с удостоверением, назначенным системой (SAI) в качестве удостоверения конечной точки. SAI — это тип удостоверения по умолчанию для конечных точек, а некоторые основные роли автоматически назначаются. Для получения дополнительной информации см. Автоматическое назначение ролей для идентификации конечной точки.

Интерфейс командной строки не требует явного предоставления маркера плоскости управления. Вместо этого команда 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.

    Примечание.

    Режим aad_token проверки подлинности поддерживается только для управляемых сетевых конечных точек. Для сетевых конечных точек Kubernetes установите auth_mode на key или aml_token.

  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

Получите ключ или токен плоскости данных

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

Время существования маркеров зависит от режима проверки подлинности:

  • Ключ: срок действия ключей не истекает, но их следует регулярно поворачивать для обеспечения безопасности. regenerateKeys Используйте функцию для поворота ключей.
  • Токен машинного обучения Azure (aml_token): кратковременные маркеры, включающие refreshAfterTimeUtc поле. Запросить новый токен после этого времени, чтобы избежать истечения срока действия.
  • Токен Microsoft Entra (aad_token): следует политике продолжительности существования токена идентификатора Microsoft Entra (обычно 60–90 минут). Обновите токен до expiryTimeUtc.

Чтобы получить ключ или токен машинного обучения Azure, удостоверение пользователя, запрашивающее его, должно иметь назначенную правильную роль, как описано в разделе „Авторизация для операций плоскости управления”. Пользователю не нужны дополнительные роли для получения токена 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

Проверка маркера плоскости данных (необязательно)

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

Совет

Сайт jwt.ms — это инструмент, принадлежащий Microsoft, который полностью декодирует токены в браузере — данные не отправляются на сервер. Никогда не вставлять маркеры в ненадежные средства декодирования.

{
    "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, чтобы увидеть режим проверки подлинности и удостоверение пользователя.

Устранение ошибок аутентификации

В следующей таблице перечислены распространенные ошибки аутентификации и их разрешения.

Error Вероятно, причина Резолюция
401 — не авторизовано Отсутствующий, просроченный или предназначенный для неверной аудитории токен Убедитесь, что аудитория токена соответствует типу конечной точки: management.azure.com для управляющей плоскости, ml.azure.com для плоскости данных. Обновление истекших токенов.
403 Запрещено Идентификация пользователя не имеет необходимой роли RBAC Назначьте AzureML Data Scientist или настраиваемую роль с правом доступа score/action на уровне конечной точки. См. раздел "Назначение разрешений для удостоверения".
aad_token не принято Использование aad_token конечной точки Kubernetes Переключение на key или aml_token. Аутентификация по маркеру Microsoft Entra поддерживается только для управляемых онлайн конечных точек.
AADSTS700016 или аналогичная ошибка Entra В запросе токена указан неправильный ресурс или аудитория Убедитесь, что параметр ресурса соответствует типу операции: https://management.azure.com для управляющей плоскости, https://ml.azure.com для плоскости данных.