As you know, Azure Active Directory provides you a compelling set of activity, security and audit reports that you can access through the Reports tab in the Azure Management portal. One of the common pieces of feedback we get is the desire to access these reports programmatically, in order to pull the data into SIEM systems, custom dashboards, Excel, Power BI, etc.
Today, I am thrilled to announce the public preview of the Azure AD Reporting API. Using this set of REST APIs you can now programmatically access data from Azure AD reports in a format best suited to your specific needs.
The Azure AD reporting API enables you to:
- Programmatically access data from Azure AD reports using simple REST-based APIs.
- Use a variety of tools and programming languages to access the data, such as C#, PowerShell, or any tool or programming language that supports REST APIs with OAuth.
- Choose the format of the data returned (JSON, XML or text).
The Reporting API uses OAuth to authorize access to the web APIs. This means that you can use the same consistent authorization model you use with the Azure Active Directory Graph APIs to access the Azure AD reporting data.
As with the reports available through the Azure Management portal, some of the reports exposed through the reporting API require an Azure Premium license. To obtain an Azure AD trial subscription click here.
Getting started with the Azure AD Reporting APIs
The easiest way to experiment with using the APIs is to follow the Getting started with the Azure AD Reporting API guide, which walks you through the steps of retrieving reporting data through the APIs from a sample PowerShell script. Once you follow the steps and successfully retrieve reporting data, you can modify the script to meet your particular needs. In addition, we have published a sample C# application which demonstrates how to call the API from C#.
What data is currently available?
We currently support the following reports through the APIs.
- AuditEvents – shows a record of all audited events.
- AccountProvisioningEvents – shows errors that occur during the provisioning/de-provisioning of user accounts to/from SaaS applications to Azure Active Directory.
- SignInsFromUnknownSourcesEvents – lists users who have successfully signed in to your directory from an IP address that has been recognized by Microsoft as an anonymous proxy IP address. These proxies are often used by users that want to hide their computer’s IP address, and may be used for malicious intent – sometimes hackers use these proxies. Data in this report include the number of times a user successfully signed in to your directory from that address and the proxy’s IP address.
- SignInsFromIPAddressesWithSuspiciousActivityEvents – lists sign in attempts from IP addresses where suspicious activity has been noted. Suspicious activity includes many failed sign in attempts from the same IP address over a short period of time, and other activities that may indicate that a hacker has been trying to sign in from this IP address. Data in this report include the user name, and the date, time and IP address from which each attempt was made.
SignInsFromMultipleGeographiesEvents – lists users who successfully signed in from two different regions, where the time between the sign-ins is shorter than the time it would take to travel between these locations. Possible causes include:
- User is sharing their password
- User is using a remote desktop to launch a web browser for sign in
- User is using a VPN or going through a proxy in another region.
- A hacker has signed in to the account of a user from a different country.
Data in this report include the locations of the two sign in events, the time between the sign-ins, and the estimated travel time between these locations.
signInsAfterMultipleFailuresEvents – lists users who have successfully signed in after multiple consecutive failed sign in attempts. Possible causes include:
- User had forgotten their password
- User is the victim of a successful password guessing brute force attack
Data in this report include the number of consecutive failed sign in attempts made prior to the successful sign in and a timestamp associated with the first successful sign in.
The following APIs require an Azure Premium license:
- signInsFromPossiblyInfectedDevicesEvents – lists users who have signed in from devices which are suspected of being infected with malware . Data in this report include the user name, client, IP address, location, last sign in time, the latest time suspicious activity was reported from the device, and the suspected infection.
- IrregularSignInActivityEvents – lists users accounts for with sign-ins that our machine learning algorithms have identified as “anomalous”. Such anomalies include sign-ins from atypical locations, devices, times of day or a combination of these. This may indicate that a hacker has been trying to sign in using this account. The machine learning algorithm classifies events as “anomalous” or “suspicious”, where “suspicious” indicates a higher likelihood of a security breach. Data in this report include the user name, the reason it was identified as anomalous, and the data and time of the sign in event.
- allUsersWithAnomalousSignInActivityEvents – lists user accounts with anomalous sign in activity. This report includes data from all other anomalous activity reports. Data in this report include details about the user, the type of anomaly detected, the date and time, IP address, location, device and classification of the event.
CompromisedCredentialsEvent – lists user accounts whose credentials, according to reported to Microsoft by researchers, industry partners, or law enforcement were posted online.
Data in this report include the event time, the type of credential, reason why the account was marked compromised, and user ID, name and display name.
As always, we’ll continue to tweak and improve the offering based on your feedback.
Hopefully this will expand your options for working with our activity, security and audit reports going forward!
David Howell (Twitter: @David_A_Howell)
Partner Group Program Manager, Microsoft Identity and Security Services Division