Tutorial: Get data using the Azure Active Directory reporting API with certificates

The Azure Active Directory (Azure AD) reporting APIs provide you with programmatic access to the data through a set of REST-based APIs. You can call these APIs from a variety of programming languages and tools. If you want to access the Azure AD Reporting API without user intervention, you must configure your access to use certificates.

In this tutorial, you learn how to use a test certificate to access the MS Graph API for reporting. We don't recommend using test certificates in a production environment.

Prerequisites

  1. To access sign-in data, make sure you have an Azure Active Directory tenant with a premium (P1/P2) license. See Getting started with Azure Active Directory Premium to upgrade your Azure Active Directory edition. 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. Create or switch to a user account in the global administrator, security administrator, security reader or report reader role for the tenant.

  3. Complete the prerequisites to access the Azure Active Directory reporting API.

  4. Download and install Azure AD PowerShell V2.

  5. Install MSCloudIdUtils. This module provides several utility cmdlets including:

    • The ADAL libraries needed for authentication
    • Access tokens from user, application keys, and certificates using ADAL
    • Graph API handling paged results
  6. If it's your first time using the module run Install-MSCloudIdUtilsModule, otherwise import it using the Import-Module Powershell command. Your session should look similar to this screen: Windows Powershell

  7. 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 the Export-Certificate commandlet to export it to a certificate file.

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

Get data using the Azure Active Directory reporting API with certificates

  1. Navigate to the Azure portal, select Azure Active Directory, then select App registrations and choose your application from the list.

  2. Select Settings > Keys and select Upload Public Key.

  3. Select the certificate file from the previous step and select Save.

  4. Note the Application ID, and the thumbprint of the certificate you just registered with your application. To find the thumbprint, from your application page in the portal, go to Settings and click Keys. The thumbprint will be under the Public Keys list.

  5. Open the application manifest in the inline manifest editor and replace the keyCredentials property with your new certificate information using the following schema.

    "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. Save the manifest.

  7. Now, you can get an access token for the MS Graph API using this certificate. Use the Get-MSCloudIdMSGraphAccessTokenFromCert cmdlet from the MSCloudIdUtils PowerShell module, passing in the Application ID and the thumbprint you obtained from the previous step.

    Azure portal

  8. Use the access token in your Powershell script to query the Graph API. Use the Invoke-MSCloudIdMSGraphQuery cmdlet from the MSCloudIDUtils to enumerate the signins and directoryAudits endpoint. This cmdlet handles multi-paged results, and sends those results to the PowerShell pipeline.

  9. Query the directoryAudits endpoint to retrieve the audit logs. Azure portal

  10. Query the signins endpoint to retrieve the sign-in logs. Azure portal

  11. You can now choose to export this data to a CSV and save to a SIEM system. 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.

Next steps