Customizing ADFS To Match Azure AD Centered User Experience


Back in December 2017 the User Experience (UX) for Azure AD login changed to a centered (or centred, depending upon where in the world you speak English) login page with pagination. Pagination is where you enter the username on one screen and the password on the next. This was covered in new Azure Active Directory centered sign-in experience and recently in early April 2018 Microsoft announced changes to the UX to include the removal of all the right-aligned pages (for example the MFA screens and password reset).

This means that the only right aligned UX will be in organizations where ADFS is still in use (ADFS from Windows Server 2016 and earlier – its centred by default for ADFS in Windows Server 2019). If you have moved to Pass Through Authentication or Password Hash Authentication with Single Sign-On enable for either of these auth methods then you will have the new UX.

So how can you get the ADFS UX to match. Actually its very simple. There are two files needed, one is the stylesheet to adjust the view of the HTML forms and the second is the JavaScript file needed to hide the password field when asking for the username and visa versa. And as well as the two files, two PowerShell cmdlets. One to upload the files to ADFS and the second to enable the new theme. And it is even simpler to roll back the changes with immediate effect. This is a simple change with much benefit for your end users.

So lets take a look on a default unbranded ADFS installation. This is ADFS 2012 R2, but this same process works with ADFS 2016:

image

We are going to take this ADFS implementation and change it to:

image

Later in this blog post we will also look at the logo and background illustration branding that can have an impact on how the above looks.

Downloading the UX File

First though we need to get the stylesheet and the JavaScript files. These are written by Microsoft and available on GitHub as Open Source content. If you find issues with them, fork the code, modify it to fix your issues, and request the updates are merged back in to the master branch of the code!

You will find the GitHub CenteredUI resources on https://github.com/Microsoft/adfsWebCustomization/tree/master/centeredUi.

On this page you will find the readme and two files – the stylesheet, which is called ThemeCenterBrand.css and the JavaScript, which is called paginatedOnload.js. For Right to Left languages use the ThemeCenterBrandRTL.css file instead.

In ADFS there is a default theme which gives the above original look and feel, and we will create a new theme, upload the above two files to the new theme and then activate the new theme. To rollback your changes, activate the “Default” theme instead.

So in the GitHub repository, open each of the two files, click the Raw button to get the file contents and nothing else and copy the css or js to a empty text file that you save with the above file names to a folder on your primary ADFS server.

Note that it is important to save the files as UTF-8 and not ANSI or Unicode. The JavaScript won’t work if you use Unicode and if you use ANSI you remove all the internationalization and languages from the code.

Now that you have both files in a folder on your primary ADFS server you have the option to customise them. Customization might include adding languages and the localization text for any missing language.

Once you have customised the files if necessary, minimize the JavaScript file using an online JS minimizer service. In the defaults I was able to compress both the JavaScript and CSS files and save 36KB, which is a saving for every user and every login, and as well as less bandwidth, results in faster page load times.

Customizing the UX in ADFS

Once you have the two files available on the ADFS server, you can run the following PowerShell on the ADFS server:

# Enable IdpInitiatedSignOn if using ADFS 2016, as it is off by default:
Set-AdfsProperties –EnableIdpInitiatedSignonPage $True
# Create a new theme and set the stylesheet and JavaScript to the downloaded files
New-AdfsWebTheme -Name AzureAD -SourceName default -StyleSheet @{path="c:\adfsTheme\ThemeCenterBrand.css"}
Set-AdfsWebTheme -TargetName AzureAD -AdditionalFileResource @{Uri="/adfs/portal/script/onload.js"; path="c:\adfsTheme\paginatedOnload.js"}

The above creates a theme called “AzureAD” which is a copy of “Default” and changes the stylesheet to your downloaded stylesheet. The second line updates the new theme with the new JavaScript file.

If you have already created custom themes and want to use them as the source, then that is possible – but remember to include in the replacement stylesheet and JavaScript your original customizations.

Then to go live with the theme run either of the two following PowerShell cmdlets:

#To update the theme for all relying parties in ADFS
Set-AdfsWebConfig -ActiveThemeName AzureAD
#To update the theme for only Office365/AzureAD relying party trust and leave your current defaults for any other relying party trusts you have in place (ADFS 2016 only)
Set-AdfsRelyingPartyWebTheme -TargetRelyingPartyName urn:federation:MicrosoftOnline -SourceWebThemeName AzureAD

image

image

Note that the CSS and JS files are uploaded to ADFS and will replicate automatically to all ADFS servers in the farm within 15 minutes. You do not need the source files on each server in the farm.

Different UX Options

The following screenshot is with the CSS only and not the JavaScript uploaded. Notice no pagination and that the background image is not overlayed by a dark tint (in line with Azure AD login designs)

image

The below image shows the pagination working, with the generic avatar and just the password field. If the username is provided by a user_hint then this would be the first page the users sees if connecting from a non-domain joined machine. If you are on the LAN and domain joined, then you will never see these customizations anyway as single sign-on will take effect.

image

Illustrations and Logo UX Changes

In https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/ad-fs-user-sign-in-customization there are further steps on changing the illustration (the background image) and the logo. Lets see how this works and what it looks like to finish

First your logo should be 24px by 256px max, without padding and a transparent background.

Second, your illustration should be 16:9 or 16:10 aspect ratio and 1024px by 1080px and under 200KB, with the highest resolution possible as it will be scaled to all screen resolutions as needed.

Finally, once these are all ready, you can run the PowerShell to update the logo and illustration. Below I have customised the company name as well, though that is replaced by the logo anyway

Set-AdfsGlobalWebContent -CompanyName "C7 Solutions"
Set-AdfsWebTheme -TargetName AzureAD -Logo @{Path="C:\adfsTheme\C7 Solutions - Login Banner.png"}
Set-AdfsWebTheme -TargetName AzureAD -Illustration @{Path="C:\adfsTheme\o-OXFORD-UNIVERSITY-1024-1080.jpg"}

image

image

Mobile and Modern Auth UX

When on a smaller device, such as on a phone, or in the Modern Auth popups in Office applications etc. you get a UX similar to the below:

image followed by image

Comments

13 responses to “Customizing ADFS To Match Azure AD Centered User Experience”

  1. Rkast avatar
    Rkast

    Hi Brian, very nice article really clear with the pictures. The branding looks very nice! I surely will implement this at customer this week.

    Question i have, you mention ‘ user_hint ‘ can you ellaborate more on this? How can we use this or send an user_hint? We use smart links for internal sso but this user_hint would be nice for extranet users.

    1. Brian Reid avatar

      It’s application specific, and I think Open ID Connect also calls it login_hint. Smart links (I.e. longer URL or 301 redirect services do similar) and it all falls into the same category as domain_hint for redirecting directly to ADFS and not going via Home Realm Selection on the AzureAD login portal

  2. Andrew Kemp avatar

    That’s pretty cool just applied it in my lab. applied the same illustration and logo to the Azure AD Portal, so when using Azure MFA with ADFS 4 you get the same look and not just the same feel.

    1. Brian Reid avatar

      Or make use of the AzureAD branding that you get with AzureAD Basic, or AzureAD Premium or Office 365 licences and then the Azure MFA etc pages match your branding and illustration rather than taking Microsoft’s graphic, which might be copyright anyway!

  3. Matthew avatar

    Very specific instructions, I was able to follow them and make the change to my lab AD FS via RDP from my iPad in about 10mins. I couldn’t get the js minimizer to download the new files but this was just for a lab anyway.

  4. Dylan avatar
    Dylan

    Hi,

    I was wondering if you could help me out. You mention the generic avatar, but I can’t find where in the js file it mentions that (line 724 for me is ” backButton.id = “backButton”;” – what text should I be looking for?) – to display the generic avatar, do I have to host the avatar file (https://github.com/Microsoft/adfsWebCustomization/blob/master/centeredUi/images/empty_user.png) somewhere? At the moment our ADFS server (with the centeredUI enabled) does not show the grey box and avatar icon around the username on the password page (I am using the paginatedOnload.js), seems like I’m missing something 🙁

    Is it possible for the js to pull the thumbnailphoto from AD for the avatar image?

    Thanks for any help!
    Dylan

    1. Brian Reid avatar

      Did you save the css and js files you downloaded as UTF-8 encoded files as mentioned in the blog? If not, this is the behaviour that I expect to see

    2. DetroitTechno avatar
      DetroitTechno

      I’m having the same issue, no avatar.

      1. Brian Reid avatar

        And did you save the files you downloaded UTF-8 encoded files?

  5. Joshua Sylvester avatar
    Joshua Sylvester

    how would you Accept SAM-account name as a login format on the ADFS form-based password update page? i can’t get it to work.

    1. Brian Reid avatar

      You use “DOMAIN\samAccountName” style login. ADFS is on a server that is in DOMAIN or in any domain in that forest or in any domain that there exists a trust to.

  6. Balachandran Ramar avatar
    Balachandran Ramar

    Hi,
    If we have multiple Claims Provider, than is it possible to skip asking password, instead Once the user enterred the UPN, based on the HRD customization, it would need to redirect to claims provider trust 🙂

    Regards,
    Bala

    1. Brian Reid avatar

      So this article just covers Microsoft’s centered UX experience and not any further code development of the forms signing pages. The link to the github repository includes more on customization of the code

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.