Tutorial: Obtención de datos mediante Reporting API de Azure Active Directory con certificadosTutorial: Get data using the Azure Active Directory reporting API with certificates

Las API de generación de informes de Azure Active Directory (Azure AD) proporcionan acceso mediante programación a los datos a través de un conjunto de API de REST.The Azure Active Directory (Azure AD) reporting APIs provide you with programmatic access to the data through a set of REST-based APIs. Estas API pueden llamarse desde una variedad de lenguajes de programación y herramientas.You can call these APIs from a variety of programming languages and tools. Si quiere acceder a Reporting API de Azure AD sin intervención del usuario, debe configurar el acceso para usar certificados.If you want to access the Azure AD Reporting API without user intervention, you must configure your access to use certificates.

En este tutorial, aprenderá a crear un certificado de prueba para acceder a Microsoft Graph API para la creación de informes.In this tutorial, you learn how to use a test certificate to access the MS Graph API for reporting. El uso de certificados de prueba no se recomienda en un entorno de producción.We don't recommend using test certificates in a production environment.

PrerrequisitosPrerequisites

  1. Para obtener acceso a datos de inicio de sesión, asegúrese de que tiene un inquilino de Azure Active Directory con una licencia prémium (P1 y P2).To access sign-in data, make sure you have an Azure Active Directory tenant with a premium (P1/P2) license. Consulte Introducción a Azure Active Directory Premium para actualizar la edición de Azure Active Directory.See Getting started with Azure Active Directory Premium to upgrade your Azure Active Directory edition. Tenga en cuenta que si no tuvo ningún dato de actividades antes de la actualización, los datos tardarán un par de días en mostrarse en los informes después de actualizar a una licencia premium.Note that if you did not have any activities data prior to the upgrade, it will take a couple of days for the data to show up in the reports after you upgrade to a premium license.

  2. Cree o cambie a una cuenta de usuario con el rol Administrador global, Administrador de seguridad, Lector de seguridad o Lector de informes en el inquilino.Create or switch to a user account in the global administrator, security administrator, security reader or report reader role for the tenant.

  3. Complete los requisitos previos para acceder a la API de generación de informes de Azure Active Directory.Complete the prerequisites to access the Azure Active Directory reporting API.

  4. Descargue e instale Azure AD PowerShell V2.Download and install Azure AD PowerShell V2.

  5. Instale MSCloudIdUtils.Install MSCloudIdUtils. Este módulo proporciona varios cmdlets de utilidades incluidos los siguientes:This module provides several utility cmdlets including:

    • Las bibliotecas ADAL necesarias para la autenticaciónThe ADAL libraries needed for authentication
    • Los tokens de acceso de usuario, las claves de aplicación y los certificados mediante ADALAccess tokens from user, application keys, and certificates using ADAL
    • Graph API con control de resultados paginadosGraph API handling paged results
  6. Si es la primera vez que usa el módulo, ejecute Install-MSCloudIdUtilsModule; en caso contrario, puede importarlo mediante el comando de PowerShell Import-Module.If it's your first time using the module run Install-MSCloudIdUtilsModule, otherwise import it using the Import-Module PowerShell command. La sesión debe tener un aspecto similar a esta pantalla: Windows PowerShellYour session should look similar to this screen: Windows PowerShell

  7. Use el commandlet New-SelfSignedCertificate de PowerShell para crear un certificado de prueba.Use the New-SelfSignedCertificate PowerShell commandlet to create a test certificate.

    $cert = New-SelfSignedCertificate -Subject "CN=MSGraph_ReportingAPI" -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256
    
  8. Use el commandlet Export-Certificate para exportarlo en un archivo de certificado.Use the Export-Certificate commandlet to export it to a certificate file.

    Export-Certificate -Cert $cert -FilePath "C:\Reporting\MSGraph_ReportingAPI.cer"
    
    

Obtención de datos mediante Reporting API de Azure Active Directory con certificadosGet data using the Azure Active Directory reporting API with certificates

  1. Vaya a Azure Portal, seleccione Azure Active Directory, luego, seleccione Registros de aplicaciones y elija la aplicación de la lista.Navigate to the Azure portal, select Azure Active Directory, then select App registrations and choose your application from the list.

  2. Seleccione Certificates & secrets (Certificados y secretos) en la sección Administrar de la hoja de registro de aplicaciones y elija Cargar certificado.Select Certificates & secrets under Manage section on Application registration blade and select Upload Certificate.

  3. Seleccione el archivo de certificado del paso anterior y elija Agregar.Select the certificate file from the previous step and select Add.

  4. Anote el identificador de la aplicación y la huella digital del certificado que acaba de registrar con la aplicación.Note the Application ID, and the thumbprint of the certificate you just registered with your application. Para encontrar la huella digital, en la página de la aplicación en el portal, vaya a Certificates & secrets (Certificados y secretos) en la sección Administrar.To find the thumbprint, from your application page in the portal, go to Certificates & secrets under Manage section. La huella digital estará en la lista Certificados.The thumbprint will be under the Certificates list.

  5. Abra el manifiesto de aplicación en el editor de manifiesto insertado y compruebe que la propiedad keyCredentials está actualizada con la nueva información del certificado, como se muestra a continuación.Open the application manifest in the inline manifest editor and verify the keyCredentials property is updated with your new certificate information as shown below -

    "keyCredentials": [
         {
             "customKeyIdentifier": "$base64Thumbprint", //base64 encoding of the certificate hash
             "keyId": "$keyid", //GUID to identify the key in the manifest
             "type": "AsymmetricX509Cert",
             "usage": "Verify",
             "value":  "$base64Value" //base64 encoding of the certificate raw data
         }
     ]
    
  6. Ahora, puede obtener un token de acceso para MS Graph API con este certificado.Now, you can get an access token for the MS Graph API using this certificate. Use el cmdlet Get-MSCloudIdMSGraphAccessTokenFromCert del módulo MSCloudIdUtils de PowerShell pasando el identificador de la aplicación y la huella digital que obtuvo en el paso anterior.Use the Get-MSCloudIdMSGraphAccessTokenFromCert cmdlet from the MSCloudIdUtils PowerShell module, passing in the Application ID and the thumbprint you obtained from the previous step.

    Captura de pantalla que muestra una ventana de PowerShell con un comando que crea un token de acceso.

  7. Use el token de acceso del script de Powershell para consultar Graph API.Use the access token in your PowerShell script to query the Graph API. Use el cmdlet Invoke-MSCloudIdMSGraphQuery desde MSCloudIDUtils para enumerar el punto de conexión de SignIns y DirectoryAudits.Use the Invoke-MSCloudIdMSGraphQuery cmdlet from the MSCloudIDUtils to enumerate the signins and directoryAudits endpoint. Este cmdlet controla los resultados de paginado múltiple y los envía a la canalización de PowerShell.This cmdlet handles multi-paged results, and sends those results to the PowerShell pipeline.

  8. Consulte el punto de conexión DirectoryAudits para recuperar los registros de auditoría.Query the directoryAudits endpoint to retrieve the audit logs.

    Captura de pantalla que muestra una ventana de PowerShell con un comando para consultar el punto de conexión de DirectoryAudits mediante el token de acceso anterior en este procedimiento.

  9. Consulte el punto de conexión de SignIns para recuperar los registros de inicio de sesión.Query the signins endpoint to retrieve the sign-in logs.

    Captura de pantalla que muestra una ventana de PowerShell con un comando para consultar el punto de conexión de Signins mediante el token de acceso anterior en este procedimiento.

  10. Ahora puede exportar estos datos en un archivo CSV y guardarlos en un sistema SIEM.You can now choose to export this data to a CSV and save to a SIEM system. También puede encapsular el script en una tarea programada para obtener datos de Azure AD de su inquilino periódicamente sin tener que almacenar las claves de aplicación en el código fuente.You can also wrap your script in a scheduled task to get Azure AD data from your tenant periodically without having to store application keys in the source code.

Pasos siguientesNext steps