Skip to content

Commit 4914d14

Browse files
ttorblettorble
authored
Merge pull request #285782 from v-luckywang/0829-Update_spo_spn
[ADF][New feature] Update SharePoint Online List SPN Cert
2 parents 94e8af6 + 84cf94b commit 4914d14

File tree

2 files changed

+76
-38
lines changed

2 files changed

+76
-38
lines changed

‎articles/data-factory/connector-sharepoint-online-list.md

Lines changed: 76 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ author: jianleishen
66
ms.subservice: data-movement
77
ms.custom: synapse
88
ms.topic: conceptual
9-
ms.date: 01/05/2024
9+
ms.date: 08/29/2024
1010
ms.author: jianleishen
1111
---
1212
# Copy data from SharePoint Online List by using Azure Data Factory or Azure Synapse Analytics
@@ -33,38 +33,6 @@ Specifically, this SharePoint List Online connector uses service principal authe
3333
> [!TIP]
3434
> This connector supports copying data from SharePoint Online **List** but not file. Learn how to copy file from [Copy file from SharePoint Online](#copy-file-from-sharepoint-online) section.
3535
36-
## Prerequisites
37-
38-
The SharePoint List Online connector uses service principal authentication to connect to SharePoint. Follow these steps to set it up:
39-
40-
1. Register an application with the Microsoft identity platform. To learn how, see [Quickstart: Register an application with the Microsoft identity platform](../active-directory/develop/quickstart-register-app.md). Make note of these values, which you use to define the linked service:
41-
42-
- Application ID
43-
- Application key
44-
- Tenant ID
45-
46-
2. Grant SharePoint Online site permission to your registered application by following the steps below. To do this, you need a site admin role.
47-
48-
1. Open your SharePoint Online site link. For example, the URL in the format `https://<your-site-url>/_layouts/15/appinv.aspx` where the placeholder `<your-site-url>` is your site.
49-
2. Search the application ID you registered, fill the empty fields, and click "Create".
50-
51-
- App Domain: `contoso.com`
52-
- Redirect URL: `https://www.contoso.com`
53-
- Permission Request XML:
54-
55-
```xml
56-
<AppPermissionRequests AllowAppOnlyPolicy="true">
57-
<AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web" Right="Read"/>
58-
</AppPermissionRequests>
59-
```
60-
61-
:::image type="content" source="media/connector-sharepoint-online-list/sharepoint-online-grant-permission-admin.png" alt-text="Grant SharePoint Online site permission to your registered application when you have site admin role.":::
62-
63-
> [!NOTE]
64-
> In the context of configuring the SharePoint connector, the "App Domain" and "Redirect URL" refer to the SharePoint app that you have registered in Microsoft Entra ID to allow access to your SharePoint data. The "App Domain" is the domain where your SharePoint site is hosted. For example, if your SharePoint site is located at "https://contoso.sharepoint.com", then the "App Domain" would be "contoso.sharepoint.com". The "Redirect URL" is the URL that the SharePoint app will redirect to after the user has authenticated and granted permissions to the app. This URL should be a page on your SharePoint site that the app has permission to access. For example, you could use the URL of a page that displays a list of files in a library, or a page that displays the contents of a document.
65-
66-
3. Click "Trust It" for this app.
67-
6836
## Get started
6937

7038
[!INCLUDE [data-factory-v2-connector-get-started](includes/data-factory-v2-connector-get-started.md)]
@@ -103,13 +71,18 @@ The following properties are supported for a SharePoint Online List linked servi
10371
| ------------------- | ------------------------------------------------------------ | ------------ |
10472
| type | The type property must be set to: **SharePointOnlineList**. | Yes |
10573
| siteUrl | The SharePoint Online site url, e.g. `https://contoso.sharepoint.com/sites/siteName`. | Yes |
106-
| servicePrincipalId | The Application (client) ID of the application registered in Microsoft Entra ID. Refer to [Prerequisites](#prerequisites) for more details including the permission settings.| Yes |
107-
| servicePrincipalKey | The application's key. Mark this field as a **SecureString** to store it securely, or [reference a secret stored in Azure Key Vault](store-credentials-in-key-vault.md). | Yes |
74+
| servicePrincipalId | The Application (client) ID of the application registered in Microsoft Entra ID. | Yes |
75+
| servicePrincipalCredentialType | Specify the credential type to use for service principal authentication. Allowed values are `ServicePrincipalKey` and `ServicePrincipalCert`. | No |
76+
| ***For ServicePrincipalKey*** | | |
77+
| servicePrincipalKey | The application's key. Mark this field as a **SecureString** to store it securely, or [reference a secret stored in Azure Key Vault](store-credentials-in-key-vault.md). Refer to this [section](#grant-permission-for-using-service-principal-key) for more details including the permission settings. | No |
78+
| ***For ServicePrincipalCert*** | | |
79+
| servicePrincipalEmbeddedCert | Specify the base64 encoded certificate of your application registered in Microsoft Entra ID, and ensure the certificate content type is **PKCS #12**. Mark this field as a **SecureString** to store it securely, or [reference a secret stored in Azure Key Vault](store-credentials-in-key-vault.md). Refer to this [article](/sharepoint/dev/solution-guidance/security-apponly-azuread) for permission settings.| No |
80+
| servicePrincipalEmbeddedCertPassword | Specify the password of your certificate if your certificate is secured with a password. Mark this field as a **SecureString** to store it securely, or [reference a secret stored in Azure Key Vault](store-credentials-in-key-vault.md). | No |
81+
| | | |
10882
| tenantId | The tenant ID under which your application resides. | Yes |
10983
| connectVia | The [Integration Runtime](concepts-integration-runtime.md) to use to connect to the data store. If not specified, the default Azure Integration Runtime is used. | No |
11084

111-
112-
**Example:**
85+
**Example 1: Using service principal key authentication**
11386

11487
```json
11588
{
@@ -119,16 +92,81 @@ The following properties are supported for a SharePoint Online List linked servi
11992
"typeProperties": {
12093
"siteUrl": "<site URL>",
12194
"servicePrincipalId": "<service principal id>",
95+
"servicePrincipalCredentialType": "ServicePrincipalKey",
12296
"servicePrincipalKey": {
12397
"type": "SecureString",
12498
"value": "<service principal key>"
12599
},
126100
"tenantId": "<tenant ID>"
101+
},
102+
"connectVia": {
103+
"referenceName": "<name of Integration Runtime>",
104+
"type": "IntegrationRuntimeReference"
127105
}
128106
}
129107
}
130108
```
131109

110+
**Example 2: Using service principal certificate authentication**
111+
112+
```json
113+
{
114+
"name": "SharePointOnlineList",
115+
"properties": {
116+
"type": "SharePointOnlineList",
117+
"typeProperties": {
118+
"siteUrl": "<site URL>",
119+
"servicePrincipalId": "<service principal id>",
120+
"servicePrincipalCredentialType": "ServicePrincipalCert",
121+
"servicePrincipalEmbeddedCert": {
122+
"type": "SecureString",
123+
"value": "<base64 encoded string of (.pfx) certificate data>"
124+
},
125+
"servicePrincipalEmbeddedCertPassword": {
126+
"type": "SecureString",
127+
"value": "<password of your certificate>"
128+
},
129+
"tenantId": "<tenant ID>"
130+
},
131+
"connectVia": {
132+
"referenceName": "<name of Integration Runtime>",
133+
"type": "IntegrationRuntimeReference"
134+
}
135+
}
136+
}
137+
```
138+
### Grant permission for using service principal key
139+
140+
The SharePoint List Online connector uses service principal authentication to connect to SharePoint. Follow these steps to set it up:
141+
142+
1. Register an application with the Microsoft identity platform. To learn how, see [Quickstart: Register an application with the Microsoft identity platform](../active-directory/develop/quickstart-register-app.md). Make note of these values, which you use to define the linked service:
143+
144+
- Application ID
145+
- Application key
146+
- Tenant ID
147+
148+
2. Grant SharePoint Online site permission to your registered application by following the steps below. To do this, you need a site admin role.
149+
150+
1. Open your SharePoint Online site link. For example, the URL in the format `https://<your-site-url>/_layouts/15/appinv.aspx` where the placeholder `<your-site-url>` is your site.
151+
2. Search the application ID you registered, fill the empty fields, and click "Create".
152+
153+
- App Domain: `contoso.com`
154+
- Redirect URL: `https://www.contoso.com`
155+
- Permission Request XML:
156+
157+
```xml
158+
<AppPermissionRequests AllowAppOnlyPolicy="true">
159+
<AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web" Right="Read"/>
160+
</AppPermissionRequests>
161+
```
162+
163+
:::image type="content" source="media/connector-sharepoint-online-list/sharepoint-online-grant-permission-admin.png" alt-text="Grant SharePoint Online site permission to your registered application when you have site admin role.":::
164+
165+
> [!NOTE]
166+
> In the context of configuring the SharePoint connector, the "App Domain" and "Redirect URL" refer to the SharePoint app that you have registered in Microsoft Entra ID to allow access to your SharePoint data. The "App Domain" is the domain where your SharePoint site is hosted. For example, if your SharePoint site is located at "https://contoso.sharepoint.com", then the "App Domain" would be "contoso.sharepoint.com". The "Redirect URL" is the URL that the SharePoint app will redirect to after the user has authenticated and granted permissions to the app. This URL should be a page on your SharePoint site that the app has permission to access. For example, you could use the URL of a page that displays a list of files in a library, or a page that displays the contents of a document.
167+
168+
3. Click "Trust It" for this app.
169+
132170
## Dataset properties
133171

134172
For a full list of sections and properties that are available for defining datasets, see [Datasets and linked services](concepts-datasets-linked-services.md). The following section provides a list of the properties supported by the SAP table dataset.
@@ -235,7 +273,7 @@ You can copy file from SharePoint Online by using **Web activity** to authentica
235273

236274
:::image type="content" source="media/connector-sharepoint-online-list/sharepoint-online-copy-file-flow.png" alt-text="sharepoint copy file flow":::
237275

238-
1. Follow the [Prerequisites](#prerequisites) section to create Microsoft Entra application and grant permission to SharePoint Online.
276+
1. Follow the [Grant permission for using service principal key](#grant-permission-for-using-service-principal-key) section to create Microsoft Entra application and grant permission to SharePoint Online.
239277

240278
2. Create a **Web Activity** to get the access token from SharePoint Online:
241279

‎articles/data-factory/media/connector-sharepoint-online-list/configure-sharepoint-online-list-linked-service.png

10.6 KB
Loading

0 commit comments

Comments
 (0)