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

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 necesita acceso mediante programación a Defender for Cloud Apps en nombre de un usuario, consulte Obtener acceso con el contexto de usuario. Si no está seguro de qué acceso necesita, consulte la página Administración de tokens de API .

Microsoft Defender for Cloud Apps 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 Defender for Cloud Apps. 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:

• Cree una aplicación de Microsoft Entra.
• Obtenga un token de acceso mediante esta aplicación.
• Use el token para acceder a Defender for Cloud Apps API.

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

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

1. En el Centro de administración 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 Microsoft Entra.

2. Para permitir que la aplicación acceda a Defender for Cloud Apps y asígnele el permiso "Leer todas las alertas", en la página de la aplicación, seleccione Permisos> de API Agregar API depermisos>que usa> mi organización, escriba Microsoft Cloud App Security y, a continuación, seleccione Microsoft Cloud App Security.

   Nota:

   Microsoft Cloud App Security no aparece en la lista original. Empiece a escribir su nombre en el cuadro de texto para verlo aparecer. Asegúrese de escribir este nombre, aunque el producto se llame ahora Defender for Cloud Apps.

   

   • Seleccione Permisos> de aplicaciónInvestigation.Read y, a continuación, seleccione Agregar permisos.

     

     Debe seleccionar los permisos pertinentes. Investigation.Read es solo un ejemplo. Para ver otros ámbitos de permisos, consulte Ámbitos de permisos admitidos.

     • Para determinar qué permiso necesita, consulte la sección Permisos de la API a la que le interesa llamar.

3. Seleccione Conceder consentimiento de administrador.

   Nota:

   Cada vez que agregue un permiso, debe seleccionar Conceder consentimiento del administrador para que el nuevo permiso surta efecto.

   

4. Para agregar un secreto a la aplicación, seleccione Certificados & secretos, nuevo secreto de cliente, agregue una descripción al secreto y, a continuación, seleccione Agregar.

   Nota:

   Después de seleccionar Agregar, seleccione Copiar el valor de secreto generado. No podrá recuperar este valor después de salir.

   

5. Anote el identificador de la aplicación y el identificador de inquilino. En la página de la aplicación, vaya a Información general y copie el identificador de aplicación (cliente) y el identificador de directorio (inquilino).

   

6. Solo para asociados Microsoft Defender for Cloud Apps. Establezca la aplicación en multiinquilino (disponible en todos los inquilinos después del consentimiento). Esto es necesario para aplicaciones de terceros (por ejemplo, si crea una aplicación destinada a ejecutarse en el inquilino de varios clientes). Esto no es necesario si crea un servicio que solo desea ejecutar en el inquilino (por ejemplo, si crea una aplicación para su propio uso que solo interactuará con sus propios datos). Para establecer que la aplicación sea multiinquilino:

   • Vaya a Autenticación y agregue 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 la aplicación Cuentas en cualquier directorio organizativo para la aplicación multiinquilino.

   Necesita que la aplicación se apruebe en cada inquilino donde quiera usarla. Esto se debe a que la aplicación interactúa Defender for Cloud Apps en nombre del cliente.

   Usted (o el cliente si está escribiendo una aplicación de terceros) debe seleccionar el vínculo de consentimiento y aprobar la aplicación. El consentimiento debe realizarse con un usuario que tenga privilegios administrativos en Active Directory.

   El vínculo de consentimiento se forma 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 0000000000-0000-0000-0000-0000000000000 se reemplaza por el identificador de aplicación.

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

Ámbitos de permisos admitidos

Nombre del permiso	Descripción	Acciones admitidas
Investigation.read	Realice todas las acciones admitidas en las actividades y alertas excepto las alertas de cierre. Vea los intervalos IP, pero no agregue, actualice ni elimine. Realice todas las acciones de entidades.	Lista de actividades, captura y comentarios Lista de alertas, capturar, marcar como leído o no leído Lista de entidades, capturar, capturar árbol Lista de subredes
Investigation.manage	Realice todas las acciones de investigation.read además de administrar alertas e intervalos IP.	Lista de actividades, captura y comentarios Lista de alertas, capturar, marcar como leído/no leído, cerrar Lista de entidades, capturar, capturar árbol Lista de subredes, crear, actualizar o eliminar
Discovery.read	Realice todas las acciones admitidas en las actividades y alertas excepto las alertas de cierre. Enumera los informes y categorías de detección.	Lista de alertas, capturar, marcar como leído o no leído Informes de lista de detección, categorías de informes de lista
Discovery.manage	Permisos discovery.read Cerrar alertas, cargar archivos de detección y generar scripts de bloque	Lista de alertas, capturar, 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	Enumerar intervalos IP.	Lista de subredes
Settings.manage	Enumeración y administración de intervalos IP.	Lista de subredes, crear, actualizar o eliminar

Obtener un token de acceso

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

Usar 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 ha probado con NuGet Microsoft.Identity.Client 4.47.2.

1. Cree una nueva aplicación de consola.

2. Instale NuGet Microsoft.Identity.Client.

3. Agregue lo siguiente:

   using Microsoft.Identity.Client;
   

4. Copie y pegue el código siguiente en la aplicación (no olvide 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

Consulte 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.

1. Abra un símbolo del sistema y establezca CLIENT_ID en el identificador de aplicación de Azure.
2. Establezca CLIENT_SECRET en el secreto de aplicación de Azure.
3. Establezca TENANT_ID en el identificador de inquilino de Azure del cliente que quiere usar la aplicación para acceder a Defender for Cloud Apps.
4. 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

Obtiene una respuesta con el siguiente formato:

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

Validar el token

Asegúrese de que tiene el token correcto:

1. Copie y pegue el token que obtuvo en el paso anterior en JWT para descodificarlo.
2. Valide que obtiene una notificación de "roles" con los permisos deseados.
3. En la imagen siguiente, puede ver un token descodificado adquirido de una aplicación con permisos para todos los roles de Microsoft Defender for Cloud Apps:

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

1. Elija la API que desea usar. Para obtener más información, consulte API de Defender for Cloud Apps.
2. Establezca el encabezado de autorización en la solicitud http que envíe a "Bearer {token}" (Bearer es el esquema de autorización).
3. La hora de expiración del token es de una hora. Puede 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

Recursos adicionales

• Administración de tokens de API