Merge pull request #2710 from gautamdsheth/feature/filter-sp

Feature: Added Filter parameter to service principal cmdlet

Author: KoenZomers

CHANGELOG.md

@@ -23,6 +23,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 - Added `-KeyColumn` to `Add-PnPDataRowsToSiteTemplate` which allows for overwriting existing list items in a site template [#2616](https://github.com/pnp/powershell/pull/2616)
 - Added `IsTeamsConnected`, `IsTeamsChannelConnected` and `TeamChannelType` to be returned when `Get-PnPTenantSite` cmdlet is executed. [#2656](https://github.com/pnp/powershell/pull/2656)
 - Added `-EnvironmentVariable` parameter to `Connect-PnPOnline` to connect using Azure environment variables. [#2681](https://github.com/pnp/powershell/pull/2681)
+- Added `-Filter` parameter to `Get-PnPAzureADServicePrincipal` cmdlet to retrieve specific application registrations based on filter conditions. It supports simple and advanced queries. [#2710](https://github.com/pnp/powershell/pull/2710)
 - Added `-Filter` parameter to `Get-PnPMicrosoft365Group` cmdlet to retrieve specific M365 groups based on filter conditions. It supports simple and advanced queries.
 
 ### Changed

documentation/Get-PnPAzureADServicePrincipal.md

@@ -22,7 +22,7 @@ Gets service principal/application registrations in Azure Active Directory.
 ### All
 
 ```powershell
-Get-PnPAzureADServicePrincipal [-Connection <PnPConnection>]
+Get-PnPAzureADServicePrincipal [-Filter <string>] [-Connection <PnPConnection>]
 ```
 
 ### By App Id
@@ -83,6 +83,13 @@ Get-PnPAzureADServicePrincipal -AppName "My application"
 
 Retrieves the application registration with the name "My application" from Azure Active Directory
 
+### EXAMPLE 5
+```powershell
+Get-PnPAzureADServicePrincipal -Filter "startswith(description, 'contoso')"
+```
+
+Retrieves the application registration with the description starting with "contoso" from Azure Active Directory. This example demonstrates using Advanced Query capabilities (see: https://learn.microsoft.com/graph/aad-advanced-queries?tabs=http#group-properties).
+
 ## PARAMETERS
 
 ### -AppId
@@ -141,6 +148,20 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -Filter
+Specify the query to pass to Graph API in $filter.
+
+```yaml
+Type: String
+Parameter Sets: Filter
+
+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/Apps/GetAzureADServicePrincipal.cs

@@ -30,12 +30,15 @@ public class GetAzureADServicePrincipal : PnPGraphCmdlet
         public string AppName;
 
         [Parameter(Mandatory = true, ParameterSetName = ParameterSet_BYBUILTINTYPE)]
-        public ServicePrincipalBuiltInType BuiltInType;        
+        public ServicePrincipalBuiltInType BuiltInType;
+
+        [Parameter(Mandatory = false, ParameterSetName = ParameterSet_ALL)]
+        public string Filter;
 
         protected override void ExecuteCmdlet()
         {
             AzureADServicePrincipal servicePrincipal = null;
-            switch(ParameterSetName)
+            switch (ParameterSetName)
             {
                 case ParameterSet_BYAPPID:
                     servicePrincipal = ServicePrincipalUtility.GetServicePrincipalByAppId(Connection, AccessToken, AppId);
@@ -50,12 +53,12 @@ protected override void ExecuteCmdlet()
                     servicePrincipal = ServicePrincipalUtility.GetServicePrincipalByBuiltInType(Connection, AccessToken, BuiltInType);
                     break;
                 case ParameterSet_ALL:
-                    var servicePrincipals = ServicePrincipalUtility.GetServicePrincipals(Connection, AccessToken);
+                    var servicePrincipals = ServicePrincipalUtility.GetServicePrincipals(Connection, AccessToken, Filter);
                     WriteObject(servicePrincipals, true);
                     return;
             }
 
-            if(servicePrincipal == null)
+            if (servicePrincipal == null)
             {
                 throw new PSArgumentException("Service principal not found");
             }

src/Commands/Utilities/ServicePrincipalUtility.cs

@@ -16,9 +16,19 @@ internal static class ServicePrincipalUtility
         /// <summary>
         /// Returns all service principals
         /// </summary>
-        public static List<AzureADServicePrincipal> GetServicePrincipals(PnPConnection connection, string accesstoken)
+        public static List<AzureADServicePrincipal> GetServicePrincipals(PnPConnection connection, string accesstoken, string filter = null)
         {
-            var result = Utilities.REST.GraphHelper.GetResultCollectionAsync<AzureADServicePrincipal>(connection, $"https://{connection.GraphEndPoint}/v1.0/servicePrincipals", accesstoken).GetAwaiter().GetResult();
+            string requestUrl = $"https://{connection.GraphEndPoint}/v1.0/servicePrincipals";
+            Dictionary<string, string> additionalHeaders = null;
+            if (!string.IsNullOrEmpty(filter))
+            {
+                requestUrl = $"{requestUrl}?$filter=({filter})";
+                additionalHeaders = new Dictionary<string, string>
+                {
+                    { "ConsistencyLevel", "eventual" }
+                };
+            }
+            var result = REST.GraphHelper.GetResultCollectionAsync<AzureADServicePrincipal>(connection, requestUrl, accesstoken, additionalHeaders: additionalHeaders).GetAwaiter().GetResult();
             return result.ToList();
         }
 
@@ -28,7 +38,7 @@ public static List<AzureADServicePrincipal> GetServicePrincipals(PnPConnection c
         public static AzureADServicePrincipal GetServicePrincipalByBuiltInType(PnPConnection connection, string accesstoken, ServicePrincipalBuiltInType builtInType)
         {
             AzureADServicePrincipal result = null;
-            switch(builtInType)
+            switch (builtInType)
             {
                 case ServicePrincipalBuiltInType.MicrosoftGraph:
                     result = ServicePrincipalUtility.GetServicePrincipalByAppId(connection, accesstoken, new Guid("00000003-0000-0000-c000-000000000000"));
@@ -53,13 +63,13 @@ public static AzureADServicePrincipal GetServicePrincipalByObjectId(PnPConnectio
             try
             {
                 result = Utilities.REST.GraphHelper.GetResultCollectionAsync<AzureADServicePrincipal>(connection, $"https://{connection.GraphEndPoint}/v1.0/servicePrincipals?$filter=id eq '{objectId}'", accesstoken).GetAwaiter().GetResult();
-                
+
                 var servicePrincipal = result.FirstOrDefault();
                 servicePrincipal.AppRoles.ForEach(ar => ar.ServicePrincipal = servicePrincipal);
                 return servicePrincipal;
             }
             catch (Exception) { }
-            return null;            
+            return null;
         }
 
         /// <summary>
@@ -71,7 +81,7 @@ public static AzureADServicePrincipal GetServicePrincipalByAppId(PnPConnection c
             try
             {
                 result = Utilities.REST.GraphHelper.GetResultCollectionAsync<AzureADServicePrincipal>(connection, $"https://{connection.GraphEndPoint}/v1.0/servicePrincipals?$filter=appid eq '{appId}'", accesstoken).GetAwaiter().GetResult();
-                
+
                 var servicePrincipal = result.FirstOrDefault();
                 servicePrincipal.AppRoles.ForEach(ar => ar.ServicePrincipal = servicePrincipal);
                 return servicePrincipal;
@@ -89,7 +99,7 @@ public static AzureADServicePrincipal GetServicePrincipalByAppName(PnPConnection
             try
             {
                 result = Utilities.REST.GraphHelper.GetResultCollectionAsync<AzureADServicePrincipal>(connection, $"https://{connection.GraphEndPoint}/v1.0/servicePrincipals?$filter=displayName eq '{appName}'", accesstoken).GetAwaiter().GetResult();
-                
+
                 var servicePrincipal = result.FirstOrDefault();
                 servicePrincipal.AppRoles.ForEach(ar => ar.ServicePrincipal = servicePrincipal);
                 return servicePrincipal;
@@ -205,7 +215,7 @@ public static void RemoveServicePrincipalRoleAssignment(PnPConnection connection
             {
                 Utilities.REST.GraphHelper.DeleteAsync(connection, $"https://{connection.GraphEndPoint}/v1.0/servicePrincipals/{principalToRemoveRoleFrom.Id}/appRoleAssignments/{assignment.Id}", accesstoken).GetAwaiter().GetResult();
             }
-        } 
+        }
 
         /// <summary>
         /// Removes the provided role from the role assignments of the provided service principal
@@ -243,7 +253,7 @@ public static void RemoveServicePrincipalRoleAssignment(PnPConnection connection
                     Utilities.REST.GraphHelper.DeleteAsync(connection, $"https://{connection.GraphEndPoint}/v1.0/servicePrincipals/{principalToRemoveRoleFrom.Id}/appRoleAssignments/{assignment.Id}", accesstoken).GetAwaiter().GetResult();
                 }
             }
-        }        
+        }
 
         /// <summary>
         /// Removes a role assignment from the provided service principal
@@ -255,6 +265,6 @@ public static void RemoveServicePrincipalRoleAssignment(PnPConnection connection
         public static void RemoveServicePrincipalRoleAssignment(PnPConnection connection, string accesstoken, AzureADServicePrincipalAppRoleAssignment appRoleAssignmenToRemove)
         {
             Utilities.REST.GraphHelper.DeleteAsync(connection, $"https://{connection.GraphEndPoint}/v1.0/servicePrincipals/{appRoleAssignmenToRemove.PrincipalId}/appRoleAssignments/{appRoleAssignmenToRemove.Id}", accesstoken).GetAwaiter().GetResult();
-        }        
+        }
     }
 }