ADFS Customization
Applies to version 2020.1.3; author: Mateusz Syrek
ADFS customization
ADFS is one of the authentication providers that can be used with WEBCON BPS Portal. This article explains how you can customize your login page when you use ADFS. Before you can customize your login page, you need to have your WEBCON PORTAL registered in ADFS. For instructions on how to do it, please refer to this article Integration of WEBCON BPS Portal with ADFS.
To start, let us take a look at two default themes provided by Microsoft in Windows Server 2019. If you have an older version of Windows Server, go to the last section of this article, download the theme we link to, upload it to your server and then return here to follow the instructions on customizing your login page
Without further ado, these are the default login page themes available in Windows Server 2019:
Configuration in Windows Server 2019
Now, we are going to describe how you can configure and customize the theme.
The ADFS login page is divided into sections you can see on the screenshot:
Each section can be edited with PowerShell, CSS styles, or JavaScript.
We recommend that you start your customization by making a copy of the default theme, and then we will walk you through the steps to modify it to suit your needs.
In PowerShell, use the command:
New-AdfsWebTheme -Name DefaultAdfs2019 -SourceName MyADFSWebTheme
It will create a copy of the theme named MyADFSWebTheme.
You can activate it right away and follow this article making changes to it. To do so, use this command:
Set-AdfsWebConfig -ActiveThemeName MyADFSWebTheme
You can monitor the changes in WEBCON Designer Studio without activating an authentication provider.
To do it, use the command:
Set-AdfsProperties -EnableIdPInitiatedSignonPage $true
The IdpInitiatedSignon website will be activated, allowing you to verify the ADFS installation.
Now, enable it and go to the page // <ADFS name>. <domain> /adfs/ls/idpinitiatedsignon.htm to open a test login page.
After that, you are ready to start the customization.
To avoid creating CSS styles and the scripts from scratch, export our theme (you will find two versions attached at the bottom of the article). To do this, create an empty directory on the disk, e.g., with the same name as the theme, and use the command:
Export-AdfsWebTheme -Name MyADFSWebTheme -DirectoryPath "C:MyADFSWebTheme"
All graphics, styles and scripts of our theme will be exported.
Now, you can replace the graphic files with your images. If you do not do that, your ADFS login page will mirror the BPS Portal login page (see below).
To replace graphics, styles, and scripts in the theme, use PowerShell with administrator privileges and enter this command: Set-AdfsWebTheme.
Let us explain the syntax of this command. First, you indicate the theme's name, then the path to the file you want to replace.
Below you can see examples of commands for replacing basic files:
- Illustration
Set-AdfsWebTheme -TargetName MyADFSWebTheme -Illustration @{path="C:ADFS_WebThemeillustrationillustration.jpg"}
- Logo
Set-AdfsWebTheme -TargetName MyADFSWebTheme -Logo @{path="C:ADFS_WebThemelogologo.png"}
- CSS styles
Set-AdfsWebTheme -TargetName MyADFSWebTheme -StyleSheet @{path="C:ADFS_WebThemecssstyle.css"}
- JavaScript (executed on page load)
Set-AdfsWebTheme - TargetName MyADFSWebTheme - AdditionalFileResource @ { Uri = ' /adfs/portal/script/onload.js '; path = " C: ADFS_WebTheme script onload.js "}
To make your ADFS login page look like an integral part of your BPS Portal, upload your graphics, CSS styles, and scripts to the theme.
Changing password in ADFS
ADFS provides a website where the user can change the password. By default, it is disabled. It must be activated in the ADFS management console. Find it and enable at this address: https://<ADFS name>.<domain>/adfs/portal/updatepassword/
Once you enable the site for changing password, you have to configure an access path to it.
To do this, add a description to the login site and link it to the ADFS site for changing user password. The description will appear under the Login button. This can be done with PowerShell (with administrator privileges) when you use the command Set-AdfsGlobalWebContent.
For the purposes of this article, we will only add a description of the login page and a description of the page for changing the password:
- Login page description.
Set-AdfsGlobalWebContent -SignInPageDescriptionText "<p>Click <A href='/adfs/portal/updatepassword/'>here</A> to change your password.</p>"
- Description for the change password page.
Set-AdfsGlobalWebContent - UpdatePasswordPageDescriptionText " Password must be at least 7 characters long. <br> The password must contain one character from at least three categories: lowercase letter, number, special character. "
After these operations, the description will be set globally in the entire ADFS content, directing from the login page to the password change page. It will also be displayed on the site for changing the password, together with the requirements for a new password.
Consult the screenshot below to see a real-life example:
The ADFS login page is multi-lingual, and by extending the command Set-AdfsGlobalWebContent with PL locations, a different description will be displayed to a user with a Polish browser language, e.g.
Set-AdfsGlobalWebContent -Locale "pl" -UpdatePasswordPageDescriptionText "Hasło musi zawierać co najmniej 7 znaków.<br>W haśle musi się znaleźć po jednym znaku z przynajmniej z trzech kategorii: mała litera, cyfra, znak specjalny."
The description will change to the language used by the user's browser.
Azure AD UX Web Theme
You can still achieve the results described here even if you have a version older than Windows Server 2019. Go to the Microsoft Using an Azure AD UX Web Theme in Active Directory Federation Services page to download the theme that can give the user the sign-in experience more similar to the Azure experience. Then, follow the instructions from this Microsoft page and upload the theme to your server.
Once you have done it, you can customize the theme for your login page following this article's instructions.
For more information on customizing the ADFS login page, consult this Microsoft's website:
https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/ad-fs-paginated-sign-in
