Configure SharePoint Online integration in D365FO OneBox

In this article we will discuss why Microsoft SharePoint Online integration in D365FO does not work in a local development environment (OneBox) and how to fix the issue.

Definition of terms

Term Definition
OneBox instance A development environment deployed on a local machine.
Azure instance A development environment deployed in the cloud.

Configure SharePoint storage

Microsoft SharePoint Online is one of the storage locations in D365FO that are supported natively. Currently, on-premise SharePoint (a local SharePoint server) is not supported.

To configure SharePoint storage in D365FO, follow these steps:

  1. Go to the Document management parameters page.
  2. On the SharePoint tab, in the Default SharePoint server field, review the host name that was automatically detected for the SharePoint site. Typically, the SharePoint host is in the form, and accounts on that tenant are usually in the form
  3. Click Test SharePoint connection to test the specified SharePoint host name. This verifies if the security and the license are working correctly.
  4. Click Open SharePoint to open the specified SharePoint host name in a browser. Note that this does not verify the security, it just opens the specified SharePoint’s URL in a browser.

SharePoint communication works for a current user only if the following conditions are met:

  • An Office 365 license is associated with the user’s account.
  • The user is a typical user in the tenant, not an external user.
  • There is a SharePoint site for the tenant.
  • Properly set the following configuration keys in the web.config file:
    • Aad.AADTenantId – AAD Tenant ID in the form
    • Aad.Realm – Microsoft Dynamics ERP Application ID
    • Aad.ACSServiceEndpoint – ACS service endpoint
    • Aad.ACSServicePrincipal – Azure ESTS Service Application ID
    • Infrastructure.S2SCertThumbprint – S2S certificate thumbprint
An example of configuration key values

If all conditions are met, SharePoint communication works fine on any D365FO instance deployed in Azure but not on an instance deployed in OneBox.

In OneBox instance we get the error: Unable to communicate with the SharePoint server:


To find out why the communication does not work, we need more detailed error description. Luckily, it can be found in Event Viewer under the node Applications and Services Logs | Microsoft | Dynamics | AX-DocumentManagement | Microsoft-Dynamics-AX-DocumentManagement/Operational.

As you can see from the error description, the real cause for the communication failure is that we are not authorized to obtain the security token for communication with SharePoint. An error occurs on a token creation.

The system uses the S2S certificate to sign the AAD access token request. The token grants AOS the access to SharePoint in the name of the given users. This perfectly works on Azure but fails on OneBox.

If we compare the S2S certificates from an Azure instance and from OneBox instance for the same tenant, we can see that they differ. It turns out that the S2S certificate from Azure instance is added to the AAD application Microsoft Dynamics ERP service principal credentials to enable the trust, while from OneBox instance it is not.

Application Microsoft Dynamics ERP on Azure

The S2S certificate in OneBox instance

The S2S certificate in Azure instance

Enable authentication with the S2S certificate from OneBox in AAD

To fix this problem we need to run a few PowerShell commands to add the S2S certificate from our OneBox instance as a new credential to the service principal for the Microsoft Dynamics ERP application. To do that, follow these steps:

  1. Open Manage computer certificates.
  2. Select the S2S certificate under the node Personal | Certificates.
  3. Right click on the certificate and select All Tasks | Export
  4. In the Certificate Export Wizard select:
    1. No, do not export private key
    2. Base-64 encoded X.509 (.CER)
    3. Filename
  5. Run Windows PowerShell ISE as administrator.
  6. Check if the MSOnline module is installed in the Windows PowerShell – if not refer to how to install the module.
  7. Check if you have proper permissions on Azure to maintain credentials for applications. Otherwise the next step will fail.
  8. Execute the following commands to add the S2S certificate as a new credential to the service principal for the Microsoft Dynamics ERP application. Before that replace the placeholder <Certificate> with the filename you selected in the step 4.

Update web.config with Azure ESTS Service Application ID

SharePoint integration will start working after we change the value of the configuration key Aad.ACSServicePrincipal in web.config. The value of this key in OneBox instance (00000001-0001-0000-c000-000000000000) is not the same as in Azure instance (00000001-0000-0000-c000-000000000000). Why the values differ is not clear.

As mentioned before, this value defines Azure Access Control Service (ACS) Application ID in AAD. This service is used to check our credentials when we try to connect to SharePoint Online.

Application ID provided in OneBox instance (00000001-0001-0000-c000-000000000000) does not exist in AAD, but Application ID provided in Azure instance (00000001-0000-0000-c000-000000000000) exists and defines the Azure ESTS Service application (aka Access Control Service – ACS).

To change the values in the web.config file, follow these steps:

  1. Go to the ..\AOSService\webroot folder.
  2. Find and open the web.config file as administrator.
  3. Find the configuration key Aad.ACSServicePrincipal.
  4. Replace the existing value “00000001-0001-0000-c000-000000000000” with the new one “00000001-0000-0000-c000-000000000000“.
  5. Save the changes and close the file.

To check if SharePoint integration works now, click Test SharePoint connection on the Document Management Parameters page in D365FO. You should now get the message: Successfully connected to SharePoint server ‘’.

The proper solution: Create a new S2S Self-Signed certificate

To solve the SharePoint communication problem for OneBox, we used the S2S certificate which is already part of OneBox instance provided by Microsoft. This means that this certificate is the same in all deployed OneBox instances around the globe, which could pose a security risk.

To avoid this risk, we need to create our own S2S Self-Signed certificate in OneBox instance, add it to the Microsoft Dynamics ERP service principal on AAD to enable the trust and replace the value of the configuration key Infrastructure.S2SCertThumbprint in the web.config file with the thumbprint value of our newly created certificate.

To create a self-signed certificate, follow these steps:

  1. Run PowerShell ISE as administrator.
  2. Execute the following command to create the certificate. Before that replace the placeholders <Certificate Name>, <Valid From> and <Valid To> with the desired values.
    New-SelfSignedCertificate -Subject "CN=<Certificate Name>" -CertStoreLocation "Cert:\LocalMachine\My" -KeyExportPolicy Exportable -KeySpec Signature -NotBefore <Valid From> -NotAfter <Valid To>
  3. Open Manage computer certificates.
  4. Select the created certificate under the node Personal | Certificates.
  5. Right click on the certificate and select All Tasks | Manage Private Keys
  6. Add users IUSR and NETWORK SERVICE and set the Read permission for both.

To add the created certificate to the Microsoft Dynamics ERP application on Azure, follow the 8 steps outlined in the beginning of the Enable authentication with the S2S certificate from OneBox in AAD chapter. Be careful to export the newly created certificate and not the default one which is indicated in the step 2.

If everything is done properly, testing of SharePoint connection using the new certificate should be successful.

In the companies where we have more than one deployed OneBox instance, it is recommended to create only one S2S Self-Signed certificate, export it and then install it on all locally deployed OneBox instances inside the company. The web.config file should also be updated accordingly. This task should be done by the IT department.
For creating self-signed certificates, you can also use this free Self-Signed Certificate Generator.

On new April 2022 OneBox

April 2022 OneBox comes with provisioning script that you should run before first use. It assumes that you register a new AAD application and use it when running Generate Self-Signed Certificates script, but it is hard to establish trust between this application and SharePoint.

The easiest recommended approach is to reuse the standard Microsoft Dynamics ERP application:

  1. Run the script Generate Self-Signed Certificates (Run as Admin) with ApplicationID 00000015-0000-0000-c000-000000000000 and thumbprint of your S2S certificate.
  2. Adjust web.config
    <add key="Aad.ACSServicePrincipal" value="00000001-0000-0000-c000-000000000000" />
    <add key="GraphApi.GraphAPIAzureAccessControlPrincipalId" value="00000001-0000-0000-c000-000000000000" />
  3. Run Admin User Provisioning tool.
  4. Restart IIS and Batch serivice.
If you do not provide certificate thumbprint in Generate Self-Signed Certificates script, it will generate it and you can take its thumbprint from Infrastructure.S2SCertThumbprint in the web.config.
The script will fail when running more than once! Delete the generated certificates and revert C:\DynamicsTools\CleanVHD to original content before rerunning it.

7 thoughts on “Configure SharePoint Online integration in D365FO OneBox

  1. Hi admin,

    I tried to To add the created certificate to the Microsoft Dynamics ERP application on Azure, follow the 8 steps outlined in the beginning of the Enable authentication with the S2S certificate from OneBox in AAD chapter. But Power Shell show errror at line “Connect -MsolService”. I make sure that the MSOnline module is already installed in the Windows PowerShell.

    Error in Power Shell.

    Connect : The term ‘Connect’ is not recognized as the name of a cmdlet, function, script file, or operable program. Check
    the spelling of the name, or if a path was included, verify that the path is correct and try again.
    At line:2 char:1
    + Connect -MsolService
    + ~~~~~~~
    + CategoryInfo : ObjectNotFound: (Connect:String) [], CommandNotFoundException
    + FullyQualifiedErrorId : CommandNotFoundException

    Please give me an advise.

    Thank you so much

    1. Hi Nguyễn,

      Please install the Connect-MsolService using the following steps:
      – Go to PowerShell as Administrator on your OneBox machine
      – Run the command: Install-Module MSOnline
      – Run the command: Install-Module AzureAD

      After the successful installation the command Connect-MsolService should be working as expected.

      Hope that this helps.
      Kind regards,

  2. I am getting the same error “unable to communicate” but I cannot find the error in event viewer log. Also I can see my aadclient certificate is expired on local machine.

    What do you suggest in this case.

    1. Hi Abdul,

      I see that the reason you can not connect to SharePoint is because of the expired certificate. To resolve the issue, you need to create a new self-signed certificate as described in the chapter The proper solution: Create a new S2S Self-Signed certificate. If you did everything correctly, the connection to SharePoint will be successful.

      Kind regards,

      1. I did created SSL certificate and updated web.config, stil unable to communicate with Sharepoint. I updated web.config SSL certificate thumbprint also.. still it did not work. any ideas?

  3. The April 2022 D365FO Onebox has unique generated certificates and environment is linked to your Azure application. I have added the chapter describing the specifics while you still have to do other steps.

Leave a Reply

Your email address will not be published.


Docentric respects your privacy. Learn how your comment data is processed >>

Docentric respects your privacy. Learn how your comment data is processed >>