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
What can we do with it? Read granted SharePoint site using graph api
Why do we need it? To upload uman-generated files
What can we do with it? Read users
Why do we need it? To retrieve file metadata
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:
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
Generate a certificate and upload the public key file (.cer).
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 2 above mentioned scopes (i.e. -Sites.Selected, User.Read.All) and add them.
Click Add a permission and then select SharePoint followed by Application permissions. Select the Sites.Selected permission and add it.
Click Grant admin consent for <application name>
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.
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.
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.
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, replacego-to-marketkeycontentwith the name of the site, but make sure to remove all the spaces.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.
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
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 certificate private key in a very secure manner to the uman person you are in contact with.
Grant admin consent
Users may encounter a "Need admin approval" prompt when first connecting. Admins can grant consent organization-wide:
Open Azure Portal: Navigate to the Microsoft Entra ID (Enterprise Applications) page.
Admin Consent Requests: In the left-hand menu, click Admin consent requests.
Approve uman: Locate the request for uman and click Approve to grant the required permissions.
If nothing shows up under 'My Pending,' make sure to check the 'All' reviews section as well.
If users still face issues after approval, ensure they (or a group they belong to) are added under Users and groups within the uman Enterprise Application in Entra ID.