Autenticación de clientes para puntos de conexión en línea

  • Artículo

SE APLICA A:Extensión ML de la CLI de Azure v2 (actual)SDK de Python azure-ai-ml v2 (actual)

En este artículo se explica cómo autenticar a clientes para realizar operaciones de plano de control y plano de datos en puntos de conexión en línea.

Una operación de plano de control controla un punto de conexión y lo cambia. Las operaciones de plano de control incluyen operaciones de creación, lectura, actualización y eliminación (CRUD) en puntos de conexión en línea e implementaciones en línea.

Una operación de plano de datos usa datos para interactuar con un punto de conexión en línea sin cambiar el punto de conexión. Por ejemplo, una operación de plano de datos podría consistir en enviar una solicitud de puntuación a un punto de conexión en línea y obtener una respuesta.

Requisitos previos

Antes de seguir los pasos de este artículo, asegúrese de que tiene los siguientes requisitos previos:

Limitaciones

Los puntos de conexión con el modo de autenticación del token de Microsoft Entra (aad_token) no admiten la puntuación mediante la CLI az ml online-endpoint invoke, el SDK ml_client.online_endpoints.invoke() o las pestañas Probar o Consumir de Estudio de Azure Machine Learning. En su lugar, use un SDK genérico de Python o la API de REST para pasar el token de plano de control. Para obtener más información, consulte Puntuar datos usando la clave o el token.

Preparación de la identidad de un usuario

Se necesita la identidad de un usuario para realizar operaciones de plano de control (es decir, operaciones CRUD) y operaciones de plano de datos (es decir, enviar solicitudes de puntuación) en el punto de conexión en línea. Use la misma identidad de usuario o identidades de usuario diferentes para las operaciones de plano de control y de plano de datos. En este artículo, se usará la misma identidad de usuario para las operaciones de plano de control y de plano de datos.

Para crear una identidad de usuario en Microsoft Entra ID, consulte Configuración de la autenticación. Necesitará el id. de identidad más adelante.

Asignación de permisos a la identidad

En esta sección, asignará permisos a la identidad de usuario que se usa para interactuar con el punto de conexión. Para empezar, use un rol integrado o cree un rol personalizado. A partir de entonces, se asigna el rol a la identidad del usuario.

Use un rol integrado

El AzureML Data Scientistrol integrado se puede usar para administrar y usar puntos de conexión e implementaciones, y usa caracteres comodín para incluir las siguientes acciones de RBAC de plano de control:

  • 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

y para incluir las siguientes acciones de RBAC de plano de datos:

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

Opcionalmente, el rol integrado Azure Machine Learning Workspace Connection Secrets Reader se puede usar para acceder a secretos desde las conexiones del área de trabajo e incluye las siguientes acciones de RBAC de plano de control:

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

Si usa estos roles integrados, no se necesita ninguna acción en este paso.

(Opcional) creación de un rol personalizado

Omita este paso si usa roles integrados u otros roles personalizados creados previamente.

  1. Defina el ámbito y las acciones de los roles personalizados mediante la creación de definiciones JSON de los roles. Por ejemplo, la siguiente definición de rol permite al usuario realizar operaciones CRUD de un punto de conexión en línea en un área de trabajo especificada.

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

    La siguiente definición de rol permite al usuario enviar solicitudes de puntuación a un punto de conexión en línea en un área de trabajo especificada.

    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. Use las definiciones JSON para crear roles personalizados:

    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>

    Nota:

    Para crear roles personalizados, necesita uno de tres roles:

    • propietario
    • Administrador de acceso de usuarios
    • un rol personalizado con permiso de Microsoft.Authorization/roleDefinitions/write (para crear, actualizar o eliminar roles personalizados) y permiso de Microsoft.Authorization/roleDefinitions/read (para ver roles personalizados).

    Para obtener más información sobre la creación de roles personalizados, consulte Roles personalizados de Azure.

  3. Compruebe la definición de roles:

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

Asignar el rol a la identidad

  1. Si usa el rol integrado AzureML Data Scientist, use el código siguiente para asignar el rol a la identidad de usuario.

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

  2. Opcionalmente, si usa el rol integrado Azure Machine Learning Workspace Connection Secrets Reader, use el código siguiente para asignar el rol a la identidad de usuario.

    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. Si usa un rol personalizado, use el código siguiente para asignar el rol a la identidad de usuario.

    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>

    Nota:

    Para asignar roles personalizados a la identidad de usuario, se necesita uno de estos tres roles:

    • propietario
    • Administrador de acceso de usuarios
    • un rol personalizado que permite los permisos Microsoft.Authorization/roleAssignments/write (para asignar roles personalizados) y Microsoft.Authorization/roleAssignments/read (para ver las asignaciones de roles).

    Para obtener más información sobre los distintos roles de Azure y sus permisos, consulte roles de Azure y Asignación de roles de Azure mediante Azure Portal.

  4. Confirme la asignación de roles:

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

Obtención del token de Microsoft Entra para operaciones de plano de control

Realice este paso si planea realizar operaciones de plano de control con la API de REST, que usará directamente el token.

Si planea usar otras formas, como la CLI de Azure Machine Learning (v2), el SDK de Python (v2) o Estudio de Azure Machine Learning, no es necesario obtener manualmente el token de Microsoft Entra. En su lugar, durante el inicio de sesión, su identidad de usuario ya se autenticaría, el token se recuperaría automáticamente y se le pasaría.

Es posible recuperar el token de Microsoft Entra para operaciones de plano de control desde el punto de conexión de recursos de Azure: https://management.azure.com.

  1. Inicie sesión en Azure.

    az login

  2. Si desea usar una identidad específica, use el código siguiente para iniciar sesión con la identidad:

    az login --identity --username <identityId>

  3. Use este contexto para obtener el token.

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

(Opcional) comprobación del punto de conexión del recurso y el id. de cliente para el token de Microsoft Entra

Después de recuperar el token de Microsoft Entra, compruebe que el token sea para el punto de conexión correcto de recursos de Azure management.azure.com y el id. de cliente sea correcto decodificando el token a través de jwt.ms, que devolverá una respuesta JSON con la siguiente información:

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

Creación de un punto de conexión

En el ejemplo siguiente, se crea el punto de conexión con una identidad asignada por el sistema (SAI) como identidad del punto de conexión. El SAI es el tipo de identidad predeterminado de la identidad administrada para los puntos de conexión. Algunos roles básicos se asignan automáticamente para la SAI. Para obtener más información sobre la asignación de roles para una identidad asignada por el sistema, consulte Asignación automática de roles para la identidad del punto de conexión.

La CLI no requiere que proporcione explícitamente el token del plano de control. En su lugar, la CLI le autentica durante el inicio de sesión y el token se recupera y se pasa automáticamente.

  1. Cree un archivo YAML de definición de punto de conexión.

    endpoint.yml:

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

  2. Reemplace auth_mode por key para la autenticación de claves, o bien aml_token para la autenticación de tokens de Azure Machine Learning. En este ejemplo, usará aad_token para la autenticación de tokens de Microsoft Entra.

    az ml online-endpoint create -f endpoint.yml

  3. Compruebe el estado del punto de conexión:

    az ml online-endpoint show -n my-endpoint

  4. Si desea invalidar auth_mode (por ejemplo, para aad_token) al crear un punto de conexión, ejecute el código siguiente:

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

  5. Si desea actualizar el punto de conexión existente y especificar auth_mode (por ejemplo, para aad_token), ejecute el código siguiente:

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

de una implementación

Para crear una implementación, consulte Implementación de un modelo de ML con un punto de conexión en línea o Uso de REST para implementar modelos como puntos de conexión en línea. No hay ninguna diferencia en cómo se crean implementaciones para distintos modos de autenticación.

El siguiente código es un ejemplo de cómo crear una implementación. Para obtener más información sobre la implementación de puntos de conexión en línea, consulte Implementación de modelos de ML con puntos de conexión en línea (a través de la CLI)

  1. Creación de un archivo YAML de definición de implementación.

    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. Cree la implementación mediante el archivo YAML. En este ejemplo, establezca todo el tráfico en la nueva implementación.

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

Obtención del URI de puntuación para el punto de conexión

Si tiene previsto usar la CLI para invocar el punto de conexión, no es necesario obtener explícitamente el URI de puntuación, ya que la CLI lo controla por usted. Sin embargo, aún podría usar la CLI para obtener el URI de puntuación y usarlo con otros canales, como la API de REST.

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

Obtención de la clave o token para operaciones de plano de datos

Se puede usar una clave o token para las operaciones de plano de datos, aunque el proceso de obtención de la clave o el token sea una operación de plano de control. En otras palabras, se usa un token de plano de control para obtener la clave o el token que, posteriormente, se usará para realizar las operaciones de plano de datos.

La obtención de la clave o token de Azure Machine Learning requiere que el rol correcto se asigne a la identidad de usuario que lo solicite, tal y como se describe en Autorización para operaciones de plano de control. La identidad de usuario no necesita ningún rol adicional para obtener el token de Microsoft Entra.

Clave o token de Azure Machine Learning

Si tiene previsto usar la CLI para invocar el punto de conexión, y en caso de que el punto de conexión esté configurado para usar un modo de autenticación de clave o token de Azure Machine Learning (aml_token), no es necesario obtener explícitamente el token de plano de datos, ya que la CLI la controla por usted. Sin embargo, aún podría usar la CLI para obtener el token de plano de datos y usarlo con otros canales, como la API de REST.

Para obtener la clave o el token de Azure Machine Learning (aml_token), use el comando az ml online-endpoint get-credentials. Este comando devuelve un documento JSON que contiene la clave o el token de Azure Machine Learning.

Las claves se devuelven en los campos primaryKey y secondaryKey. En el ejemplo siguiente se muestra cómo usar el parámetro --query para devolver solo la clave principal:

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

Los tokens de Azure Machine Learning se devuelven en el campo accessToken:

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

Además, los campos expiryTimeUtc y refreshAfterTimeUtc contienen los tiempos de expiración y actualización del token.

Token de Microsoft Entra

Para obtener el token de Microsoft Entra (aad_token) mediante la CLI, use el comando az account get-access-token. Este comando devuelve un documento JSON que contiene el token de Microsoft Entra.

El token de Microsoft Entra se devuelve en el campo accessToken:

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

Nota:

  • La extensión ml de la CLI no admite la obtención del token de Microsoft Entra. Use az account get-access-token en su lugar, tal y como se describe en el código anterior.
  • El token para operaciones de plano de datos se recupera del punto de conexión de recursos de Azure ml.azure.com en lugar de management.azure.com, a diferencia del token para operaciones de plano de control.

Comprobación del punto de conexión del recurso y el id. de cliente para el token de Microsoft Entra

Después de obtener el token de Entra, compruebe que el token sea para el punto de conexión correcto de recursos de Azure ml.azure.com y el id. de cliente sea correcto decodificando el token a través de jwt.ms, que devolverá una respuesta JSON con la siguiente información:

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

Puntuación de datos mediante la clave o el token

Clave o token de Azure Machine Learning

Use az ml online-endpoint invoke para puntos de conexión con una clave o un token de Azure Machine Learning. La CLI controla la clave o el token de Azure Machine Learning automáticamente, por lo que no es necesario pasarla explícitamente.

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

Token de Microsoft Entra

No se admite el uso de az ml online-endpoint invoke para puntos de conexión con un token de Microsoft Entra. Use la API de REST en su lugar y use el URI de puntuación del punto de conexión para invocar el punto de conexión.

Registro y supervisión del tráfico

Para habilitar el registro de tráfico en la configuración de diagnóstico del punto de conexión, siga los pasos descritos en Habilitación o deshabilitación de registros.

Si la configuración de diagnóstico estuviera habilitada, compruebe la tabla AmlOnlineEndpointTrafficLogs para ver el modo de autenticación y la identidad del usuario.

Contenido relacionado