Acceso a la API de Microsoft Defender for Cloud Apps con el contexto de usuario

En esta página se describe cómo crear una aplicación para obtener acceso mediante programación a Defender for Cloud Apps en nombre de un usuario.

Si necesitas acceso mediante programación a Microsoft Defender for Cloud Apps sin un usuario, consulta Acceso a Microsoft Defender for Cloud Apps con el contexto de la aplicación.

Si no estás seguro de qué acceso necesitas, lee la página Introducción.

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 permitirán automatizar flujos de trabajo e innovar en función de las funcionalidades de Microsoft 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:

• Creación de una aplicación de Microsoft Entra
• Obtención de un token de acceso mediante esta aplicación
• Utiliza el token para acceder a la API de Defender for Cloud Apps

En esta página 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.

Nota:

Al acceder a la API de Microsoft Defender for Cloud Apps en nombre de un usuario, necesitarás el permiso de aplicación y el permiso de usuario correctos. Si no estás familiarizado con los permisos de usuario en Microsoft Defender for Cloud Apps, consulta Administrar el acceso de administrador.

Sugerencia

Si tienes permiso para realizar una acción en el portal, tienes permiso para realizar la acción en la API.

Creación de una aplicación

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

2. Cuando aparezca la página Registrar una aplicación, introduzca la información de registro de su aplicación:

   • Nombre: escriba un nombre significativo para la aplicación, que se mostrará a los usuarios de la aplicación.

   • Tipos de cuentas compatibles: seleccione qué cuentas desea que admita la aplicación.

     Tipos de cuenta admitidos	Descripción
     Solo las cuentas de este directorio organizativo	Seleccione esta opción si va a crear una aplicación de línea de negocio (LOB). Esta opción no está disponible si no va a registrar la aplicación en un directorio. Esta opción se asigna a una cuenta para un solo inquilino de Microsoft Entra. Esta es la opción predeterminada a menos que registre la aplicación fuera de un directorio. En los casos en los que la aplicación se registra fuera de un directorio, el valor predeterminado son las cuentas personales de Microsoft y cuentas multiinquilino de Microsoft Entra.
     Cuentas en cualquier directorio organizativo	Seleccione esta opción si desea tener como destino todos los clientes de negocios y del sector educativo. Esta opción se asigna a un multiinquilino solo de Microsoft Entra. Si ha registrado la aplicación como solo para un único inquilino de Microsoft Entra, puede actualizarla para que sea de multiinquilino de Microsoft Entra y que vuelva a ser para un solo inquilino mediante el panel Autenticación.
     Cuentas en cualquier directorio organizativo y cuentas Microsoft personales	Seleccione esta opción para dirigirse al conjunto más amplio de clientes. Esta opción asigna cuentas personales de Microsoft y cuentas multiinquilinos de Microsoft Entra. Si registró la aplicación como cuentas multiinquilino de Microsoft Entra y cuentas personales de Microsoft, no puede cambiar esto en la interfaz de usuario. En su lugar, debe usar el editor de manifiesto de la aplicación para cambiar los tipos de cuenta admitidos.

   • URI de redirección (opcional): seleccione el tipo de aplicación que se va a crear, **Web o Cliente público (móvil y escritorio) y, a continuación, escriba el identificador URI de redireccionamiento (o la dirección URL de respuesta) para la aplicación.

     • Para aplicaciones web, proporcione la dirección URL base de la aplicación. Por ejemplo, http://localhost:31544 podría ser la dirección URL de una aplicación web que se ejecuta en la máquina local. Los usuarios utilizan esta dirección URL para iniciar sesión en una aplicación cliente web.
     • Para aplicaciones cliente públicas, proporciona el identificador URI que utiliza Microsoft Entra ID para devolver las respuestas de los tokens. Escriba un valor específico para la aplicación, como myapp://auth.

     Si desea ejemplos específicos de aplicaciones web o aplicaciones nativa, visite nuestras guías de inicio rápido.

     Cuando termine, seleccione Registrar.

3. Permitir que la aplicación acceda a Microsoft Defender for Cloud Apps y asígnale el permiso "Leer alertas":

   • En la página de la aplicación, selecciona Permisos de API>Agregar permisos> de API que usa 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.

     

   • Elija Permisos delegados>Investigation.Read> seleccione Agregar permisos

     

   • Nota importante: Selecciona 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.

   • Selecciona Conceder consentimiento de administrador

     Nota: Cada vez que agregues permisos, debes seleccionar Conceder consentimiento del administrador para que el nuevo permiso surta efecto.

     

4. 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 la siguiente información:

     

Á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

Con C#

• Copia o pega la siguiente clase en la aplicación.
• Use el método AcquireUserTokenAsync con el identificador de aplicación, el identificador de inquilino y la autenticación para adquirir un token.

Nota:

Aunque en el ejemplo de código siguiente se muestra cómo adquirir un token mediante el flujo de nombre de usuario y contraseña, Microsoft recomienda usar flujos de autenticación más seguros en un entorno de producción.

namespace MDA
{
    using System.Net.Http;
    using System.Text;
    using System.Threading.Tasks;
    using Newtonsoft.Json.Linq;

    public static class MDAUtils
    {
        private const string Authority = "https://login.microsoftonline.com";

        private const string MDAId = "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1";
        private const string Scope = "Investigation.read";

        public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
        {
            using (var httpClient = new HttpClient())
            {
                var urlEncodedBody = $"scope={MDAId}/{Scope}&client_id={appId}&grant_type=password&username={username}&password={password}";

                var stringContent = new StringContent(urlEncodedBody, Encoding.UTF8, "application/x-www-form-urlencoded");

                using (var response = await httpClient.PostAsync($"{Authority}/{tenantId}/oauth2/token", stringContent).ConfigureAwait(false))
                {
                    response.EnsureSuccessStatusCode();

                    var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false);

                    var jObject = JObject.Parse(json);

                    return jObject["access_token"].Value<string>();
                }
            }
        }
    }
} 

Validar el token

Comprueba que tiene un token correcto:

• Copia o pega en JWT el token que obtuviste en el paso anterior para descodificarlo

• Comprueba que obtienes una notificación "scp" con los permisos de aplicación deseados

• En la captura de pantalla siguiente puedes ver un token descodificado adquirido desde la aplicación en el tutorial:

  

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

• Establece el encabezado de autorización en la solicitud HTTP que envíes a "Bearer {token}" (Bearer es el esquema de autorización)

• La hora de expiración del token es de 1 hora (puedes enviar más de una solicitud con el mismo token)

• 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
• Plataforma de identidad y flujo de código de autorización de OAuth 2.0