Acceso a Microsoft Defender for Cloud Apps con el contexto de la aplicación

Artículo
08/22/2024

En esta página se describe cómo crear una aplicación para obtener acceso mediante programación a Defender for Cloud Apps sin un usuario. Si necesitas acceso mediante programación a Defender for Cloud Apps en nombre de un usuario, consulta Obtener acceso con el contexto de usuario. Si no estás seguro de qué acceso necesitas, consulta la página Administración de tokens de API.

Microsoft Defender for Cloud Apps expone gran parte de tus datos y acciones a través de un conjunto de API mediante programación. Esas API le permiten automatizar flujos de trabajo e innovar en función de las funcionalidades de Defender for Cloud Apps. El acceso a la API requiere autenticación de OAuth2.0. Para obtener más información, consulta Flujo de códigos de autorización OAuth 2.0.

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

Crear una aplicación de Microsoft Entra.
Obtén un token de acceso mediante esta aplicación.
Utiliza el token para acceder a la API de Defender for Cloud Apps.

En este artículo se explica cómo crear una aplicación de Microsoft Entra, obtener un token de acceso a Microsoft Defender for Cloud Apps y validar el token.

Creación de una aplicación para Defender for Cloud Apps

En el Centro de administración de Microsoft Entra, registre una nueva aplicación. Para obtener más información, consulte Inicio rápido: Registro de una aplicación con el centro de administración de Microsoft Entra.
Para permitir que la aplicación acceda a Defender for Cloud Apps asignarle el permiso "Leer todas las alertas", en la página de la aplicación, selecciona Permisos de API>>Añadir permisos API que utiliza mi organización>, escribe Microsoft Cloud App Security y, a continuación, selecciona Microsoft Cloud App Security.

Nota:

Microsoft Cloud App Security no aparece en la lista original. Empieza a escribir tu nombre en el cuadro de texto para ver que aparece. Asegúrate de escribir este nombre, aunque el producto ahora se llame Defender for Cloud Apps.
- Seleccione Investigación de permisos>Investigation.Read y, a continuación, seleccione Agregar permisos.
  
  Debes seleccionar los permisos pertinentes. Investigation.Read es solo un ejemplo. Para ver otros ámbitos de permisos, consulta Ámbitos de permisos admitidos
  - Para determinar qué permiso necesitas, consulta la sección Permisos de la API a la que te interesa llamar.
Seleccione Conceder consentimiento de administrador.

Nota:

Cada vez que agregues un permiso, debes seleccionar Conceder consentimiento del administrador para que el nuevo permiso surta efecto.
Para agregar un secreto a la aplicación, selecciona Secretos & de certificados, Nuevo secreto de cliente, agrega una descripción al secreto y, a continuación, selecciona Agregar.

Nota:

Después de seleccionar Agregar, selecciona Copiar el valor del secreto generado. No podrás recuperar este valor después de salir.
Anota el identificador de aplicación y el identificador de inquilino. En la página de la aplicación, ve a Información general y copia el Id. de aplicación (cliente) y Id. de directorio (inquilino).
Solo para socios de Microsoft Defender for Cloud Apps. Establece la aplicación en multiinquilino (disponible en todos los inquilinos después del consentimiento). Esto es necesario para aplicaciones de terceros (por ejemplo, si creas una aplicación diseñada para ejecutarse en el inquilino de varios clientes). Esto no es necesario si creas un servicio que deseas ejecutar solo en el inquilino (por ejemplo, si creas una aplicación para tu propio uso que solo interactuará con tus propios datos). Para establecer que la aplicación sea multiinquilino:
- Ve a Autenticación y agrega https://portal.azure.com como URI de redirección.
- En la parte inferior de la página, en Tipos de cuenta admitidos, seleccione el consentimiento de aplicación Cuentas de cualquier directorio de la organización para la aplicación multiinquilino.
Necesitas que la aplicación se apruebe en cada inquilino donde quieras usarla. Esto se debe a que la aplicación interactúa con Defender for Cloud Apps en nombre del cliente.

Tú (o tu cliente si escribes una aplicación de terceros) debéis seleccionar el enlace de consentimiento y aprobar la aplicación. El consentimiento debe realizarse con un usuario que tenga privilegios administrativos en Active Directory.

El enlace de consentimiento se crea de la siguiente manera:
```
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 reemplaza por el identificador de aplicación.

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

Ámbitos de permisos admitidos

Nombre de permiso	Descripción	Acciones admitidas
Investigation.read	Realiza todas las acciones admitidas en actividades y alertas, excepto las alertas de cierre. Visualiza los intervalos IP, pero no agrega, actualiza ni elimina. Realiza todas las acciones de entidades.	Lista de actividades, captura, comentarios Lista de alertas, captura, marcar como leído/no leído Lista de entidades, captura, árbol de captura Lista de subredes
Investigation.manage	Realiza todas las acciones investigation.read además de administrar alertas e intervalos IP.	Lista de actividades, captura, comentarios Lista de alertas, captura, marcar como leído/no leído, cerrar Lista de entidades, captura, árbol de captura Lista de subredes, creación, actualización y eliminación
Discovery.read	Realiza todas las acciones admitidas en actividades y alertas, excepto las alertas de cierre. Enumera los informes y categorías de detección.	Lista de alertas, captura, marcar como leído/no leído Informes de lista de detección, categorías de informes de lista
Discovery.manage	Permisos Discovery.read Cierra las alertas, carga los archivos de detección y genera scripts de bloqueo	Lista de alertas, captura, marcar como leído/no leído, cerrar Informes de lista de detección, categorías de informes de lista Carga de archivos de detección, generación de script de bloque
Settings.read	Lista de intervalos IP.	Lista de subredes
Settings.manage	Enumera y administra intervalos IP.	Lista de subredes, creación, actualización y eliminación

Obtención de un token de acceso

Para obtener más información sobre los tokens de Microsoft Entra, consulta el tutorial de Microsoft Entra.

Uso de PowerShell

# This script acquires the App Context Token and stores it in the variable $token for later use in the script.
# Paste your Tenant ID, App ID, and App Secret (App key) into the indicated quotes below.

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

$resourceAppIdUri = '05a65629-4c1b-48c1-a78b-804c4abdd4af'
$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

Uso de C#

El código siguiente se probó con NuGet Microsoft.Identity.Client 4.47.2.

Cree una nueva aplicación de consola.
Instalar NuGet Microsoft.Identity.Client.
Agregue lo siguiente:
```
using Microsoft.Identity.Client;
```

Copia y pega el código siguiente en la aplicación (no olvides actualizar las tres variables: tenantId, appId, appSecret):

string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
string appId = "00001111-aaaa-2222-bbbb-3333cccc4444"; // 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 = "05a65629-4c1b-48c1-a78b-804c4abdd4af";

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

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

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

string token = authResult.AccessToken;

Uso de Python

Consulta Biblioteca de autenticación de Microsoft (MSAL) para Python.

Uso de Curl

Nota:

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

Abre un símbolo del sistema y establece CLIENT_ID en el identificador de aplicación de Azure.
Establece CLIENT_SECRET en el secreto de la aplicación de Azure.
Establece TENANT_ID en el identificador de inquilino de Azure del cliente que quiere usar la aplicación para acceder a Defender for Cloud Apps.
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=05a65629-4c1b-48c1-a78b-804c4abdd4af/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k

Obtendrá una respuesta de la siguiente forma:

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

Validar el token

Asegúrate de que tienes el token correcto:

Copia y pega el token obtenido en el paso anterior en JWT para descodificarlo.
Comprueba que obtengas una notificación de "roles" con los permisos deseados
En la imagen siguiente, puedes ver un token descodificado adquirido desde una aplicación con permisos para todos los roles de Microsoft Defender for Cloud Apps:

Captura de pantalla de la validación del token.

Uso del token para acceder a la API de Microsoft Defender for Cloud Apps

Elige el campo que deseas usar. Para obtener más información, consulta APIs de Defender for Cloud Apps.
Establece el encabezado de autorización en la solicitud http que envíes a "Bearer {token}" (Bearer es el esquema de autorización).
El tiempo de expiración del token es de una hora. Puedes enviar más de una solicitud con el mismo token.

A continuación se muestra un ejemplo de envío de una solicitud para obtener una lista de alertas mediante C#:

    var httpClient = new HttpClient();

    var request = new HttpRequestMessage(HttpMethod.Get, "https://portal.cloudappsecurity.com/cas/api/v1/alerts/");

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

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

    // Do something useful with the response

Consulte también

Administración de tokens de API

Compartir a través de