SharePoint
SharePoint
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.SelectedWhat 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.AllWhat can we do with it? Read users
Why do we need it? To retrieve file metadata
Azure
Please follow the steps below:
In the Azure portal, navigate to the Microsoft Entra ID and then go to App registrations
Click on New registration and fill in the name for the application (i.e. uman)
Click Register at the bottom of the screen, the other settings can be the defaults
If that is successful, note down the Application (client) ID and Directory (tenant) ID that are displayed in the overview
Navigate to Certificates & secrets in the navigation bar on the left
Create a new client secret and save the value
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
Navigate to API permissions in the navigation bar on the left
Click Add a permission and then select Microsoft Graph followed by Application permissions
Search for the 3 above mentioned scopes (i.e. Sites.Selected) and select them
After adding the permissions, click Grant admin consent for <application name> and confirm
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:
Create a new sharepoint site
Go-To-Market key content. (This can be a standard team site)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)
In the form that is shown, fill in your application (client) ID in the App Id field
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
App Domain doesn’t really matter, so you can just put app.uman.ai
Redirect URL can remain empty
For the Permission Request XML field, copy the block below in there:
<AppPermissionRequests AllowAppOnlyPolicy="true"> <AppPermissionRequest Scope="http://sharepoint/content/sitecollection" Right="FullControl"/> </AppPermissionRequests>
Click Create, validate that the permissions you are granting are correct, followed by a click on Trust on the next page
(Optional) Disable the legacy service principal setting again by replacing
$truewith$falsein 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.
Grant admin consent
Grant admin consent to the Microsoft Entra ID applications if required.
Google Drive
Google Drive
For Google Drive we work with a Google service account provided by uman. During the set-up process you will be given a service account email address and service account identifier.
Pre-requisites
It is required to have a Google Workspace in order for uman to be able to index content.
Scopes
Create a new Shared Drive and grant the Manager access role to the uman-provided service account. Adding the service account to the Shared Drive will grant the following permissions implicitly:
https://www.googleapis.com/auth/drive: required to upload uman-generated files to Google Drivehttps://www.googleapis.com/auth/drive.activity.readonly: required to read activities related to those files
Next to adding the service account to the desired Shared Drives, you need to grant the service account the following domain-wide scopes:
https://www.googleapis.com/auth/admin.directory.user.readonly: required to read all users, relevant for the metadata of files.
For instructions on how to grant these domain-wide delegation, check the Google docs.
Setup process
Please follow the steps below:
Create a new Shared Drive
Go-To-Market key contentRetrieve the service account email address and identifier from the uman team
Grant the service account the
Manageraccess role to the newly created Shared DriveGrant the service account the aforementioned domain-wide scopes
Let the uman team know that the steps above have happened successfully and provide an email address of an administrator (at least ‘User Management Admin’ role) that uman can use to impersonate the admin scope calls
Optional: You can grant a group (containing all the users) Viewer-access to the Shared Drive, so that everyone in the organization can see the content, but not modify it.
Whitelist applications
Whitelist the uman applications if required.