#ADFS, IWA and the WIASupportedUserAgents property

Recently, I’ve found myself answering several questions and writing emails and some change control paperwork on the topic of Integrated Windows Authentication (IWA) in AD FS.  I’m going to commit the behaviour to this blog for posterity and easy (lazy) reference.

Active Directory Federation Services (AD FS) 2012 R2 or 2016 implicitly support IWA and Forms Based Authentication (FBA).  The federation service servers authenticate clients based on the set of permitted handlers configured in the system.  When AD FS receives a request to a token endpoint (and the SSO cookie is not present or is present and is not valid) it grabs the user agent of the client and performs a comparison to see if any of the strings defined in the WIASupportedUserAgents property match against the user agent.

The comparison is a String contains comparison in 2012 R2 and 2016 by default, however 2016 also supports regex match should you configure it (by adding strings prefixed by an equals and a tilde =~, the same character set used to describe regex in the claims language, e.g. =~Windows\s*NT.*Edge).

If there is a match then the IWA handler is invoked.  If there is not a match the FBA handler is invoked.  Whether or not FBA is enabled in global authentication policy is irrelevant here.  Let me re-state that.  FBA is available and will be used without you specifically selecting (enabling) it within the global authentication policy.  IWA fails back to FBA regardless of the global authentication policy configuration. 

However, if AD FS is provided with instructions on what handler to invoke, e.g the WAUTH parameter in WS-Fed or the RequestedAuthnContext in SAML2P then the global authentication policy is inspected and the request will fail if FBA is not enabled.  This is important if any of your clients request a specific authentication handler.  And be sure to remember that Modern Authentication applications, i.e. applications that authenticate to Azure AD using ADAL, are such applications.  If a modern authentication app sends prompt=login to Azure AD for a federated domain AAD will translate that into &wauth=urn:oasis:names:tc:SAML:1.0:am:password&wfresh=0 which will fail if FBA is not enabled.

Note that AD FS 2016, and AD FS 2012 R2 with the July 2016 update rollup (kb3172614), have new functionality to natively support prompt=login without translating it into WS-Fed, so that IWA can still be used.  This is configured on your federated domain in Azure AD using Set-MsolFederationSettings.

Enabling IWA beyond Internet Explorer

Out of the box AD FS 2012 R2 has a bunch of user agents defined to support IWA using Internet Explorer and the Windows 8.1 authentication broker.  Other IWA-capable browsers are excluded by default.  By default Chrome and Firefox, for example, don’t work – you have to configure them to do IWA, hence we fallback to FBA as that is a better user experience.

AD FS 2016 also supports Microsoft Edge by default, and has a string for OneDrive for Business (OD4B) Next Generation Sync Client (NGSC) .

Many customers need to enable IWA for Edge and Chrome in 2012 R2 and Chrome in 2016.  So let’s look at the WIASupportedUserAgents  property by OS.

WIASupportedUserAgents in 2012 R2

A default installation of AD FS 2012 R2 has the following values defined in the WIASupportedUserAgents property:

  • MSAuthHost/1.0/In-Domain
  • MSIE 6.0
  • MSIE 7.0
  • MSIE 8.0
  • MSIE 9.0
  • MSIE 10.0
  • Trident/7.0
  • MSIPC
  • Windows Rights Management Client

The AD FS documentation provides an update to this default list.

  • MSIE 6.0
  • MSIE 7.0; Windows NT
  • MSIE 8.0
  • MSIE 9.0
  • MSIE 10.0; Windows NT 6
  • Windows NT 6.3; Trident/7.0, Windows NT 6.3; Win64; x64; Trident/7.0
  • Windows NT 6.3; WOW64; Trident/7.0
  • Windows NT 6.2; Trident/7.0
  • Windows NT 6.2; Win64; x64; Trident/7.0
  • Windows NT 6.2; WOW64; Trident/7.0
  • Windows NT 6.1; Trident/7.0
  • Windows NT 6.1; Win64; x64; Trident/7.0
  • Windows NT 6.1; WOW64; Trident/7.0
  • MSIPC
  • Windows Rights Management Client

Which accidently removes the authentication broker!  (MSAuthHost/1.0/In-Domain)

WIASupportedUserAgents in 2016

A default installation of AD FS 2012 R2 has the following values defined in the WIASupportedUserAgents property:

  • MSAuthHost/1.0/In-Domain
  • MSIE 6.0
  • MSIE 7.0
  • MSIE 8.0
  • MSIE 9.0
  • MSIE 10.0
  • Trident/7.0
  • MSIPC
  • Windows Rights Management Client
  • MS_WorkFoldersClient
  • =~Windows\s*NT.*Edge

MS_WorkFoldersClient is new, as is the last entry for Microsoft Edge.  The last entry demonstrates new functionality in AD FS 2016 that supports regex match – remember that the default behaviour in 2016 is the same as the only behaviour in 2012 R2, which is to perform a contains string comparison.  Anything that starts with an equals and tilde is a regex.

Adding support for Chrome and Firefox and Opera

The easiest way to include Chrome and Firefox and Opera into the mixture is to add the following string:

  • Mozilla/5.0 (Windows NT

Do be sure to include “(Windows NT” otherwise you’ll match Android and iOS devices, which is really bad, trust me.

Truthfully, this string will probably match most variants of IE too, however unless you want to strip out of box values out and test it, the least painful option is to just add it at the end.

Summary

If you want Chrome or browsers other than Internet Explorer to perform Integrated Windows Authentication you have to update your WIASupportedUserAgents  property to identify and support the browser.  You must be mindful that you only want to match browsers that are actually capable of doing IWA – you must not include mobile devices, for example.  And you also need to understand that if you don’t configure the browser to perform IWA then you will not fallback to forms, but will instead see the browsers native credential input box.  I generally add “Mozilla/5.0 (Windows NT” without the quotes to the existing value.  That keeps the change control paperwork simple.

I discuss more information on the settings needed for Chrome and Firefox in this post if you are interested:

However it is important to note that Chrome now supports Enhanced Protection for Authentication (Channel Binding encryption) so you DO NOT NEED TO TURN IT OFF as many older blogs will recommend (including my referenced post).  More information on that change to Chrome here:

You don’t have to enable forms based authentication for intranet in the global authentication provider to support fallback to FBA for non-IWA browsers.  However you do need to enable FBA if you are an Azure AD/Office 365 user or you have any relying parties that might specify an authentication mechanism using WAUTH or RequestedAuthnContext.

Lastly, please do test changes to WIASupportedUserAgents in a lab before unleashing on your production network.

If you choose to bin the out of box configuration and implement a minimal configuration please let us know via the comments.

Advertisements

About Paul Williams

IT consultant working for Microsoft specialising in Identity Management and Directory Services.
This entry was posted in AD FS and tagged , , , , , , , , , , . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s