Microsoft champions hybrid IT, that is, some IT on-premises, some in the cloud; but its cloud-first strategy means that on-premises customers sometimes have a hard time getting the most from their software.

I have posted before about Dynamics CRM, which is very expensive but in places oddly sloppy, as if Microsoft has quality control issues or just does not care about some of the details in the product.

I encountered another example of this when attempting to configure Power BI desktop to connect to an on-premises instance of Dynamics CRM. At one time this was not supported, but it is now possible using OAuth to authenticate (presuming you have an internet-facing CRM deployment, which is generally the case).

There is an official document explaining how to set this up here.

That said, it seems that whoever wrote the document did not follow through the steps to check that they work, because they do not.

The first error is in in the documentation for enabling OAuth, which tells you to use ClaimsSettings in PowerShell:

However this is not the right setting, and the steps given will give you an error. The correct setting is called OAuthClaimsSettings. It is disabled by default. Set it to enabled using similar steps to those above.

Second, the document tells you to run the Add-Adfsclient command “on the PC where you are running Power BI Desktop”. In fact this must be run on the server where ADFS is installed.

The command itself is not all that reassuring:

Add-AdfsClient -ClientId “a672d62c-fc7b-4e81-a576-e60dc46e951d” -Name “Microsoft Power BI” -RedirectUri @(“https://de-users-preview.sqlazurelabs.com/account/reply/”, “https://preview.powerbi.com/views/oauthredirect.html”) -Description “ADFS OAuth 2.0 client for Microsoft Power BI”

Note the word “preview” that appears a couple of times in this mysterious command.

Even if you do all this, many people have struggled with connection issues. For myself, when I got this working on a test setup, I still got the error:

OData: The feed’s metadata document appears to be invalid. Error: The metadata document could not be read from the message content.

The fix in my case was to use “https://orgname.yourdomain/XRMServices/2011/Organizationdata.svc” for the feed, instead of “https://orgname.yourdomain/api/data/v8.2/”. Then I was up and running.

Maybe someone just needs to tell Microsoft to fix its documentation? A good point, but Cobalt’s Chris Capistran pointed out the errors back in April and nothing has changed.

Of course this sort of thing is not all bad for Microsoft partners, who can come in with superior knowledge and get things working.