SharePoint Connector Documentation
Index

Authentication Tips and Tricks

This page collects practical tips for setting up each authentication method and Microsoft login method of the SharePoint Connector, and explains what happens behind the scenes so you can fix a connection that does not work. It complements Authentication Methods, which describes the methods and how to choose between them.

Before You Connect

Which fields each login method uses

The setup page greys out the app registration fields that the selected Microsoft Login Method does not use (Client Id also stays enabled for Certificate authentication). A greyed-out field is never read. The table shows what each method actually reads.

Field App Registration Device Code Modern App Registration PKCE Certificate (Authentication Method)
Client Id Required Not used (connector's own app registration) Required Optional (blank = connector's own app registration) Required
Client Secret Value Required Not used Required Not used Not used
Callback URL Required, must contain page=70319501 Not used The OAuthLanding.htm page The OAuthLanding.htm page Not used
Entra Tenant Id Not used (signs in through the common endpoint) Not used (common endpoint) Optional Optional Not used (the Microsoft Entra tenant of the Business Central environment)
Certificate Not used Not used Not used Not used Required

A new SharePoint Setup starts with PKCE and a blank Client Id, so the connector's app registration is used until you choose otherwise.

When Authentication Method is Certificate, the Microsoft Login Method is ignored: Connect does not open a sign-in window, it requests an app-only token with the certificate.

Fill in the connection first

  • For every login method, Connect stops when Base URL or Document Library (base folder) is empty. With Certificate authentication it does not check them, but the Base URL is still needed for the token. Base URL is the root of your tenant, like https://contoso.sharepoint.com, without a site or trailing slash. A subsite goes into Subsite Name. A Base URL that does not end in sharepoint.com gives a warning.
  • All login methods ask for access to the Base URL: App Registration requests it as the classic SharePoint resource, Device Code, Modern App Registration and PKCE request the scope <Base URL>/AllSites.Manage, and Certificate requests <Base URL>/.default. If you change the Base URL later, connect again.
  • Azure Cloud decides which Microsoft login server is used: login.microsoftonline.com for Public and login.microsoftonline.us for US (Government). It applies to every login method.

Selecting a Microsoft Login Method fills in the Callback URL

When you change Microsoft Login Method, the connector fills in the matching Callback URL:

  • App Registration: https://businesscentral.dynamics.com/<environment>?page=70319501
  • Modern App Registration and PKCE: the Business Central landing page, https://businesscentral.dynamics.com/OAuthLanding.htm on Business Central Online

On-premises, replace the generated App Registration URL with your own web client URL followed by ?page=70319501. For Modern App Registration and PKCE the default already comes from your web client URL followed by /OAuthLanding.htm; only change it if the web client is reached through a different public address (for example behind a reverse proxy).

The Callback URL field validates the value for the selected method: a warning appears when the App Registration URL lacks page=70319501, or when the Modern App Registration or PKCE URL does not end in OAuthLanding.htm. Modern App Registration and PKCE only use the Callback URL when it ends in OAuthLanding.htm; any other value is ignored and the Business Central default landing page is used.

Allow pop-ups

App Registration, Modern App Registration and PKCE open the Microsoft sign-in in a separate browser window. Allow pop-ups for https://businesscentral.dynamics.com (or your on-premises web client address) before you click Connect. Device Code and Certificate do not open a window.

Allow HttpClient Requests

The connector's calls to the Microsoft login server and to SharePoint are outbound HTTP requests from the extension. In sandboxes these are blocked by default, and the sign-in or the first SharePoint call fails. When the connector detects the block it stops with:

Cannot communicate with web services. Please turn on "Allow HttpClient Requests" on SharePoint Connector in Extension Management to continue.

Other calls report a generic login server or SharePoint error instead. Open Extension Management, select the SharePoint Connector, and enable Allow HttpClient Requests before you connect.

Sign in with the right account

With Proxy authentication, everyone shares the account you sign in with, so sign in with the service account that should own the documents, not your own. Modern App Registration and PKCE always show the account picker. Device Code and App Registration do not force it, so the Microsoft account your browser is already signed in with may be used. Use a private browser window when you need to sign in with a different account than the one your browser remembers.

Device Code

The simplest method: no app registration, no secret, no callback URL. It works on Business Central Online and on-premises.

  1. Set Microsoft Login Method to Device Code and click Connect.
  2. A page shows a message from Microsoft with a code and a link to https://microsoft.com/devicelogin.
  3. Open the link (on any device), enter the code and sign in.
  4. Keep the Business Central page open. It polls the login server and closes itself when the sign-in is complete.

Tips

  • The code is only valid for a limited time (Microsoft issues it for about 15 minutes). If you take longer, the page reports that the authentication timed out. Click Connect again for a new code.
  • Device Code signs in with the connector's own multi-tenant app registration (Application ID e9b03b0e-51c8-4a53-8c08-777f2aa14d92) and asks for the delegated SharePoint permission AllSites.Manage plus offline_access. The first user is asked to consent. If your organization does not allow users to consent to applications, an administrator must approve it, either by ticking Consent on behalf of your organization in the consent prompt, or afterwards under Enterprise applications in the Microsoft Entra admin center.
  • Device Code always signs in through the common endpoint. The Entra Tenant Id field is not used.
  • No pop-up is involved, so Device Code is the method to use when browser pop-ups cannot be allowed.

PKCE

PKCE signs in with a normal Microsoft sign-in window and does not need a client secret. With Client Id blank it uses the connector's own multi-tenant app registration (Application ID 4c5c9ab3-1dc9-49ec-9b59-495fd03fbe15). This is a different app registration than the one used by Device Code, so consent granted for one does not cover the other.

  1. Set Microsoft Login Method to PKCE. The Callback URL is filled in with the OAuthLanding.htm page.
  2. Leave Client Id blank, unless you want to use your own app registration (see below).
  3. Click Connect. A page opens with the text "A Microsoft sign-in window opens. Please allow pop-ups from this page, or click Sign in if no window opens."
  4. Sign in and consent. The window returns to the Business Central landing page and closes, and the connector redeems the code.

Tips

  • If the browser blocked the pop-up, click the Sign in button on the page. It opens the window from a user click, which browsers allow.
  • Closing the sign-in window before finishing simply closes the page. Click Connect again.
  • "The sign-in response does not belong to this sign-in (state mismatch), please try again." means an old sign-in window answered. Close all sign-in windows and click Connect again.
  • When you switch to PKCE while Client Id is filled in, a message reminds you that PKCE will use that app registration, which must then be a public client. Clear the Client Id to use the connector's app registration.
  • The connector's app registration has https://businesscentral.dynamics.com/OAuthLanding.htm as its redirect URL, so with a blank Client Id, PKCE only works on Business Central Online. On-premises, use your own app registration.
  • The Entra Tenant Id field is optional. Blank means the common endpoint. Fill it in when your own app registration is single tenant, otherwise Microsoft Entra refuses the sign-in (AADSTS50194).

Using your own app registration with PKCE

  1. In the app registration, open Authentication and add the platform Mobile and desktop applications with the Callback URL from the setup page as a custom redirect URI. Do not use Web (needs a client secret) or Single-page application (its codes can only be redeemed by a browser).
  2. Set Allow public client flows to Yes.
  3. Under API permissions, add the SharePoint delegated permission AllSites.Manage and grant admin consent.
  4. Enter the Application (client) ID in Client Id, leave Client Secret Value empty, and click Connect.

If the redirect URI is registered under the wrong platform, the connector recognizes the Microsoft errors AADSTS7000218 and AADSTS9002327 and tells you to move the URL to Mobile and desktop applications. An app registration made for App Registration or Modern App Registration (platform Web) cannot be reused for PKCE as is.

Modern App Registration

Uses your own app registration with a client secret and signs in through the standard Business Central sign-in window.

  1. Create the app registration with a Web redirect URI equal to the Callback URL from the setup page (.../OAuthLanding.htm), add the SharePoint delegated permission AllSites.Manage, grant admin consent, and create a client secret. See Microsoft Entra App Registration.
  2. Set Microsoft Login Method to Modern App Registration, enter Client Id and Client Secret Value.
  3. Click Connect, pick the account in the sign-in window and sign in.

Tips

  • Connect stops with "Modern App Registration requires a Client Secret from the App Registration in Microsoft Entra." when the secret is missing. Enter the secret Value from Certificates & secrets, not the Secret ID. The setup page warns when the value you entered looks like a GUID, because that is usually the Secret ID.
  • "The sign-in was not completed." means the sign-in window was closed before finishing. Click Connect again.
  • AADSTS65001 gets a specific message: the app registration has no consented delegated SharePoint permission. The typical cause is reusing an app registration made for Certificate authentication, which only has application permissions. Add the delegated AllSites.Manage permission and grant admin consent.
  • Entra Tenant Id: leave it blank on Business Central Online, the tenant of the environment is used. Fill it in on-premises when Business Central does not use Microsoft Entra authentication and the app registration is single tenant (otherwise AADSTS50194). A verified domain like contoso.onmicrosoft.com also works.
  • The sign-in returns a refresh token that the connector stores and renews silently. If the token could not be read from the sign-in, the connector keeps the Business Central token cache instead and tests right away that it can renew from it, so a setup that cannot stay connected fails during Connect instead of asking every user to sign in again later.
  • With Activate Debug Mode enabled (a hidden setting), a message shows the reason when the silent renewal from the token cache fails.

App Registration

The original method: your own app registration, a client secret, and the connector's own callback page in Business Central.

  1. Create the app registration with a Web redirect URI equal to the Callback URL from the setup page (it must contain page=70319501), add the SharePoint delegated permission AllSites.Manage, grant admin consent, and create a client secret. The sign-in also asks for the standard offline_access scope so that a refresh token is issued.
  2. Set Microsoft Login Method to App Registration, enter Client Id and Client Secret Value, check the Callback URL.
  3. Click Connect. A page with the text "Please allow popups from this page." opens the Microsoft sign-in in a new window.
  4. After signing in, the window lands on a Business Central page that says "Authentication finished, please close this window." and tries to close itself. The login page checks every second whether the connection is stored, then closes the window and itself.

Tips

  • The redirect URI in Microsoft Entra must match the Callback URL character for character, including the environment name and ?page=70319501. The sign-in itself uses the redirect URI registered in Microsoft Entra; the Callback URL is sent when the connector redeems the code, and a mismatch then fails with "Error: Login Server did not return a token (...)" with AADSTS50011 in the reply.
  • If the callback page shows "Did not receive a access code from the login process, is the callback Uri correct?", the sign-in window did reach the callback page but Microsoft Entra sent no authorization code, typically because it returned an error instead. Look at the address of the window for an error parameter, and check the permissions and consent of the app registration.
  • Every Business Central environment has its own Callback URL, so an app registration set up for one environment does not work for another as is. Modern App Registration and PKCE share one landing page URL across all Business Central Online environments.
  • Users who connect need the SP Conn. User EFQ permission set: it includes the login and callback pages.
  • App Registration signs in through the common endpoint with the classic (v1) SharePoint resource. The Entra Tenant Id field is not used.
  • When the client secret expires, the silent renewal starts failing, typically with "Error: Login Server returned 401" (Microsoft Entra rejects the client credentials without details). Create a new secret, enter it, and click Connect again (with Personal authentication, every user).

Certificate

App-only access: the connector authenticates as the app registration itself, with a self-signed certificate instead of a secret and without any user signing in. SharePoint does not accept app-only tokens obtained with a client secret, which is why this method uses a certificate.

  1. Set Authentication Method to Certificate and enter the Client Id of your app registration.
  2. Click the assist-edit (...) on the Certificate field and confirm. The connector generates a self-signed certificate (RSA 2048, SHA-256, valid for two years from today), stores it, shows "Certificate Created", and downloads the public part as sharepointconnector.cer.
  3. In the app registration, upload sharepointconnector.cer under Certificates & secrets > Certificates.
  4. Under API permissions, add a SharePoint application permission (for example Sites.FullControl.All or Sites.ReadWrite.All) and grant admin consent. Delegated permissions do not work for this flow.
  5. Click Connect. No window opens: the status changes to "Connected to SharePoint" when a token could be obtained.

Tips

  • The token is requested from the Microsoft Entra tenant of the Business Central environment, so Certificate authentication needs Business Central Online or an on-premises installation that uses Microsoft Entra authentication. The Entra Tenant Id field is not used.
  • There is no refresh token and no stored connection. The connector requests a new access token whenever it has none, and keeps it in memory until shortly before it expires. Disconnect only clears the token in memory.
  • Generating a new certificate replaces the stored one. Upload the new .cer file to the app registration afterwards, then remove the old certificate there.
  • Note the expiry date: two years after creation the certificate stops working and you must generate and upload a new one. The setup page only shows whether a certificate is loaded, not its expiry.
  • All SharePoint actions are performed as the app, so files show the app as author and per-user SharePoint permissions do not apply. Use Proxy or Personal when you need that.
  • If Microsoft Entra rejects the token request, the connector shows the response from the login server directly ("Error: Login Server returned ..."). Look for the AADSTS code in it: AADSTS700027 means the certificate on the app registration does not match the stored one, AADSTS700016 means the Client Id is not an app in the tenant.

Proxy and Personal

  • Proxy stores one connection for the whole tenant (or per company, see below). Disconnect removes it for everyone; sessions that already hold an access token keep working until it expires.
  • Personal stores one connection per Business Central user. Disconnect on the setup page only removes the connection of the user who clicks it.
  • With Personal, a user without a stored connection is asked to connect as soon as a page with the SharePoint FactBox opens. The same Connect to SharePoint page also opens with Proxy while no connection has been stored yet. It needs pop-ups allowed, and in a production environment it requires the connector to be registered.
  • Background work runs under the user who started it. Auto-upload after posting runs in the posting session or, with Auto Upload Process set to Background, in a background session started by the posting user, so both use the posting user's connection. Incoming Documents processed by the job queue run as the user on the job queue entry, so with Personal authentication that user must have connected too.
  • Switching between Proxy and Personal, or to another Microsoft Login Method, leaves the old stored connection unusable. Click Connect again (every user, with Personal).

Where the Connector Keeps Things

What Where Notes
Refresh token Isolated storage of the extension, one entry for Proxy or one per user for Personal Written by a separate session so it is saved even when the calling transaction rolls back. If that session cannot be started the connector stops with "Could not store the Refresh Token".
Access token Memory of the current session Reused until about five minutes before it expires, then renewed from the refresh token (the token from a Modern App Registration sign-in is not reused, it is renewed at the first check). Not shared between sessions.
Client Secret Value Encrypted isolated storage Never stored in the setup table.
Certificate Isolated storage (private key and public certificate) Only the public part is downloaded.

Separate Access Token per Company

This hidden setting (Separate Access Token per Company, set through configuration, not on the page) moves the refresh token, the client secret and the certificate from tenant-wide storage to per-company storage. After turning it on, each company needs its own Connect, its own Client Secret Value, and its own certificate. Turning it off makes the per-company values invisible again, so re-enter the secret and connect again.

Setup changes drop the session token

Any change to the authentication settings (authentication method, login method, Base URL, Client Id, Client Secret Value, Entra Tenant Id, Azure Cloud, Callback URL, certificate, or the per-company setting) makes every session forget its access token, also when the changed field is greyed out for the current login method. The next SharePoint call renews it from the stored refresh token. When the change made the stored refresh token unusable (another login method, another Client Id), the renewal fails and you must click Connect again.

When a Connection Stops Working

  • Automatic recovery: on a 401 or an expired-token reply from SharePoint the connector renews the access token and retries, up to three times per call, before reporting an error.
  • "Could not refresh the authentication to SharePoint, Please go to SharePoint Setup (alt-Q) and click Connect." means there is no stored connection for this user and company, or the connector could not renew the token from a stored Modern App Registration token cache. Reconnect.
  • "Error: Login Server did not return a token (...)" means Microsoft Entra refused the refresh token (revoked, expired, or issued for other settings). The reply in the parentheses contains the AADSTS code, see Connection and Authentication Errors. Reconnect.
  • "Error: Login Server returned 401" (or another status code) means Microsoft Entra rejected the request itself, typically because the client secret is wrong or expired. Only the Certificate method includes the full reply from Microsoft Entra in this message.
  • "Could not contact Microsoftonline Login Server" (PKCE: "Could not contact the Microsoft login server.") means the login server could not be reached at all: check outbound access to login.microsoftonline.com (or .us) from the Business Central server.
  • A refresh token can be revoked by your administrator, by a password reset for the signed-in account, or by conditional access. With Proxy authentication, that hits every user at once, so use a service account whose password does not rotate and that is excluded from interactive sign-in policies you do not want to apply to the connector.

Checklist Before Contacting Support

  • Base URL is https://<tenant>.sharepoint.com with no site name in it
  • The right fields for the login method are filled in (see the table at the top)
  • Callback URL matches the redirect URI in the app registration exactly, on the right platform (Web for App Registration and Modern App Registration, Mobile and desktop applications for PKCE)
  • The app registration has the SharePoint permission the method needs (delegated AllSites.Manage, or an application permission for Certificate) with admin consent granted
  • The client secret Value was entered, and it has not expired
  • Pop-ups are allowed and Allow HttpClient Requests is enabled
  • After any setup change, Connect was clicked again

The setup page also links to the publisher's video playlist with setup walkthroughs under Setup tips and tricks.