Automating Azure AD Auditing PowerShell: Simplifying Log Analysis. Do you want to simplify Azure AD auditing by automating it with PowerShell? We guide you through the various ways to accomplish this, starting with an overview of Azure AD auditing.
In the overview section, explain the Azure Active Directory audit and sign-in logs and the information they provide. After that, the article dives into 2 ways to use PowerShell to automate Azure AD auditing: log analysis and retention configuration.
Overview of Automating Azure AD Auditing with PowerShell
Azure Active Directory provides audit logs and sign-in logs. In comparison, sign-in logs track user and application sign-in, and audit logs record activities on Azure AD after successful sign-in.
In terms of records, sign-in logs record information such as the user that signed in, the application they signed in to, and the status of the sign-in. Additionally, this log saves other information like the sign-in device’s IP address and the location of the user/device.
Similarly, the audit log tracks information such as the user who performed the activity, the activity performed, and the status of the action.
Most admins use the Azure Portal to run audit and sign-in log reports. However, for admins that need to automate this process, PowerShell provides a robust option.
In the following sections, we explore how to use PowerShell for automating and auditing Azure AD sign-in and audit logs.
Automating Azure AD Auditing with PowerShell: Analysing Audit Logs
The PowerShell commands required to analyse Azure AD audit and sign-in logs are part of the AzureADPreview module. Therefore, before running the commands, you must install and import this module on your computer.
After installing the module, it is also required to run the connect-AzureAD command before running any other command. The first subsection below explains how to install the module and run the connect-AzureAD command.
Install AzureADPreview and Connect to Azure AD Tenant
1. Search “powershell” (without the quotes) and select “Run as administrator.” Your PC prompts you to authorize the app to make changes to your device – click Yes.
2. Once PowerShell opens, modify the execution policy to allow PowerShell to run downloaded modules.
powershell.exe -ExecutionPolicy RemoteSigned
3. To install the Azure AD public preview module, run this command. Including the AllowClobber parameter allows PowerShell to overwrite existing commands as any new command installed.
Install-module AzureADPreview -Force -AllowClobber
4. After installing the module, run the import-module command to import the module’s commands into the current PowerShell session. Perform an optional step that confirms if the module is available in the current session by running the Get-Module command.
Import-Module AzureADPreview
Get-Module AzureADPreview
This screenshot shows all the commands in this subsection in PowerShell.
Before proceeding with the following subsections, let’s run the Connect-AzureAD to authenticate to Azure Active Directory and allow us to execute any other command.
Replace username@domainname.com with your Azure AD login email.
When you run this command, PowerShell displays a sign-in pop-up requesting the password for the Azure AD account. Enter the password and click OK.
Connect-AzureAD -Credential (Get-Credential username@domainname.com)
If the sign-in is successful, PowerShell displays your Azure tenant information.
Try our Active Directory & Office 365 Reporting & Auditing Tools
Try us out for Free. 100’s of report templates available. Easily customise your own reports on AD, Azure AD & Office 355.
Analyse Azure AD Audit Logs with PowerShell
The Get-AzureADAuditDirectoryLogs command is used to report Azure AD audit logs. Running this command without any parameters returns too much information.
To reduce the amount of information, we utilise the Top and Filter parameters. The Top parameter allows you to specify the number of records to return.
This command displays the last three records in the Azure Active Directory audit log.
Get-AzureADAuditDirectoryLogs -Top 3
Here is the result. As you see, this report lists the results, which is not very useful.
To display the result in a table, we pipe Get-AzureADAuditDirectoryLogs to Format-Table.
Get-AzureADAuditDirectoryLogs -Top 3 | Format-Table
With this last modification, the report is displayed in a table!
Although the Top parameter is great, the most useful parameter is Filter. This parameter allows you to return specific results from the Azure AD audit logs.
For example, to return all audit logs about an object with a display name, ‘WordPress Site (Azure CLI)’ I execute this command:
Get-AzureADAuditDirectoryLogs -Filter "targetResources/any(tr:tr/displayName eq 'WordPress Site (Azure CLI)')"
Beyond filtering results by target resource, we could use other filtering methods. For instance, filter by the status of the action: Success or failure.
The command below returns the last three failure actions recorded in the audit log.
Get-AzureADAuditDirectoryLogs -Filter "result eq 'failure'" -Top 3 | Format-Table
And here is the result.
Finally, for this subsection, you could filter by the person who initiated the activity recoded in the Azure AD audit log. To illustrate, run this command to return all activities initiated by a user with UPN, name@DomainName.com.
To run this command, change name@DomainName.com to a real UPN.
Get-AzureADAuditDirectoryLogs -Filter "initiatedBy/user/userPrincipalName eq 'name@DomainName.com'"
Here is the result in my Azure AD that returns all activities for a real user.
Analyse Azure AD Sign-in Logs with PowerShell
The Azure AD sign-in log report is run using the Get-AzureADAuditSignInLogs command. This AzureADPreview PowerShell command has the same parameters as the Get-AzureADAuditDirectoryLogs command.
Let’s start by running a command that returns the sign-in log report for a specific user.
Get-AzureADAuditSignInLogs -Filter "userDisplayName eq 'Victor Ashiedu'"
Since the above command returned too many results, I modify the command to display the last 3.
Get-AzureADAuditSignInLogs -Filter "userDisplayName eq 'Victor Ashiedu'" -Top 3 | Format-Table
The last command displays less information allowing for better analysis of the sign-in logs.
I can also combine 2 filtering operations – user display name and date to display specific Azure AD sign-in logs. Here is an example that returns all sign-in logs recorded on 2023-08-28 for a user with the display name ‘Victor Ashiedu.’
Get-AzureADAuditSignInLogs -Filter "(userDisplayName eq 'Victor Ashiedu') and (createdDateTime gt 2023-08-28)" | Format-Table
Automating Azure AD Auditing with PowerShell: Configuring Audit Log Retention
Azure Active Directory audit logs are retained for 12 months by default. However, modify the default log retention period by creating a custom audit log retention policy.
In the following subsections, we explore how to create, view, edit, and delete Azure AD Audit log retention policies using Windows PowerShell scripts.
The commands required for this section are part of the ExchangeOnlineManagement module. So, in the first subsection below, weinstall this module.
Install the ExchangePowerShell PowerShell Module
1. Follow the steps we described for opening PowerShell as administrator and modifying the execution policy in the first section. After that, run the command below to install the ExchangePowerShell module.
Install-Module -Name ExchangeOnlineManagement -AllowClobber -Force
2. Once the command runs successfully, use the Import-Module command to import the module to your PowerShell session. Additionally, you may execute the Get-Module command to confirm that the module is available on your PC.
Import-Module ExchangeOnlineManagement
Get-Module ExchangeOnlineManagement
3. Next, run the Connect-ExchangeOnline to authenticate to Exchange Online. After that, run the Connect-IPPSSession commands to Connect to Security & Compliance PowerShell. Change name@domainname.com to your Azure AD UPN.
Connect-ExchangeOnline -Credential (Get-Credential name@domainname.com)
Connect-IPPSSession -UserPrincipalName name@domainname.com
Create and Modify Azure AD Audit Log Retention using PowerShell
Once you’ve connected successfully, create a new audit log retention policy with this command.
New-UnifiedAuditLogRetentionPolicy -Name "Microsoft AzureAD Audit Policy" -Description "One-year retention policy for all Azure AD activities" -RecordTypes AzureActiveDirectory -RetentionDuration TwelveMonths -Priority 99
The command creates a new one-year AzureAD audit retention policy with a priority of 99.
The New-UnifiedAuditLogRetentionPolicy command allows you to specify the type of audit log retention using the RecordTypes parameter. Get the names of the retention record types from the RecordTypes link.
As I mentioned earlier, my last command created an audit log policy for Azure Active Directory logs, with RecordTypes specified as AzureActiveDirectory. If I wanted the audit log retention policy to apply to SharePoint events, I would have included SharePoint in the RecordTypes list.
To modify this audit log retention policy to include this record type, I’ll run the command below.
Get-UnifiedAuditLogRetentionPolicy | ForEach-Object { Set-UnifiedAuditLogRetentionPolicy -Identity $_ -Priority 101 -RetentionDuration TwelveMonths -RecordTypes AzureActiveDirectory, SharePoint }
View Azure AD Audit Log Retention Policies using PowerShell
To display all azure AD audit logs, run this command.
Get-UnifiedAuditLogRetentionPolicy -RecordType AzureActiveDirectory
The command returns all Azure Active Directory retention policies. However, we filter the report using the Where-Object command. Here is a sample command that returns the retention policy, “Microsoft AzureAD AuditPolicy.”
Get-UnifiedAuditLogRetentionPolicy | Where-Object Name -eq "Microsoft AzureAD AuditPolicy"
Finally, the result is displayed in a table by piping the last result to Format-Table.
Get-UnifiedAuditLogRetentionPolicy | Where-Object Name -eq "Microsoft AzureAD AuditPolicy" | Format-Table
Delete Azure AD Audit Log Retention Policies using PowerShell
To delete an Azure AD audit retention policy, pipe the output of Get-UnifiedAuditLogRetentionPolicy to Remove-UnifiedAuditLogRetentionPolicy. For instance, the command below deletes the audit retention policy I created earlier.
Get-UnifiedAuditLogRetentionPolicy | Where-Object Name -eq "Microsoft AzureAD AuditPolicy" | Remove-UnifiedAuditLogRetentionPolicy
By running the command without including the Force parameter, PowerShell prompts for confirmation.
To avoid this prompt, include the Force parameter.
Get-UnifiedAuditLogRetentionPolicy | Where-Object Name -eq "Microsoft AzureAD AuditPolicy" | Remove-UnifiedAuditLogRetentionPolicy -ForceDeletion
Unfortunately, trying to force deletion returns an error that states that the policy cannot be force deleted since it is not in a “pending deletion state.” So, the only option is to respond to the prompt to confirm the deletion.
Automating Azure AD Auditing PowerShell: Simplifying Log Analysis Conclusion
Azure Active Directory audit and sign-in logs provide essential information for monitoring the health and security of the tenant. Although the Azure Portal provides the option to run reports, PowerShell provides a way to automate the reporting of these logs.
In this article, we explained some information provided by these logs. Additionally, we discussed how to use PowerShell to automate the analysis and configure the retention policies of these all-important Azure AD logs.
Try InfraSOS for FREE
Try InfraSOS Active Directory, Azure AD & Office 365 Reporting & Auditing Tool
- Free 15-Days Trial
- SaaS AD Reporting & Auditing Solution
