Microsoft 365 Governance, Purview, Search, SharePoint, Copilot, Automation, PowerShell, Azure etc.
Tag Archives: Sites.Selected
Sites.Selected is a new feature for Azure registered apps. It allows an application access to a specific SharePoint site collection via MS Graph API and SharePoint REST API.
Below is the sample Python code to authenticate against Microsoft 365 as current user with MSA library and to call Microsoft Graph API – specifically get SharePoint Site, get Site lists with requests library.
But first, you have to have an App Registration in Azure (Entra ID) with delegated permissions consented and authentication configured.
Delegated Permissions
If your solution needs access to all SharePoint sites – consider Sites.FullControl.All or Sites.Manage.All or Sites.ReadWrite.All or Sites.Read.All depending on access level you need. Effective permissions would be a min from both – permissions configured for app registration and permissions current user have. Once consented at the app registration – these permissions will work right away.
If your solution needs access to one (or a few) SharePoint sites – consider Sites.Selected API permissions as it will scope down access to only sites that are required for your solution to work. Remember, Sites.Selected API permissions, even consented at the app registration, does require second step – SharePoint admin should provide (read or write or manage or fullcontrol) permissions for the app registration to a specific site or sites.
Authentication
You’d also need to configure authentication blade. How? It depends on the kind of application you are building etc. For example for native apps I do: – add platform – “Mobile and Desktop app” – select “https://login.microsoftonline.com/common/oauth2/nativeclient” – select “msal096fd951-7285-4e4f-9c1f-23a393556b19://auth (MSAL only)” – add custom Redirect URI: “http://localhost”
This config works for Python code below
Python Code
You’d need to install/import the libraries: json, configparser, msal, requests
Here is the code:
import json
import configparser
import msal
import requests
config = configparser.ConfigParser()
config.read('config.cfg')
client_id = config.get('delegated','clientId')
authority = config.get('delegated','authority')
scopes = config.get('delegated','scope').split()
siteId = config.get('delegated','siteId')
print( client_id)
print( authority)
print( scopes)
print( siteId)
global_token_cache = msal.TokenCache()
global_app = msal.PublicClientApplication(
client_id,
authority=authority, # For Entra ID or External ID
token_cache=global_token_cache,
)
def acquire_and_use_token():
# The pattern to acquire a token looks like this.
result = None
result = global_app.acquire_token_interactive(scopes)
if "access_token" in result:
print("Token was obtained from:", result["token_source"]) # Since MSAL 1.25
# print("Token acquisition result", json.dumps(result, indent=2))
return result["access_token"]
else:
print("Token acquisition failed", result) # Examine result["error_description"] etc. to diagnose error
return None
token = acquire_and_use_token()
http_headers = {'Authorization': 'Bearer ' + token,
'Accept': 'application/json',
'Content-Type': 'application/json'}
graph_url = 'https://graph.microsoft.com/v1.0/sites/' + siteId + '?$select=id,webUrl,displayName'
siteResponse = requests.get(graph_url, headers=http_headers)
print(siteResponse.status_code)
site = json.loads(siteResponse.content)
# print("Site (raw) : ")
# print(site)
print("Site webUrl : ", site["webUrl"])
print("Site displayName : ", site["displayName"])
# Lists
graph_url = 'https://graph.microsoft.com/v1.0/sites/' + siteId + '/lists'
listsResponse = requests.get(graph_url, headers=http_headers)
print(listsResponse.status_code)
lists = json.loads(listsResponse.content)
# print("Site lists (raw):")
# print(lists)
print("Site lists:")
for list in lists["value"]:
print(" Display Name:", list["displayName"])
print(" Id:", list["id"])
print(" Web Url:", list["webUrl"])
print(" Created Date:", list["createdDateTime"])
print(" Last Modified Date:", list["lastModifiedDateTime"])
Application permissions
If your scenario is to call Graph API from Python with application permissions (aka unattended or daemon app) – the main difference is authentication. It is described here. It also requires App registration configured like this.
Microsoft says “Initially, Sites.Selected existed to restrict an application’s access to a single site collection. Now, lists, list items, folders, and files are also supported, and all Selected scopes now support delegated and application modes.”. This article deep-dives into providing and using SelectedOperations.Selected granular permissions to SharePoint:
Lists.SelectedOperations.Selected
Provides application access to a specific list
ListItems.SelectedOperations.Selected
Provides application access to one or more list items, files, or folders
Files.SelectedOperations.Selected
Provides application access to to one or more files or library folders
Set of SelectedOperations permissions is exactly what Microsoft promised a few years ago. And this is great, as we really need granular access to SharePoint sites. I’ve been supporting enterprise SharePoint for more than 10 years now, and I know that it was always a concern when application require access to a list/library or a folder or even document, but admins have to provide access to entire site.
Especially, I believe, this feature becomes more in demand because of Copilot for Microsoft 365. As for now – it’s mostly developers and data analytics who needs unattended application access to SharePoint, but what if regular users powered with m365 Copilot license start creating autonomous agents?
So below is my lab setup, PowerShell scripts and guides with screenshots on how to provide granular (not to entire site but to library/list or folder, or even just one document or list item) permissions to SharePoint and how to use provided permissions.
Admin App
First, we need an Admin App – an app we will use to provide permissions.
The only requirement – this app should have Microsoft.Graph Sites.FullControl.All API permissions consented:
Target Site and Dev Setup
For this lab/demo setup, I have created a team under Microsoft Teams (so it’s a group-based Teams-connected SharePoint site), then test list and test library:
There must be an App Registration for client application – application that will have access to Test-List-01 and Test-Lib-01 only. This app registration should have Microsoft Graph “Lists.SelectedOperations.Selected” API permissions consented:
and I will use Python to access SharePoint programmatically.
At this moment (we have a client app and secret, and “” API permissions, but did not provide for this app access to specific sites or libraries) – we should be able to authenticate to Microsoft 365, but not able to get any kind of data (we can get token, but other call to Graph API would return 403 error – Error: b'{“error”:{“code”:”accessDenied”,”message”:”Request Doesn\’t have the required Permission scopes to access a site.”,):
PowerShell script to provide selectedoperations.selected access for an app to a specific list would be as below. Here we use plain calls to MS Graph API. Full script for your refence is available at GitHub, but here is the essential part:
I use Python console app as a client application. Link to the code at the GitHub is shared below under References, but the core part of the Python code is (I do not use any Microsoft or other libraries here, just plain requests to Microsoft Graph for authentication and for data):
import requests
import json
from secrets import clientSc, clientId, tenantId, siteId, listId
# specify client id, client secret and tenant id
# clientId = ""
# clientSc = ""
# tenantId = ""
apiUri = "https://login.microsoftonline.com/" + tenantId + "/oauth2/v2.0/token"
body = {
"client_id" : clientId,
"client_secret" : clientSc,
"scope" : "https://graph.microsoft.com/.default",
"grant_type" : "client_credentials"
}
try:
response = requests.post(apiUri, data=body)
token = json.loads(response.content)["access_token"]
except:
print("Error: ", json.loads(response.content)["error_description"])
exit()
print("Got token: ", token[0:10], "...")
headers={'Authorization': 'Bearer {0}'.format(token)}
# Get specific site list
print("Geting specific site list")
# graph_url = 'https://graph.microsoft.com/v1.0/sites/' + siteId + '/lists/' + listId
graph_url = 'https://graph.microsoft.com/beta/sites/' + siteId + '/lists/' + listId
graphResponse = requests.get( graph_url, headers=headers )
print(" Response status code: ", graphResponse.status_code)
if graphResponse.status_code == 200:
list = json.loads(graphResponse.content)
print(" List display name: ", list["displayName"])
Note. I’m not sure if it’s a bug or my incorrect setup, but I noticed that if I provide access for the app to the list – app can read site.
For a long time Azure Data Factory did not support modern authentication and we had to provide legacy ACS permissions for Microsoft Azure Data Factory to connect to SharePoint. That’s not the case anymore. Finally Microsoft updated authentication page so Azure Data Factory v2 (ADF V2) supports authentication via app registration with Sites.Selected API permissions, providing Client Id and Certificate. Below are steps to configure ADF v2 connection to SharePoint with a Certificate.
That is how authentication part looks like:
The steps would be
Obtain a certificate
Get a service principal (Register your app in Entra Id )
Upload the certificate to the app registration
Provide access for the app id (client id) to your SharePoint site
Configure linked service in ADF
Detailed Step-by-Step guide ADF connect to SharePoint with a Certificate
1. Obtain a certificate
There are no special technical requirements for a Certificate. Since this is about trust between two parties and you own both – the certificate can be self-signed (e.g. generated with PowerShell as described here). But some organizations still require all certificates used in an org to be trusted by org CA.
2. Register app in Azure to get a service principal
To get a service principal – Client ID (app id) – your must create a so-called “App registration” in Entra Id (Azure AD). Specific requirements: app should have both – Microsoft Graph API and SharePoint API Sites.Selected permissions configured and consented. The process is described, e.g. here.
3. Upload the certificate to the app registration
Under Secrets and Certificates section of you App Registration – select Certificates tab and upload your certificate.
4. Provide access for the app id (client id) to your SharePoint site
This is something only your admins can do. Having Microsoft Graph API and SharePoint API Sites.Selected permissions configured and consented does not mean you automatically have access to SharePoint. Sites.Selected API permissions presence means you are allowed to get access specific SharePoint sites, but what are these sites and what kind of access? So you’d request your SharePoint tenant admins to provide access (e.g. read-only or read-write or full control) for your App Id (client id) to specific SharePoint site Urls. If you are an admin – check this.
5. Configure linked service in ADF
The last step is to configure your Data Factory connection to SharePoint list using service principal and certificate you got earlier with steps 1-4.
Microsoft announced EOL of ACS, and we as SharePoint administrators must take actions. ACS retirement as is a really big deal – entire era of SharePoint app-only service principals will be gone. SharePoint developers used ACS apps since 2013 to build solutions, and when it comes to software development – it always takes time. Imaging the code that was designed for ACS now needs to be reviewed and re-written to adopt changes, then re-compiled, re-tested, re-deployed etc. So it is critical that we should take measures now to avoid bigger issues in April 2026.
Recommended transition tactics: for developers
Get a new App Registration in Azure (Entra Id) with Sites.Selected permissions, ensure no ACS permissions provided to the app (see details on Sites.Selected) and use it
Prioritize using Microsoft Graph API
If Graph API does not provide required functionality – it’s ok to use SharePoint API, but keep in mind in this case certificate should be used (not secret) for authentication
Recommended transition tactics: for SharePoint admins
High-level recommended steps are:
Keep saving audit logs
Encourage users and developers to register applications in Azure (not in SharePoint)
Start providing Sites.Selected permissions
Disable ability for site owners to use AppRegNew and AppInv Stop registering service principals via AppRegNew and providing ACS permissions via AppInv
Pull report on existing Apps that use ACS permissions
Notify developers and users of the ACS apps
Switch ACS off earlier than Microsoft
Thinkin on devs – keep in mind: – ACS apps have a huge legacy – tons of articles and code examples and so on… – Switching to a modern authentication method would require changes in code (though minor, but still), so developers must be engaged – Any change in code would require another round of code compilation, testing, deploying etc.
That means it is not easy (sometimes it is not even possible) to adopt a new modern authentication method. It requires efforts and time, so you need to notify dev as earlier as possible. So it is crucial to complete steps above and start communicating to users as earlier as possible.
Detailed steps for SharePoint administrators:
Keep audit logs
This should be done in advance, but if you did not – starting today and until it’s over you’d get audit logs from Microsoft 365 purview center – consider selecting all events with record type SharePointAppPermissionOperation. Also might be helpful to keep events anyone visited appinv.aspx or appregnew.aspx page. Pull logs now starting with earliest available event (usually 90 days). Some audit logs are available only through Microsoft Graph API. See more details regarding audit logs for ACS tracking KBA.
Encourage users registering applications in Azure (not in SharePoint)
Creating App Registrations in Azure is usually not what SharePoint admins do. Sometimes users are allowed to register apps, sometimes it is blocked for a regular user and done by identity management (or so) but the main idea – users and developers should be able to get service principals (App Registrations) in Azure. Users would need Sites.Selected permissions consented (see more about Sites.Selected) or granular permissions consented (more on granular permissions to SharePoint).
Some pro’s of App Registered in Entra Id (vs SharePoint App-only service principals): – It supports authentication with client secret and/or certificate, custom expiration time – It supports both APIs – Microsoft Graph API and classic SharePoint REST API
Be prepared to instruct users how to get and use certificates in their app registrations.
Provide Sites.Selected permissions
99% of requests for application permissions to SharePoint would require access to a specific site (sites), or to a specific list/library/folder/file (but not to entire tenant). So consider providing Sites.Selected permissions by default (or granular permissions when they are in GA). Create a process so users can request permissions to SharePoint sites for their Azure-Registered Apps. Consider automation if you are a large company (here is one of the possible Sites.Selected automation solutions).
Inform user that ACS is deprecated and you do not provide any new ACS permissions.
Disable registering new service principals in SharePoint
Once you are good in providing non-ACS permissions, it’s time to disable registering service principals in SharePoint. Users should not be able to get a new SharePoint App-only service principals (apps that they used to get from SharePoint sites just going to AppRegNew.aspx).
Disable ability for site owners register service principals in SharePoint via appregnew.aspx is done via Set-SPOTenant PowerShell cmdlet:
When the value is set to false, the service principal can only be created or updated by the SharePoint tenant admin. Using AppInv.aspx page will also be disabled for site owners. Your users will start seeing “Your SharePoint tenant admin doesn’t allow site collection admins…” message (see details), but that’s ok.
There might be rare cases when your in-house solutions or 3-rd party apps got their secrets expired and would require new legacy ACS-based permissions, it is tempting to allow ACS permissions as an exception (as technically it is possible for SharePoint service admin to provide ACS-based access to sites), but I would strictly discourage you to do so. If you decide to provide ACS – track this activity (so you know for whom this ACS-based permissions were provided).
Pull report on existing ACS Apps that use ACS permissions
You need to know who are your vulnerable clients – you should pull reports to get a list of existing Apps that use ACS permissions, apps owners, maybe sites these apps have access to and sites owners
You can get list of developers combining – audit log data from Admin Center and Graph API – report from Entra Id on apps and owners – report from SharePoint sites on permissions provided for apps – reports generated by PnP Microsoft 365 assessment tool
Consider the following steps to get ACS apps owners
get ACS apps with permissions using Microsoft 365 assessment tool
pull these apps owners from Entra Id
using Graph API audit logs data – mark apps active/inactive based on date of the latest login
Notify developers and users of the ACS apps
From the step above we can have a lost of legacy ACS apps and their owners, as well as apps activity (last login), so we can start communicating developers (app owners):
As earlier as possible – e.g. in March-April 2025 (1 year before ACS EOL), notify all apps owners that they need to transition to Azure apps and Selected permissions
Get ACS apps activity and repeat communication, including active app owners
Get ACS apps activity and repeat communication, including owners of sites apps still have access to
Communicate to all apps owners that there will be a temporary and permanent shut down of ACS (see below)
I case you have ACS apps with tenant-level permissions – communicate to them separately
Switch ACS off earlier than Microsoft
You need to plan actual ACS apps disablement in tenant in advance – earlier than Microsoft will do it (in case Microsoft will not put it off). Also consider temporary switch off ACS (“scream test”) even earlier, let say, starting September 2025.
Temporary and permanent ACS disablements before official ACS EOL are needed as scream tests – in case there are users who ignored all communications and still use ACS apps. Disabling ACS early may cause problems with existing applications, but it is necessary to avoid more serious consequences when the time comes for Microsoft to turn it off. So be prepared to handle tickets and communicate to apps owners in advance.
This might be your draft plan:
schedule the first and 2nd temporary (e.g. during 1 hour) ACS apps disablement ~ 6 and 5 months before EOL
schedule the 3rd and 4th temporary (e.g. during 24 hours) ACS apps disablement ~ 4 and 3 months before EOL
schedule the full (permanent) ACS apps disablement ~ 2 months before EOL
In 2021 Microsoft implemented “Sites.Selected” Graph API permissions to allow application access (without a signed in user) to specific sites (entire site only). In 2024 Microsoft implemented granular access – to specific list/libraries, as well as to specific documents/files and list items. Now name convention is *.SelectedOperations.Selected. Permissions come in two flavors – delegated and application:
Files.SelectedOperations.Selected – Allow the application to access a subset of files (files explicitly permissioned to the application). The specific files and the permissions granted will be configured in SharePoint Online or OneDrive.
ListItems.SelectedOperations.Selected – Allow the application to access a subset of lists. The specific lists and the permissions granted will be configured in SharePoint Online.
Lists.SelectedOperations.Selected – Allow the application to access a subset of lists. The specific lists and the permissions granted will be configured in SharePoint Online.
You administer Microsoft 365 SharePoint Online. Part of your daily activities is providing Microsoft Graph and SharePoint Sites.Selected API permissions to other users (developers).
In Aug/Sep 2023 Microsoft pushed an update that prevents site collection admins to create or update an Azure Access Control (ACS) principal (that was the way most of developers used to get Client Id and Client secret to access SharePoint site). So your users are probably getting something like Your SharePoint tenant admin doesn’t allow site collection admins to create or update an Azure Access Control (ACS) principal message attempting to create or update SharePoint App-only principal at AppRegNew.aspx or AppInv.aspx pages. Here are more details on the issue.
Microsoft and MVPs shared some technique how to provide Sites.Selected API permissions, but dealing with scripts manually, elevating individual permissions every time you need to run the script – it all takes time and not very efficient. More and more devs are reaching you on the app. So you want to automate this process.
SharePoint list as a frontend here you can accept intake requests, organize approval workflow and display automation results
Azure Function App as a backend here will be your PowerShell script hosted that runs on scheduled basis and takes care of actual permissions provisioning
Solution details
High-level, getting application permissions to some specific SharePoint site is a two-step process:
get application registration in Azure and properly configure it
get permissions for this application to a specific SharePoint site
For the first step – check this and this articles. I’ll focus on the second step below.
You can provide Sites.Selected permissions for the app to a site with
I will be using second one one. Also PnP.PowerShell will be used to get access to SharePoint intake site and read/update requests from SharePoint list and so on.
Azure App Registration
I registered an admin Application in Azure – “SharePoint Automation App”, added Graph Sites.FullControl.All and SharePoint Sites.FullControl.All permissions, then added Microsoft Graph Directory.Read.All permissions and got tenant admin consent:
I generated a self-signed certificate and added it to the app:
This app will be used to call provide permissions, and to connect to the SharePoint front-end.
Users will register their applications in Azure, add Graph Sites.Selected and SharePoint Sites.Selected permissions, got tenant admin consent, then request permissions to the specific site by creating an intake request – new list item.
Front-End SharePoint Site
I created a SharePoint site for automation. This site will play a front-end role for users. I created a list “Sites.Selected” and updated list columns so I have the following fields:
Target Site Url
Application Id
Permissions (read/write)
Automation Output
In real-world (Prod) – You can (should) also implement approval workflow as you’d provide permissions for the application to the site only with this site owner approval. The PowerShell code behind should also validate site owner’s consent with app access to site. But for the sake of simplicity I’ll skip this in my demo.
Azure Function App
I created an Azure Function App with the following parameters: – Runtime stack: PowerShell Core – Version: 7.2. – OS: Windows – Hosting plan: Consumption
And then PowerShell timer-triggered function in Visual Studio Code.
Function requirements.psd1 (it takes a few hours for Azure to install modules; while modules are installing – you might see “[Warning] The first managed dependency download is in progress, function execution will continue when it’s done. Depending on the content of requirements.psd1, this can take a few minutes. Subsequent function executions will not block and updates will be performed in the background.”):
@{
'Az' = '10.*'
'PnP.PowerShell' = '2.*'
}
Azure Az module to access other Azure resources. PnP.PowerShell module will be used to access SharePoint.
I will keep my admin Azure registered app in a key vault, so need somehow to let the key vault know that this specific app can access this specific credentials. So I enabled system assigned managed Identity for the Function App:
MS: “This resource is registered with Azure Active Directory. The managed identity can be configured to allow access to other resources…”. I’m going to use an object (principal) Id of this function to grant access to keyvault.
Azure key vault
Surely we do not hard-code app secrets. So we need a key vault o store app credentials.
I created a key vault under the same resource group in Azure and named it “SharePointAutomationDemo”. Then I added a roles assignment – “Key Vault Secret User” and “Key vault Reader” to the Function App via it’s managed identity:
I also assigned “Key Vault Administrator” role to the user (developer) who will add certificates/secrets to this key vault and develop Azure function code.
With the new ‘Lists.SelectedOperations.Selected’, ‘ListItems.SelectedOperations.Selected’ and ‘Files.SelectedOperations.Selected’ permissions it is new possible to provide application permissions at a specific list, library or list item levels or at a particular document level, so automation solution would be a little more complicated.
You are trying to register an application at SharePoint site with appregnew.aspx page and you are getting an error or notification message “Your SharePoint tenant admin doesn’t allow site collection admins to create an Azure Access Control (ACS) principal“.
Or you are trying to provide ACS-based permissions for an application to SharePoint site with appinv.aspx page and you are getting “Your SharePoint tenant admin doesn’t allow site collection admins to update app permissions. Please contact your SharePoint administrator.”
You can still view and even delete your apps permissions from /_layouts/15/appprincipals.aspx page:
Reason
This is due to a recent update to Microsoft 365 (tenant governance security measures enhancement MC660075) implemented by Microsoft in Aug/Sep 2023. According to the update, only tenant administrators can create or update ACS service principal by default.
The root cause for this is that the Microsoft is pushing developers out of that legacy ACS-based SharePoint Apps-only service principals towards Azure-registered applications with Sites.Selected API permissions as they are more secure etc. In Nov 2023 Microsoft announcement retirement of ACS principals.
Key differences between ASC and Sites.Selected are:
ACS-based SharePoint app/permissions
Apps registered in Azure with Sites.Selected API permissions
Support authentication with client secret only, Secrets are valid for 1 year exactly.
Support authentication with client secret and/or certificate, custom expiration time.
Support granular access to SharePoint site, e.g. to site collection or web (subsite) or a specific list or library.
Support only access to entire site collection (but Microsoft says granular access is coming) Granular permissions are available – ‘Lists.SelectedOperations.Selected’, ‘ListItems.SelectedOperations.Selected’ and ‘Files.SelectedOperations.Selected’ permissions allows to provide application access to list, library or list item or particular documents
Support only classic SharePoint REST API and CSOM
Support both – classic SharePoint REST API and CSOM and Microsoft Graph API
App id (client id) is created via appregnew.aspx at a specific SharePoint site by site collection administrator (disabled in Sep 2023).
App id (client id) is created in Azure portal (Entra Id), API Sites.Selected permissions are configured via Azure portal (Entra Id) and require tenant admin consent.
Permissions for the app to a site are provided at the site by site collection administrator via appinv.aspx page (disabled in Sep 2023).
Permissions for the App to to a specific SharePoint site are provided via Graph API by SharePoint admin with PowerShell script.
Solution #1 – switch to Sites.Selected
Register an application in Azure (via Entra Id – Azure portal GUI, PowerShell script or your company’s specific helpdesk/servicedesk request)
Update the app so both – MS Graph API Sites.Selected and SharePoint Sites.Selected permissions are configured, then
API permissions must be consented – so you’d seek/request your tenant admin consent
Obtain and upload client certificate (recommended) or generate client secret (at this moment you should be able to authenticate to tenant)
Request access for the app to a specific SharePoint site – your SharePoint service admin should be able to do that (at this moment you should be able to authorize to your SharePoint site).
Validate your app has access to the target SharePoint site with PowerShell (check validation scripts below under References).
Use recommended by Microsoft technique, code samples are available for the most popular languages/platforms – Python, C#, Java etc. (check below under References).
Secure your certificate and/or secret. It is not a good idea to use hard-coded secrets, so consider using special services/storages for secrets (aka Vaults)
If you are hosting your application in Azure – consider using managed identity.
There are 3-rd party (and Microsoft) apps developed using classic approach (examples – Azure data Factory, Alteryx). So in some cases Sites.Selected permissions are not enough to get access to SharePoint.
Solution #2 – admin to register/update an ACS app
This option is acceptable if you have existing application that require ACS-based access. This option is not recommended for new development, as ACS is deprecated and scheduled for retirement.
Microsoft (MC660075 in Message Center): “site collection admin will be unable to register app or update app permissions through above pages unless authorized explicitly by the SharePoint tenant admin” and “With this update site owners will not be able to register/update apps unless the tenant admin explicitly allows it.”
That is incorrect. Site collection admin cannot register app (appregnew) or provide permissions to the app (appinv) anymore. Tenant admin does not authorize site collection admins. Instead tenant (or SharePoint) admin can register an app or provide permissions to the app at a specific site (not changing the entire default behavior back…). But there was no such option (!) in the middle of October 2023, when this feature was enabled at all tenants. Even having a SharePoint admin or tenant admin permissions – if you tried to register an app with AppRegNew.aspx – you got the same error message “Your SharePoint tenant admin doesn’t allow site collection admins to…”.
Later (Checked today – Nov 6, 2023) it seems like Microsoft has implemented it! E.g. now SharePoint or tenant admin is able to register an app with AppRegNew.aspx or update it with AppInv.aspx at any specific site collection. SharePoint or tenant admin must also be among this site collection admins.
It is ok (and I’d say the preferred way) to provide ACS permissions to the app registered in Azure, so do not register apps in SharePoint anymore (do not use AppRegNew.aspx).
Bottom line: if ACS-based permissions are required for app here you go:
register application in Azure (Entra id)
activate your SharePoint service/tenant admin role
ensure you are also target site collection administrator
navigate to the site appinv.aspx page – e.g. “https://yourtenant.sharepoint.com/sites/yoursite/_layouts/15/appinv.aspx” and us Azure registered app (client) Id. E.g. for lookup provide
Azure registered app (client) Id for – click lookup
localhost as app domain
https://localhost as redirect url
Permission Request XML – depending on permissions you need, e.g. for full app access to entire site collection:
It is possible to switch back this new default behavior that prevents site collection admin to register/update apps at SharePoint. This is done with PowerShell command
To run this command – you’d need to be a SharePoint service or tenant admin.
But this will be a step back on your journey in improving m365 tenant safety, as after that you’ll have a self-registered service principals out of control again. So devs will be using it not being aware of ACS retirement and when Microsoft switch off ACS – it will be a disaster, as all app will stop working. That is why Microsoft implemented this feature to soft-disable ACS and allowed us 2 years to redesign or apps and migrate from ACS to Entra Id apps with Sites.Selected. So this solution is not recommended.
In case you really need an exception to provide an ACS-based service principal – there is Solution number 2.
Full text of Microsoft’s MC660075 message
(Updated) SharePoint admin control for App registration / update
Tag MAJOR UPDATE ADMIN IMPACT FEATURE UPDATE
Message Summary Updated August 30, 2023: We have updated the content below for clarity. Thank you for your patience.
This is an enhancement to the security measures for administrative governance that modifies the default procedures for SharePoint app registration via AppRegNew.aspx page and permission updates via AppInv.aspx page. Following the implementation of this change, site collection admin will be unable to register app or update app permissions through above pages unless authorized explicitly by the SharePoint tenant admin.
Upon attempting to register an application on AppRegnew.aspx page, a notification will be displayed stating “Your SharePoint tenant admin doesn’t allow site collection admins to create an Azure Access Control (ACS) principal. Please contact your SharePoint tenant administrator.”
Similarly, upon attempting to update app permissions on AppInv.aspx page, a notification will be displayed stating “Your SharePoint tenant admin doesn’t allow site collection admins to update app permissions. Please contact your SharePoint tenant administrator.”
Kindly note that app registration and permission update via Microsoft Azure portal are not impacted by this change.
When this will happen:
The rollout process is scheduled to commence in late August and is expected to conclude in mid-September.
How this will affect your organization:
With this update site owners will not be able to register/update apps unless the tenant admin explicitly allows it.
To modify the default behavior, the tenant administrator must execute the following shell command to explicitly establish the flag as TRUE, thereby superseding the default value of FALSE. The service principal can only be created or updated by the tenant administrator by default. However, when the flag is set to TRUE, both the SharePoint tenant admin and site collection admin will be able to create or update the service principal through SharePoint.
The shell command is: Set-SPOTenant -SiteOwnerManageLegacyServicePrincipalEnabled $true
Note: The property ‘SiteOwnerManageLegacyServicePrincipalEnabled’ becomes visible in tenant settings after SharePoint Online Management shell is updated to 16.0.23710.12000 or a later version. But before this rollout, the value will always be TRUE even explicitly set to FALSE. It will only automatically be switched to FALSE as the default value after the rollout is launched.
What you need to do to prepare:
No proactive measures are required to prepare for this change. Nevertheless, it is advisable to inform your users of this modification and update any relevant documentation as necessary.
Sites.Selected permissions are required for the non-interactive applications to get access to a specific SharePoint site using Microsoft Graph API and/or SharePoint API. (Since Microsoft announced EOL of SharePoint App-only service principals, Sites.Selected is the only option going forward). Below are
Historically, we utilized so called SharePoint app-only service principals to get unattended (daemon/service) access to one specific site programmatically. Initially in on-prem, later in SPO. SharePoint app-only service principals use ACS-based authentication and allow calls to SharePoint (REST) API and usage of SharePoint CSOM.
Then Microsoft started developing Graph API. You’d need to register your app in Azure to get App Id and App secret to authenticate to Microsoft Graph API. You’d also configure specific API permissions for this app to get access to services you need. Unfortunately, for a long time there were no options to get access to only one specific site with Graph API. Available API permissions allowed access to entire SharePoint only.
Then, in 2021 Microsoft introduced Graph API “Sites.Selected” application permissions. Hooray! The problem was dev had to have two service principals – new Sites.Selected to call Graph API and classic SP-App-only to call SharePoint API. Later, in 2022 Microsoft implemented SharePoint “Sites.Selected” API permissions… More on this…
Long story short, below are the detailed steps to configure Sites.Selected for you unattended app access to SharePoint site.
Steps to get and configure Sites.Selected permissions
1. Register an application in Azure (Entra Id) via Azure portal GUI, PowerShell script or helpdesk/servicedesk request. E.g. with GUI you’d login to portal.azure.com, the search for “App registrations” and select “+ New registration”:
If you are not allowed to register an Entra Id app due to permissions restrictions in your company – connect with your IT/admins, as there must me some way to request an app.
Once you get an application registration – you are this app owner now – you should be able to navigate to your app registration and configure it (see Step 2 and below).
2. Update the app “API permissions” – so both – MS Graph API Sites.Selected and SharePoint Sites.Selected application API permissions are configured:
Request tenant admin consent for your API permissions. Finally your app registration “API permissions” should look like:
3. App Secret or Certificate Under Certificates and secrets – generate client secret, copy secret value to safe location.
Or you can obtain trusted (or create a self-signed) certificate, and upload it to your app registration. Certificates are considered as more secure option then secrets.
4. At the Overview page – grab your app client id and tenant id :
At this moment, having tenant id, app (client) id and client secret (or certificate) – you should be able to authenticate against Microsoft 365 tenant with app-only authentication path.
But! Having just Sites.Selected API permissions configured for app does not mean your app has access to any SharePoint site. Access for the app to a specific site is provided by SharePoint team via Graph API calls. That leads us to the next step.
5. Application access to SharePoint site You need to request this from your SharePoint service admin (or if you are an admin – DIY), but access needs to be provided for the specific app to the specific site with specified permissions (Read-Only or Read/Write or Manage or Full Control) – Here is the Graph API – Here is PowerShell PNP cmdlet
Obviously, Read role allows an app to read site content; Write role is similar to “Contributor” user permissions – it allows CRUD operations against list items (library documents and metadata), but does not allow create/update/delete lists/libraries (for this – you’d need Manage role).
Use Sites.Selected permissions
Once your SharePoint tenant/service admin confirmed that access has been provided – you can use app client id and client secret (or certificate) to work with SharePoint from your code using Graph API. There are some good tutorials published:
Generally, this Sites.Selected permissions allows you to make calls that are documented under “Files” and “Sites and Lists” Graph API documentation. I.e. get site details, get site lists/libraries, create lists and libraries, CRUD operations against list items, download/upload library documents – all within the specific site. Sites.Selected permissions does not allow search operations, anything related to group or team etc.
If you have concerns if permissions for your app were provided correctly or not – you can validate your app access to the target SharePoint site with simple PowerShell scripts: here is the sample code
Note: Sites.Selected API permissions allows you call Microsoft Graph API with client Id and client secret. Calling SharePoint API with client secret is not supported. You have to use client id and certificate to call SharePoint API having app with Sites.Selected permissions.
Call SharePoint API with client Id and client secret is possible only if ACS-based permissions are provided for the app to the site, which is not recommended due to announced retirement (see below).
Secure your credentials
You do not want to hard-code your client secret as you do not want your credentials be leaked. So you need to secure your secrets in production. Solutions for secrets are included in cloud providers offerings, you can also use GitHub environment variables. If you are hosting your application in Azure – consider using key vault to keep your secrets. You can configure managed identity for your application and provide access to the key vault for you application managed id.
Govern Sites.Selected permissions
(For SharePoint admins).
Existing admins API/cmdlets allows yo to provide Sites.Selected permissions for specific app to specific site, and to get Sites.Selected permissions provided to the specific site. But there is no API/cmdlet for the specific app to get all sites (with permissions) this app has access to. Meantime as SharePoint admin if you keep providing permissions upon users/devs requests – after some time you have no idea what app has access to what site with which level of access, especially in large organizations.
Surely you can (and should) pull reports on all registerd apps with access to SharePoint, but…
There is a solution developed by Joe Rodgers (Microsoft). This solution use SharePoint list as an inventory/storage and Power Automate flows to pull data from Entra Id and SharePoint and provides kind of dashboard so you can review details of all app registrations in the tenant with at SharePoint Online permission. Cool!
Note: you would not provide Sites.Selected permissions just upon user/developer request. You’d always get an approval from target site owner. Target site owner must understand that application will have permanent unattended access to entire SharePoint site with permissions specified (read or write or manage or full control).
Generally, to provide an Application with Sites.Selected API permissions configured access to a specific site, SharePoint admin would run a set of PowerShell commands (or C# program or…) to ensure the client id exists, API permissions are configured and consented, to get app owners, target site owners, to get existing app permissions etc. Finally, admin would provide permissions and validate that permissions were provided correctly. It does not take long…
Update: Microsoft announced decommissioning of ACS permissions. So using ACS for any new development is not recommended.
It may be acceptable to grant ACS permissions to existing custom applications or third-party or Microsoft apps/web apps (e.g. Alteryx, Azure Data Factory) – applications that only support a client ID and secret and use the SharePoint API under the hood – but only to avoid disruption to business processes and keeping in mind that ACS will expire soon, so these applications must be replaced/updated before 2026.
Update: Microsoft implemented granular (permissions to list, item or file) alongside with Sites.Selected permissions. Original implementations of Sites.Selected allowed access to entire site collection only. With new ‘Lists.SelectedOperations.Selected’, ‘ListItems.SelectedOperations.Selected’ and ‘Files.SelectedOperations.Selected’ permissions it is possible to provide application permissions to list, library or list item or particular document (reference).
