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
|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:
- Go to the Document management parameters page.
- 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 tenantname.sharepoint.com, and accounts on that tenant are usually in the form email@example.com.
- Click Test SharePoint connection to test the specified SharePoint host name. This verifies if the security and the license are working correctly.
- 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 tenantname.com
- 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: tenantname.sharepoint.com.
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:
- Open Manage computer certificates.
- Select the S2S certificate aadclient.erp.ppe.dynamics.com under the node Personal | Certificates.
- Right click on the certificate and select All Tasks | Export…
- In the Certificate Export Wizard select:
- No, do not export private key
- Base-64 encoded X.509 (.CER)
- Run Windows PowerShell ISE as administrator.
- Check if the MSOnline module is installed in the Windows PowerShell – if not refer to https://www.powershellgallery.com/packages/MSOnline/220.127.116.11 how to install the module.
- Check if you have proper permissions on Azure to maintain credentials for applications. Otherwise the next step will fail.
- 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.
<# Connect to AAD #>
<# Microsoft Dynamics ERP Application id #>
$appid = "00000015-0000-0000-c000-000000000000"
$cer = New-Object System.Security.Cryptography.X509Certificates.X509Certificate
<# Filename with the path of the exported S2S certificate #>
$binCert = $cer.GetRawCertData()
$credValue = [System.Convert]::ToBase64String($binCert);
<# Add the certificate to the Microsoft Dynamics ERP application #>
New-MsolServicePrincipalCredential -AppPrincipalId $appid -Type asymmetric -Value $credValue -Usage verify
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.
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:
- Go to the ..\AOSService\webroot folder.
- Find and open the web.config file as administrator.
- Find the configuration key Aad.ACSServicePrincipal.
- Replace the existing value “00000001-0001-0000-c000-000000000000” with the new one “00000001-0000-0000-c000-000000000000“.
- 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 ‘tenantname.sharepoint.com’.
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:
- Run PowerShell ISE as administrator.
- 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>
- Open Manage computer certificates.
- Select the created certificate under the node Personal | Certificates.
- Right click on the certificate and select All Tasks | Manage Private Keys…
- 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.
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:
- Run the script Generate Self-Signed Certificates (Run as Admin) with ApplicationID 00000015-0000-0000-c000-000000000000 and thumbprint of your S2S certificate.
- Adjust web.config
<add key="Aad.ACSServicePrincipal" value="00000001-0000-0000-c000-000000000000" />
<add key="GraphApi.GraphAPIAzureAccessControlPrincipalId" value="00000001-0000-0000-c000-000000000000" />
- Run Admin User Provisioning tool.
- Restart IIS and Batch serivice.
The script will fail when running more than once! Delete the generated certificates and revert C:\DynamicsTools\CleanVHD to original content before rerunning it.
On new December 2022 OneBox
Follow the steps for April 2022 OneBox, but the script does not update web.config with your S2S certificate thumbprint anymore (bug reported). Therefore you have to manually replace the current value of Infrastructure.S2SCertThumbprint with your S2S certificate thumbprint in the whole file (5 appearances).