Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

New article - Create Azure functions for SharePoint webhooks using an azd template #10118

Merged
merged 23 commits into from
Mar 5, 2025
Merged
Changes from 1 commit
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
40d4fab
Create sharepoint-webhooks-using-azd-template.md
Yvand Jan 31, 2025
0280a8b
Update sharepoint-webhooks-using-azd-template.md
Yvand Feb 5, 2025
c9254e0
Update sharepoint-webhooks-using-azd-template.md
Yvand Feb 5, 2025
b410108
Update sharepoint-webhooks-using-azd-template.md
Yvand Feb 5, 2025
07314ad
Update sharepoint-webhooks-using-azd-template.md
Yvand Feb 10, 2025
02a0b66
Update sharepoint-webhooks-using-azd-template.md
Yvand Feb 10, 2025
d161b1a
Update sharepoint-webhooks-using-azd-template.md
Yvand Feb 10, 2025
b16395c
Update sharepoint-webhooks-using-azd-template.md
Yvand Feb 11, 2025
363ff5a
Update sharepoint-webhooks-using-azd-template.md
Yvand Feb 11, 2025
53f2c53
Update sharepoint-webhooks-using-azd-template.md
Yvand Feb 14, 2025
83c4281
Update sharepoint-webhooks-using-azd-template.md
Yvand Feb 17, 2025
e69a919
replace absolute links to learn site
Yvand Feb 17, 2025
ee30ad5
fix warning
Yvand Feb 17, 2025
d73ebdc
grammatical & markdown fixes
andrewconnell Feb 19, 2025
8a7effc
Update sharepoint-webhooks-using-azd-template.md
Yvand Feb 26, 2025
1dc96bb
Update sharepoint-webhooks-using-azd-template.md
Yvand Feb 26, 2025
4459b04
Update sharepoint-webhooks-using-azd-template.md
Yvand Feb 27, 2025
dbb476c
Update sharepoint-webhooks-using-azd-template.md
Yvand Feb 27, 2025
3442cc3
Update sharepoint-webhooks-using-azd-template.md
Yvand Feb 27, 2025
086c12f
Update sharepoint-webhooks-using-azd-template.md
Yvand Feb 27, 2025
9ed7854
Update sharepoint-webhooks-using-azd-template.md
Yvand Feb 27, 2025
a11a23c
copy & format edits
andrewconnell Feb 27, 2025
53326b3
Update sharepoint-webhooks-using-azure-functions.md
Yvand Feb 27, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
grammatical & markdown fixes
- typos
- links shouldn't point to "this", rather be descriptive
- markdown fixes
  - paragraphs should be seperated by newlines
  - bullets should be `-`, not `+`
andrewconnell authored Feb 19, 2025
commit d73ebdcb7a8df826bb1b56d8a579e2f5e7a3eace
34 changes: 22 additions & 12 deletions docs/apis/webhooks/sharepoint-webhooks-using-azd-template.md
Original file line number Diff line number Diff line change
@@ -7,21 +7,21 @@ ms.localizationpriority: low
# Azure functions for SharePoint webhooks using azd

[Azure Developer CLI (azd)](https://aka.ms/azd) is an open-source tool that accelerates provisioning and deploying app resources in Azure.
This article uses [this azd template](https://github.com/Azure-Samples/azd-functions-sharepoint-webhooks) to deploy an Azure function app that connects to your SharePoint Online tenant, to register and manage [webhooks](overview-sharepoint-webhooks.md), and process the notifications from SharePoint.
This article uses the [Azure function app for SharePoint webhooks public template](https://github.com/Azure-Samples/azd-functions-sharepoint-webhooks) to deploy an Azure function app that connects to your SharePoint Online tenant, to register and manage [webhooks](overview-sharepoint-webhooks.md), and process the notifications from SharePoint.

## Prerequisites

+ [Node.js 20](https://www.nodejs.org/)
+ [Azure Functions Core Tools](/azure/azure-functions/functions-run-local?pivots=programming-language-typescript#install-the-azure-functions-core-tools)
+ [Azure Developer CLI (azd)](/azure/developer/azure-developer-cli/install-azd)
+ An Azure subscription trusting the same Entra ID directory as your SharePoint tenant
- [Node.js 20](https://www.nodejs.org/)
- [Azure Functions Core Tools](/azure/azure-functions/functions-run-local?pivots=programming-language-typescript#install-the-azure-functions-core-tools)
- [Azure Developer CLI (azd)](/azure/developer/azure-developer-cli/install-azd)
- An Azure subscription trusting the same Entra ID directory as your SharePoint tenant

## Permissions required to provision the resources in Azure

The account running `azd` must have at least the following roles to successfully provision the resources:

+ Azure role [`Contributor`](/azure/role-based-access-control/built-in-roles/privileged#contributor): To create all the resources needed
+ Azure role [`Role Based Access Control Administrator`](/azure/role-based-access-control/built-in-roles/privileged#role-based-access-control-administrator): To assign roles (to access the storage account and Application Insights) to the managed identity of the function app
- Azure role [`Contributor`](/azure/role-based-access-control/built-in-roles/privileged#contributor): To create all the resources needed
- Azure role [`Role Based Access Control Administrator`](/azure/role-based-access-control/built-in-roles/privileged#role-based-access-control-administrator): To assign roles (to access the storage account and Application Insights) to the managed identity of the function app

## Deploy the function app in Azure

@@ -35,24 +35,28 @@ The account running `azd` must have at least the following roles to successfully

1. Open the file `infra/main.parameters.json`, and set the variables `TenantPrefix` and `SiteRelativePath` to match your SharePoint tenant.

Review [this article](/azure/developer/azure-developer-cli/manage-environment-variables) to manage the azd's environment variables.
Review the article on [Manage environment variables](/azure/developer/azure-developer-cli/manage-environment-variables) to manage the azd's environment variables.

1. Finally, run the command `azd up` to build the app, provision the resources in Azure and deploy the app package.

## Grant the function app access to SharePoint Online

The authentication to SharePoint is done using `DefaultAzureCredential`, so the credential used depends if the function app runs locally, or in Azure.
If you never heard about `DefaultAzureCredential`, you should familirize yourself with its concept by reading [this article](https://aka.ms/azsdk/js/identity/credential-chains#use-defaultazurecredential-for-flexibility).

If you never heard about `DefaultAzureCredential`, you should familiarize yourself with its concept by reading [this article](https://aka.ms/azsdk/js/identity/credential-chains#use-defaultazurecredential-for-flexibility).

### Using its managed identity

`DefaultAzureCredential` will use a managed identity to authenticate to SharePoint. This may be the existing, system-assigned managed identity of the function app service, or a user-assigned managed identity.
`DefaultAzureCredential` will use a managed identity to authenticate to SharePoint. This may be the existing, system-assigned managed identity of the function app service or a user-assigned managed identity.

This tutorial will assume that the system-assigned managed identity is used.

#### Grant the SharePoint API permission Sites.Selected to the managed identity

Navigate to your function app in [the Azure portal](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.Web%2Fsites/kind/functionapp) > click `Identity` and note the `Object (principal) ID` of the system-assigned managed identity.

In this tutorial, it is `d3e8dc41-94f2-4b0f-82ff-ed03c363f0f8`.

Then, use one of the scripts below to grant this identity the app-only permission `Sites.Selected` on the SharePoint API:

> [!IMPORTANT]
@@ -96,11 +100,14 @@ az rest --method POST --uri "https://graph.microsoft.com/v1.0/servicePrincipals/
#### Grant the managed identity effective access to a SharePoint site

Navigate to the [Enterprise applications](https://entra.microsoft.com/#view/Microsoft_AAD_IAM/StartboardApplicationsMenuBlade/) > Set the filter `Application type` to `Managed Identities` > Click on your managed identity and note its `Application ID`.

In this tutorial, it is `3150363e-afbe-421f-9785-9d5404c5ae34`.

Then, use one of the scripts below to grant it the app-only permission `manage` (minimum required to register a webhook) on a specific SharePoint site:

> [!IMPORTANT]
> The app registration used to run those scripts must have at least the following permissions:
>
> - Delegated permission `Application.ReadWrite.All` in the Graph API (requires admin consent)
> - Delegated permission `AllSites.FullControl` in the SharePoint API (requires admin consent)

@@ -131,8 +138,10 @@ m365 spo site apppermission add --appId $targetapp --permission manage --siteUrl

## Call the function app

For security reasons, when running in Azure, the function app requires an app key to pass in query string parameter `code`. The app keys can be found in the function app service > App Keys.
Most of the HTTP functions take optional parameters `tenantPrefix` and `siteRelativePath`. If they are not specified, the values in the app's environment variables ar used.
For security reasons, when running in Azure, the function app requires an app key to pass in the query string parameter `code`. The app keys can be found in the function app service's **App Keys** keys page.

Most of the HTTP functions take optional parameters `tenantPrefix` and `siteRelativePath`. If they are not specified, the values in the app's environment variables are used.

Below is a sample script in PowerShell to call the function app:

```powershell
@@ -161,6 +170,7 @@ Invoke-RestMethod -Method POST -Uri "https://${funchost}.azurewebsites.net/api/w
## Cleanup the resources in Azure

You can delete all the resources this project created in Azure, by running the command `azd down`.

Alternatively, you can delete the resource group, which has the azd environment's name by default.

## See also