Understanding and debugging the web authentication broker workflow (HTML)

You can use the web authentication broker to enable single sign-on (SSO) for your users and seamlessly authenticate to a single service across multiple Windows Store apps. The web authentication broker supports the OAuth and OpenID internet authentication protocols, so you can integrate your app with a web service that provides user authentication. This allows you to utilize user identity in your apps from services such as Facebook, Flickr, Google, and Twitter.

When an app calls the web authentication broker, the user gets a dialog box in which the necessary web pages are rendered to sign in. The provider of the service must allow the user to explicitly consent to that authentication, and typically includes a "Keep me logged in" option. The provider must also make it clear to the user how their identity is being used, typically by providing a link to a privacy statement from the logon page. After the user completes those steps, the dialog box goes away and the user continues with the app.

The following diagram shows an example modal dialog box.

Benefits of using web authentication broker

The web authentication broker provides the following benefits:

• An easy-to-use programming interface that frees the app developer from hosting a browser control within their own app.
• Integration of a provider's web page with a Windows 8 user interface. For more information for online providers, see Web authentication broker for online providers.
• User credentials that are isolated from your app.
• Native support for single sign-on with online providers.

How web authentication broker works

The web authentication broker is the broker or facilitator between your app and your authentication service. It consists of a set of APIs, a broker, and a web host. Your app uses the APIs to communicate with the broker. The broker creates a new web host process in a separate app container. The broker communicates with the app, assembles the user interface (UI), and controls the lifecycle of the web authentication host. The web authentication host renders the pages from the online authentication provider's website.

The following diagram shows the flow of information using web authentication broker.

The typical workflow of using web authentication broker is as follows:

1. 1. Your app invokes the web authentication broker using the WebAuthenticationBroker.AuthenticateAsync method. You provide a providing a starting request URI and a callback URI for when the authentication call completes. These correspond to an Authorization Endpoint URI and Redirection URI in the OAuth 2.0 protocol. The OpenID protocol and earlier versions of OAuth have similar concepts.
2. The broker creates a system dialog box that is modal to the calling app.
3. The broker selects a dedicated app container that is separate from the calling app or any other app on the system and clears any persisted cookies. Note  This app container is never shared between two apps simultaneously unless the broker was started in the single sign-on (SSO) mode.  
4. The broker starts the web authentication host in the selected app container.
5. The broker attaches the host's window to the dialog box it created earlier. The host window is responsible for rendering the web content.
6. The web authentication host navigates to the request URI. Typically this is a logon page.
7. As the user interacts with the online provider website by clicking links or submitting information, the host checks each URI for a match with a callback URI provided by the app before navigating to it.
8. If a match is found, the host ends the navigation and signals the broker.
9. The broker takes down the dialog box, clears any persisted cookies created by the host from the app container, and returns the protocol data back to the application.

How Web authentication broker single sign-on works

The Web authentication broker enables single sign-on (SSO) by allowing persisted cookies in a special purpose SSO app container. To use this container, your app can call the overload of the AuthenticateAsync method that does not take a callback URI. The starting redirect URL must be in the form of "ms-app://<SID>" where <SID> matches the SID of the calling package. You can then register the SID for each of your apps with the authentication service as a valid redirect URL (also referred to as a "redirection endpoint").

For example, Fabrikam is a developer of a Windows Store app that uses Contoso’s services. At development time, Fabrikam registered its application with the Windows Dev Center and as a result received a unique SID. Then Fabrikam registered their app SIDs as valid redirect URLs with the Contoso.com authentication service. Fabrikam registered two of its SIDS as redirect URLs, one of which was "ms-app://S-1-5-4321".

At runtime, Fabrikam's Windows Store app invokes Web authentication broker in SSO mode. As part of processing the request, Contoso.com verifies that the redirect URL is in the set of registered URLs. After Contoso authenticates the user, it then redirects to the requested redirect URL with an access token appended: "ms-app://S-1-5-4321?token=ABC". When the web authentication broker encounters a URL of this form that matches the calling app's SID, it returns the token contained in the query string or post data back to the app.

If there were any cookies already created in the SSO app container, the user would not need to sign in to Contoso. If any other app were to try to impersonate Fabrikam’s app, it would have failed because Contoso verified the identity of the app by making sure it one of the already registered redirect URLs is being requested and web authentication broker made sure that only the app that shares the same SID as one that Contoso wants to redirect to gets the protocol data.

Troubleshooting Web authentication broker

There are several ways to troubleshoot the web authentication broker APIs for your app, including reviewing operational logs and reviewing web requests and responses using Fiddler.

Operational logs

Often you can determine what is not working by using the operational logs. There is a dedicated event log channel Microsoft-Windows-WebAuth\Operational that allows website developers to understand how their web pages are being processed by the Web authentication broker. To enable it, launch eventvwr.exe and enable Operational log under the Application and Services\Microsoft\Windows\WebAuth. Also, the Web authentication broker appends a unique string to the user agent string to identify itself on the web server. The string is "MSAuthHost/1.0". Note that the version number may change in the future, so you should not to depend on that version number in your code. An example of the full user agent string is as follows:

User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; Win64; x64; Trident/6.0; MSAuthHost/1.0)

Example of using operational logs

1. Enable operational logs
2. Run Contoso social application
3. The generated logs entries can be used to understand the behavior of Web authentication broker in greater detail. In this case, these can include:
   • Navigation Start: Logs when the AuthHost is started and contains information about the start and termination URLs.
   • 
   • Navigation Complete: Logs the completion of loading a web page.
   • Meta Tag: Logs when a meta-tag is encountered including the details.
   • Navigation Terminate: Navigation terminated by the user.
   • Navigation Error: AuthHost encounters a navigation error at a URL including HttpStatusCode.
   • Navigation End: Terminating URL is encountered.

Using Fiddler with web authentication broker

The Fiddler web debugger can be used with Windows 8 apps.

1. Since the AuthHost runs in its own app container to give it the private network capability, you must set a registry key: Windows Registry Editor Version 5.00

   HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\authhost.exe\EnablePrivateNetwork = 00000001

   •                      Data type
                          DWORD

2. Add a rule for the AuthHost as this is what is generating the outbound traffic.

   CheckNetIsolation.exe LoopbackExempt -a -n=microsoft.windows.authhost.a.p_8wekyb3d8bbwe
   CheckNetIsolation.exe LoopbackExempt -a -n=microsoft.windows.authhost.sso.p_8wekyb3d8bbwe
   CheckNetIsolation.exe LoopbackExempt -a -n=microsoft.windows.authhost.sso.c_8wekyb3d8bbwe
   D:\Windows\System32>CheckNetIsolation.exe LoopbackExempt -s
   List Loopback Exempted AppContainers
   [1] -----------------------------------------------------------------
       Name: microsoft.windows.authhost.sso.c_8wekyb3d8bbwe
       SID:  S-1-15-2-1973105767-3975693666-32999980-3747492175-1074076486-3102532000-500629349
   [2] -----------------------------------------------------------------
       Name: microsoft.windows.authhost.sso.p_8wekyb3d8bbwe
       SID:  S-1-15-2-166260-4150837609-3669066492-3071230600-3743290616-3683681078-2492089544
   [3] -----------------------------------------------------------------
       Name: microsoft.windows.authhost.a.p_8wekyb3d8bbwe
       SID:  S-1-15-2-3506084497-1208594716-3384433646-2514033508-1838198150-1980605558-3480344935
   

3. Add a firewall rule for incoming traffic to Fiddler.

For more information, see Blog on using Fiddler web debugger with Windows Store apps.

Related topics

Web authentication broker for online providers

Web authentication broker sample

Windows.Security.Authentication.Web