A while back I was lucky enough to chat with a member of the AD FS development team, to compare notes and discuss features missing or lacking in the current release.  One item that popped up and  which I rued the absence of, was the ability to customize relying parties. It turned out that this was a fairly common feature request. This omission, I’m glad to see, has been addressed in AD FS under Windows Server 2016. While the changes described are mostly cosmetic, they do allow some basic changes to the look and feel of the environment and, most importantly, improve overall user experience.  Let’s have a look at some of these.

Our basic configuration consists of a Windows Server 2016 TP4 server with the AD FS role installed and the presence of a relying party trust to a SAML-based web application.  Our relying party, called ‘simpleSAMLphp Demo’, will be the guinea-pig for this little exercise, though it plays no real part besides kicking off the sign-in process (RP-initiated sign-on). All changes are made on the AD FS side to customize the login experience.

 

Message-Level

Here we tinker with messages presented to the connecting user/device via the Set-AdfsRelyingPartyWebContent cmdlet.

Set-AdfsRelyingPartyWebContent -TargetRelyingPartyName “simpleSAMLphp Demo” -CompanyName “Cepa Fidelis ” -OrganizationalNameDescriptionText “Enter your Access Onion account” -SignInPageDescription “This is for access to simpleSAMLphp Demo RP”

 

Logos and Illustrations

In addition to customizing messages, it’s also possible to present specific logo and illustrations on a per RP basis. Here we copy the content to the AD FS server and then run the Set-AdfsRelyingPartyWebTheme cmdlet : 

Set-AdfsRelyingPartyWebTheme -TargetRelyingPartyName “simpleSAMLphp Demo” -Logo @{path=”C:\Content\rp1\logo.png”} -Illustration @{path=”C:\Content\rp1\illustration.png”}

 

…and connecting users are magically transported to the Tirol

 

Page-level

This allows for page-level changes on a per RP basis. Previously in AD FS 2012 R2, such changes were possible only at the federation service level and thereby applicable to all relying parties.

Set-AdfsRelyingPartyWebTheme -TargetRelyingPartyName “simpleSAMLphp Demo” -OnLoadScriptPath @{path=”c:\content\rp1\onload.js”}

As with Windows Server 2012 R2, we can export the default theme to obtain the javascript (onload.js) that we wish to modify.

Export-AdfsWebTheme –Name default –DirectoryPath c:\content\default

One of the more common onload.js customization changes employed in AD FS 2012 R2 lay with a code change to support the use of sAMAccountName style formatting, similar to that supported in AD FS 2.0. This involved changing the onload.js file and then hardcoding the domain name into the form as described here.

Summary

Well, that’s nice, but these examples are just scratching the surface.. Take a look at the Get-AdfsRelyingPartyWebContent cmdlet  and we can see there are multiple additional options that can be changed.

Let’s set a descriptor for additional authentication text.

Set-AdfsRelyingPartyWebContent -TargetRelyingPartyName “simpleSAMLphp Demo” -SignInPageAdditionalAuthenticationDescriptionText “This application requires additional authentication. Please choose the appropriate multi-factor authentication mechanism. Time wasters will be shot.”

 

Similarly, looking at the cmdlet (Set-AdfsRelyingPartyWebTheme) used to configure logos and illustrations, there’s also some hidden nuggets.

Here, we copy the web theme from one RP (simpleSAMLphp Demo) to another (Office 365). 

Logon to Office 365 and the default AD FS theme has logos and illustration changed.

Note that the text/messaging has not been altered, because we did not elect to change this for our O365 RP via Set-AdfsRelyingPartyWebContent.

Explore… explore… have fun!