Feature: Added Get-PnPAzureADActivityReportDirectoryAudit to get audit logs

CHANGELOG.md

@@ -22,6 +22,8 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 - Added `-RequestFilesLinkEnabled` option to `Set-PnPSite` to allow configuring the request files anonymously feature on a per site collection level [#2360](https://github.com/pnp/powershell/pull/2360)
 - Added `ScriptSafeDomainName` option to `Set-PnPSite` to allow contributors to insert iframe from specified domains only. [#2363](https://github.com/pnp/powershell/pull/2363)
 - Added `AlertTemplateName` paramter to `Add-PnPAlert` to allow configuring the Alert Template type name in the email. [#2362](https://github.com/pnp/powershell/pull/2362)
+- Added `Get-PnPAzureADActivityReportDirectoryAudit` to retrieve the audit logs generated by Azure AD. [#2095](https://github.com/pnp/powershell/pull/2095)
+
 
 ### Changed
 - Changed to no longer require `https://` to be prefixed when using `Connect-PnPOnline -Url tenant.sharepoint.com` [#2139](https://github.com/pnp/powershell/pull/2139)
@@ -36,6 +38,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 - Marked `-Resource` parameter from `Get-PnPAccessToken` cmdlet as obsolete as it was not used anymore anyway. It will be removed in a future version. [#2182](https://github.com/pnp/powershell/pull/2182)
 
 ### Fixed
+
 - Fixed issue where passing in `-Connection` to `Disconnect-PnPOnline` would throw an exception [#2093](https://github.com/pnp/powershell/pull/2093)
 - Fixed `Get-PnPSiteSearchQueryResults` throwing `Value cannot be null` exception [#2138](https://github.com/pnp/powershell/pull/2138)
 - Fixed `New-PnPUPABulkImportJob` not returing the job Id [#2144](https://github.com/pnp/powershell/pull/2144)

documentation/Get-PnPAzureADActivityReportDirectoryAudit.md

@@ -0,0 +1,107 @@
+---
+external help file: PnP.PowerShell.dll-Help.xml
+Module Name: PnP.PowerShell
+online version: https://pnp.github.io/powershell/cmdlets/Get-PnPAzureADActivityReportDirectoryAudit.html
+schema: 2.0.0
+applicable: SharePoint Online
+title: Get-PnPAzureADActivityReportDirectoryAudit
+---
+
+# Get-PnPAzureADActivityReportDirectoryAudit
+
+## SYNOPSIS
+
+**Required Permissions**
+
+* Microsoft Graph API: AuditLog.Read.All and Directory.Read.All
+
+Returns the audit logs generated by Azure AD.
+
+## SYNTAX
+
+```powershell
+Get-PnPAzureADActivityReportDirectoryAudit [-Identity <string>] [-Filter <string>] [-Connection <PnPConnection>]
+```
+
+## DESCRIPTION
+
+This cmdlet gets the list of audit logs generated by AzureAD. This includes audit logs generated by different services in Azure AD such as user, app, device and group Management, privileged identity management (PIM), access reviews, terms of use, identity protection, password management (self-service and admin password resets) and others.
+
+## EXAMPLES
+
+### Example 1
+
+```powershell
+Get-PnPAzureADActivityReportDirectoryAudit
+```
+
+Returns all audit logs generated by Azure AD.
+
+### Example 2
+
+```powershell
+Get-PnPAzureADDirectoryAudit -Identity "Directory_c3b82411-5445-4620-aace-6a684a252673_02R72_362975819"
+```
+
+Returns the audit log with specific ID.
+
+### Example 3
+
+```powershell
+Get-PnPAzureADDirectoryAudit -Filter "activityDateTime le 2018-01-24"
+```
+
+Returns the audit logs based on filter condition.
+
+## PARAMETERS
+
+### -Identity
+
+Specify the ID of the audit log.
+
+```yaml
+Type: string
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Filter
+
+Specify the Filter condition for the audit log report.
+
+```yaml
+Type: string
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Connection
+
+Optional connection to be used by the cmdlet. Retrieve the value for this parameter by either specifying -ReturnConnection on Connect-PnPOnline or by executing Get-PnPConnection.
+
+```yaml
+Type: PnPConnection
+Parameter Sets: (All)
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+## RELATED LINKS
+
+[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)

src/Commands/AzureAD/GetAzureADActivityReportDirectoryAudit.cs

@@ -0,0 +1,43 @@
+using PnP.PowerShell.Commands.Attributes;
+using PnP.PowerShell.Commands.Base;
+using PnP.PowerShell.Commands.Utilities.REST;
+using System.Management.Automation;
+
+namespace PnP.PowerShell.Commands.AzureAD
+{
+    [Cmdlet(VerbsCommon.Get, "PnPAzureADActivityReportDirectoryAudit")]
+    [RequiredMinimalApiPermissions("AuditLog.Read.All")]
+    public class GetAzureADActivityReportDirectoryAudit : PnPGraphCmdlet
+    {
+        [Parameter(Mandatory = false)]
+        public string Identity;
+
+        [Parameter(Mandatory = false)]
+        public string Filter;
+        protected override void ExecuteCmdlet()
+        {
+            var auditLogUrl = "/v1.0/auditLogs/directoryaudits";
+
+            if (!string.IsNullOrEmpty(Identity))
+            {
+                auditLogUrl += $"/{Identity}";
+            }
+
+            if (!string.IsNullOrEmpty(Filter))
+            {
+                auditLogUrl += $"?$filter={Filter}";
+            }
+
+            if (ParameterSpecified(nameof(Identity)))
+            {
+                var auditResults = GraphHelper.GetAsync<Model.AzureAD.AzureADDirectoryAudit>(Connection, auditLogUrl, AccessToken).GetAwaiter().GetResult();
+                WriteObject(auditResults, false);
+            }
+            else
+            {
+                var auditResults = GraphHelper.GetResultCollectionAsync<Model.AzureAD.AzureADDirectoryAudit>(Connection, auditLogUrl, AccessToken).GetAwaiter().GetResult();
+                WriteObject(auditResults, true);
+            }
+        }
+    }
+}

src/Commands/Model/AzureAD/AzureADAuditAdditionalDetail.cs

@@ -0,0 +1,12 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+
+namespace PnP.PowerShell.Commands.Model.AzureAD
+{
+    public class AzureADAuditAdditionalDetail
+    {
+        public string key { get; set; }
+        public string value { get; set; }
+    }
+}

src/Commands/Model/AzureAD/AzureADAuditInitiatedBy.cs

@@ -0,0 +1,15 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+using System.Text.Json.Serialization;
+
+namespace PnP.PowerShell.Commands.Model.AzureAD
+{
+    public class AzureADAuditInitiatedBy
+    {
+        [JsonPropertyName("user")]
+        public AzureADAuditUser User { get; set; }
+        [JsonPropertyName("app")]
+        public object app { get; set; }
+    }
+}

src/Commands/Model/AzureAD/AzureADAuditModifiedProperty.cs

@@ -0,0 +1,17 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+using System.Text.Json.Serialization;
+
+namespace PnP.PowerShell.Commands.Model.AzureAD
+{
+    public class AzureADAuditModifiedProperty
+    {
+        [JsonPropertyName("displayName")]
+        public string DisplayName { get; set; }
+        [JsonPropertyName("oldValue")]
+        public object OldValue { get; set; }
+        [JsonPropertyName("newValue")]
+        public string NewValue { get; set; }
+    }
+}

src/Commands/Model/AzureAD/AzureADAuditTargetResource.cs

@@ -0,0 +1,23 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+using System.Text.Json.Serialization;
+
+namespace PnP.PowerShell.Commands.Model.AzureAD
+{
+    public class AzureADAuditTargetResource
+    {
+        [JsonPropertyName("id")]
+        public string Id { get; set; }
+        [JsonPropertyName("displayName")]
+        public string DisplayName { get; set; }
+        [JsonPropertyName("type")]
+        public string Type { get; set; }
+        [JsonPropertyName("modifiedProperties")]
+        public List<AzureADAuditModifiedProperty> ModifiedProperties { get; set; }
+        [JsonPropertyName("groupType")]
+        public string GroupType { get; set; }
+        [JsonPropertyName("userPrincipalName")]
+        public string UserPrincipalName { get; set; }
+    }
+}

src/Commands/Model/AzureAD/AzureADAuditUser.cs

@@ -0,0 +1,19 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+using System.Text.Json.Serialization;
+
+namespace PnP.PowerShell.Commands.Model.AzureAD
+{
+    public class AzureADAuditUser
+    {
+        [JsonPropertyName("id")]
+        public string Id { get; set; }
+        [JsonPropertyName("displayName")]
+        public string DisplayName { get; set; }
+        [JsonPropertyName("userPrincipalName")]
+        public string UserPrincipalName { get; set; }
+        [JsonPropertyName("ipAddress")]
+        public string IPAddress { get; set; }
+    }
+}

src/Commands/Model/AzureAD/AzureADDirectoryAudit.cs

@@ -0,0 +1,33 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+using System.Text.Json.Serialization;
+
+namespace PnP.PowerShell.Commands.Model.AzureAD
+{
+    public class AzureADDirectoryAudit
+    {
+        [JsonPropertyName("id")]
+        public string Id { get; set; }
+        [JsonPropertyName("category")]
+        public string Category { get; set; }
+        [JsonPropertyName("CorrelationId")]
+        public string CorrelationId { get; set; }
+        [JsonPropertyName("result")]
+        public string Result { get; set; }
+        [JsonPropertyName("resultReason")]
+        public string ResultReason { get; set; }
+        [JsonPropertyName("activityDisplayName")]
+        public string ActivityDisplayName { get; set; }
+        [JsonPropertyName("activityDateTime")]
+        public DateTime ActivityDateTime { get; set; }
+        [JsonPropertyName("loggedByService")]
+        public string LoggedByService { get; set; }
+        [JsonPropertyName("initiatedBy")]
+        public AzureADAuditInitiatedBy InitiatedBy { get; set; }
+        [JsonPropertyName("targetResources")]
+        public List<AzureADAuditTargetResource> TargetResources { get; set; }
+        [JsonPropertyName("additionalDetails")]
+        public List<AzureADAuditAdditionalDetail> AdditionalDetails { get; set; }
+    }
+}