GuidesAPI Reference
Guides

Azure OAuth App and SharePoint

Setting up an Azure OAuth App requires the following:

  • Creating the OAuth App
  • Optionally restricting the OAuth App to only be able to access specific SharePoint sites
  • Granting permission for the OAuth App to use the SharePoint Rest API

Each of these steps is covered in detail below.

Creating an Azure OAuth App

Before you can configure the connector, you must create an OAuth App in the SharePoint Online platform.

The native connector will authenticate to SharePoint as the registered OAuth application/client.

You’ll need to provide values for

  • Client ID
  • Tenant ID
  • Client secret Id
  • Client secret value
  • Tenant name

To get started, first log in to SharePoint Online and access your administrative dashboard ensuring that you are logged in as at least an Azure Portal service account.

Follow these steps:

  1. Sign in to https://portal.azure.com/ and click on Azure Active Directory.
  2. Select App Registrations and click New Registration.
  3. Give the app a name. E.g. "Interact Workplace Search".
  4. Register the application.
  5. Make a note of the Application (client) ID and Directory (tenant) ID.
  6. Navigate to Client credentials: Certificates & Secrets.
  7. Select New client secret
  8. Pick a name for your client secret and select an expiration date.
    • note: after this expiration date, you will have to reconfigure your connector credentials by following these steps again
  9. Note the client secret Secret ID.
  10. Note the client secret Secret Value (you must do this immediately before leaving the page).

You can then enter the credentials into the SharePoint Online Connector

The TenantName for the SharePoint Online Connector should be the name of the tenant.

For example, if your tenant is contoso.onmicrosoft.com, then you would enter contoso. So, it should look like:

{
  "ApplicationClientId": "[Your ApplicationClientId]",
  "DirectoryTenantId": "[Your DirectoryTenantId]",
  "SecretId": "[Your SecretId]",
  "SecretValue": "[Your SecretValue]",
  "TenantName": "contoso"
}

Next, you will have to set up the permissions for the OAuth App.

  1. Navigate to API Permissions and click Add Permission.
  2. Add the following application permissions:
    • Graph API
      • Sites.Read.All
        • Is used to fetch the sites and their metadata
        • (See "Restricting OAuth App API Permissions to Specific Sites" for more detail)
      • Files.Read.All
        • Is used to fetch the sites and their metadata
      • Group.Read.All
        • Is used to fetch groups for document-level permissions
      • User.Read.All
        • Is used to fetch user information for document-level permissions
    • SharePoint
      • Sites.Read.All
        • (See "Restricting OAuth App API Permissions to Specific Sites" for more detail)

Depending on how you want to use the native connector, its possible to synchronise Team Sites (Group Sites) without any additional OAuth App permissions by listing them individually within the config, as explicit sites that you want to synchronise.

But, if you want to configure the connector to automatically discover all team sites and synchronise them all (apart from an optional set of disallowed team sites), then you will also need to add the following permissions to the OAuth App:

  • Graph API
    • Team.ReadBasic.All
    • TeamSettings.Read.All
    • TeamSettings.ReadWrite.All

You will need to get someone with admin permissions to grant admin consent, using the Grant Admin Consent link from the permissions screen.

Save the tenant name (or Domain name) displayed from within Azure.

Restricting OAuth App API Permissions to Specific Sites

The Sites.Read.All permission scopes, which are set within the Microsoft Graph and the SharePoint APIs, will allow the app registration to access all sites within your tenant. However, it can be preferable to only allow the app to access specific sites.

Beyond the initial "Creating an Azure OAuth App" process, the following steps can be taken so that the OAuth App only has access to specific sites.

  • Modify the Azure OAuth API Permission Scopes to include Sites.Selected instead of Sites.Read.All
  • Grant access for the Azure OAuth App to be able to access the sites that you want to synchronise
  • Update the SharePoint Online Native Connector to no longer perform automatic site collection discovery (which it performs by default) and instead only connect to a specified site collection.

Modifying the API Permission Scopes

This can be achieved by using the Sites.Selected scope instead of the Sites.Read.All scope (for both the Microsoft Graph and the SharePoint APIs).

🚧

If modifying an existing app registration to only access selected sites, then be sure to fully remove the Sites.Read.All scopes from both the Microsoft Graph and SharePoint APIs and also ensure you subsequently remove any corresponding admin consent for those permissions. Failing to do this will result in the app registration still being able to access all sites.

Once the permissions have been set they should look like:

As a result of making these changes, the connector will no longer be able to discover site collections or sites. Additional steps must be taken before the connector is able to access the sites for synchronisation.

Granting OAuth App Permissions to Specific Sites

The following links by Microsoft describe in detail how to granting permission for an OAuth App to access a specific Site Collection using either the Graph API (Explorer) or PowerShell:

Note: for the purposes of the guides above, you can find the id of a site, by navigating to it and then appending /_api/site/id in the url.

Configuring the Connector to No Longer Perform Automatic Site Collection Discovery

The SharePoint Online Native Connector by default performs a Graph API request to fetch a list of site collections as part of its synchronisation process. This call is no longer allowed (Access Denied) if the Sites.Read.All permission scope has been removed and replaced with the Sites.Selected.All permission score.

Therefore, it is neccesary to update the connector config JSON to to change the site collection discovery mode to be Specific rather than AutomaticDiscovery (which is the default value).

This will be achieved by adding the following json into the root of the configuration JSON.

"SiteCollectionOptions" : {  
  "Mode" : "Specific"  
  "WebUrl" : "[The url of the site collection]"  
}

Using the Specific mode will mean that the connector will no longer perform the automatic site collection discovery, and instead will only connect to the site collection specified by the WebUrl parameter.

The WebUrl should be set to your SharePoint Site Collection URL. For example: https://contoso.sharepoint.com


SharePoint Configuration

The Azure OAth App does not automatically have access to the SharePoint REST API, so the additional step is also required.

Refer to the following documentation for setting SharePoint permissions.

  1. To set DisableCustomAppAuthentication to false, connect to SharePoint using PowerShell and run set-spotenant -DisableCustomAppAuthentication $false
  2. To assign full permissions to the tenant in SharePoint Online, go to the Manage App Permissions page within SharePoint.
    1. The URL follows this pattern: https://<office_365_tenant_URL>-admin/_layouts/15/appinv.aspx. For example, if your SharePoint URL is https://contoso.sharepoint.com, then you should go to https://contoso-admin.sharepoint.com/_layouts/15/appinv.aspx.
  3. This loads the SharePoint admin centre page, where you can create the app permissions request.
    1. In the App ID box, enter the application ID that you recorded earlier, and then click Lookup. The application name will appear in the Title box.
    2. In the App Domain box, type <tenant_name>.onmicrosoft.com - where <tenant_name> should be replaced by your tenant name (e.g. contoso.onmicrosoft.com)
    3. In the App’s Permission Request XML box, type the following XML string:
<AppPermissionRequests AllowAppOnlyPolicy="true">
    <AppPermissionRequest Scope="http://sharepoint/content/tenant" Right="FullControl" />
    <AppPermissionRequest Scope="http://sharepoint/social/tenant" Right="Read" />
</AppPermissionRequests>

🚧

Please ensure that the above xml is applied exactly as specified (with line breaks) otherwise the permissions may not apply correctly

Troubleshooting

"Insufficient privileges to complete the operation."

If you see the "Insufficient privileges to complete the operation." error message, then ensure that the relevant API permissions (Graph, SharePoint) have been set.

"Attempted to perform an unauthorized operation"

If you see the following in your workplace search logs:

Error | Value of parsed object was null. Serialised value: "{"odata.error":{"code":"-2147024891, System.UnauthorizedAccessException","message":{"lang":"en-US","value":"Attempted to perform an unauthorized operation."}}}"

Then this normally means that the SharePoint Configuration has not been applied correctly. Ensure that the above SharePoint Configuration steps have been followed correctly, and that the steps were performed on the SharePoint Admin site (-admin suffix).

"Microsoft.IdentityModel.Tokens.AudienceUriValidationFailedException"

if you see the following error in your workplace search logs:

Error | Failed to process serialised response. Serialised value: "{"error_description":"Exception of type 'Microsoft.IdentityModel.Tokens.AudienceUriValidationFailedException' was thrown."}"

This can be a result of not setting the TenantName parameter in the SharePoint Online connector credentials JSON correctly. For example, if your tenant is contoso.onmicrosoft.com, then you would enter contoso. So, it should look like:

{
  "ApplicationClientId": "[Your ApplicationClientId]",
  "DirectoryTenantId": "[Your DirectoryTenantId]",
  "SecretId": "[Your SecretId]",
  "SecretValue": "[Your SecretValue]",
  "TenantName": "contoso"
}

This could also mean that the SharePoint Configuration has not been applied correctly. Ensure that the above SharePoint Configuration steps have been followed correctly, and that the steps were performed on the SharePoint Admin site (-admin suffix).

Updated 2 days ago