Dodeca SharePoint Connector

Overview

The Dodeca SharePoint Connector provides connectivity to SharePoint Online and on-premises SharePoint sites. It is implemented as a native connector module and is imported into a Dodeca tenant like any other connector module.

The module provides three capabilities:

  • SharePointConnection — a reusable connection/authorization definition for a SharePoint site.

  • SharePointConnector — a DataSet connector that downloads a single SharePoint document and adapts it into a Dodeca DataSet (e.g., via an Excel or CSV adaptor).

  • SharePointOperations — a WorkbookScript method that uploads, downloads, lists, and deletes SharePoint documents, list items, and attachments from a workbook script.

Prerequisites

  • The connector module imported into the Dodeca tenant and the application restarted.

  • For the recommended authentication path (see below): the Microsoft Authorization Connector must be downloaded, imported into the Dodeca tenant, and the application restarted before a SharePoint connection can use it.

Authentication Modes

SharePointConnection supports two authentication approaches. Only the first is supported for new connections.

Mode Property Status

Microsoft Authorization Connector

OAuthConnectionID

Recommended

Direct (legacy) OAuth

TenantID / ClientID / ClientSecret / ClientCertificate / ClientCertificatePassword

Deprecated

Set OAuthConnectionID to the ID of a Microsoft Authorization Connector connection (an OAuthConnection of kind MicrosoftConnection). The Microsoft Authorization Connector performs the actual Entra ID (Azure AD) sign-in — interactive delegated login, client credentials, or certificate, depending on how that connection is configured — and SharePointConnection requests a token scoped to the SharePoint site from it.

Property Value

OAuthConnectionID

ID of a Microsoft Authorization Connector connection

SiteUrl

The SharePoint site URL, e.g. https://contoso.sharepoint.com/sites/finance

This path authenticates directly against the Microsoft identity platform (Entra ID) and is unaffected by the Azure ACS retirement described below.

Choosing App-Only vs. Delegated (Public Client) Authentication

Whether the Entra app registration behind a SharePoint connection is configured as app-only (confidential client) or delegated (public client) determines whose identity SharePoint sees for every operation this connector performs:

App-only (confidential client) Delegated (public client)

Credential

ClientSecret or ClientCertificate

None — no secret to protect

Acts as

The Entra app itself

The signed-in Dodeca user

SharePoint sees

The app’s identity for every operation

Each user’s own identity

Best suited to

A privileged, unattended system (e.g., a scheduled report/close-book generator) that can reasonably protect a secret

Arbitrary end users publishing to SharePoint through Dodeca, where no shared secret should need to be distributed to client workstations

If a ClientCertificate (or, formerly, ClientSecret) would otherwise need to be installed on every end-user workstation just so that arbitrary users can publish documents, that’s a sign the connection should be reconfigured as delegated/public client instead: Dodeca then publishes to SharePoint on the signed-in user’s behalf, and no secret needs to be protected on the client at all.

Redirect URI (reply URL) for delegated / public client apps

A public client Entra app registration needs a redirect URI (reply URL) of type "Mobile and desktop applications". Dodeca uses MSAL.NET, which by default targets the standard native-client redirect URI:

https://login.microsoftonline.com/common/oauth2/nativeclient

Register this exact URI on the Entra app registration and no further configuration is required — both the OAuthConnectionID (Microsoft Authorization Connector) path and the legacy direct SharePointConnection delegated path (OAuthInteractive, or neither ClientSecret nor ClientCertificate set) use it automatically via MSAL’s default redirect URI.

Only the OAuthConnectionID path supports overriding this with an arbitrary custom redirect URI, via the RedirectUri property on the Microsoft Authorization Connector connection — set it there and register the matching value on the Entra app registration. The legacy direct SharePointConnection properties have no equivalent override and always use the MSAL default.

Granting Sites.Selected Access to a Specific SharePoint Site

When the Entra app registration behind a SharePoint connection uses the Sites.Selected permission — recommended over tenant-wide Sites.Read.All/Sites.ReadWrite.All — configuration is a two-step process, and both steps are required:

  1. Consent to the Sites.Selected permission on the app registration in Entra ID. Note that Sites.Selected exists on two API resources — Microsoft Graph and SharePoint (Office 365 SharePoint Online). This connector calls SharePoint directly (CSOM/REST with SharePoint-audience tokens), so the SharePoint Sites.Selected permission is the one that gates its calls; consenting the Graph one as well is harmless and covers Graph-based tooling.

  2. Grant the app access to each specific site, with a role, via the Microsoft Graph site permissions endpoint. An app registration with Sites.Selected consented but no site grants has access to no sites at all — that is the designed behavior of the permission, not a misconfiguration.

The roles that can be granted per site:

Role Allows

read

Reading the metadata and contents of the site’s lists and libraries

write

Everything read allows, plus creating and modifying content — the minimum for publishing documents with SharePointOperations (AddDocument, AddAttachment, AddListItem, and the Delete* overloads)

owner / fullcontrol

Full control of the site

An administrator can create and verify grants with PnP PowerShell:

# Inspect the grants that already exist on the connected site
Get-PnPAzureADAppSitePermission

# Grant the app read+write access to a specific site
Grant-PnPAzureADAppSitePermission -AppId <client-id> -DisplayName "<app display name>" `
    -Permissions Write -Site https://contoso.sharepoint.com/sites/finance

or by calling the Graph endpoint directly:

POST https://graph.microsoft.com/v1.0/sites/{siteId}/permissions
Content-Type: application/json

{
  "roles": ["write"],
  "grantedToIdentities": [
    { "application": { "id": "<client-id>", "displayName": "<app display name>" } }
  ]
}

Creating a site-level grant is itself a privileged operation: the identity making the call needs Sites.FullControl.All (or to be a sufficiently privileged SharePoint/tenant administrator signing in interactively with PnP PowerShell).

Delegated connections intersect with the user’s own permissions. For a delegated (public client) connection, effective access is the intersection of the signed-in user’s SharePoint permissions and the app’s site grant — the app can never exceed the user, and the user can never exceed the app’s grant through Dodeca. In particular, "the user can browse to the library and upload manually" demonstrates the user’s access only; it says nothing about whether the app has a grant.

Symptom of a missing (or read-only) site grant: the connection test can report success while every document library and list operation fails with The specified document library or path could not be found. — regardless of the path used, including paths that resolve fine in a browser. The connection test verifies only that the signed-in identity can open the site, and SharePoint reports folders the app cannot access as non-existent rather than as access denied. If a path has been verified in a browser and operations still report it as not found, check the site grant before debugging the path.

Deprecated: direct OAuth properties

TenantID, ClientID, ClientSecret, ClientCertificate, and ClientCertificatePassword are legacy properties retained for backward compatibility with connections created before the Microsoft Authorization Connector existed. They are hidden in the property grid unless already populated, and new connections should use OAuthConnectionID instead. When OAuthConnectionID is not set, the connection falls back to one of three direct token-acquisition flows depending on which properties are populated:

If set Flow used Identity platform

ClientSecret

App-only token via Azure ACS (https://accounts.accesscontrol.windows.net)

Azure ACS — being retired, see below

ClientCertificate (and no ClientSecret)

Entra ID app-only token via MSAL confidential client, using TenantID + ClientID + the certificate

Entra ID (Azure AD)

Neither

Entra ID delegated token via MSAL public client (interactive sign-in, with silent/cached retry), using TenantID + ClientID

Entra ID (Azure AD)

⚠ Azure ACS Retirement and This Connector

Microsoft has been retiring Azure Access Control Service (ACS), the legacy accounts.accesscontrol.windows.net app-only authentication mechanism originally used by SharePoint Add-ins and script-based app-only principals. Per Microsoft’s retirement announcement, ACS stopped issuing tokens for new tenants on November 1, 2024, and was fully retired for all remaining tenants on April 2, 2026 — a date that has now passed. SharePoint Online app-only connections that rely on an ACS-issued token stop authenticating once retirement takes effect for a given tenant, regardless of client code; there is no workaround short of switching to a non-ACS credential flow. See Microsoft’s retirement FAQ if you need to confirm rollout status for a specific tenant.

This connector has exactly one code path that depends on Azure ACS: the ClientSecret-based flow (SharePointConnection.ClientSecret set, or the WorkbookScript AuthenticationPolicy=OAuthClientSecret). Internally this calls AcsTokenHelper against https://accounts.accesscontrol.windows.net to obtain an app-only token using a ClientID/ClientSecret pair registered as a SharePoint "Add-in" (S2S) principal. This flow is deprecated in the connector’s metadata and should not be used for new connections against SharePoint Online. Given the April 2, 2026 cutoff has passed, any connection still using this flow should be treated as non-functional (or at imminent risk, depending on tenant-level rollout) rather than merely deprecated.

Every other authentication path in this connector — the recommended OAuthConnectionID path, the ClientCertificate path, the OAuthInteractive/OAuthPassword delegated MSAL paths, and on-premises DefaultNetworkCredentials/SpecifiedCredentials — authenticates directly against Entra ID (Azure AD) or Windows-integrated auth, not Azure ACS, and is unaffected by the retirement.

If you currently have a SharePoint connection using ClientSecret (or AuthenticationPolicy=OAuthClientSecret): follow Microsoft’s ACS-to-Azure-AD upgrade guide alongside these connector-specific steps.

  1. Register (or reuse) an Entra ID app registration for the connector — see Granting access via Entra ID App-Only for the certificate-based app-only setup this connector expects.

  2. Either:

    • Import the Microsoft Authorization Connector and switch the SharePoint connection to OAuthConnectionID (recommended — this also gives you delegated or certificate-based app-only auth managed centrally), or

    • Add a certificate credential to the app registration and switch to ClientCertificate on the SharePointConnection (or AuthenticationPolicy=OAuthClientCertificate in the WorkbookScript method) as a drop-in app-only replacement.

  3. Grant the app registration SharePoint permissions under Entra ID/Microsoft Graph rather than the legacy SharePoint "Add-in" permissions model tied to ACS. Prefer the Sites.Selected permission over tenant-wide Sites.Read.All/Sites.ReadWrite.All where possible — it scopes the app registration to specific site collections, granted per-site via the Graph site permissions endpoint, rather than every site in the tenant. See "Granting Sites.Selected Access to a Specific SharePoint Site" above for the required per-site grant, without which the app registration has no access at all.

SharePointConnector (DataSet Connector)

Downloads a single document from a SharePoint document library and adapts its content stream into a DataSet using a configured IDataSetAdaptor (e.g., an Excel or delimited-text adaptor).

Property Value

ConnectionID

ID of the SharePointConnection used to authenticate

DocumentLibraryName

Name of the document library, e.g. Shared Documents

DocumentName

Name of the document to retrieve

Both DocumentLibraryName and DocumentName are required; the connector validates this before querying.

SharePointOperations (WorkbookScript Method)

Uploads, downloads, lists, and deletes SharePoint documents, list items, and attachments from a workbook script. The method is exposed to workbook scripts as SharePointOperations (headless) and to grid controls bound to a WorkbookView as WorkbookViewSharePointOperations, and is invoked via one of the overloads below.

Overload Description

AddAttachment

Uploads a local file as a list item attachment; replaces the attachment if it already exists

AddDocument

Uploads a local file to a document library; creates a new version if the document already exists

AddListItem

Adds a list item (by Title) if it doesn’t already exist; no-ops if it does

GetAttachment

Downloads a list item attachment to a local file

GetDocument

Downloads a document from a document library to a local file

GetListItems

Retrieves the item titles for a list into a DataCache

DeleteAttachment

Deletes a list item attachment

DeleteDocument

Deletes a document

DeleteListItem

Deletes a list item

ValidateCredentials

Validates that the resolved credentials can connect to and open the site

Each overload accepts a ConnectionID argument for the recommended SharePointConnection-based authentication path described above, plus a large set of legacy per-call arguments (SiteUrl, AuthenticationPolicy, TenantID, ClientID, ClientSecret, ClientCertificate, ClientCertificatePassword, Username, Password, Domain, SiteType) that are used only when ConnectionID is omitted. When ConnectionID is specified, all of the legacy arguments are ignored.

For the full argument reference for every overload, see the online documentation: https://developer.dodecasoftware.com/dodeca/SharePoint/wbs-methods-documentation.html

Legacy AuthenticationPolicy values (used only without ConnectionID)

AuthenticationPolicy Description Azure ACS dependency

DefaultNetworkCredentials

Uses the current Windows security context (NTLM/Negotiate/Kerberos). On-premises/extranet only.

None

SpecifiedCredentials

Uses Username, Password, and optionally Domain. On-premises/extranet only.

None

OAuthClientCertificate

Entra ID app-only token using TenantID + ClientID + ClientCertificate (+ optional ClientCertificatePassword).

None

OAuthInteractive

Entra ID delegated token using TenantID + ClientID, interactive with silent/cached retry.

None

OAuthPassword

Entra ID delegated token using ClientID + Username + Password (resource owner password flow).

None

OAuthClientSecret

App-only token using ClientID + ClientSecret against Azure ACS.

Yes — see retirement notice above

SiteType (Online, OnPrem, or Extranet) controls how DefaultNetworkCredentials/SpecifiedCredentials credentials are applied — Online uses SharePoint Online cookie-based auth, Extranet uses an explicit NTLM credential cache, and OnPrem passes the credential directly.

Client Certificate Formats

Wherever a client certificate is accepted (SharePointConnection.ClientCertificate, or the ClientCertificate WorkbookScript argument), the value may be any of:

  • A file path to a certificate file (optionally combined with ClientCertificatePassword).

  • A certificate thumbprint (40 or 64 hex characters), looked up first in CurrentUser\My, then LocalMachine\My.

  • A base64-encoded certificate byte array (optionally combined with ClientCertificatePassword).

Supported SharePoint Versions

The connector module is built separately for each SharePoint target, controlled by the SharePointVersion build property. Download the module build matching your SharePoint environment:

SharePointVersion Target

Online (default)

SharePoint Online / Microsoft 365

Standard

SharePoint Online, built against the netstandard2.0 CSOM libraries

2019

On-premises SharePoint Server 2019 (and later on-prem releases using the same CSOM surface)

2016

On-premises SharePoint Server 2016

2013

On-premises SharePoint Server 2013

On SharePoint 2013 and 2016, DocumentLibraryName or DocumentLibraryPath must be specified explicitly for document operations — there is no default document library fallback on those targets the way there is on 2019-and-later/Online.

Further Reading