Skip to main content

Integrate uman on your own DMS tenant (Google/SharePoint)

uman needs to be able to connect to a document management system (DMS) in order to upload the generated content.

Updated over a week ago

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).
​

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 site using graph api

    • 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

  • https://microsoft.sharepoint.com/Sites.Selected

    • What can we do with it? Read granted SharePoint site using SharePoint api

    • Why do we need it? To update permissions and grant users access

Create Microsoft Entra ID application

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. Generate a certificate and upload the public key file (.cer).

  7. Navigate to API permissions in the navigation bar on the left

  8. Click Add a permission and then select Microsoft Graph followed by Application permissions. Search for the 2 above mentioned scopes (i.e. -Sites.Selected, User.Read.All) and add them.

  9. Click Add a permission and then select SharePoint followed by Application permissions. Select the Sites.Selected permission and add it.

  10. Click Grant admin consent for <application name>

  11. If the statuses of the granted permissions turn green, you're (almost) set!
    At this point, the api permissions should look like this:
    ​

Create and grant Sharepoint site

Next, we need to grant the newly created Microsoft Entra ID application access to a SharePoint Site. Create a new sharepoint site, this can be a standard team site. Make sure to add a descriptive name, for example Go-To-Market key content.

Granting access can programmatically be achieved by using a client certificate or the SharePoint app invitation page. We highly recommend using a client certificate since this is more future proof.

Granting access using a client certificate

This can be achieved through several methods: Microsoft Graph API, PnP PowerShell, ... This example will use Microsoft Graph API in combination with curl.

  1. Create a new, temporary, Microsoft Entra ID Application. This application will be used to grant the other application access to the SharePoint site. This application should be deleted after the permission has been granted.

    • Add the Microsoft Graph Application Permission Sites.FullControl.All

    • Add a new client secret and store the value.

  2. Use the following curl command to retrieve an access token. This access token will be used in the next curl commands.
    ​

    curl -X POST \
      "https://login.microsoftonline.com/$TENANT_ID/oauth2/v2.0/token" \
      -H "Content-Type: application/x-www-form-urlencoded" \
      --data-urlencode "grant_type=client_credentials" \
      --data-urlencode "client_id=$CLIENT_ID" \
      --data-urlencode "client_secret=$CLIENT_SECRET" \
      --data-urlencode "scope=https://graph.microsoft.com/.default"

    Replace $TENANT_ID, $CLIENT_ID and $CLIENT_SECRET with the values of the temporary application, created in step 1. Make sure to also store the value of the access token.

  3. Use the following curl command to get the site ID of the SharePoint site (for example Go-To-Market key content).
    ​

    curl -X GET \
    "https://graph.microsoft.com/v1.0/sites/$TENANT_NAME.sharepoint.com:/sites/go-to-marketkeycontent" \
      -H "Authorization: Bearer $ACCESS_TOKEN"

    Replace $TENANT_NAME with the name of the tenant. This can be found in the url of the newly created site. For example: https://xxxx.sharepoint.com/sites/go-to-marketkeycontent/ => xxxx is the $TENANT_NAME. $ACCESS_TOKEN is the access token retrieved in the previous step. Store the value of the site ID. If you used a different name for the site, replace go-to-marketkeycontent with the name of the site, but make sure to remove all the spaces.

  4. Use the following curl command to grant the Microsoft Entra ID Application fullcontrol access to the SharePoint site.

    curl -X POST \
      https://graph.microsoft.com/v1.0/sites/$SITE_ID/permissions \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -d '{
        "roles": ["fullcontrol"],
        "grantedToIdentities": [
          {
            "application": {
              "id": "$CLIENT_ID",
              "displayName": "uman"
            }
          }
        ]
      }'

    Replace $SITE_ID with the site ID retrieved in the previous step and $ACCESS_TOKEN with the access token retrieved in step 2. Replace $CLIENT_ID with the client ID of the Microsoft Entra ID Application that has the Sites.Selected permission.

  5. The connection has been succesfully set up, you can now delete the temporary application.

Let the uman team know that the steps were executed successfully and provide the url of the newly created site, the application (client) ID, directory (tenant) ID and certificate private key in a very secure manner to the uman person you are in contact with.

Granting access using the SharePoint app invitation page

This is a deprecated approach and highly discouraged

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 certificate private key 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

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 Drive

  • https://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:

  1. Create a new Shared Drive Go-To-Market key content

  2. Retrieve the service account email address and identifier from the uman team

  3. Grant the service account the Manager access role to the newly created Shared Drive

  4. Grant the service account the aforementioned domain-wide scopes

  5. 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.

Did this answer your question?