Merge pull request #2920 from gautamdsheth/feature/acs-list

Feature: Added cmdlets to retrive SP Addins and ACS principals

CHANGELOG.md

@@ -50,6 +50,8 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 - Added `-OpenDocumentsMode` option to `Set-PnPList` which allows configuring if documents should be opened in the browser or in the local client [#2873](https://github.com/pnp/powershell/pull/2873)
 - Added `-Properties` parameter to `Get-PnPUserProfileProperty` cmdlet which allows retrieval of specific properties if specified. [#2840](https://github.com/pnp/powershell/pull/2840)
 - Added support for specifying the `-ContentUrl` configuration in `Add-PnPTeamsTab` cmdlet when trying to add a Planner as a tab in Teams channel. [#2850](https://github.com/pnp/powershell/pull/2850)
+- Added `Get-PnPSharePointAddIn` cmdlet to retrive list of SharePoint addins installed in the site collection. [#2920](https://github.com/pnp/powershell/pull/2920)
+- Added `Get-PnPAzureACSPrincipal` cmdlet to retrieve list of installed Azure ACS Principals in the site collection or tenant. [#2920](https://github.com/pnp/powershell/pull/2920)
 - Added `-LogoFilePath` parameter to `Register-PnPAzureADApp` cmdlet to allow setting the logo for the Azure AD app. [#2881](https://github.com/pnp/powershell/pull/2881)
 - Added support for `-Verbose` in `Move-PnPFile` which will show if it has problems determining if the destination location is a folder or a file [#2888](https://github.com/pnp/powershell/pull/2888)
 

documentation/Get-PnPAzureACSPrincipal.md

@@ -0,0 +1,105 @@
+---
+Module Name: PnP.PowerShell
+schema: 2.0.0
+applicable: SharePoint Online
+online version: https://pnp.github.io/powershell/cmdlets/Get-PnPAzureACSPrincipal.html
+external help file: PnP.PowerShell.dll-Help.xml
+title: Get-PnPAzureACSPrincipal
+---
+
+# Get-PnPAzureACSPrincipal
+
+## SYNOPSIS
+
+**Required Permissions**
+
+* SharePoint: Access to the SharePoint Tenant Administration site
+
+Returns the list of Azure ACS Principals
+
+## SYNTAX
+
+```powershell
+Get-PnPAzureACSPrincipal [-Scope <AzureACSPrincipalScope>] [-IncludeSubsites <SwitchParameter>] [-Connection <PnPConnection>]
+```
+
+## DESCRIPTION
+
+## EXAMPLES
+
+### EXAMPLE 1
+```powershell
+Get-PnPAzureACSPrincipal
+```
+
+Returns the Azure ACS principals
+
+### EXAMPLE 2
+```powershell
+Get-PnPAzureACSPrincipal -IncludeSubsites
+```
+
+Returns the lists of Azure ACS principals installed in your site collection as well as the subsites.
+
+### EXAMPLE 3
+```powershell
+Get-PnPAzureACSPrincipal -Scope Tenant
+```
+
+Returns the lists of Azure ACS principals installed in your Tenant.
+
+### EXAMPLE 4
+```powershell
+Get-PnPAzureACSPrincipal -Scope All -IncludeSubsites
+```
+
+Returns the lists of all Azure ACS principals installed in your Tenant including subsites. This a very heavy operation, so it might take some time before we get the results.
+
+## PARAMETERS
+
+### -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
+```
+
+### -Scope
+When specified, it determines the scope of the Azure ACS principals. 
+Supported values are `List, Web, Site, Tenant , All`.
+
+```yaml
+Type: Enum (AzureACSPrincipalScope)
+Parameter Sets: (All)
+Required: False
+Position: Named
+Default value: List
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -IncludeSubsites
+When specified, it determines whether we should use also search the subsites of the connected site collection and lists the Azure ACS principals.
+
+```yaml
+Type: SwitchParameter
+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)
+
+

documentation/Get-PnPSharePointAddIn.md

@@ -0,0 +1,77 @@
+---
+Module Name: PnP.PowerShell
+schema: 2.0.0
+applicable: SharePoint Online
+online version: https://pnp.github.io/powershell/cmdlets/Get-PnPSharePointAddIn.html
+external help file: PnP.PowerShell.dll-Help.xml
+title: Get-PnPSharePointAddIn
+---
+
+# Get-PnPSharePointAddIn
+
+## SYNOPSIS
+
+**Required Permissions**
+
+* SharePoint: Access to the SharePoint Tenant Administration site
+
+Returns the list of SharePoint addins installed in the site collection
+
+## SYNTAX
+
+```powershell
+Get-PnPSharePointAddIn [-IncludeSubsites <SwitchParameter>] [-Connection <PnPConnection>]
+```
+
+## DESCRIPTION
+
+## EXAMPLES
+
+### EXAMPLE 1
+```powershell
+Get-PnPSharePointAddIn
+```
+
+Returns the SharePoint addins installed in your site collection
+
+### EXAMPLE 2
+```powershell
+Get-PnPSharePointAddIn -IncludeSubsites
+```
+
+Returns the SharePoint addins installed in your site collection as well as the subsites.
+
+## PARAMETERS
+
+### -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
+```
+
+### -IncludeSubsites
+When specified, it determines whether we should use also search the subsites of the connected site collection and lists the installed AddIns.
+
+```yaml
+Type: SwitchParameter
+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/Apps/GetAzureACSPrincipal.cs

@@ -0,0 +1,64 @@
+using Microsoft.SharePoint.Client;
+using PnP.Core.Admin.Model.SharePoint;
+using PnP.Core.Services;
+using PnP.PowerShell.Commands.Base;
+using PnP.PowerShell.Commands.Enums;
+using PnP.PowerShell.Commands.Utilities;
+using System;
+using System.Collections.Generic;
+using System.Management.Automation;
+
+namespace PnP.PowerShell.Commands.Apps
+{
+    [Cmdlet(VerbsCommon.Get, "PnPAzureACSPrincipal")]
+    [OutputType(typeof(List<IACSPrincipal>))]
+    public class GetAzureACSPrincipal : PnPAdminCmdlet
+    {
+        [Parameter(Mandatory = false)]
+        public AzureACSPrincipalScope Scope;
+
+        [Parameter(Mandatory = false)]
+        public SwitchParameter IncludeSubsites;
+        protected override void ExecuteCmdlet()
+        {
+            var tenantAdminSiteUrl = Connection.TenantAdminUrl ?? UrlUtilities.GetTenantAdministrationUrl(ClientContext.Url);
+
+            VanityUrlOptions vanityUrlOptions = new()
+            {
+                AdminCenterUri = new Uri(tenantAdminSiteUrl)
+            };
+
+            using var context = ClientContext.Clone(Connection.Url);
+
+            using var pnpContext = Framework.PnPCoreSdk.Instance.GetPnPContext(context);
+
+            if (Scope == AzureACSPrincipalScope.Tenant)
+            {
+                // First load a list possible principal app ids from Azure AD
+                var legacyServicePrincipals = pnpContext.GetSiteCollectionManager().GetLegacyServicePrincipals();
+                if (legacyServicePrincipals != null)
+                {
+                    // Pass in the list of app ids to get the final list of principals
+                    var principals = pnpContext.GetSiteCollectionManager().GetTenantACSPrincipals(legacyServicePrincipals, vanityUrlOptions);
+                    WriteObject(principals, true);
+                }
+            }
+
+            else if (Scope == AzureACSPrincipalScope.All)
+            {
+                var legacyServicePrincipals = pnpContext.GetSiteCollectionManager().GetLegacyServicePrincipals();
+                if (legacyServicePrincipals != null)
+                {
+                    // Pass in the list of app ids to get the final list of principals
+                    var principals = pnpContext.GetSiteCollectionManager().GetTenantAndSiteCollectionACSPrincipals(legacyServicePrincipals, IncludeSubsites, vanityUrlOptions);
+                    WriteObject(principals, true);
+                }
+            }
+            else
+            {
+                var principals = pnpContext.GetSiteCollectionManager().GetSiteCollectionACSPrincipals(IncludeSubsites, vanityUrlOptions);
+                WriteObject(principals, true);
+            }
+        }
+    }
+}

src/Commands/Apps/GetSharePointAddIn.cs

@@ -0,0 +1,37 @@
+using PnP.Core.Services;
+using System.Collections.Generic;
+using System.Management.Automation;
+using PnP.Core.Admin.Model.SharePoint;
+using System;
+using PnP.PowerShell.Commands.Utilities;
+using PnP.PowerShell.Commands.Base;
+using Microsoft.SharePoint.Client;
+
+namespace PnP.PowerShell.Commands.Apps
+{
+    [Cmdlet(VerbsCommon.Get, "PnPSharePointAddIn")]
+    [OutputType(typeof(List<ISharePointAddIn>))]
+    public class GetSharePointAddIn : PnPAdminCmdlet
+    {
+        [Parameter(Mandatory = false)]
+        public SwitchParameter IncludeSubsites;
+
+        protected override void ExecuteCmdlet()
+        {
+            var tenantAdminSiteUrl = Connection.TenantAdminUrl ?? UrlUtilities.GetTenantAdministrationUrl(ClientContext.Url);
+
+            VanityUrlOptions vanityUrlOptions = new()
+            {
+                AdminCenterUri = new Uri(tenantAdminSiteUrl)
+            };
+
+            using var context = ClientContext.Clone(Connection.Url);
+
+            // need to retrieve PnPContext for the connected site not the admin site
+            using var pnpContext = Framework.PnPCoreSdk.Instance.GetPnPContext(context);
+
+            List<ISharePointAddIn> addIns = pnpContext.GetSiteCollectionManager().GetSiteCollectionSharePointAddIns(IncludeSubsites, vanityUrlOptions);
+            WriteObject(addIns, true);
+        }
+    }
+}

src/Commands/Enums/AzureACSPrincipalScope.cs

@@ -0,0 +1,29 @@
+namespace PnP.PowerShell.Commands.Enums
+{
+    /// <summary>
+    /// Possible scopes to retrieve ACS Principals of
+    /// </summary>
+    public enum AzureACSPrincipalScope
+    {
+        /// <summary>
+        /// Retrieves the list scoped Azure ACS principal
+        /// </summary>
+        List,
+        /// <summary>
+        /// Retrieves the web scoped Azure ACS principal
+        /// </summary>
+        Web,
+        /// <summary>
+        /// Retrieves the site collection scoped Azure ACS principal
+        /// </summary>
+        Site,
+        /// <summary>
+        /// Retrieves the Tenant scoped Azure ACS principal
+        /// </summary>
+        Tenant,
+        /// <summary>
+        /// Retrieves the all Azure ACS principals
+        /// </summary>
+        All
+    }
+}