Today quietly Microsoft released a SharePoint Azure AD app registration permission level Sites.Selected. This allows PnP PowerShell cmdlets and CSOM to be used using SharePoint application permissions to a specific site(s). This is independent & different to the Microsoft Graph permission level Sites.Selected. I covered this in a previous blog article in March 2021 when this was released for MS Graph. One downfall with this was only pure Microsoft Graph commands could be run on the SharePoint site and the existing PnP PowerShell cmdlets did not work with MS Graph Sites.Selected. This was because the PnP cmdlets mainly for SharePoint use CSOM and SPO Rest behind the scenes which was not compatible – this now changes and is big news! Now you can use PnP PowerShell and csom and authenticate and pass commands without user interaction i.e. without MFA or perform mass provisioning/migration using a SharePoint Azure AD App. It is widely considered that authenticating through an app rather than a user is treated more favourably by Microsoft when running a high frequency of repetitive commands such as migrations and you are less likely to be throttled.
What this means…
Historically to do anything as an Azure AD app for SharePoint (without MS Graph) the only permission levels available have been to allow access to ALL sites in the tenant i.e. Sites.FullControl.All. Giving the app permission to ALL site collections has meant security focussed tenant administrators are unable to grant this level of access rather than just the site collections(s) the app needs to work on.
There is now a new granular/resource specific permission level in the SharePoint Azure AD app registration page named Sites.Selected which allows applications to be given Read or Write permissions to specific known site collections rather than all site collections. Once an app is given Sites.Selected permission it will by default have no permission to any SharePoint site collections. and the app will then need to be explicitly added to the permissions object of the SharePoint site through Microsoft Graph/PnP.PowerShell. The new Sites.Selected SharePoint permissions are also not available for Delegated (as a user) permissions. At the moment the permissions can only be applied to a site via code and there is no user interface to administrate via a web browser but it is envisaged there will be a official UI made available at some stage. In the meantime Frederik Thorild has created a great open source SPFX solution you should look at that allows you to add Sites to apps using Sites.Selected using an SPFX web part.
I will now show you through a mixture of PnP.PowerShell and PowerShell how to setup an Azure AD app registration and then configure the app with just the new SharePoint Sites.Selected permission to authenticate to a specific SharePoint site collection. We can then use this app to authenticate using to the specific site and run existing PnP PowerShell cmdlets and scripts. Finally we will show what happens when the app tries to access a site collection it does not have permission for.
1. Create Azure AD App with SharePoint Application Permissions Enabled for Sites.Selected
We will now use PnP.PowerShell to create using just one command Register-PnPAzureADApp an Azure AD application named SPSitesSelected with just SharePoint Sites.Selected permission. I truly recommend using PnP PowerShell just for this as it makes creating the application and certificate so easy!
Firstly ensure PnP.PowerShell is installed and as of 16/01/2022 the Pre Release version will need used on Install-Module so Sites.Selected permissions can be added. If the normal release is used Sites.Selected for -SharePointApplicationPermissions will not be available.
Then to Register the Azure AD App – update the commands below with your tenant’s details and then run the command. If the username that your run the command under does not have Global Administrator permissions then you will need to get an Global Admin to approve the permission request.
Run the Register-PnPAzureADApp cmdlet above and then you will see a consent prompt for the app your are creating asking you to consent for “Access selected site collections” aka Sharepoint Sites.Selected.
Click accept to the consent screen and then you will be presented with a Can’t reach this page being displayed – this message can be ignored.
PowerShell will then confirm the Azure AD app has been created – take a note of the Client ID & certificate thumbprint.
2. Grant Azure AD App Permission To A Selected SharePoint Site Collection
We will now sign into SharePoint using PnP.PowerShell’s Connect-PnPOnline command as a global administrator or as an application with Sites.FullControl.All permissions.
We will then add the Azure AD app to a specific site collection’s permissions using Grant-PnPAzureADAppSitePermission – so the app can access the specified site collection. See the command below where I am giving the App write permissions to the site https://tenantname.sharepoint.com/sites/sitesselected:
You can change the -Permissions parameter to be Read or Write respectively to give read or write access for the application to the site.
You can use the following PnP.PowerShell commands to further administrate Azure AD App Site permissions:
- Get-PnPAzureADAppSitePermission to retrieve the Azure AD App permissions permissions for a site.
- MS Graph Equivalent – Get Site Permission
- Remove-PnPAzureADAppSitePermission to revoke a permissions for a app to a site.
- MS Graph Equivalent – Delete Site Permission
- Set-PnPAzureADAppSitePermission to change the permission of an app on a site i.e. change from Write to Read.
- MS Graph Equivalent – Update Site Permission
3. Connect with the Azure AD app that has SharePoint Sites.Selected permission and connect to the specified SharePoint site collection using PnP PowerShell
Now we have added the Azure AD app to the permissions for the site collection (my site is /sites/SitesSelected) I will now show you how to connect to your app and then connect to the site using PnP PowerShell. Finally we will try and connect to another site and we should see that we get the error message “Access Denied”
Connect via Azure AD app using PnP PowerShell to selected SharePoint site & run Get-PnPList cmdlet
Connect using Connect-PnPOnline and ensure the -ClientId, -Thumbprint (certificate) & -Tenant are used. Use the values for the app we just created
Success!! We were able to connect to the /sites/SitesSelected site and able to use Get-PnPList to retrieve all lists in the site.
Try to connect to a site collection where the App has not been granted permissions
I will now show you what happens if you try to connect to a site where you have not been granted Sites.Selected permissions to and it will show that you are performing an unauthrorized operation when running Get-PnPList.
Sites.Selected/Resource Specific permissions for SharePoint in Azure AD App (app registration) is a game changer. Now scripts using PnP PowerShell cmdlets (using CSOM or SPO Rest under the hood) for SharePoint can run under applications and be secured to just a site(s) and not ALL sites. If an application is used to authenticate then there are no multi-factor-authentication (MFA) prompts so I can see this being very useful in automations i.e. running PowerShell in Azure functions etc. App based authentication is generally treated better by Microsoft so you are likely to be throttled than running as a user.
This is the continuation of the work that has recently been done with Microsoft Graph to allow MS Graph to use Sites.Selected permissions but then that was limited as Graph does not have full feature parity with CSOM and SPO Rest.
PnP.PowerShell has made it really easy to create a Azure App secured with a certificate and granted Sites.Selected permissions in SharePoint. I then used PnP.PowerShell to grant the Azure App write permissions to a site, then I was able to connect using this Azure AD application using SharePoint Sites.Selected permissions and then run PnP PowerShell cmdlets.
I hope this blog article and code samples is helpful for you and helps your organisation. Please let me know in the comments below if you have any feedback, questions or are using it in your organisation?