Sharepoint

SharePoint Online #

Authentication #

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

Authentication with a user is also supported, but is not recommended. At the bottom of this page, you will find a small section regarding this method.

Azure AD 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

Please follow the steps below:

  1. In the Azure portal, navigate to the Azure Active Directory 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!

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

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

User setup #

Note: your user will need admin permissions or receive consent of an admin

To complete this method successfully, you’ll first need an account and enter the workspace of your organization. If you do not have an account yet, please request an invite with admin permissions and follow the account creation steps. Once that is done, navigate to app.uman.ai, and more specifically, to your workspace. Then, please follow the steps below:

  1. At the top-left corner of the application, left-click on the chevron on the right of the workspace name.
  2. Left-click on Connected Apps
  3. Left-click the Connect button to the right of the SharePoint integration
  4. Follow the OAuth flow and accept the admin consent
  5. Validate you can see sites after left-clicking on Sync folders in the Connected Apps window