From 401c5be9eff23ffc8f4eece93677e0844eefbf35 Mon Sep 17 00:00:00 2001 From: Artem Shelkovnikov Date: Fri, 10 Jan 2025 12:01:07 +0100 Subject: [PATCH 1/4] Update Sharepoint Online connector documentation --- .../connectors-sharepoint-online.asciidoc | 57 ++++++++++++++----- 1 file changed, 43 insertions(+), 14 deletions(-) diff --git a/docs/reference/connector/docs/connectors-sharepoint-online.asciidoc b/docs/reference/connector/docs/connectors-sharepoint-online.asciidoc index 2680e3ff840a6..1fa258674a771 100644 --- a/docs/reference/connector/docs/connectors-sharepoint-online.asciidoc +++ b/docs/reference/connector/docs/connectors-sharepoint-online.asciidoc @@ -75,12 +75,10 @@ Follow these steps: * Leave the *Redirect URIs* blank for now. * *Register* the application. * Find and keep the **Application (client) ID** and **Directory (tenant) ID** handy. -* Locate the **Secret** by navigating to **Client credentials: Certificates & Secrets**. -* Select **New client secret** -* Pick a name for your client secret. -Select an expiration date. (At this expiration date, you will need to generate a new secret and update your connector configuration.) -** Save the client secret **Secret ID** before leaving this screen. -** Save the client secret **Value** before leaving this screen. +* Create a certificate and private key. This can, for example, be done by running `openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout azure_app.key -out azure_app.crt` command. Store both in a safe and secure place +* Locate the **Certificates** by navigating to **Client credentials: Certificates & Secrets**. +* Select **Upload certificate** +* Upload the certificate created in one of previous steps: `azure_app.crt` * Set up the permissions the OAuth App will request from the Azure Portal service account. ** Navigate to **API Permissions** and click **Add Permission**. ** Add **application permissions** until the list looks like the following: @@ -114,6 +112,18 @@ When entities are not available via the Graph API the connector falls back to us [discrete#es-connectors-sharepoint-online-oauth-app-permissions] ====== SharePoint permissions +Microsoft is retiring Azure ACS: https://learn.microsoft.com/en-us/sharepoint/dev/sp-add-ins/retirement-announcement-for-azure-acs. Because of that, setting up permissions for new tenants and for old tenants can be different. We recommend switching to usage of certificates for older tenants too, but if it's not yet possible, a legacy permission setup can still be used. + +[discrete#es-connectors-sharepoint-online-oauth-app-certificate-auth] +===== Certificate Authentication + +This authentication method does not require additional setup other than creating and uploading certificates to the OAuth App. + +[discrete#es-connectors-sharepoint-online-oauth-app-secret-auth] +===== Secret Authentication + +This method is only applicable to tenants created before November 1st, 2024. This method will be fully retired as of April 2nd, 2026. + Refer to the following documentation for setting https://learn.microsoft.com/en-us/sharepoint/dev/solution-guidance/security-apponly-azureacs[SharePoint permissions^]. * To set `DisableCustomAppAuthentication` to false, connect to SharePoint using PowerShell and run `set-spotenant -DisableCustomAppAuthentication $false` @@ -219,8 +229,17 @@ The tenant name for the Azure account hosting the Sharepoint Online instance. Client ID:: The client id to authenticate with SharePoint Online. +Authentication Method:: +Authentication method to use to connector to Sharepoint Online and Rest APIs. `secret` is deprecated and `certificate` is recommended. + Secret value:: -The secret value to authenticate with SharePoint Online. +The secret value to authenticate with SharePoint Online, if Authentication Method: `secret` is chosen. + +Content of certificate file:: +Content of certificate file if Authentication Method: `certificate` is chosen. + +Content of private key file:: +Content of private key file if Authentication Method: `certificate` is chosen. Comma-separated list of sites:: List of site collection names or paths to fetch from SharePoint. @@ -588,12 +607,10 @@ Follow these steps: * Leave the *Redirect URIs* blank for now. * *Register* the application. * Find and keep the **Application (client) ID** and **Directory (tenant) ID** handy. -* Locate the **Secret** by navigating to **Client credentials: Certificates & Secrets**. -* Select **New client secret** -* Pick a name for your client secret. -Select an expiration date. (At this expiration date, you will need to generate a new secret and update your connector configuration.) -** Save the client secret **Secret ID** before leaving this screen. -** Save the client secret **Value** before leaving this screen. +* Create a certificate and private key. This can, for example, be done by running `openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout azure_app.key -out azure_app.crt` command. Store both in a safe and secure place +* Locate the **Certificates** by navigating to **Client credentials: Certificates & Secrets**. +* Select **Upload certificate** +* Upload the certificate created in one of previous steps: `azure_app.crt` * Set up the permissions the OAuth App will request from the Azure Portal service account. ** Navigate to **API Permissions** and click **Add Permission**. ** Add **application permissions** until the list looks like the following: @@ -624,9 +641,21 @@ The connector uses the https://learn.microsoft.com/en-us/sharepoint/dev/apis/sha When entities are not available via the Graph API the connector falls back to using the Sharepoint https://learn.microsoft.com/en-us/sharepoint/dev/sp-add-ins/get-to-know-the-sharepoint-rest-service[REST API^]. ==== -[discrete#es-connectors-sharepoint-online-client-oauth-app-permissions] +[discrete#es-connectors-sharepoint-online-oauth-app-permissions] ====== SharePoint permissions +Microsoft is retiring Azure ACS: https://learn.microsoft.com/en-us/sharepoint/dev/sp-add-ins/retirement-announcement-for-azure-acs. Because of that, setting up permissions for new tenants and for old tenants can be different. We recommend switching to usage of certificates for older tenants too, but if it's not yet possible, a legacy permission setup can still be used. + +[discrete#es-connectors-sharepoint-online-oauth-app-certificate-auth] +===== Certificate Authentication + +This authentication method does not require additional setup other than creating and uploading certificates to the OAuth App. + +[discrete#es-connectors-sharepoint-online-oauth-app-secret-auth] +===== Secret Authentication + +This method is only applicable to tenants created before November 1st, 2024. This method will be fully retired as of April 2nd, 2026. + Refer to the following documentation for setting https://learn.microsoft.com/en-us/sharepoint/dev/solution-guidance/security-apponly-azureacs[SharePoint permissions^]. * To set `DisableCustomAppAuthentication` to false, connect to SharePoint using PowerShell and run `set-spotenant -DisableCustomAppAuthentication $false` From 2e377d147aacb1431ea08370001ed8d5bfba2d1c Mon Sep 17 00:00:00 2001 From: Artem Shelkovnikov Date: Fri, 10 Jan 2025 12:04:15 +0100 Subject: [PATCH 2/4] Update connectors-sharepoint-online.asciidoc --- .../docs/connectors-sharepoint-online.asciidoc | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/reference/connector/docs/connectors-sharepoint-online.asciidoc b/docs/reference/connector/docs/connectors-sharepoint-online.asciidoc index 1fa258674a771..f40c415ab5cb9 100644 --- a/docs/reference/connector/docs/connectors-sharepoint-online.asciidoc +++ b/docs/reference/connector/docs/connectors-sharepoint-online.asciidoc @@ -771,8 +771,17 @@ The tenant name for the Azure account hosting the Sharepoint Online instance. `client_id`:: The client id to authenticate with SharePoint Online. +`auth_method`:: +Authentication method to use to connector to Sharepoint Online and Rest APIs. `secret` is deprecated and `certificate` is recommended. + `secret_value`:: -The secret value to authenticate with SharePoint Online. +The secret value to authenticate with SharePoint Online, if auth_method: `secret` is chosen. + +`certificate`:: +Content of certificate file if auth_method: `certificate` is chosen. + +`private_key`:: +Content of private key file if auth_method: `certificate` is chosen. `site_collections`:: List of site collection names or paths to fetch from SharePoint. From a0278845e7f4f35bb15f63a0f4ef717b6b1ba81b Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Fri, 10 Jan 2025 14:47:21 +0100 Subject: [PATCH 3/4] Apply suggestions from code review --- .../docs/connectors-sharepoint-online.asciidoc | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/docs/reference/connector/docs/connectors-sharepoint-online.asciidoc b/docs/reference/connector/docs/connectors-sharepoint-online.asciidoc index f40c415ab5cb9..8625236c41523 100644 --- a/docs/reference/connector/docs/connectors-sharepoint-online.asciidoc +++ b/docs/reference/connector/docs/connectors-sharepoint-online.asciidoc @@ -112,7 +112,10 @@ When entities are not available via the Graph API the connector falls back to us [discrete#es-connectors-sharepoint-online-oauth-app-permissions] ====== SharePoint permissions -Microsoft is retiring Azure ACS: https://learn.microsoft.com/en-us/sharepoint/dev/sp-add-ins/retirement-announcement-for-azure-acs. Because of that, setting up permissions for new tenants and for old tenants can be different. We recommend switching to usage of certificates for older tenants too, but if it's not yet possible, a legacy permission setup can still be used. +Microsoft is https://learn.microsoft.com/en-us/sharepoint/dev/sp-add-ins/retirement-announcement-for-azure-acs[retiring Azure Access Control Service (ACS)]. This affects permission configuration: + +* *Tenants created after November 1st, 2024*: Certificate authentication is required +* *Tenants created before November 1st, 2024*: Secret-based authentication must be migrated to certificate authentication by April 2nd, 2026 [discrete#es-connectors-sharepoint-online-oauth-app-certificate-auth] ===== Certificate Authentication @@ -641,17 +644,19 @@ The connector uses the https://learn.microsoft.com/en-us/sharepoint/dev/apis/sha When entities are not available via the Graph API the connector falls back to using the Sharepoint https://learn.microsoft.com/en-us/sharepoint/dev/sp-add-ins/get-to-know-the-sharepoint-rest-service[REST API^]. ==== -[discrete#es-connectors-sharepoint-online-oauth-app-permissions] +[discrete#es-connectors-sharepoint-online-client-oauth-app-permissions] ====== SharePoint permissions -Microsoft is retiring Azure ACS: https://learn.microsoft.com/en-us/sharepoint/dev/sp-add-ins/retirement-announcement-for-azure-acs. Because of that, setting up permissions for new tenants and for old tenants can be different. We recommend switching to usage of certificates for older tenants too, but if it's not yet possible, a legacy permission setup can still be used. +Microsoft is https://learn.microsoft.com/en-us/sharepoint/dev/sp-add-ins/retirement-announcement-for-azure-acs[retiring Azure Access Control Service (ACS)]. This affects permission configuration: +* *Tenants created after November 1st, 2024*: Certificate authentication is required +* *Tenants created before November 1st, 2024*: Secret-based authentication must be migrated to certificate authentication by April 2nd, 2026 -[discrete#es-connectors-sharepoint-online-oauth-app-certificate-auth] +[discrete#es-connectors-sharepoint-online-client-oauth-app-certificate-auth] ===== Certificate Authentication This authentication method does not require additional setup other than creating and uploading certificates to the OAuth App. -[discrete#es-connectors-sharepoint-online-oauth-app-secret-auth] +[discrete#es-connectors-sharepoint-online-client-oauth-app-secret-auth] ===== Secret Authentication This method is only applicable to tenants created before November 1st, 2024. This method will be fully retired as of April 2nd, 2026. From 980be953f9eb8969d1e4e9aa4baef2b2ebc1a9ef Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Fri, 10 Jan 2025 15:29:35 +0100 Subject: [PATCH 4/4] Use callout --- .../connector/docs/connectors-sharepoint-online.asciidoc | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/reference/connector/docs/connectors-sharepoint-online.asciidoc b/docs/reference/connector/docs/connectors-sharepoint-online.asciidoc index 8625236c41523..d09e089f194ad 100644 --- a/docs/reference/connector/docs/connectors-sharepoint-online.asciidoc +++ b/docs/reference/connector/docs/connectors-sharepoint-online.asciidoc @@ -125,7 +125,10 @@ This authentication method does not require additional setup other than creating [discrete#es-connectors-sharepoint-online-oauth-app-secret-auth] ===== Secret Authentication +[IMPORTANT] +==== This method is only applicable to tenants created before November 1st, 2024. This method will be fully retired as of April 2nd, 2026. +==== Refer to the following documentation for setting https://learn.microsoft.com/en-us/sharepoint/dev/solution-guidance/security-apponly-azureacs[SharePoint permissions^]. @@ -659,7 +662,10 @@ This authentication method does not require additional setup other than creating [discrete#es-connectors-sharepoint-online-client-oauth-app-secret-auth] ===== Secret Authentication +[IMPORTANT] +==== This method is only applicable to tenants created before November 1st, 2024. This method will be fully retired as of April 2nd, 2026. +==== Refer to the following documentation for setting https://learn.microsoft.com/en-us/sharepoint/dev/solution-guidance/security-apponly-azureacs[SharePoint permissions^].