How to use Microsoft graph SharePoint Sites.Selected application permission in a Azure AD application for more granular control

As per this announcement made on Feb 2021, Microsoft graph now provides option to have granular permissions level using Sites.Selected application permission for the AD application instead of granting permission for all the sites in the tenant. The permission Sites.Selected does not provide access to any SharePoint site collections for the application unless the AD application has been assigned with permission roles read or write by an Admin. On this post let us see how to grant a site permission (Read or Write) to an AD Application with Sites.Selected permission by using postman client. As of the time I am writing this post there is no user interface to assign permissions to specific site collections for the application.

Pre-Requisite:

  1. Register Azure AD Application (APP 1) in Azure AD Portal with the following permissions
    • Sites.Selected (Admin Consented)
  2. Another AD Application (APP 2) with following permission only for the admins to assign selected roles to the above App
    • Sites.FullControl.All (Admin Consented)

App Registration:

Start with registering the above said two Azure AD applications

APP 1:

Register an Azure AD application with the following permission

APP 2 (Admin App):

Another app for admins for granting roles to APP 1

Grant permission role to the SharePoint site for the Azure AD Application:

This step is grant permission for the Azure AD application with Sites.Selected application permission to a given site collection. Perform the following steps to grant the role (Read/Write or Read and Write) to the AD app (APP 1)

  1. Gather the Client ID, Tenant ID and Client secret of the admin app
  2. In PostMan, make a HTTP request to generate the access token for the admin app – APP 2

Request Method: POST

Request URL: https://login.microsoftonline.com/yourtenantID/oauth2/v2.0/token

Request Header:

Key: Content-Type

Value: application/x-www-form-urlencoded

Request Body:

grant_type: client_credentials

scope: https://graph.microsoft.com/.default

client_id: adminappclientid

client_secret: adminappclientsecret

  1. Copy the access_token to be used for granting roles.
  2. Get the Client ID of the Azure AD Application – APP 1 with Sites.Selected permission
  3. Decide on the Role (Read or Write) for the granting the Site specific role for the APP 1 with Sites.Selected permission.
  4. Get the SiteId of the SharePoint site to be assigned permissions for the application (App 1). An easy way to get the siteId is by viewing the page source from the browser with the site open.
  5. In PostMan, make a HTTP request to grant the site role to the APP 1. Replace the siteId with the actual siteId which will be a guid

Request Method: POST

Request URL: https://graph.microsoft.com/v1.0/sites/siteId/permissions

Request Header:

Key: Content-Type

Value: application/json

Request Body: raw

Replace the id with APP 1 client id and the display name of the APP 1

{

  "roles": ["write"],

  "grantedToIdentities": [{

    "application": {

      "id": "xxxxxx-APP1GUID-4ad9-xxxx-4d36e68b0454",

      "displayName": "AppNamewithSelectedPermissions-App1"

    }

  }]

}
  1. Paste the access token on the token box as shown below with Authorization type selected as Bearer Token
  1. Send the request for granting the role for APP 1. After the request is made the APP 1 with the Sites.Selected permission has access to the site with write role we have granted to. The same way you can assign app access to multiple SharePoint sites.

Grant the Role using PnP PowerShell:

There is a PnP PowerShell cmdlet to grant access to SharePoint site for the registered AD application with Sites.Selected permission. The command to grant permission can be executed by the Site Collection administrator after creating a connection to the site

Connect-PnPOnline https://tenantname.sharepoint.com/sites/siteName -Interactive

You will be prompted to enter credentials including the second factor. After the connection is created, enter the following command to grant Write permission to the AD App

Grant-PnPAzureADAppSitePermission -AppId 'AzureAppIdwithSitesdotselectedpermission' -DisplayName 'App Name here' -Site 'https://tenantname.sharepoint.com/sites/sitename' -Permissions Write

To install PnP PowerShell module on the local workstation, enter the following command

Install-Module -Name PnP.PowerShell

There is also a PnP cmdlet to register an AD app in the Azure Active directory.

Grant the Role by an Admin using the Graph Explorer tool:

Role can also be assigned by an admin with out having the admin AD app (APP 2) using the graph explorer tool. This can be done only by an Admin

If there is any error related to permissions, make sure the admin consents to Sites.FullControl.All for the Graph tool. There is also an SPFx community webpart developed by a community member with User Interface for this operation

https://github.com/pnp/sp-dev-fx-webparts/tree/master/samples/react-sites-selected-admin

Reference:

Assign permission role programmatically: https://docs.microsoft.com/en-us/graph/api/site-post-permissions?view=graph-rest-1.0&tabs=csharp

Summary: On this post we have seen how to grant access to Azure AD which has the Sites.Selected permission. You can also grant permission/role to an app with sites.selected permission programmatically. Hope you have found this informational & thanks for reading. If you are visiting my blog for the first time, please do take a look at my other blogposts.

8 thoughts on “How to use Microsoft graph SharePoint Sites.Selected application permission in a Azure AD application for more granular control

  1. Hello Mohamed,

    Have you try with the APP1 (with Sites.Selected permission) download files or create a new upload session?

    Regards
    Joel

    Like

    1. It should work, I have tested today downloading files from a Document Library with the following API request using APP1 token

      To GET Drive Id (Document Library Id) from a SharePoint site: https://graph.microsoft.com/v1.0/sites/siteId/drives

      To Get the Download link URL of a file: https://graph.microsoft.com/v1.0/sites/siteId/drives/driveidfrompreviousrequest(libraryID)/root:/filenamewithextension
      To get All files from a document library: https://graph.microsoft.com/v1.0/sites/siteId/drives/driveidfrompreviousrequest(libraryID)/root/children
      Site ID: https://graph.microsoft.com/v1.0/sites/{host-name}:/{server-relative-path}
      https://graph.microsoft.com/v1.0/sites/yourM365DomainName.sharepoint.com:/sites/spSiteName

      Reference:
      https://docs.microsoft.com/en-us/graph/api/driveitem-get?view=graph-rest-1.0&tabs=http
      https://docs.microsoft.com/en-us/graph/api/resources/sharepoint?view=graph-rest-1.0

      If the App has Write role assigned, it should be able to upload files as well

      Like

      1. In my case the download Url is generated but when I try to download appears the access denied message 😦
        {“error”:{“code”:”accessDenied”,”message”:”Access denied”}}

        I’ve tried with an app with Sites.FullControl.All and it works.

        Like

      2. It seems that there’s a bug.
        Mohamed, could you please try to download a file using only Sites.Selected permissions?

        I was granted with ‘read’ role by an admin that used his admin app – I can browse through the selected site, but cannot download files.

        Liked by 2 people

  2. Hi, Thanks for the post, it is really interesting! We were going to test the feature, since we are receiving this kind of requests. However, due to the fact is still in preview and it seems there could be bugs…, do you recommend wait a while until Microsoft confirms the feature is reliable?

    Liked by 1 person

    1. Hey David! Thanks for reading the post, yes it a much sought after feature. As far as I have tested, it has few issues when comes downloading files from SharePoint libraries. These issues has been brought to Microsoft product teams attention. I recommend you to wait until it is generally available. Please do take a look at the roadmap for this feature
      https://www.microsoft.com/en-us/microsoft-365/roadmap?filters=&searchterms=Sites.selected

      Liked by 1 person

Leave a Reply to David A. Cancel reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s