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

Introduction

 

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

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 

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.

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:

Set-AdfsWebTheme -TargetName custom -AdditionalFileResource @{Uri='/adfs/portal/script/onload.js';path="c:\theme\script\onload.js"}

For AD FS on Windows Server 2016:

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.

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

if (typeof Login != 'undefined'){
    Login.submitLoginRequest = function () {
    var u = new InputUtil();
    var e = new LoginErrors();
    var userName = document.getElementById(Login.userNameInput);
    var password = document.getElementById(Login.passwordInput);
    if (userName.value && !userName.value.match('[@\\\\]'))
    {
        var userNameValue = 'contoso.com\\' + userName.value;    // replace contoso.com with custom ADFS Name
        document.forms['loginForm'].UserName.value = userNameValue;
    }

    if (!userName.value) {
       u.setError(userName, e.userNameFormatError);
       return false;
    }

    if (!password.value)
    {
        u.setError(password, e.passwordEmpty);
        return false;
    }
    document.forms['loginForm'].submit();
    return false;
};
}

Update Password 

if (typeof UpdatePassword !== 'undefined') {

    UpdatePassword.submitPasswordChange = function () {
        var u = new InputUtil();
        var e = new UpdErrors();
        var userNameValue;
        var userName = document.getElementById(UpdatePassword.userNameInput);
        var oldPassword = document.getElementById(UpdatePassword.oldPasswordInput);
        var newPassword = document.getElementById(UpdatePassword.newPasswordInput);
        var confirmNewPassword = document.getElementById(UpdatePassword.confirmNewPasswordInput);

        if (!userName.value || !userName.value.match('[@\\\\]')) {
            userNameValue = 'Contoso.com\\'+userName.value;    // replace contoso.com with custom ADFS Name
            document.forms['updatePasswordForm'].UserName.value = userNameValue;
        }
        if (userName.value && userName.value.match('[@]')) {
            var matchresult = userName.value.match('[@]');
            var firstat = matchresult[0];
            var splitresult = userName.value.split(firstat);
            userNameValue = 'contoso.com\\' + splitresult[0];
            document.forms['updatePasswordForm'].UserName.value = userNameValue;
        }

        if (!oldPassword.value) {
            u.setError(oldPassword, e.oldPasswordEmpty);
            return false;
        }

        if (oldPassword.value.length > maxPasswordLength) {
            u.setError(oldPassword, e.oldPasswordTooLong);
            return false;
        }

        if (!newPassword.value) {
            u.setError(newPassword, e.newPasswordEmpty);
            return false;
        }

        if (!confirmNewPassword.value) {
            u.setError(confirmNewPassword, e.confirmNewPasswordEmpty);
            return false;
        }

        if (newPassword.value.length > maxPasswordLength) {
            u.setError(newPassword, e.newPasswordTooLong);
            return false;
        }

        if (newPassword.value !== confirmNewPassword.value) {
            u.setError(confirmNewPassword, e.mismatchError);
            return false;
        }

        var error = document.getElementById('error');
        error.innerHTML = '';
        return true;
    };
}