Web authentication broker considerations for online providers (XAML)

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

As an authentication provider, there are certain details to consider when setting up your authentication service to be consumed by Windows Store apps. In addition, you can customize the web page that is displayed to the user of the Windows Store app with your preferred markup.

Considerations for online authentication providers

Web authentication broker is built on the top of the same technologies that power Internet Explorer in Windows. However, due to a very special purpose of this component some features of the Internet Explorer were disabled or locked to specific configuration. Also, Web authentication broker provides a dedicated event logging channel to help troubleshoot issues with pages that it processes.

Internet Explorer standard document mode

The Web authentication broker displays all pages in the IE standards mode for the specific release of Windows. For example, in Windows 8 the Web authentication broker displays pages in "IE10 Standards Mode". You can use the developer tools in Internet Explorer to see how your page works under different document modes. For more information on Internet Explorer compatibility, see the MSDN topics for Internet Explorer.

Disabled and locked down features

Several features of Internet Explorer are either completely disabled or locked down to specific values that can’t be changed in the Internet Options of the operating system.

HTTPS requirement

The first URL that an application will use to communicate with the online provider is required to be HTTPS.

Dimension for different VIEW states

A Windows 8 app may appear in several different sized apps, portrait or landscape orientation, or within a Charm such as Share Charm. Depending in which view the Web authentication broker appears, the size with which the web pages has to work could be different. For more information, see the Guidelines for window sizes and scaling to screens topic and the Guidelines for sharing content topic.

The web page should use CSS media queries to check the size it has to work with and lay itself out accordingly. However, the page should not be designed based on the exact pixels documented here and should be able to scale to different sizes. The sizes specified in this document are subject to change in future OS versions.

If a page can’t fit all of the information in the allotted space (for example, a long list of permissions that an application is requesting), the Web authentication broker will provide scroll bars to allow the user to scroll the page as needed. Zooming is also provided by pinch zoom for touch-based devices and Ctrl + mouse wheel for desktop and laptop PCs.

To test different scaling factors use the Web authentication broker SDK sample app loaded in Microsoft Visual Studio Professional 2012 which allows simulating different view sizes.

Sample view

The following example shows the Web authentication broker UI where the web page dimensions are:

• Width: 260 pixels
• Height: Screen height (depends on the screen resolution)

Note that the Web authentication broker UI is only on the right side of the screen capture.

Charm view

For the Charm view, the web page dimensions are:

• Width: 566 pixels
• Height: Screen height (depends on the screen resolution)

The following example shows the Web authentication broker UI in Charm view.

File picker view

For the file picker view, the web page dimensions are:

• Width: 566 pixels
• Height: Screen height (depends on the screen resolution)

The following example shows the Web authentication broker UI in file picker view.

No new windows by default

By default, no URLs will result in a new window being opened but will instead be displayed within the Web authentication broker window. This includes window.open JavaScript method, "target" attribute of the hyperlinks, or when the user uses the Ctrl+Click mechanism to force a new window to open. The exception to this rule is when a web page declares a link as safe to be navigated in a browser as described in the Customizing Target of the Hyperlinks.

Customizing web authentication pages

A web page customizes the user interface (UI) with the title, icon, and header color by using metadata tags defined on the web page. Web developers can use HTML <meta> tags to display the provider's personality and brand in the Web authentication broker UI. In addition, developers can direct more intricate user actions, for example signing up and recovering passwords. The concept is very similar to Pinned Sites feature of the Windows Internet Explorer 9 and Windows 7.

In addition to customizing the user interface around the web page area, the web page should also take advantage of the Windows 8 controls’ styles, be enabled for touch, and enable links to be opened in the browser where appropriate.

The following is an example of a web page that has taken advantage of the Web authentication broker customization model.

Customizing the icon

The web page can provide an icon by using an mswebdialog-logo meta tag.

<meta name="mswebdialog-title" content="Contoso Social"/>

The content is a URL that can be a page relative or absolute. The scheme of the URL can be HTTP or HTTPS. The format of the file should be either PNG or JPG. The size of the image should be 30x30 pixels. If the image is of the different size, it will be scaled down or up by the operating system to fit the 30x30 space. The image should be designed to render well when scaled up to 140% and 180% to account for higher resolution screens. To test different scaling factors, use the Web authentication broker SDK sample app loaded in Visual Studio 11 which allows simulating different resolutions and scaling factors using the Device windows of the Design mode.

Customize the title text

The web page can provide the title by using the mswebdialog-title meta tag.

<meta name="mswebdialog-title" content="Contoso Social"/>

The title should be short and should reflect the brand of the provider (for example, Contoso).

Customize the header color

The web page can provide the color that represents its brand identity to be used for the header of the dialog by using the mswebdialog-header-color meta tag.

<meta name="mswebdialog-header-color" content="#1267DF"/>

The color can be any value specified here. However, the Web authentication broker will ignore any alpha channel value. With this color specifically and with colors used on the page in general, it is recommended to follow the same colors used in provider’s Windows 8 app if such app exists.

Note  Icons and colors are cached per server on the client once META tags are parsed. Clear the client cache before launching the UI in order for the changes to take effect. To do so, modify the following registry settings.

// Registry location under HKLM used for setting various AuthHost parameters.
#define AUTH_HOST_LOCAL_MACHINE_REGPATH \
    L"SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\Image File Execution Options\\authhost.exe"
// MaxAge to use for downloading logo images
#define AUTH_HOST_LOGO_IMAGE_MAX_AGE_SECONDS_REG_VALUE_NAME \
    L"LogoImageMaxAgeSeconds"
// 24 hours
#define AUTH_HOST_LOGO_IMAGE_MAX_AGE_SECONDS_DEFAULT        \
    (24 * 60 * 60)

Once an icon is downloaded it is not picked up again for 24 hours. In order to test with logo images, set the reg key above with a lower value.

Customize the web page

In addition to customizing the UI around the web page, developers should also create web pages that are seamless and integrated with the overall Windows 8 experience. This includes using recommended styles, making sure web pages work great with touch enabled devices, and open certain web pages in the web browser.

• Styling

  It is strongly encouraged to use the styling recommended here to create a more consistent user experience across Web authentication broker web pages and other UI components of Windows 8. The web page should use a white background and no borders. The buttons such as Login or Cancel should be positioned at the right bottom corner and use the same color as the header. Finally, since Web authentication broker provides a Back button, consider eliminating a Cancel button from the web page completely.

• Enabling touch

  The web page should be designed with a touch-based user interaction in mind. For more information about designing for touch in Windows 8, see the Touch interaction design topic.

• Customizing target of the hyperlinks

  Web authentication broker is great for delivering web pages that require a single user action such as logon or OAuth authorization pages. However, for more intricate user flows such as account creation, recovering from a lost or forgotten password, showing privacy statements and so on, where the user is expected to invest some time in understanding and completing the flow, it is recommended that these pages be launched in the user’s preferred browser to support full-navigation and reach browsing. Web authentication broker by default doesn’t allow new browser windows to be opened from a web page (see section No New windows By Default for more details). However, by using the meta tag mswebdialog-newwindowurl the web page can declare which URLs should be opened in the browser.

  The mswebdialog-newwindowurl allows the web page to specify a URL or part of the URL that the Web authentication broker will use to match (left-hand string match) against every time it is asked to open a URL in a new window either by using the target attribute or window.open() method. If there is a match, the URL will be opened in the user’s default browser. If there is no match, the Web authentication broker will navigate to the URL itself (default behavior). For example:<meta name="mswebdialog-newwindowurl" content="https://www.contoso.com/privacy"/>

  In the case of this meta tag, the Web authentication broker will open the https://www.contoso.com/privacy/policy.html in the browser, but will directly navigate to https://www.contoso.com/termsofuse.html. Note that links that don’t attempt to open in a new window (for example, links that are not using target attribute or window.open() method) are not affected by this meta tag. The content is a URL that can be a page relative or absolute. The scheme of the URL can be HTTP or HTTPS. You should define mswebdialog-newwindowurl meta tags to cover any links that are not part of the core user flow such as privacy statements, sign up forms, and such. If you support login with a third-party authentication provider (for example, OpenID providers), make sure to keep those interactions within the Web authentication broker. To enable all links on your page as safe to be opened in the browser, use the star syntax, such as, <meta name="mswebdialog-newwindowurl" content="*"/> Note that the “*” can only be used exclusively and can’t be combined with another URL, for example, "https://www.contoso.com/*" is not a valid syntax.

Rules applied to all meta tags

When Web authentication broker processes meta tags, the following rules apply:

• The effect of the meta tag will persist across all pages under same second level domain (for example, contoso.com) unless another meta tag of the same name but different content is encountered.
• If multiple meta tags of the same name are encountered on the same page, the Web authentication broker will choose only one of them and ignore the rest. Which specific meta tag is chosen is undefined. Note  This rule does not apply to the mswebdialog-newwindowurl meta tag that allows multiple instances on the same page.  

Related topics

Web Authentication Broker

Web authentication broker sample

Windows.Security.Authentication.Web

Connecting to online identity providers