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 upload uman-generated files
  • https://graph.microsoft.com/User.Read.All
    • What can we do with it? Read users
    • Why do we need it? To retrieve file metadata

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

Grant the App Registration access to Sharepoint:

  1. Create a new sharepoint site Go-To-Market key content. (This can be a standard team site)
  2. 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 just created)
  3. In the form that is shown, fill in your application (client) ID in the App Id field
  4. 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
  5. App Domain doesn’t really matter, so you can just put app.uman.ai
  6. Redirect URL can remain empty
  7. For the Permission Request XML field, copy the block below in there:
<AppPermissionRequests AllowAppOnlyPolicy="true">
  <AppPermissionRequest Scope="http://sharepoint/content/sitecollection" Right="FullControl"/>
</AppPermissionRequests>
  1. Click Create, validate that the permissions you are granting are correct, followed by a click on Trust on the next page
  2. (Optional) Disable the legacy service principal setting again by replacing $true with $false in the PowerShell command above

Let the uman team know that the steps above have happened successfully and provide the url of the newly created site, the application (client) ID, directory (tenant) ID and client secret in a very secure manner to the uman person you are in contact with.