Sharepoint Graph or REST API

It is important to note the difference between the Graph and REST APIs before selecting how to connect Relatics to Sharepoint. An application integration with the Graph option is recommended because Microsoft no longer supports a REST integration (see note). This can be done by creating a new app registration in the Microsoft Entra ID admin interface and selecting the Graph API options. Then, use the following article to connect that app registration to Relatics: Application integration using Microsoft Graph.

It is also possible to use the REST API to connect Sharepoint to Relatics. This can be done by creating an app-only principal. After correctly configuring the principal, find out how to configure Application integration using Microsoft REST.

Note:

• App-only principals are deprecated, meaning they are no longer supported by Microsoft updates and will soon be disabled completely. However, they are still regularly used. So, this article will offer solutions to certain common problems while configuring them.

Troubleshoot app-only principal^*

For simplicity’s sake, an app-only principal is assumed to exist already, but a few common problems and their solutions will be discussed. There are a few ways in which problems could appear. For example, you might find it impossible to enter a site or select lists after configuring a key to access an external application in the environment settings and configuring the interface to Sharepoint in the workspace. These are indicators of an incorrect configuration in Sharepoint.

Note:

• Use the latest version of Sharepoint admin PowerShell to configure the app-only principal.

Problem: The App-Only principals are disabled. An example of an error Relatics might return is: “Type token is not allowed”.

Solution: If the principal needs to be used for a REST API, a setting must be configured correctly on the tenant, which can be set using the Sharepoint Powershell module. To check if this setting is configured correctly, enter the following command in PowerShell:

get-spotenant

look for the value of DisableCustomAppAuthentication (see appendix A for more detailed examples). If the value for DisableCustomAppAuthentication returns $true the principal is not ready to be used by the REST API, and the following command should be run:

set-spotenant -DisableCustomAppAuthentication $false

Problem: Relatics has no access to the desired Sharepoint sites, leading to Relatics not loading Sharepoint lists.

Solution: The rights of an app-only principal are configurable using a specific page of the Sharepoint tenant. This page is accessible at a similar URL to: ‘https://company.sharepoint.com/_layouts/15/appinv.aspx’ (company being a variable field depending on your tenant). On the configuration page, in the field App Id, fill in the client ID of the app-only principal. In the field Permission request XML, the scope and rights of the principal can be configured. The following XML is an example of how to give the principal reading and writing rights to the complete Sharepoint tenant (see appendix B for an example in Sharepoint):

<AppPermissionRequests AllowAppOnlyPolicy="true">
­  <AppPermissionRequest Scope="http://sharepoint/content/tenant" Right="FullControl" />
</AppPermissionRequests>

Use the following table to determine the scope of the defined rights:

Use the following table to determine the rights of the defined scope:

Notes:

• Importantly, the values for the scope and rights of the app-only principal should not differ from their presentation in the tables above. E.g. the XML should contain Scope=”http://sharepoint/content/tenant” Right=”FullControl” when giving the principal full rights over the tenant.
• If the AppPermissionRequest Scope is set to for example “http://sharepoint/content/sitecollection” this requires the app-only principal to be created on that specific site collection using an URL similar to: ‘https://company.sharepoint.com/sites/sitename/_layouts/15/appregnew.aspx’

Appendix A

PowerShell example for retreiving the app-only principal settings of a tenant with multi-factor authentication:

Install-Module -Name Microsoft.Online.SharePoint.PowerShell
$orgName="<name of your Office 365 organization, example: contoso>"
Connect-SPOService -Url https://$orgName-admin.sharepoint.com
get-spotenant 

PowerShell example for retreiving the app-only principal settings of a tenant without multi-factor authentication:

Install-Module -Name Microsoft.Online.SharePoint.PowerShell
$adminUPN="<the full email address of a SharePoint administrator account, example: jdoe@contoso.onmicrosoft.com>"
$orgName="<name of your Office 365 organization, example: contoso>"
$userCredential = Get-Credential -UserName $adminUPN -Message "Type the password."
Connect-SPOService -Url https://$orgName-admin.sharepoint.com -Credential $userCredential
get-spotenant


Notes:

• The italicized parts of the PowerShell scripts can vary for each Sharepoint tenant.
• To change the value of the setting, use: set-spotenant -DisableCustomAppAuthentication $false instead of: get-spotenant.

Appendix B

(Microsoft, 2023)

Reference

Microsoft. (2023, November 28). Granting access using SharePoint App-Only. https://learn.microsoft.com/en-us/sharepoint/dev/solution-guidance/security-apponly-azureacs

* In Sharepoint, the administration role of your user must be set to Global administrator or Sharepoint administrator to enable this feature.