Configure SharePoint Online integration in D365FO OneBox

posted on Posted on by Vilko Jenko

comments Tags: , , ,
tags 19 comments

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 tenantname.sharepoint.com, and accounts on that tenant are usually in the form user1@tenantname.onmicrosoft.com.
  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 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.

Troubleshooting

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 aadclient.erp.ppe.dynamics.com 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 https://www.powershellgallery.com/packages/MSOnline/1.1.183.8 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 '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:

  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.

On new December 2022 OneBox and newer

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).

If your account has MFA enabled

Many companies enforce multi-factor authentication (MFA) for all accounts which is however a good practice. The problem is that command Connect-MsolService does not work with MFA enabled accounts, even if they have just conditional MFA and are used from location where MFA is not activated. The reliable alternative is to use script Add-CertToServicePrincipal.ps1 that you can find in Microsoft Dynamics 365 Finance + Operations (on-premises), Deployment scripts (version 2.19.1 or later) instead of the script that starts with Connect-MsolService above in this article.

«
»

19 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

    Reply

    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,
      Klemen

      Reply

  3. 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.

    Reply

    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,
      Vilko

      Reply

      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?

        Reply

  4. 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.

    Reply

  5. Hi, i’m trying to follow your guide for the April 2022 update, but I can’t get it to work.

    My onebox is already setup and running, so I have already run the provisioning scripts. What should I do now?

    You say to: “Run the script Generate Self-Signed Certificates (Run as Admin) with ApplicationID 00000015-0000-0000-c000-000000000000 and thumbprint of your S2S certificate.”

    But how can Ax work if I use the generic application ID 00000015-0000-0000-c000-000000000000 instead of my Azure application id?
    Do I have to provide a certificate or can I let the provisioning script to generate one?
    And what do you mean exactly with “Delete the generated certificates and revert C:\DynamicsTools\CleanVHD to original content before rerunning it.”

    I tried a lot of combination but none seems to works.

    I will be very grateful if you provide a more detailed guide in this issue

    Reply

    1. Hi Omar,

      This article describes how to establish the trust between Azure application called Microsoft Dynamics ERP (created by Microsoft) with ID 00000015-0000-0000-c000-000000000000 and your SharePoint. Up to April 2022 all local OneBoxes were using this ID and it still works if you follow our steps.
      However you can create your Azure application and use its ID, but then you have to adjust the scripts.

      If you have an already provisioned environment I would recommend the following:

      1. Revert you C:\DynamicsTools\CleanVHD folder back to original state. If you do not have it, you can get it here.
      2. Run steps from section “On new April 2022 OneBox” without S2S certificate. Find the thumbprint of generated S2S certificate in web.config Infrastructure.S2SCertThumbprint.
      3. Run steps from section “Enable authentication with the S2S certificate from OneBox in AAD” with you new S2S certificate (select it in step 2).
      Reply

  6. Hi,

     

    I tried what was described in the article on VHD 10.0.37 OneBox.

    But unfortunately I get the following error.

    Do you have any ideas what could be the problem?

    “ComponentName SharePointHelper
    Operation VerifyAuthentication
    httpStatusCode 401
    requestId 54dfefa0-006f-7000-9950-8220941fe6c4
    errorMessage
    responseLength 74
    responseHeaders {“x-ms-diagnostics”:”3001000;reason=\”There has been an error authenticating the request.\”;category=\”invalid_client\””,”sprequestguid”:”54dfefa0-006f-7000-9950-8220941fe6c5″,”request-id”:”54dfefa0-006f-7000-9950-8220941fe6c5″,”date”:”Mon, 20 Nov 2023 08:11:03 GMT”}”

     

    Thanks in advance for your help

     

    Regards,

    László

    Reply

    1. Hi László,

      Is this the error that you get in Event log?
      If not check the Event log if you find more informative error there. The current error does not tell much.
      The procedure described in the article till works for us on 10.0.38 Preview and also on latest VHD.

      Reply

      1. Hi,

        Thank you for the feedback.
        Yes, I copied the error from the event log.
        Did you have to configure something in the Azure portal?

        Reply

        1. You do not have to create a new Azure application, because we are using the existing application created by Microsoft. However, you have to do all the steps described in the article.
          On new VM (April 2022 or later) you can run the provisioning script only once. You can backup C:\DynamicsTools\CleanVHD and restore it to rerun the script.
          My advice for your error would be to run the process again with clean CleanVHD.

          Reply

  7. Thank you for this article. It is very useful.

    Couple things or problems:

    Connect-MsolService is not working with MFA

    I did this steps with Connect-AzAccount and New-AzADAppCredential
    As alternative I think you can just go to your Azure Application and upload Certificate there

    I did not generate Certificate manually, I used MS provided script “Generate Self-Signed Certificates”

    And then used “aadclient-onebox-locator1-dynamics-com” certificate

    Issue I still have:

    When testing sharepoint connection I got this info:

    “You are not authorized to connect to ‘<SomeName>.sharepoint.com'”

    EventViewer shows me this:

    ComponentName SharePointHelper
    Operation VerifyAuthentication
    httpStatusCode 401
    responseHeaders {“x-ms-diagnostics”:”3005004;reason=\”The token does not contain valid algorithm in header.\”;category=\”invalid_client\””,”sprequestguid”:”<Some GIUD>”,”request-id”:”<Some GUID>”,”date”:”Fri, 19 Jan 2024 12:00:46 GMT”}

    Do application need to have some additional permissions to sharepoint?

    Reply

    2. In last days we are actively working on this issue. We have managed to find some working solutions and will publish it in next days when we day when we finish the research. Till then a hint, it works best when registering application S2S certificate with Add-CertToServicePrincipal.ps1 script (from infrastructure scripts for on-premises deployments from the Shared asset library) and use Microsoft Dynamics ERP application (00000015-0000-0000-c000-000000000000), not your own.

      Reply

  8. Hi Justas, Lakshmi,

    After longer investigation we can say that we always get the error “The token does not contain valid algorithm in header.” if we use our Azure application, but not if we use application Microsoft Dynamics ERP which is managed by MS. Even though MS recommends to use an own application (for local and cloud devbox), SharePoint does not trust it. We have a MS support case open, but not results yet.
    The procedure described in this article still works. Just when using MFA enabled account do not use the script that starts with Connect-MsolService (above in this article). Instead use the script Add-CertToServicePrincipal.ps1 that you can find in Microsoft Dynamics 365 Finance + Operations (on-premises), Deployment scripts (version 2.19.1 or later). More details added in last section of the article.

    Reply

    1. I don’t have that script because I just have a downloaded VHD – not on-prem.
      I was able to use connect-msolservice and add the service principal credential (cert from running the scripts to set up the box) to Microsoft Dynamics ERP but I still get the “The token does not contain valid algorithm in header” and it seems to use network service account (Says Security UserId=”S-1-5-20″. Do you other guys have this working? I added the credential using the admin account for my instance. The admin account has access to SharePoint. Not sure what I’m missing here!

      Reply

      1. Hi Laura,

        The Add-CertToServicePrincipal.ps1 script in included in Microsoft Dynamics 365 Finance + Operations (on-premises), Deployment scripts ZIP that you get on LCS>Shared asset library\Model. Take the latest version.
        The procedure described in this article (updated February 3) is working for us on local and cloud devbox. If you send me your email to miha.vuk@docentric.com, I can send you the exact steps.
        As this article has grown over time and it is hard to read, we also plan to publish a new one with updated clear steps and just the relevant content.

        Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

*

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

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