Microsoft SharePoint

SharePoint Online #

Authentication #

In SharePoint Online, the best practice for authenticating is using a Microsoft Entra ID App-Only App Registration. This is an application that is defined in your Microsoft Entra ID and can be granted permissions to SharePoint (and other services in Office 365, but this is not necessary).

Microsoft Entra ID App-Only setup #

Note: permission to create a new app registration is required for this setup.

Required scopes #

  • https://graph.microsoft.com/Sites.Selected
    • What can we do with it? Read granted SharePoint sites and subsites
    • Why do we need it? To browse the environment for files and folders
  • https://graph.microsoft.com/User.Read.All
    • What can we do with it? Read users
    • Why do we need it? To retrieve file metadata and permissions
  • https://graph.microsoft.com/GroupMember.Read.All
    • What can we do with it? Read groups and its memberships
    • Why do we need it? To support permission mirroring

Azure #

Please follow the steps below:

  1. In the Azure portal, navigate to the Microsoft Entra ID and then go to App registrations
  2. Click on New registration and fill in the name for the application (i.e. uman)
  3. Click Register at the bottom of the screen, the other settings can be the defaults
  4. If that is successful, note down the Application (client) ID and Directory (tenant) ID that are displayed in the overview
  5. Navigate to Certificates & secrets in the navigation bar on the left
  6. Create a new client secret and save the value
  7. Hand over the application (client) ID, directory (tenant) ID and client secret in a very secure manner to the uman person you are in contact with
  8. Navigate to API permissions in the navigation bar on the left
  9. Click Add a permission and then select Microsoft Graph followed by Application permissions
  10. Search for the 3 above mentioned scopes (i.e. Sites.Selected) and select them
  11. After adding the permissions, click Grant admin consent for <application name> and confirm
  12. If the statuses of the granted permissions turn green, you’re (almost) set!

SharePoint #

Next, we need to grant uman access in Sharepoint. As of September 2023, you cannot link the created app registration to a site anymore without explicit tenant administrator consent. The SharePoint administrator will need to (temporarily) change a tenant setting to allow this. In PowerShell, this can be done with the following command:

Set-SPOTenant -SiteOwnerManageLegacyServicePrincipalEnabled $true

We use the SharePoint app-only grant to get access to SharePoint. For new tenants, CustomAppAuthentication is disabled by default. This needs to be changed, using the following command in PowerShell:

Set-SPOTenant -DisableCustomAppAuthentication $false

Perform these steps for every Sharepoint site that you want to grant to uman.

  1. Navigate to https://<mytenant>.sharepoint.com/sites/<site_name>/_layouts/15/appinv.aspx (replacing <mytenant> with the name of your tenant, i.e. uman; replacing <site_name> with the site you want to grant)
  2. In the form that is shown, fill in your application (client) ID in the App Id field
  3. Press Lookup, this should populate the Title field. If this is not the case, please validate that you filled in the correct application (client) ID in the field
  4. App Domain doesn’t really matter, so you can just put app.uman.ai
  5. Redirect URL can remain empty
  6. For the Permission Request XML field, copy the block below in there:
<AppPermissionRequests AllowAppOnlyPolicy="true">
  <AppPermissionRequest Scope="http://sharepoint/content/sitecollection" Right="Read"/>
</AppPermissionRequests>
  1. Click Create, validate that the permissions you are granting are correct, followed by a click on Trust on the next page
  2. If you are planning to enable permission mirroring, make sure to set 'OnlyAllowMembersViewMembership': False for every sitegroup in the site
  3. (Optional) Disable the legacy service principal setting again by replacing $true with $false in the PowerShell command above

We can’t read all the available sharepoint sites with Sites.Selected, so a list containing the sites should be given to us. We can retrieve the site_ids based on the site_names