Troubleshooting CRM for Tablets Login Issues with ADFS

All CRM 2013 and CRM Online customers have access to the CRM for Tablets app that’s available for Windows 8, iOS and Android devices. Since it’s an app from the new age of mobile computing, the users can simply download it from the respective app store of the platform provider and install it. Configuring the app to connect with your CRM organization can however prove to be a bit trickier task than this.

If you’re using CRM Online hosted by Microsoft in their data centers, connecting the tablet app to the CRM server in the cloud is usually a straightforward process. Just enter the URL for your organization, then punch in the credentials and off you go. Well, to be more precise, upon your first connection the organization you’ll be taken to a screen that asks you to hold on tight while the app is being set up. This is because all of the metadata related to your CRM organization’s customizations first needs to be loaded, so that you’ll see your own CRM instead of some generic, hard coded menus and fields. This step can take quite a while to finish, but just hold on tight, it’s worth it.

If you’ve got your own on-premises CRM server or you’re logging to CRM Online via your on-premises Active Directory credentials, you may need to work a bit harder to achieve connectivity between the CRM for Tablets app and the CRM server. This is because in both of these scenarios you will have ADFS (Active Directory Federation Services) sitting there in the middle, processing your login request and validating your user credentials. Of course the same technology is also used behind the pure cloud CRM Online service, but MS has done the configuration work for you, whereas with on-premises components you’ll be in charge of performing this.

Recently I was faced with a situation where a customer had deployed Dynamics CRM 2013 SP1 on-premises and done the Internet Facing Deployment via Windows Server 2008 R2 ADFS 2.0, published via Forefront TMG (Threat Management Gateway) 2010. Accessing CRM via the web client through the IFD address was working as expected, so was the CRM Outlook client. CRM for Phones was connecting without issues and I could even connect to the server via tools like XrmToolBox with no issues. There was just one problem: the CRM for Tablets wouldn’t connect to the server, no matter what. In the process of troubleshooting this particular scenario I learned a thing or two about the tablet app connectivity as well as server configuration tasks, so I thought I’d share my findings here on my blog. I’m by no means an expert on anything surrounding ADFS , but I’m stubborn enough to keep searching for answers until I find some from the great wide web.

RTFM – Read The Friendly Manual(s)

First of all, you’ll need to know your ADFS version, since there’s a few new hoops you’ll need to jump through when working with Windows Server 2012 R2 and the latest ADFS 2.2 (sometimes referred to as ADFS 3.0, since official version numbers seem to have been dropped by MS, in favor of just shipping ADFS together with Windows Server releases). The architecture of ADFS has changed considerably from earlier 2.0 and 2.1 versions, with no more IIS in the background, so the configuration process for CRM IFD also differs from the previous experience.

You’ll find the extra steps listed on this article: Configure Windows Server 2012 R2 for CRM mobile clients. On the ADFS 2.2 server you’ll need to enable forms authentication manually, since it’s not enabled by default, like in previous versions. Then you need to run a Powershell script on the CRM server to configure the OAuth provider. Finally, you should register the CRM for Tablets app ID’s with the ADFS server via another Powershell script.

You may run into an issue with the login process where the user is prompted for their AD credentials via the standard Windows domain dialog window repeatedly. This is because of some incorrect authentication settings that apparently are caused by the CRM IFD configuration process itself. To avoid these issues, you should run a repair installation on the CRM 2013 server with the Web Application Server role deployed, after you’ve done the IFD configuration and before you attempt to log in with the CRM for Tablets app.

Another aspect is the requirements imposed by the new Windows 8.1 version of the tablet app. Because of the changes on the OS layer, it’s no longer possible for Win8 apps to connect to any random server at will, but rather the developer has to specify the URL’s of these servers before publishing the app to the Windows Store. For CRM Online the domains for the service are known in advance, but for an on-premises deployment they could be absolutely anything. To overcome this, you’ll need to add a registry entry onto your device before attempting to connect to your server, otherwise the tablet app will just sit there and do nothing. Go to the page Set up CRM for Tablets, expand the section “what the admin needs to do” and grab the Powershell script from there. Running it on your device will prompt you for the CRM organization URL and create the necessary registry key for you.

When using TMG as the proxy server to publish your ADFS server, you’ll need to ensure that the configuration has been set up in a way that doesn’t interfere with the CRM login process. There’s an MSDN article on configuring Forefront Threat Management Gateway (TMG) 2010 as the web gateway for Microsoft Dynamics CRM Server 2011 that is the most recent documentation that I was able to discover on CRM & TMG coexistence. Since CRM 2013 Server is fairly similar to the earlier version when it comes to IFD, I assume these steps are perfectly valid. The documentation allowed me to discover an issue with the customer’s TMG web publishing rules, which had the the TMG default setting for authentication delegation that prevents direct client authentication with the server. As instructed on MSDN, this was changed to “No delegation, but client may authenticate directly”. At this point, the end results was still the same, with every other client being able to authenticate with CRM via ADFS, except for the CRM for Tablets app.

If (and when) errors occur when you attempt to connect with a CRM server behind ADFS, there’s an article on MSDN called “Troubleshooting and things to know about CRM for tablets“, which you should definitely review.

If you’re stuck with an unhelpful error message or a non-responsive tablet app and none of the known issues listed in the article, what you can try next is to enable tracing on the tablet app to collect more log data. Using a Windows 8.1 PC/tablet device provides you the log data in quite familiar surroundings via the Event Viewer. Now instead of a misleading message like “This operation failed because you’re offline” when you’re obviously not offline, you may be able to catch a lot more convincing error message, such as “CONSOLE6004 : Dynamics CRM [PAL] | Authentication: Authorization error: -2147093999”. It will at least give you a better keyword to search on Google Dynamics Community forums.

Digging Deeper with Fiddler

In my case the searches for error codes were unfortunately not turning up a solution that would have fit the scenario where my error was occurring. So, it was time to take a look behind the scenes and examine what’s really going on between the tablet app and the CRM & ADFS servers. When you need to analyze HTTP traffic in detail, who you gonna call? Fiddler! Surely an obvious choice for many developers out there, but somewhat of a hidden gem for a large crowd IT professionals who might well benefit from the superpowers that the tool gives you (check out this article series by CRM MVP Scott Durow for a closer look).

Firing up Fiddler on my Windows 8.1 PC allows me to also track traffic from the Metro Windows Store apps by clicking on the Win8 Config button and selecting the Microsoft Dynamics CRM app from the list. Note that you could even run the Fiddler trace for the iPad version of the CRM for Tablets app, by using your PC as a proxy server (thanks for yet another great the tip, Joel!).

From this traffic log I saw that the app was first connecting to the Organization web service on the CRM server and then attempting to authenticate via the OAuth2 endpoint on the ADFS server (/adfs/oauth2/). The response to this first and last call to ADFS was “404 – file or directory not found”, which meant that there was no one home at that endpoint address. Checking out the IIS website for the ADFS 2.0 server did confirm this status: no such endpoint listed there.

I decided to compare the results with my own test server, which was also running CRM 2013 SP1 but had been IFD enabled via Windows Server 2012 R2 instead, meaning it had the very latest ADFS 2.2 version. When logging into this server from the CRM for Tablets app, I saw not just one but four requests made to the Organization web service on the CRM server. In addition, there was a call made to the main.aspx page with a client id for the tablet app being passed on. Only after these steps did the app actually attempt to authenticate via the ADFS server. Unlike in the previous case, the endpoint being used here was the /adfs/ls/ address, and instead of OAuth the tablet client logged in via WS-Federation.

What’s interesting is that the /adfs/oauth2/ endpoint does exist on my ADFS 2.2 server, but apparently this is not the route the CRM for Tablets needs to take while connecting to an on-premises CRM 2013 deployment. When testing the app with CRM Online + ADFS 2.2, I did see the the traffic quickly bounce at /common/oauth2/ on login.windows.net before coming back to the /adfs/ls/ endpoint for authentication, so there might be some sprinkles of OAuth included in the process for that deployment type.

There’s an article called “Use OAuth to Authenticate with the CRM Service” on the CRM Team blog which I reviewed next, to understand a bit more about what might be going on. The first step of the authentication process involves requesting an OAuth bearer token from the service. The response given from CRM is a “401 – not authorized” but it contains a redirect URI telling the client where they should go to authenticate.

Studying the Fiddler logs revealed that this was in fact what the first contact to the Organization web service was doing. The tablet app sent the “Authorization: Bearer” header to the server and received back a URI that was pointing to the correct ADFS server, and the familiar /adfs/ls/ endpoint. Regardless of this, the app wanted to go the the /adfs/oauth2/ endpoint for some unknown reason.

We spent a good deal of time comparing settings between this environment and other similar ones where the CRM for Tablets app was working. TMG didn’t reveal anything suspicious, nor did the CRM server. On the ADFS 2.0 server’s IIS we discovered that the problematic environment only had Anonymous Authentication enabled in the /adfs/ls/ site, whereas the other server also had Windows Authentication Enabled there.

After changing this setting on the IIS server to enable both Anonymous and Windows Authentication (note that you won’t have this on the non-IIS ADFS 2.2+ servers) and re-configuring IFD for the CRM server, we tested logging in with the tablet app once again. Surprisingly, this time it all worked and the app was able to log in to the CRM organization.

The response header from the CRM server to the app’s OAuth bearer request no longer contained a URI after the ADFS website had been enabled for Windows Authentication (which at this point had not yet been contacted by the app, mind you). This was apparently enough for the CRM for Tablets app to determine that it should try a different authorization method, leading it to successfully contact the /adfs/ls/ endpoint and log in to CRM.

So, at the end of the day we had a working on-premises / tablet combo for CRM 2013. Although the specific setting that fixed the issue was not discovered from the official documentation (nor do I have any idea why it works with the setting), at least I got the chance to review a whole bunch of useful resources related to the server configuration and troubleshooting steps when working with the CRM for Tablets app, to be better prepared for the next time when someone wants to go mobile with their on-prem Dynamics CRM environment. Plus I had a fun time looking behind the curtain with Fiddler, to understand what really goes on when the computer says “no”.