Autenticación y autorización para la API de Azure Time Series Insights

  • Artículo

Nota:

El servicio Time Series Insights (TSI) dejará de admitirse a partir de marzo de 2025. Considere la posibilidad de migrar los entornos de TSI existentes a soluciones alternativas lo antes posible. Para más información sobre la entrada en desuso y la migración, consulte nuestra documentación.

En función de las necesidades empresariales, es posible que la solución incluya una o varias aplicaciones cliente que se usan para interactuar con las APIdel entorno de Azure Time Series Insights. Azure Time Series Ideas realiza la autenticación mediante tokens de seguridad de Microsoft Entra basados en OAUTH 2.0. Para autenticar el cliente, tendrá que obtener un token de portador con los permisos correctos y pasarlo junto con las llamadas API. En este documento se describen varios métodos para obtener credenciales que puede usar para obtener un token de portador y autenticarse, incluido el uso de la identidad administrada y el registro de aplicaciones de Microsoft Entra.

Identidades administradas

En las secciones siguientes se describe cómo usar una identidad administrada de Microsoft Entra ID para acceder a la API de Azure Time Series Ideas. En Azure, las identidades administradas eliminan la necesidad de que los desarrolladores tengan que administrar credenciales al proporcionar una identidad para el recurso de Azure en Microsoft Entra ID y utilizarla para obtener tokens de Microsoft Entra. Estas son algunas de las ventajas de usar las identidades administradas:

  • No es necesario administrar credenciales. Las credenciales ni siquiera están accesible.
  • Puede usar identidades administradas para autenticarse en cualquier servicio de Azure que admita la autenticación de Microsoft Entra, incluido Azure Key Vault.
  • Las identidades administradas se pueden usar sin ningún costo adicional.

Para obtener más información sobre los dos tipos de identidades administradas, lea ¿Qué son las identidades administradas de recursos de Azure?

Puede usar identidades administradas desde:

  • Máquinas virtuales de Azure
  • Azure App Services
  • Azure Functions
  • Azure Container Instances
  • Y mucho más...

Vea Servicios de Azure que admiten identidades administradas para recursos de Azure para obtener la lista completa.

Registro de aplicaciones de Microsoft Entra

Se recomienda usar identidades administradas siempre que sea posible para que no sea necesario administrar las credenciales. Si la aplicación cliente no está hospedada en un servicio de Azure que admita identidades administradas, puede registrar la aplicación con un inquilino de Microsoft Entra. Al registrar la aplicación con el identificador de Entra de Microsoft, va a crear una configuración de identidad para la aplicación que le permita integrarse con el identificador de Microsoft Entra. Cuando registra una aplicación en Azure Portal, elige si es de un solo inquilino (solo accesible en el inquilino) o multiinquilino (accesible en otros inquilinos) y, opcionalmente, puede establecer un identificador URI de redirección (al que se envía el token de acceso).

Una vez completado el registro de la aplicación, tiene una instancia globalmente única de la aplicación (el objeto de aplicación) que reside en su directorio o inquilino principal. También tiene un identificador único global para la aplicación (el identificador de la aplicación o del cliente). En el portal, puede entonces agregar secretos o certificados y ámbitos para que la aplicación funcione, personalizar la marca de la aplicación en el cuadro de diálogo de inicio de sesión y mucho más.

Al registrar una aplicación en Azure Portal, se crean automáticamente un objeto de aplicación y un objeto de entidad de servicio en su inquilino principal. Si registra o crea una aplicación mediante las API de Microsoft Graph, la creación del objeto de entidad de servicio se hace en un paso independiente. Para solicitar tokens se necesita un objeto de entidad de servicio.

Asegúrese de revisar la lista de comprobación de seguridad de la aplicación. Como procedimiento recomendado, debe usar credenciales de certificado, no de contraseña (secretos de cliente).

Consulte Objetos de aplicación y entidad de servicio en Microsoft Entra ID para obtener más detalles.

Paso 1: Creación de la identidad administrada o el registro de aplicación

Una vez que haya identificado si va a usar una identidad administrada o un registro de aplicación, el siguiente paso consiste en aprovisionarlo.

Identidad administrada

Los pasos que usará para crear una identidad administrada variarán en función de dónde se encuentre el código y de si se va a crear o no una identidad asignada por el usuario o por el sistema. Lea Tipos de identidad administrada para comprender la diferencia. Una vez que haya seleccionado el tipo de identidad, busque y siga el tutorial correcto en la documentación de identidades administradas de Microsoft Entra. Allí encontrará instrucciones sobre cómo configurar identidades administradas para:

Registro de la aplicación

Siga los pasos enumerados en Registro de una aplicación.

  • Después de seleccionar la plataforma adecuada en el paso 4 de Configuración de la plataforma, configure los valores de URI de redirección y Tokens de acceso en el panel lateral a la derecha de la interfaz de usuario.

    • El valor de URI de redirección debe coincidir con la dirección proporcionada en la solicitud de autenticación:

      • Si se trata de aplicaciones hospedadas en un entorno de desarrollo local, seleccione Cliente público (móvil y escritorio). Asegúrese de establecer el cliente público en Sí.
      • En el caso de aplicaciones de página única hospedadas en Azure App Service, seleccione Web.

    • Determine si procede agregar una URL de cierre de sesión.

    • Marque Tokens de acceso o Tokens de id. para habilitar el flujo de concesión implícita.

    Create Redirect URIs

    Haga clic en Configurar y, a continuación, en Guardar.

  • Asocie la aplicación Microsoft Entra Azure Time Series Ideas. Seleccione Permisos de API>Agregar un permiso>API usadas en mi organización.

    Associate an API with your Microsoft Entra app

    Escriba Azure Time Series Insights en la barra de búsqueda y, luego, seleccione Azure Time Series Insights.

  • A continuación, especifique el tipo de permiso de API que requiere la aplicación. De forma predeterminada, se resalta la opción Permisos delegados. Elija un tipo de permiso y, luego, seleccione Agregar permisos.

    Specify the kind of API permission your app requires

  • Agregue credenciales si la aplicación va a llamar a las API del entorno ella misma. Las credenciales permiten que la aplicación se autentique a sí misma, por lo que no se requiere la interacción del usuario en tiempo de ejecución.

Paso 2: Concesión de acceso

Cuando el entorno de Azure Time Series Insights recibe una solicitud, primero se valida el token de portador del autor de la llamada. Si la validación es correcta, el autor de la llamada se ha autenticado y, después, se realiza otra comprobación para asegurarse de que está autorizado para llevar a cabo la acción solicitada. Para autorizar a cualquier usuario o entidad de servicio, primero debe concederles acceso al entorno asignándoles el rol de lector o colaborador.

  • Para conceder acceso mediante la interfaz de usuario de Azure Portal, siga las instrucciones indicadas en el artículo Concesión de acceso a datos en un entorno. Al seleccionar el usuario, puede buscar la identidad administrada o el registro de aplicación por su nombre o por identificador.

  • Para conceder acceso mediante la CLI de Azure, ejecute el comando siguiente. Revise esta documentación a fin de obtener la lista completa de los comandos disponibles para administrar el acceso.

    az tsi access-policy create --name "ap1" --environment-name "env1" --description "some description" --principal-object-id "aGuid" --roles Reader Contributor --resource-group "rg1"

Nota:

La extensión timeseriesinsights para la CLI de Azure necesita la versión 2.11.0 o posterior. La extensión se instalará de forma automática la primera vez que ejecute un comando az tsi access-policy. Obtenga más información sobre las extensiones.

Paso 3: Solicitud de tokens

Una vez que el registro de aplicación o la identidad administrada se haya aprovisionado y se le haya asignado un rol, está listo para empezar a usarlo a fin de solicitar tokens de portador de OAuth 2.0. El método que use para obtener un token variará en función de dónde se hospede el código y del lenguaje que elija. Al especificar el recurso (también conocido como "audiencia" del token), puede identificar Azure Time Series Insights por su dirección URL o GUID:

  • https://api.timeseries.azure.com/
  • 120d688d-1518-4cf7-bd38-182f158850b6

Importante

Si usa la dirección URL como el identificador de recurso, el token se debe emitir exactamente como https://api.timeseries.azure.com/. Se requiere la barra diagonal.

  • Por tanto, si usa Postman, AuthURL será: https://login.microsoftonline.com/microsoft.onmicrosoft.com/oauth2/authorize?scope=https://api.timeseries.azure.com//.default.
  • https://api.timeseries.azure.com/ es válido, pero https://api.timeseries.azure.com no.

Identidades administradas

Al acceder desde Azure App Service o Functions, siga las instrucciones de Obtención de tokens para recursos de Azure.

Para las aplicaciones y funciones de .NET, la manera más sencilla de trabajar con una identidad administrada es mediante la biblioteca cliente Azure Identity para .NET. Esta biblioteca cliente es popular debido a su simplicidad y beneficios de seguridad. Los desarrolladores pueden escribir código una vez y dejar que la biblioteca cliente determine cómo realizar la autenticación en función del entorno de la aplicación, ya sea en una estación de trabajo de desarrollador mediante una cuenta de desarrollador, o bien implementada en Azure con una identidad de servicio administrada. Para obtener instrucciones sobre la migración de la biblioteca AppAuthentication anterior, lea Instrucciones de migración de AppAuthentication a Azure.Identity.

Solicite un token para Azure Time Series Insights mediante C# y la biblioteca cliente Azure Identity para .NET:

using Azure.Identity;
// ...
var credential = new DefaultAzureCredential();
var token = credential.GetToken(
new Azure.Core.TokenRequestContext(
    new[] { "https://api.timeseries.azure.com/" }));
var accessToken = token.Token;

Registro de aplicación

MSAL se puede utilizar en muchos escenarios de aplicación, incluidos los siguientes (entre otros):

Para obtener un ejemplo de código de C# en el que se muestra cómo adquirir un token como un registro de aplicación y consultar datos de un entorno Gen2, vea la aplicación de ejemplo en GitHub.

Importante

Si usa la Biblioteca de autenticación de Azure Active Directory (ADAL), realice la migración a MSAL.

Parámetros y encabezados comunes

En esta sección, se describen los encabezados y parámetros comunes de la solicitud HTTP que se usan para realizar consultas frente a las API de Azure Time Series Insights Gen1 y Gen2. Los requisitos específicos de las API se describen con mayor detalle en la documentación de referencia de la API de REST de Azure Time Series Insights.

Sugerencia

Lea la Referencia de la API de REST de Azure para obtener más información sobre cómo usar las API de REST, realizar solicitudes HTTP y manipular las respuestas HTTP.

Encabezados HTTP

A continuación se describen los encabezados de solicitud obligatorios.

Encabezado de solicitud obligatorio Descripción
Authorization Para realizar la autenticación en Azure Time Series Insights, es necesario pasar un token de portador de OAuth 2.0 válido en el encabezado de autorización.

Sugerencia

Lea la visualización de muestra del SDK de cliente hospedado de Azure Time Series Insights para aprender a autenticarse con las API de Azure Time Series Insights mediante programación, usando el SDK de cliente de JavaScript junto con gráficos.

A continuación se describen los encabezados de solicitud opcionales.

Encabezado de solicitud opcional Descripción
Content-type Solo se admite application/json.
x-ms-client-request-id Un id. de solicitud de cliente. El servicio registra este valor. Permite que el servicio realice el seguimiento de la operación en todos los servicios.
x-ms-client-session-id Un id. de sesión de cliente. El servicio registra este valor. Permite que el servicio realice el seguimiento de un grupo de operaciones relacionadas en todos los servicios.
x-ms-client-application-name Nombre de la aplicación que generó esta solicitud. El servicio registra este valor.

A continuación se describen los encabezados de respuesta opcionales, pero recomendados.

Encabezado de respuesta Descripción
Content-type Solo se admite application/json.
x-ms-request-id Id. de solicitud que creó el servidor. Se puede usar para ponerse en contacto con Microsoft para investigar una solicitud.
x-ms-property-not-found-behavior Encabezado de respuesta opcional de la API GA. Los valores posibles son ThrowError (valor predeterminado) o UseNull.

Parámetros de HTTP

Sugerencia

Encontrará más detalles sobre la información de consulta necesaria y opcional en la documentación de referencia.

Los parámetros de la cadena de consulta de la URL obligatorios dependen de la versión de la API.

Release Valores de versión de API
Gen1 api-version=2016-12-12
Gen2 api-version=2020-07-31

Los parámetros de cadena de consulta de dirección URL opcionales incluyen establecer un tiempo de espera para los tiempos de ejecución de la solicitud HTTP.

Parámetro de consulta opcional Descripción Versión
timeout=<timeout> Tiempo de espera del lado servidor para la ejecución de la solicitud. Esto es aplicable solo a las API Get Environment Events y Get Environment Aggregates. El valor del tiempo de espera debe estar en un formato de duración de tipo ISO 8601, por ejemplo "PT20S", y debe estar en el intervalo 1-30 s. El valor predeterminado es 30 s. Gen1
storeType=<storeType> En el caso de los entornos de Gen2 con almacenamiento intermedio habilitado, la consulta se puede ejecutar en WarmStore o ColdStore. Este parámetro de la consulta define en qué almacén debe ejecutarse la consulta. Si no se define, la consulta se ejecutará en el almacén frío. Para consultar la tienda en caliente, storeType debe establecerse en WarmStore. Si no se define, la consulta se ejecutará en el almacén frío. Gen2

Pasos siguientes