Office 365 integration in a Dynamics NAV hosting environment

We from the Microsoft Dynamics NAV support team (Microsoft CSS) see an increasing number of support cases coming in related to Office 365 integration in a hosting environment. This range from the relatively new Edit in Excel feature or the relatively new Outlook Business Inbox to the more familiar Office 365 Single Sign On functionality. This blog post is intended to help you to first discuss the requirements with your customer, it may also help you to understand the difficulties. It should be relatively easy to implement these capabiltities, but since there are so many external components that require different configuration setup, we may end up in high labor intense support cases where we need to put all pieces together. This blog post will hopefully serve as a guide where we summarize all relevant documentation that is out there. Finally, we will showcase a typical environment with several Azure AD’s among some other typical scenarios.

Before you get started

To visualize what kind of components you do need to think about before starting the implementation, take a look at the following picture:

Edit in Excel

If you do now the basics, you are half way through to finalize the setup successfully. Let’s therefore look at the system requirements and the description of what the Edit in Excel functionality can do for you. All relevant documentation can be found on this blog. E.g. system requirements and the documentation about the functionality and setup.

SSL Cert

Yes, you can use a self-signed certificate. If you search for it on the Internet, there are many ways of creating your own cert. Fortunately, there is a way that avoids using difficult parameters in combination with deprecated tools like makecert.exe.
Self-signed certs can be easily created, and we blogged about that in 2014 here. If you get into trouble with using / configuring a self-signed certificate, it will be your first request for help to either Microsoft CSS or to your Dynamics NAV partner. Trusted certs are recommended. Trusted certs avoid that you must ship the SSL cert to every single device and install them manually in the trusted root store.
Are we done talking about SSL certs? Nope, the 2014 blog post talks about the following:

“CN=<Your site name>”

This can be something like CN=nav.microsoft.com or CN=navvm.westeurope.cloudapp.azure.com. Trusted SSL certs can be ridiculously cheap, but the Dynamics NAV support team suggest that youbuy an expensive wildcard SSL cert. Yes, a wildcard cert is much more expensive, but it does make your life easier as you can use it for any device, computer or SSL proxy that is before the NST server, etc. Then it would be something like:

“CN=*.yourdomain.com”

Credential type

You do also need to decide about credential types. For example, AccessControlService or NavUserPassword to name a few. As you may have heard, Azure team no longer support AccessControlService. As of now, the Dynamics NAV development teams are analyzing the impact of that decision of the Azure team. At present, we do not know what and if there is an impact for us.

Azure Active Directory

For instance, there may be three scenarios to think about:

1. Your company hosts several Azure AD’s
2. Your company consists of several branch offices, locations
3. Your company consists of only one tenant, one database, etc.

The first two scenarios are typical multitenant scenarios. Each single scenario can have a different business requirement. If you do not have an Azure AD, you can logon to the Azure page on the microsoft.com site and you can get a free subscription or a paid subscription. The FAQ are written here. For what we need, which is Single Sign On or SSO, the following does apply:

Just sign on and off you go.

OData endpoint

OData endpoint must be reachable for the Edit in Excel functionality to work. This does mean you need to think about security, firewalls, ports assignment and endpoints if running in a cloud environment. Also, you do need to think or make a decision if the Edit in Excel should be reachable from outside your corporate network, etc.

App Registrations

Though not exceedingly difficult to configure, our documentation lists that you need to have access to Azure AD. We are currently seeing a high incoming support call volume related to the relatively new Edit in Excel functionality that was first shipped in Dynamics NAV 2017. These support request are considered high labor intense support requests where we do require the partner or customer to test a lot themselves to find root cause of the issues they do encounter. We do also have to ask these unfortunate partners or customers to reconfigure their environment to get things to work. Not all Dynamics NAV partners are able or allowed to access customer Azure AD’s which does make partners life not easier but more difficult. It is something to discuss with your customer proactively, that the Dynamics NAV consultant does require access or does need someone to help him creating the Apps on the Azure AD.

Outlook Business Inbox

As with the Excel Add-In, let’s have a look at the system requirements first. E.g. system requirements can be found here and a high level summary of what it can do for you is written below:

Dynamics NAV includes the following add-ins for Outlook:

Contact Insights:
This add-in provides users with Dynamics NAV customer or vendor information in Outlook emails and calendar appointments. It also enables users to create and send Dynamics NAV business documents, such a sales quotes and invoices to a contact. To support these task, the add-in adds actions to the Outlook ribbon, in the Dynamics NAV group.

Document View:
When a business document is sent as an email, this add-in provides a direct link from email to the actual business document in Dynamics NAV. The add-in adds a Document Links action in the email header, which a user can select to display the document.

We've learnt from incoming support requests that the PublicWebBaseUrl is not filled in correctly all the time. We've also seen some support cases where a highly secured environment could not access all required components that are stored on the Internet needed for the Outlook Business Inbox. A Fiddler trace did show where the environment was too secured and what should be opened so that the Business Inbox could work. In some scenarios we saw that a self-signed certificate limited the full functionality of the Outlook Business Inbox. These are things to consider when deciding what type of SSL cert, you are going to buy.

Office 365

One of the other requirements is that you have a supported release of Excel for the Edit in Excel functionality to work, this can be cloud based or OnPrem (desktop) release. If you do not have yet an Office 365 subscription or Office 2016 OnPrem release, then you can get yourself a trial account here. Note that some of these Office 365 subscriptions also have support for Azure AD. The one in the link is an E3 subscription plan (trial) which does also include the Azure AD. With an Office 365 E3 subscription plan, there is no need to also get an Azure AD subscription as well. In the below scenario description, I will be using my MSDN subscription (mmels.onmicrosoft.com) for the Azure AD only and I will be using a separate Office 365 subscription (melsbergmansltd.onmicrosoft.com) for the second Azure AD needed for the authentication of the users. In the hosting scenario, I do need two Azure AD’s to demonstrate. Complicated? No, not really but it should be part of your discussions of requirements you will have to go through with your customer.

Multitenant or single tenant

There may be customers out there that do only require a single tenant environment. This is fine, of course. It has been like this for years. There may also be customers out there that do really require multi-tenant environments. Every single customer still have their own business requirements. These different requirements do require different setup. They do all want this functionality to work with the least administrative work.

Showcasing a typical hosting scenario with multiple Azure AD’s

Let’s run some PowerShell commands that do configure everything from scratch. To summarize the environments again:

If we now want to logon to the WebClient, we will receive an expected error:

It is now time to logon to the Azure portal. In the Azure portal, on the left-hand side, we click on More services and then type in App registration. Click on New Application registration. Enter the following details:

Press Create and then select the Dynamics NAV 2018 | Azure AD App to display the details of it. Copy the value: Application ID value and paste it into Notepad. Now click Properties in the right-hand side. Copy the App ID URI value and paste it in notepad. Ensure that Multi-tenanted is set to Yes. Press Save to save any changes you did make. Now click on Reply URL’s.

If you somehow run into troubles, before filing a Support ticket, please generate a copy of the manifest file as a Microsoft support engineer will ask for it. We may also ask you for the customsettings.config file and application event log file. Of course, the relevant web.config file or navsettings.json file should also be sent to the Microsoft support engineer. We can then directly look through the several configuration setup details.
Now open the customsettings.config file. If the NST instance is not the default one, you will find it in the following folder:

The App Registration Dynamics NAV 2018 | Azure AD App can be adjusted so that property Multi-tenanted is set to No.

In the described environment setup, we can now only logon with users that are defined in Dynamics NAV and only belong to tenant mmels.onmicrosoft.com.

Your company consists of only one tenant, one database, etc.

Here scenario 2 does apply with some adjustments. There is no need to create users in branch2 and branch3 (simply because they do not exist as this is a single tenant environment). We also do not have to run the exercise to create a multitenant environment. We can however still use the created application that did apply to scenario 2.

If you like this blog posting that does come out of Microsoft Dynamics CSS, please consider liking this blog posting and / or add some comments how we can improve. In the comments you can also drop any questions you may still have and or suggest topics for other blog postings.

Regards,

Marco Mels

Microsoft CSS EMEA

This posting is provided "AS IS" with no warranties, and confers no rights

Thanks your for the post. I struggled long time with the O365 powershell script. The web client with O365 login works perfect now. But I still have issues with the Windows client using O365 login. You mentioned the config file for the Windows client, but in your example it is set to NAV database login and not O365. Would be nice if you can post a config file example for the Windows client with O365 login as well.

Hello,
You can add your own custom urls if needed. However, if you follow this blog posting, the Sign-on URL is similar to the Reply URL hence there is no need to add anything there. It is completely up to you and your customer to decide if you want to use additional Reply URL’s in combination with an alternate ID, etc.

Regards,

Marco Mels

Microsoft CSS EMEA

This posting is provided “AS IS” with no warranties, and confers no rights

Hi,
Now that ACS i deprecated and will be shut down sometime in November.
Are there any plans to upgrade the earlier NAV versions, which are still under support, (2013 R2+) to use direct AAD authentication instead of ACS?

HI Marco,
and a followup question.
Have I understood this correctly; that ACS authentication is not the same as AAD authentication? In the ClientUserSetings.config file the only option is ACS however. Meanwhile, in later versions under the User Card, it seems that authentication key for ACS is not required anymore in order to login using Office36 (as it works by using AAD somehow?) .

I hope you can make this much more clear, document the options available, and specifically also require that the CSS-team to add new options for the parameter “ClientServicesCredentialsType” in ClientUserSettings.config.
Thanks in advance.

Let me try to answer this question. What will be retired is the creation of (your own) ACS namespaces via the Azure portal. This can however still be done, but only via the Classic Azure Portal (yes there is a still a way to start the old classic portal). The option to create a new Access Control Namespace has already gone from the new Azure portal. If you start the classic Azure portal, you will see only one option called Active Directory. Then you click on your Azure AD and then you can (still) click on Access Control Namespace. It is still possible to create a new one, but there is a red warning that this will be retired on November 7th, 2018. The recommendation is of course not to create one because it will be retired. This is just to explain what will be retired.
As I am not able to add links to the comments on this blog posting, I suggest you search for “How to: Configure a Deployment for ACS” via your favorite Internet browser and the link I would like to refer to should pop up in the search results. It will give you information how to create an Access Control Namespace on the Azure Management Portal. This is old information and I doubt that this information made it to be migrated to Docs for Dynamics NAV 2017 / Dynamics NAV 2018. This is the part which we no longer can support because it is not possible anymore to create a new namespace.

All existing application that have been configured with their own Access Control Namespaces do need to be migrated before the retirement date.

To recap: you cannot configure Dynamics NAV for Azure ACS anymore as you can no longer create (your own) ACS namespaces. You can however still configure your server for AAD SSO. This uses a different Access Control Service, in stead of using the Azure ACS namespaces it uses an AAD application. It is still an Access Control Service so we’re not discontinuing the use of the Access Control Service term or settings.

Hope it does clarify.

Regards,

Marco Mels

Microsoft CSS EMEA

This posting is provided “AS IS” with no warranties, and confers no rights

Thank you Marco for you replies here.
It makes it more clear, however I still don’t understand 100%. I understand that I cannot create a new namespace and that the classic Azure website is unusable – and that the previous ACS using this will stop working if you have created your own namespace manually. But! I usually (since NAV2016) only register apps on AAD and uses this for authentication. So, will my current config continue to work as they are using AAD APP and thus AAD authentication? As you wrote “This uses a different Access Control Service, instead of using the Azure ACS namespaces it uses an AAD application.” If I understand you correctly, you mean this will continue to work even after November this year? Please confirm! And just some feedback: As I wrote earlier, that we still see ACS as a value option for “ClientServicesCredentialType” in the ClientUserEettings.config file and the “CustomSettings.config” file – which makes this rather confusing (if the NAV Team rename or add the value option AADauthentication instead of just ACS – this would be cause it less confusing). Thanks

Hi, Robin Carlsson here again. Not sure if my reply was posted so I will write again (with my signed in account).
First of all, thank you Marco for you replies here.
Your replies makes it more clear, however I still don’t understand 100%. I understand that I cannot create a new namespace and that the classic Azure website is unusable – and that the previous ACS using this will stop working if you have created your own namespace manually. But! I usually (since NAV2016) only register apps on AAD and uses this for authentication. So, will my current config continue to work as they are using AAD APP and thus AAD authentication? As you wrote “This uses a different Access Control Service, instead of using the Azure ACS namespaces it uses an AAD application.” If I understand you correctly, you mean this will continue to work even after November this year? Please confirm! And just some feedback: As I wrote earlier, that we still see ACS as a value option for “ClientServicesCredentialType” in the ClientUserEettings.config file and the “CustomSettings.config” file – which makes this rather confusing (if the NAV Team rename or add the value option AADauthentication instead of just ACS – this would be cause it less confusing). Thanks

Hi Robin,
Unfortunately, our blog site marked your earlier comment as spam for some reason, which is why you couldn’t see it until today. We’ve unblocked that comment so you have both of them all visible again.

Response to: robintheswede
March 8, 2018 at 11:43
Hi, Robin Carlsson,
I do not seen an option to reply below your posting, so I hope you will see my comments. I do indeed welcome all these responses as it is clear that there are questions to be addressed. I am more then happy to try to answer. Here are some answers related to your questions:

Your question:
So, will my current config continue to work as they are using AAD APP and thus AAD authentication?

Yes, it will still continue to work. The ACS namespace is login dot windows dot net that you typically use when using Azure AD Apps. This will not be deprecated. What will be deprecated is the following: your minus namespace dot accesscontrol dot windows dot net. (hopefully this will not be considered as a link).

Your questions:
If I understand you correctly, you mean this will continue to work even after November this year? Please confirm!

Confirmed!

Your suggestion:
And just some feedback: As I wrote earlier, that we still see ACS as a value option for “ClientServicesCredentialType” in the ClientUserEettings.config file and the “CustomSettings.config” file – which makes this rather confusing (if the NAV Team rename or add the value option AADauthentication instead of just ACS – this would be cause it less confusing). Thanks

Understood the feedback! I do not know what the product group will do with this, but it might that they will first address this in Tenerife release. Fingers crossed. Fact is of course that login dot windows dot net will still work after november. So any changes in our application code may not even be necessary.

We will see what happens.

Regards,
Marco Mels
Microsoft CSS EMEA
This posting is provided “AS IS” with no warranties, and confers no rights

Hello Jens,
The free edition of Azure subscription should work as well. See my response to “hanswurst” (January 31, 2018 at 18:31). You can either ignore the reply urls (sentence) or add new reply urls after clicking (reply urls sentence).
Thanks.
Marco Mels

Hello Philippe,
SSO will work when Dynamics NAV is OnPrem and when Dynamics NAV is running on Azure. SSO will also work when Dynamics NAV is OnPrem and when the Active Directory is also OnPrem (Active Directory Federation Services).

Thanks.

Regards,

Marco Mels

Microsoft CSS EMEA

This posting is provided “AS IS” with no warranties, and confers no rights

Hello Marco,
Thank you for your reply.
I asked you because I setup O365 SSO for NAV on my on-premise deployment and it was not working (after O365 authentication) and I was wondering if it was linked to on-premise deployment.
In Windows event viewer I add error about a certificate for SSO :
Tenant ID:
Type: System.IdentityModel.Tokens.SecurityTokenValidationException
Message:
Certificate X.509 CN=accounts.accesscontrol.windows.net …

After some hours of searching I found the reason and fixed it : It was because the NAV Server parameter ServicesCertificateValidationEnabled was set to true. After set it to false, O365 SSO from NAV was working fine.

I have a hard time to make NAV 2018 CU02 work with SSO – and I wonder about a few things:

Is this true:
1) In order to enable the Windows client (not Web client) to authenticate with SSO you *MUST* install the Web Client Appl.
2) The Web Client Appl. *MUST* be configured to connect to the same NAV-Service as the Windows Client that needs the authentication.
3) 1 and 2 are needed because Azure AD will always http(s)-post the SAML Response (and the obvious receiver of a http post will be the WEB Client Appl.)

More questions:
4) Are you aware of any problems with NAV 2018 CU02 / SSO?
5) In NAV 2018 WEB Client Appl there is no folder named ‘WebClient’ and there is no ‘signin.aspx’. What should be used instead?
6) What happened to Best Practise Analyzer (It was included in NAV2017)?

1: No, not required.
2: No, not a must.
3: No, see 1 and 2.
4: Not aware of specific issues related to CU2.
5. These are deprecated, but you can still use them in the URL or WS Federation Login Endpoint.

Feel free to file a support request if you are having a hard time configuring the SSO experience.

Regards,

Marco Mels
Microsoft CSS EMEA
This posting is provided “AS IS” with no warranties, and confers no rights