How to Customize AD FS Error Messages
Written on July 21, 2016

Entering a username incorrectly in AD FS results in a reasonably useful error message. However, some folks desire to change this, which is perfectly OK too.

Poking through the HTML behind IdpInitiatedSignon.aspx (the page that is rendered for forms-based authentication to AD FS) shows that the error messages for a) invalid username format, and b) empty password, are both stored in a JavaScript function called LoginErrors().

function LoginErrors(){
    this.userNameFormatError = 'Enter your user ID in the format \u0026quot;domain\\user\u0026quot; or \u0026quot;user@domain\u0026quot;.';
    this.passwordEmpty = 'Enter your password.';
}

Fortunately, JavaScript provides great native functionality for overriding inbuilt functions, so we can simply redefine LoginErrors later on. The page will then utilise that in the event of either condition (username format error or empty password) being met. Be sure to follow the approach below that matches your environment:

Default AD FS theme (Create custom theme)

If you don’t already have a custom AD FS theme, why not? They’re a great way to customise the (somewhat bland) default AD FS interface. Let’s create one now! You can use this to apply the customisations here, as well as to update countless other display and functionality features of the AD FS interface.

New-AdfsWebTheme -Name customtheme -SourceName default

Once you’ve created your custom theme, follow the steps below.

Existing custom AD FS theme

If you already have a custom AD FS theme, you’ll want to perform the following steps:

  1. Download your custom theme (herein ‘customtheme’) to your local machine
  Export-AdfsWebTheme -name customtheme -directoryPath C:\adfs\customtheme
  1. Add the following code to the bottom of the onload.js file, modifying error messages as appropriate:
  function LoginErrors() {
      this.userNameFormatError = 'Please enter your E-mail address.';
      this.passwordEmpty = 'Enter your password.';
  }
  1. Upload the customised onload.js file to your custom theme:
  Set-AdfsWebTheme -TargetName customtheme -AdditionalFileResource @{Uri=’/adfs/portal/script/onload.js’;path="c:\adfs\customtheme\script\onload.js"}
  1. Apply the custom theme:
  Set-AdfsWebConfig -ActiveThemeName customtheme

Comments/questions

There's no commenting functionality here. If you'd like to comment, please either mention me (@[email protected]) on Mastodon or email me. I don't have any logging or analytics running on this website, so if you found something useful or interesting it would mean a lot to hear from you.