Acceso a la API de Azure Monitor Log Analytics

Artículo
11/05/2024

Puede enviar una solicitud de consulta a un área de trabajo mediante el punto de conexión https://api.loganalytics.azure.com de Log Analytics de Azure Monitor. Para acceder al punto de conexión, debe autenticarse a través de Microsoft Entra ID.

Nota:

El api.loganalytics.io punto de conexión se va a reemplazar por api.loganalytics.azure.com. El punto de conexión api.loganalytics.io seguirá siendo compatible en el futuro cercano.

Autenticación con una clave de API de demostración

Para explorar rápidamente la API sin la autenticación de Microsoft Entra, use el área de trabajo de demostración con datos de ejemplo, que admite la autenticación con clave de API.

Para autenticar y ejecutar consultas en el área de trabajo de ejemplo, use DEMO_WORKSPACE como {workspace-id} y pase la clave de API DEMO_KEY.

Si el Id. de aplicación o la clave de API son incorrectos, el servicio de API devolverá un error 403 (prohibido).

La clave de API DEMO_KEY se puede pasar de tres maneras diferentes, dependiendo de si quiere usar un encabezado, la dirección URL o la autenticación básica:

Encabezado personalizado: Proporcione la clave de API en el encabezado X-Api-Key personalizado.
Parámetro de consulta: Proporcione la clave de API en el parámetro de dirección URL api_key.
Autenticación básica: Proporcione la clave de API como nombre de usuario o contraseña. Si proporciona ambos, la clave de API debe estar en el nombre de usuario.

En este ejemplo se usa el Id. del área de trabajo y la clave de API en el encabezado:

    POST https://api.loganalytics.azure.com/v1/workspaces/DEMO_WORKSPACE/query
    X-Api-Key: DEMO_KEY
    Content-Type: application/json
    
    {
        "query": "AzureActivity | summarize count() by Category"
    }

Punto de conexión de API pública

El punto de conexión de API pública es:

    https://api.loganalytics.azure.com/{api-version}/workspaces/{workspaceId}

donde:

api-version: la versión API. La versión actual es "v1".
workspaceId: Id. del área de trabajo.

La consulta se pasa en el cuerpo de la solicitud.

Por ejemplo:

   https://api.loganalytics.azure.com/v1/workspaces/1234abcd-def89-765a-9abc-def1234abcde
   
   Body:
   {
       "query": "Usage"
   }

Configuración de la autenticación

Para acceder a la API, registre una aplicación cliente en Microsoft Entra ID y solicite un token.

Registre una aplicación en Microsoft Entra ID.
En la página de información general de la aplicación, seleccione Permisos de API.
Seleccione Agregar un permiso.
En la pestaña API que mi organización usa, busque Log Analytics y seleccione API de Log Analytics de la lista.
Seleccione Permisos delegados.
Seleccione la casilla Data.Read.
Seleccione Agregar permisos.

Ahora que la aplicación está registrada y tiene permisos para usar la API, concédale acceso al área de trabajo de Log Analytics.

En la página de información general del área de trabajo de Log Analytics, seleccione Control de acceso (IAM).
Seleccione Agregar asignación de roles.
Seleccione el rol Lector y, a continuación, seleccione Miembros.
En la pestaña Miembros, elija Seleccionar miembros.
Escriba el nombre de la aplicación en el cuadro Seleccionar.
Seleccione la aplicación y elija Seleccionar.
Seleccione Revisar y asignar.
Después de finalizar la configuración de Active Directory y los permisos del área de trabajo, solicite un token de autorización.

Nota

En este ejemplo, hemos aplicado el rol Lector. Este rol es uno de los muchos roles integrados y puede incluir más permisos de los que necesita. Se pueden crear roles y permisos más granulares. Para obtener más información, consulte Administración del acceso a las áreas de trabajo de Log Analytics.

Solicitud de un token de autorización

Antes de comenzar, asegúrese de que tiene todos los valores necesarios para realizar la solicitud correctamente. Todas las solicitudes requieren:

Identificador del inquilino de Microsoft Entra.
Id. del área de trabajo.
Identificador del cliente de Microsoft Entra para la aplicación.
Secreto de cliente de Microsoft Entra para la aplicación.

La API de Log Analytics admite la autenticación de Microsoft Entra con tres flujos de OAuth2 de Microsoft Entra ID diferentes:

Credenciales de cliente
Código de autorización
Implícita

Flujo de credenciales de cliente

En el flujo de credenciales de cliente, el token se usa con el punto de conexión de Log Analytics. Se realiza una única solicitud para recibir un token con las credenciales proporcionadas para la aplicación en el paso anterior, cuando registró la aplicación en Microsoft Entra ID.

Use resource=https://api.loganalytics.azure.com.

Obtenga un token de autenticación mediante cualquiera de los siguientes métodos:

CLI
REST API
SDK

Al solicitar un token, debe proporcionar un parámetro resource. El parámetro resource es la dirección URL del recurso al que desea acceder.

Los recursos incluyen:

https://management.azure.com
https://api.loganalytics.io
https://monitoring.azure.com

Obtención de un token mediante una solicitud de REST

Use la siguiente llamada a la API de REST para obtener un token. Esta solicitud usa un identificador de cliente y un secreto de cliente para autenticar la solicitud. El identificador de cliente y el secreto de cliente se obtienen al registrar la aplicación con Microsoft Entra ID. Para obtener más información, consulte Registro de una aplicación para solicitar tokens de autorización y trabajar con API

curl -X POST 'https://login.microsoftonline.com/<tennant ID>/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<your apps client ID>' \
--data-urlencode 'client_secret=<your apps client secret' \
--data-urlencode 'resource=https://monitoring.azure.com'

El cuerpo de la respuesta aparece en el formato siguiente:

{
    "token_type": "Bearer",
    "expires_in": "86399",
    "ext_expires_in": "86399",
    "expires_on": "1672826207",
    "not_before": "1672739507",
    "resource": "https://monitoring.azure.com",
    "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}

Obtención de un token mediante la CLI de Azure

Para obtener un token mediante la CLI, puede usar el siguiente comando

az account get-access-token

Para obtener más información, consulte az account get-access-token

Obtención de un token mediante los SDK

Los siguientes ejemplos de código muestran cómo obtener un token mediante:

C#
NodeJS
Python

C#

En el siguiente código se muestra cómo obtener un token mediante Azure. La biblioteca de identidades requiere un identificador de cliente y un secreto de cliente para autenticar la solicitud.

var context = new AuthenticationContext("https://login.microsoftonline.com/<tennant ID>");
var clientCredential = new ClientCredential("<your apps client ID>", "<your apps client secret>");
var result = context.AcquireTokenAsync("https://monitoring.azure.com", clientCredential).Result;

Como alternativa, puede usar la clase DefaultAzureCredential para obtener un token. Este método usa las credenciales predeterminadas de Azure para autenticar la solicitud y no requiere un identificador de cliente ni un secreto de cliente.

var credential = new DefaultAzureCredential();
var token = credential.GetToken(new TokenRequestContext(new[] { "https://management.azure.com/.default" }));

También puede especificar las credenciales de identidad administrada o entidad de servicio de la siguiente manera:

string userAssignedClientId = "<your managed identity client ID>";
var credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ManagedIdentityClientId = userAssignedClientId
    });

var token = credential.GetToken(new TokenRequestContext(new[] { "https://management.azure.com/.default" }));

Para obtener más información, consulte Clase DefaultAzureCredential

Node.js

Para obtener información sobre la autenticación mediante JavaScript y NodeJS, consulte Autenticación de aplicaciones JavaScript en servicios de Azure mediante el SDK de Azure para JavaScript

En el siguiente código se muestra cómo obtener un token mediante la clase DefaultAzureCredential. Este método usa las credenciales predeterminadas de Azure para autenticar la solicitud y no requiere un identificador de cliente ni un secreto de cliente.

const { DefaultAzureCredential } = require("@azure/identity");

const credential = new DefaultAzureCredential();
const accessToken = await credential.getToken("https://management.azure.com/.default");

También puede usar la clase InteractiveBrowserCredential para obtener las credenciales. Este método proporciona una experiencia de autenticación basada en explorador para que los usuarios se autentiquen con los servicios de Azure.

Para obtener más información, consulte clase DefaultAzureCredential y Clase InteractiveBrowserCredential

Como alternativa, puede usar la clase ClientSecretCredential para obtener un token. Este método requiere un identificador de cliente y un secreto de cliente para autenticar la solicitud.

const { ClientSecretCredential } = require("@azure/identity");
credential = ClientSecretCredential(
    client_id="<client_id>",
    username="<username>",
    password="<password>"
   )
const accessToken = await credential.getToken("https://management.azure.com/.default");

Para obtener más información, consulte Clase ClientSecretCredential

Python

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token('https://management.azure.com/.default')
print(token.token)

Para obtener más información, consulte clase DefaultAzureCredential y Clase InteractiveBrowserCredential

Como alternativa, puede usar la clase ClientSecretCredential para obtener un token. Este método requiere un identificador de cliente y un secreto de cliente para autenticar la solicitud.

from azure.identity import ClientSecretCredential

credential = ClientSecretCredential (
     tenant_id="<tenant id>",
     client_id="<Client id>",
     client_secret="client secret"
    )
token =  credential.get_token("https://management.azure.com/.default")
print(token.token)

Para obtener más información, consulte Clase ClientSecretCredential

Use el token en las solicitudes al punto de conexión de Log Analytics:

    POST /v1/workspaces/your workspace id/query?timespan=P1D
    Host: https://api.loganalytics.azure.com
    Content-Type: application/json
    Authorization: Bearer <your access token>

    Body:
    {
    "query": "AzureActivity |summarize count() by Category"
    }

Respuesta de ejemplo:

    {
        "tables": [
            {
                "name": "PrimaryResult",
                "columns": [
                    {
                        "name": "OperationName",
                        "type": "string"
                    },
                    {
                        "name": "Level",
                        "type": "string"
                    },
                    {
                        "name": "ActivityStatus",
                        "type": "string"
                    }
                ],
                "rows": [
                    [
                        "Metric Alert",
                        "Informational",
                        "Resolved",
                        ...
                    ],
                    ...
                ]
            },
            ...
        ]
    }

Flujo del código de autorización

El flujo principal de OAuth2 admitido es a través de códigos de autorización. Este método requiere dos solicitudes HTTP para adquirir un token con el que llamar a la API de Azure Monitor Log Analytics. Hay dos direcciones URL, con un punto de conexión por solicitud. Los formatos se describen en las secciones siguientes.

Dirección URL del código de autorización (solicitud GET)

    GET https://login.microsoftonline.com/YOUR_Azure AD_TENANT/oauth2/authorize?
    client_id=<app-client-id>
    &response_type=code
    &redirect_uri=<app-redirect-uri>
    &resource=https://api.loganalytics.io

Al enviar una solicitud a la dirección URL de autorización, client_id es el id. de la aplicación de Microsoft Entra, copiado del menú de propiedades de la aplicación. redirect_uri es la dirección URL de la página principal o de inicio de sesión de la misma aplicación de Microsoft Entra. Cuando una solicitud se realiza correctamente, este punto de conexión le redirige a la página de inicio de sesión que proporcionó en el registro con el código de autorización anexado a la dirección URL. Observe el ejemplo siguiente:

    http://<app-client-id>/?code=AUTHORIZATION_CODE&session_state=STATE_GUID

En este momento, habrá obtenido un código de autorización, que ahora debe solicitar un token de acceso.

Dirección URL del token de código de autorización (solicitud POST)

    POST /YOUR_Azure AD_TENANT/oauth2/token HTTP/1.1
    Host: https://login.microsoftonline.com
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=authorization_code
    &client_id=<app client id>
    &code=<auth code fom GET request>
    &redirect_uri=<app-client-id>
    &resource=https://api.loganalytics.io
    &client_secret=<app-client-secret>

Todos los valores son los mismos que antes, con algunas adiciones. El código de autorización es el mismo código que recibió en la solicitud anterior después de un redireccionamiento correcto. El código se combina con la clave obtenida de la aplicación de Microsoft Entra. Si no ha guardado la clave, puede eliminarla y crear una nueva desde la pestaña de claves del menú de la aplicación de Microsoft Entra. La respuesta es una cadena JSON que contiene el token con el esquema siguiente. Los tipos se indican para los valores del token.

Ejemplo de respuesta:

    {
        "access_token": "eyJ0eXAiOiJKV1QiLCJ.....Ax",
        "expires_in": "3600",
        "ext_expires_in": "1503641912",
        "id_token": "not_needed_for_log_analytics",
        "not_before": "1503638012",
        "refresh_token": "eyJ0esdfiJKV1ljhgYF.....Az",
        "resource": "https://api.loganalytics.io",
        "scope": "Data.Read",
        "token_type": "bearer"
    }

La parte del token de acceso de esta respuesta es la que se presenta a la API de Log Analytics en el encabezado Authorization: Bearer. También puede usar el token de actualización en el futuro para adquirir un nuevo access_token y refresh_token cuando el suyo haya quedado obsoleto. Para esta solicitud, el formato y el punto de conexión son:

    POST /YOUR_AAD_TENANT/oauth2/token HTTP/1.1
    Host: https://login.microsoftonline.com
    Content-Type: application/x-www-form-urlencoded
    
    client_id=<app-client-id>
    &refresh_token=<refresh-token>
    &grant_type=refresh_token
    &resource=https://api.loganalytics.io
    &client_secret=<app-client-secret>

Ejemplo de respuesta:

    {
      "token_type": "Bearer",
      "expires_in": "3600",
      "expires_on": "1460404526",
      "resource": "https://api.loganalytics.io",
      "access_token": "eyJ0eXAiOiJKV1QiLCJ.....Ax",
      "refresh_token": "eyJ0esdfiJKV1ljhgYF.....Az"
    }

Flujo de código implícito

La API de análisis de registros admite el flujo implícito de OAuth2. Para este flujo, solo se requiere una única solicitud, pero no se puede adquirir ningún token de actualización.

Dirección URL implícita de autorización de código

    GET https://login.microsoftonline.com/YOUR_AAD_TENANT/oauth2/authorize?
    client_id=<app-client-id>
    &response_type=token
    &redirect_uri=<app-redirect-uri>
    &resource=https://api.loganalytics.io

Una solicitud correcta producirá un redireccionamiento al URI de redirección con el token en la dirección URL:

    http://YOUR_REDIRECT_URI/#access_token=YOUR_ACCESS_TOKEN&token_type=Bearer&expires_in=3600&session_state=STATE_GUID

Este access_token se puede usar como valor de encabezado Authorization: Bearer cuando se pasa a la API de Log Analytics para autorizar las solicitudes.

Más información

Puede consultar documentación sobre OAuth2 con Microsoft Entra aquí:

Compartir a través de