Advanced Customization of AD FS Sign-in and Update Password Pages


AD FS provides several options for administrators to customize and tailor the end-user experience to meet their corporate needs. The following article will serve as a walkthrough for modifying the look, feel and steps to enable advanced customization using JavaScript for AD FS Sign-in and Password Update page.

AD FS page customization

AD FS by default provides a set of PowerShell commands which can be used to redesign the Landing by getting hold of some predefined ‘placeholder’ already available within the page. Refer the below table to quickly find your customization option:
Sign In page
Topic Description
AD FS Customization in Windows Server 2016 New customization options available for AD FS in Windows Server 2016
Change the company name Steps for displaying your companies name on the sign-in page
Change the company logo Steps for changing the logo that appears on the sign-in-page
Change the illustration Steps for changing the illustration that appears on the sign-in page
Add sign-in description Steps for adding a description to the sign-in page
Add help desk link Steps for adding a help desk link
Add home link Steps for adding a home link
Add privacy link Steps for adding a privacy link
Custom web themes Information on using custom web themes
Custom error messages Steps for customizing error messages
Home Realm Discovery Steps for customizing Home Realm Discovery
Update Password Customization Steps for enabling and customizing the update password page
Multi-factor authentication and external auth providers customization Information on using MFA and external auth providers
Customization for Localization Information on localization considerations
Removing the Microsoft copyright Steps on removing the Microsoft copyright
Customizing the display names and descriptions for authentication methods Steps on customizing display names and descriptions for authentication methods
Update Password Page
All the above commands will get applied to the sign-in page and update the password page by default. On top of that, the update password page has one additional cmdlet to modify the page description
  1. Set-AdfsGlobalWebContent -UpdatePasswordPageDescriptionText "This is the Contoso Update Password page."  

Advanced Customization

AD FS in Windows Server provides built-in support for customizing the sign-in experience. For a majority of these scenarios, the built-in Windows PowerShell cmdlets are all that is required. In some cases, AD FS administrators may want to provide additional sign-in experiences that are not possible through the existing PowerShell commands that ship in-box with AD FS. In certain instances, it is feasible for administrators to customize the sign-in experience further by adding additional logic to onload.js that is provided by AD FS and will be executed on all the AD FS pages.
Customizing the AD FS experience by using onload.js
The theme that is shipped out-of-the-box is called Default. Export the default theme. The following cmdlet creates a custom web theme, which duplicates the default web theme 
  1. New-AdfsWebTheme –Name custom –SourceName default  
To export the theme, use the following cmdlet. Locate onload.js under the script folder in the directory that is specified in the export cmdlet and add the custom logic to the script.
  1. Export-AdfsWebTheme –Name default –DirectoryPath c:\theme  
Update the theme with the modified onload.js. Use the following cmdlet to apply the update onload.js to a custom web theme.
For AD FS on Windows Server 2012 R2:
  1. Set-AdfsWebTheme -TargetName custom -AdditionalFileResource @{Uri='/adfs/portal/script/onload.js';path="c:\theme\script\onload.js"}  
For AD FS on Windows Server 2016:
  1. Set-AdfsWebTheme -TargetName custom -AdditionalFileResource @{Uri='/adfs/portal/script/onload.js';path="c:\theme\script\onload.js"}  
Apply the custom web theme to AD FS using the following cmdlet.
  1. Set-AdfsWebConfig -ActiveThemeName custom  

Additional Customization samples

Consider the below code snippet to accept SAM-account name as a login format on an AD FS form for Sign in and Update password page, the complete code is attached within the article. The original onload.js, the one that comes with the default web theme will execute on all ADFS pages and hence always make sure that proper logic to distinguish the current page context is handled.
Sign in Page
  1. if (typeof Login != 'undefined'){    
  2.     Login.submitLoginRequest = function () {     
  3.     var u = new InputUtil();    
  4.     var e = new LoginErrors();    
  5.     var userName = document.getElementById(Login.userNameInput);    
  6.     var password = document.getElementById(Login.passwordInput);    
  7.     if (userName.value && !userName.value.match('[@\\\\]'))     
  8.     {    
  9.         var userNameValue = '\\' + userName.value;    // replace with custom ADFS Name
  10.         document.forms['loginForm'].UserName.value = userNameValue;    
  11.     }    
  13.     if (!userName.value) {    
  14.        u.setError(userName, e.userNameFormatError);    
  15.        return false;    
  16.     }    
  18.     if (!password.value)     
  19.     {    
  20.         u.setError(password, e.passwordEmpty);    
  21.         return false;    
  22.     }    
  23.     document.forms['loginForm'].submit();    
  24.     return false;    
  25. };    
  26. }  
Update Password 
  1. if (typeof UpdatePassword !== 'undefined') {  
  3.     UpdatePassword.submitPasswordChange = function () {  
  4.         var u = new InputUtil();  
  5.         var e = new UpdErrors();  
  6.         var userNameValue;  
  7.         var userName = document.getElementById(UpdatePassword.userNameInput);  
  8.         var oldPassword = document.getElementById(UpdatePassword.oldPasswordInput);  
  9.         var newPassword = document.getElementById(UpdatePassword.newPasswordInput);  
  10.         var confirmNewPassword = document.getElementById(UpdatePassword.confirmNewPasswordInput);  
  12.         if (!userName.value || !userName.value.match('[@\\\\]')) {  
  13.             userNameValue = '\\'+userName.value;    // replace with custom ADFS Name
  14.             document.forms['updatePasswordForm'].UserName.value = userNameValue;  
  15.         }  
  16.         if (userName.value && userName.value.match('[@]')) {  
  17.             var matchresult = userName.value.match('[@]');  
  18.             var firstat = matchresult[0];  
  19.             var splitresult = userName.value.split(firstat);  
  20.             userNameValue = '\\' + splitresult[0];  
  21.             document.forms['updatePasswordForm'].UserName.value = userNameValue;  
  22.         }  
  24.         if (!oldPassword.value) {  
  25.             u.setError(oldPassword, e.oldPasswordEmpty);  
  26.             return false;  
  27.         }  
  29.         if (oldPassword.value.length > maxPasswordLength) {  
  30.             u.setError(oldPassword, e.oldPasswordTooLong);  
  31.             return false;  
  32.         }  
  34.         if (!newPassword.value) {  
  35.             u.setError(newPassword, e.newPasswordEmpty);  
  36.             return false;  
  37.         }  
  39.         if (!confirmNewPassword.value) {  
  40.             u.setError(confirmNewPassword, e.confirmNewPasswordEmpty);  
  41.             return false;  
  42.         }  
  44.         if (newPassword.value.length > maxPasswordLength) {  
  45.             u.setError(newPassword, e.newPasswordTooLong);  
  46.             return false;  
  47.         }  
  49.         if (newPassword.value !== confirmNewPassword.value) {  
  50.             u.setError(confirmNewPassword, e.mismatchError);  
  51.             return false;  
  52.         }  
  54.         var error = document.getElementById('error');  
  55.         error.innerHTML = '';  
  56.         return true;  
  57.     };  
  58. }   

Recommended Free Ebook
Similar Articles