WebAuthenticationBroker Hints

Anyone who has tried to use the WebAuthenticationBroker beyond the simplest of scenarios has probably run into problems and sometimes all you want is a good descriptive error message. Getting things setup just right often takes a certain amount of trial and error so I’m documenting a few things here which are the results of a certain amount of trial and a considerable amount of error. This is as much a reminder for myself the next time I try and do this as it is (hopefully) some useful extra information for you.

Single Sign-in

If you can get the stars to align correctly, your OAuth endpoint can perform single sign-in on a corporate network. If you read the documentation you’ll see you have to specify the flag WebAuthenticationOptions.UseCorporateNetwork when you call AuthenticateAsync. This can be confusing because this flag isn’t needed when debugging when your app is given Intranet access automatically. To set this flag you also need to specify Enterprise Authentication, Private Networks and Shared User Certificates capabilities in your application manifest. Once you’ve added these you can’t submit the app through the public Windows Store.

A caveat to this is that you can only do single sign-in if your “web” application is setup with a redirect Uri which is the app package identity and you use the overload of AuthenticateAsync which doesn’t take a redirect Uri. This is the Uri returned from a call to Windows.Security.Authentication.Web.WebAuthenticationBroker.GetCurrentApplicationCallbackUri() at runtime. This identity will change between a side-loaded developer signed package and one which has been distributed through the Windows Store or a private company portal.

Error Codes

A lot of errors within the WebAuthenticationBroker process will result in a return status of WebAuthenticationStatus.UserCancel. However this is not always because the user has explicitly cancelled the process. The ResponseErrorDetail property returns an error code to give the reason and here are some possible values:-

0x800c0019 – An SSL failure. A common cause of this is that the clock is not set correctly on your phone/PC and it can often occur when your device battery went flat and it reset itself to some default date in 2014 and you’ve forgotten to correct it.

0x800c0005 – Network connection error. This is probably because you have no mobile signal and no WiFi.

This isn’t an exhaustive list but knowing the common error codes allows you to write a descriptive message for the user to hopefully resolve the problem themselves.