Compartir a través de

Acceso de asociados a través de api de Microsoft Defender para punto de conexión

  • Artículo

Se aplica a:

Importante

Las funcionalidades avanzadas de búsqueda no se incluyen en Defender para Empresas.

¿Quiere experimentar Microsoft Defender para punto de conexión? Regístrese para obtener una prueba gratuita.

Nota:

Si es cliente del Gobierno de EE. UU., use los URI que aparecen en Microsoft Defender para punto de conexión para los clientes del Gobierno de EE. UU.

Sugerencia

Para mejorar el rendimiento, puede usar el servidor más cercano a la ubicación geográfica:

  • us.api.security.microsoft.com
  • eu.api.security.microsoft.com
  • uk.api.security.microsoft.com
  • au.api.security.microsoft.com
  • swa.api.security.microsoft.com
  • ina.api.security.microsoft.com

En esta página se describe cómo crear una aplicación de Microsoft Entra para obtener acceso mediante programación a Microsoft Defender para punto de conexión en nombre de los clientes.

Microsoft Defender para punto de conexión expone gran parte de sus datos y acciones a través de un conjunto de API mediante programación. Esas API le ayudan a automatizar los flujos de trabajo e innovar en función de las capacidades de Microsoft Defender para punto de conexión. El acceso a la API requiere la autenticación de OAuth2.0. Para obtener más información, vea Flujo de código de autorización de OAuth 2.0.

En general, debe realizar los pasos siguientes para usar las API:

  1. Cree una aplicación de Microsoft Entra multiinquilino.

  2. Obtenga autorización (consentimiento) por parte del administrador del cliente para que la aplicación acceda a los recursos de Defender para punto de conexión que necesita.

  3. Obtenga un token de acceso mediante esta aplicación.

  4. Use el token para acceder a Microsoft Defender para punto de conexión API.

Los pasos siguientes le guían sobre cómo crear una aplicación Microsoft Entra, obtener un token de acceso para Microsoft Defender para punto de conexión y validar el token.

Importante

Microsoft recomienda utilizar roles con la menor cantidad de permisos. Esto ayuda a mejorar la seguridad de la organización. Administrador global es un rol con muchos privilegios que debe limitarse a escenarios de emergencia cuando no se puede usar un rol existente.

Creación de la aplicación multiinquilino

  1. Inicie sesión en el inquilino de Azure.

  2. Vaya a Microsoft Entra ID>Registros de aplicaciones>Nuevo registro.

    Panel de navegación al registro de aplicaciones

  3. En el formulario de registro:

    • Elija un nombre para la aplicación.

    • Tipos de cuenta admitidos: cuentas en cualquier directorio organizativo.

    • URI de redirección: tipo: Web, URI: https://portal.azure.com

      Página de registro de aplicaciones asociadas de Microsoft Azure

  4. Permita que la aplicación acceda a Microsoft Defender para punto de conexión y asígnela con el conjunto mínimo de permisos necesarios para completar la integración.

    • En la página de la aplicación, seleccione Permisos> de APIAgregar API de permisos>Que mi organización usa>, escriba WindowsDefenderATP y seleccione en WindowsDefenderATP.

    • WindowsDefenderATP no aparece en la lista original. Empiece a escribir su nombre en el cuadro de texto para verlo aparecer.

      La opción Agregar un permiso

Solicitar permisos de API

Para determinar qué permiso necesita, revise la sección Permisos de la API a la que desea llamar. Por ejemplo:

En el ejemplo siguiente se usa el permiso Leer todas las alertas :

  1. Elija Permisos> de aplicaciónAlert.Read.All> seleccione Agregar permisos.

    La opción que permite agregar un permiso

  2. Seleccione Conceder consentimiento

    • Cada vez que agregue permiso, debe seleccionar en Conceder consentimiento para que el nuevo permiso surta efecto.

    La opción que permite conceder el consentimiento

  3. Agregue un secreto a la aplicación.

    • Seleccione Certificados & secretos, agregue una descripción al secreto y seleccione Agregar.

    Después de seleccionar Agregar, asegúrese de copiar el valor de secreto generado. ¡No podrás recuperarlo después de irte!

    La clave de creación de la aplicación

  4. Anote el identificador de la aplicación:

    • En la página de la aplicación, vaya a Información general y copie la siguiente información:

      Identificador de la aplicación de creación

  5. Agregue la aplicación al inquilino del cliente.

    Necesita que la aplicación se apruebe en cada inquilino de cliente en el que quiera usarlo. Esta aprobación es necesaria porque la aplicación interactúa con Microsoft Defender para punto de conexión aplicación en nombre del cliente.

    Una cuenta de usuario con los permisos adecuados para el inquilino del cliente debe seleccionar el vínculo de consentimiento y aprobar la aplicación.

    El vínculo de consentimiento tiene el siguiente formato:

    https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true

    Donde 00000000-0000-0000-0000-000000000000 se debe reemplazar por el identificador de aplicación.

    Después de seleccionar el vínculo de consentimiento, inicie sesión en el inquilino del cliente y, a continuación, conceda el consentimiento para la aplicación.

    Botón Aceptar

    Además, tendrá que pedir al cliente su identificador de inquilino y guardarlo para su uso futuro al adquirir el token.

  6. ¡Listo! ¡Ha registrado correctamente una aplicación! Consulte los ejemplos siguientes para la adquisición y validación de tokens.

Obtener un ejemplo de token de acceso

Para obtener el token de acceso en nombre del cliente, use el identificador de inquilino del cliente en las siguientes adquisiciones de tokens.

Para obtener más información sobre Microsoft Entra token, consulte Microsoft Entra tutorial.

Con PowerShell

# That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
# Paste below your Tenant ID, App ID and App Secret (App key).

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application key here

$resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$authBody = [Ordered] @{
    resource = "$resourceAppIdUri"
    client_id = "$appId"
    client_secret = "$appSecret"
    grant_type = 'client_credentials'
}
$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token
Out-File -FilePath "./Latest-token.txt" -InputObject $token
return $token

Uso de C#

Importante

El paquete NuGet Microsoft.IdentityModel.Clients.ActiveDirectory y Autenticación de Azure AD Library (ADAL) han quedado en desuso. No se han agregado nuevas características desde el 30 de junio de 2020. Para actualizar, consulte la guía de migración.

  1. Cree una nueva aplicación de consola.

  2. Instale NuGet Microsoft.Identity.Client.

  3. Agregue lo siguiente mediante código:

     using Microsoft.Identity.Client;

    Este código se ha probado con NuGet Microsoft.Identity.Client.

  4. Copie o pegue el código siguiente en la aplicación (no olvide actualizar las tres variables: tenantId, appIdy appSecret).

    string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
string appId = "11111111-1111-1111-1111-111111111111"; // Paste your own app ID here
string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here for a test, and then store it in a safe place! 
const string authority = https://login.microsoftonline.com;
const string audience = https://api.securitycenter.microsoft.com;

IConfidentialClientApplication myApp = ConfidentialClientApplicationBuilder.Create(appId).WithClientSecret(appSecret).WithAuthority($"{authority}/{tenantId}").Build();

List<string> scopes = new List<string>() { $"{audience}/.default" };

AuthenticationResult authResult = myApp.AcquireTokenForClient(scopes).ExecuteAsync().GetAwaiter().GetResult();

string token = authResult.AccessToken;

Uso de Python

Consulte Obtención de token mediante Python.

Uso de Curl

Nota:

El siguiente procedimiento supone que Curl para Windows ya está instalado en el equipo.

  1. Abra una ventana de comandos.

  2. Establezca en CLIENT_ID el identificador de la aplicación de Azure.

  3. Establezca en CLIENT_SECRET el secreto de aplicación de Azure.

  4. Establezca TENANT_ID en el identificador de inquilino de Azure del cliente que quiere usar la aplicación para acceder a Microsoft Defender para punto de conexión aplicación.

  5. Ejecute el siguiente comando:

    curl -i -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=%CLIENT_ID%" -d "scope=https://securitycenter.onmicrosoft.com/windowsatpservice/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k

    Obtiene una respuesta similar al siguiente fragmento de código:

    {"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}

Validar el token

Confirme que ha recibido un token correcto.

  1. Copie o pegue en JWT el token que obtiene en el paso anterior para descodificarlo.

  2. Confirme que obtiene una notificación de roles con los permisos adecuados.

    En la captura de pantalla siguiente, puede ver un token descodificado adquirido de una aplicación con varios permisos para Microsoft Defender para punto de conexión:

    Página de validación de tokens

    La notificación "tid" es el identificador de inquilino al que pertenece el token.

Uso del token para acceder a Microsoft Defender para punto de conexión API

  1. Elija la API que desea usar. Para obtener más información, consulte API de Microsoft Defender para punto de conexión admitidas.

  2. Establezca el encabezado Authorization en la solicitud Http a Bearer {token} la que envíe (Bearer es el esquema de autorización). La hora de expiración del token es de una hora (puede enviar más de una solicitud con el mismo token).

    Este es un ejemplo del envío de una solicitud para obtener una lista de alertas mediante C#:

    var httpClient = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.microsoft.com/api/alerts");

request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

var response = httpClient.SendAsync(request).GetAwaiter().GetResult();

 // Do something useful with the response

Recursos adicionales

Sugerencia

¿Desea obtener más información? Engage con la comunidad de seguridad de Microsoft en nuestra comunidad tecnológica: Microsoft Defender para punto de conexión Tech Community.