Custom HomeRealmDiscovery Page with AD FS 2.0

Recently I decided to dissect the structure of the default pages in AD FS 2.0 and see what can be done with creating slightly different look from its default look. I wanted to see what files control what areas in the UI and what can be done with minimum code changes.

I started working with one of the most common pages accessed in large implementation – the Home Realm Discovery page. As you probably know, the default look of this page is like this:

As part of this exercise I wanted to make it look like this:

The main page that is accessed to present Home Realm Discovery is HomeRealmDiscovery.aspx. So the first step I took a look at it to see what it is doing and if it using any other support pages. As I suspected, the site is designed to use different files for HTML, C# and CSS code. It also has special language files that contain all the configurable text strings in the UI. Some configuration is done via web.config file. Overall, to move from the default UI to my customized UI I had to modify six files and introduce two graphic files.

The following files have control over the Home Realm Discovery:

• Inetpub\adfs\ls\web.config
• Inetpub\adfs\ls \HomeRealmDiscovery.aspx
• Inetpub\adfs\ls \HomeRealmDiscovery.aspx.cs
• Inetpub\adfs\ls\App_GlobalResources\CommonResources.resx
• Inetpub\adfs\ls\App_GlobalResources\CommonResources.en.resx (and many other language files, if you need to present it in those languages)
• Inetpub\adfs\ls\MasterPages\StyleSheet.css
• Inetpub\adfs\ls\MasterPages\MasterPage.master
• Inetpub\adfs\ls\MasterPages\MasterPage.master.cs

Files with .CS extension contain C# code and I did not change them. All the logic associated with proper functionality of the AD FS for presenting the target IdPs, and other AD FS related functionality is done via those pages, but they are not controlling the UI for the Home Realm Discovery page.

On the following diagram I’ll point out what area in the Home Realm Discovery page is controlled by what configuration file.

1. The background. It is controlled via StyleSheet.css. To modify it you’ll need to modify background-image: in BODY section. By default it is using url(../App_Themes/Default/header_background.png) image. You can replace this with another image of your liking to show in the background. Image can introduce nice color change with shades and such, but you can also just specify the solid color via the tag.

2. Header. The text for the header comes from the CommonResouces files. How it is viewed is controlled by the StyleSheet.css and MasterPage.master files. I replaced the default “Sign In” text with “Contoso Federation Services”, changes style sheet to reflect different font color and its size, tags in style sheet were also used to fine tune its placement. I also had to move its location in the MasterPage.master file so it would appear to the right of the logo, and not above it.

3. STS Title. The title you see here comes from the AD FS Federation Service name you define on the AD FS Properties. The same name you see in the drop down list when you need to select your target IdP. The placement code for STS Title is controlled in MasterPage.master and via style sheet. I removed STS Title from the final page. I had to do this by introducing a new code in the style sheet and replacing the class definition in the MasterPage.master with new style that hides it.

4. The text shown inside the main area comes from the CommonResouces files. The code that defines its placement is controlled via HomeRealmDiscovery.aspx file. You’d need to introduce new sections in it with new Label Text ID and create corresponding Label Text entries in the corresponding CommonResouces files.

5. Text in the button is controlled via CommonResouces files. Its placement can be controlled via HomeRealmDiscovery.aspx file and visual elements via style sheet.

6. The border is controlled via style sheet. Elements like its sickness, colour, how wide etc

7. Optional Logo can be introduced by specifying it via web.config file. Its placement on the page is controlled via the MasterPage.master file and style sheet.

Easy! Right?

OK, so if you like to see more details, here is a bit more on the each change to get from default look to my custom look.

1. Background. Modify StyleSheet.css from this:

body

{

background-color: #ffffff;

color:#222222;

font-size: 0.8em;

font-weight: normal;

font-family: “Segoe UI”, Verdana, Tahoma, Arial, sans-serif;

margin: 0px;

background-repeat: repeat-x;

background-image: url(../App_Themes/Default/header_background.png);

}

To this:

body

{

background-color: #ffffff;

color:#222222;

font-size: 0.8em;

font-weight: normal;

font-family: “Segoe UI”, Verdana, Tahoma, Arial, sans-serif;

margin: 0px;

background-repeat: repeat-x;

background-image: url(../App_Themes/Default/custombackground.gif);

}

2. Header. First, in MasterPage.master move the following code

<div class=”Header”>

<asp:Label ID=”PageTitleLabel” runat=”server”></asp:Label>

</div>

From being in front of the

<%

string logoPath =

System.Web.Configuration.WebConfigurationManager.AppSettings[ "logo" ];

if( !String.IsNullOrEmpty( logoPath ) )

{

%>

<div class=”GroupXLargeMargin”>

<img src=”<%= logoPath %>” alt=”logo” />

</div>

<%

}

%>

To be behind it, so it looks like this:

<%

string logoPath =

System.Web.Configuration.WebConfigurationManager.AppSettings[ "logo" ];

if( !String.IsNullOrEmpty( logoPath ) )

{

%>

<div class=”GroupXLargeMargin”>

<img src=”<%= logoPath %>” alt=”logo” />

</div>

<%

}

%>

<div class=”Header”>

<asp:Label ID=”PageTitleLabel” runat=”server”></asp:Label>

</div>

Second, update StyleSheet.css Header to look like this:

.Header

{

color: #000000;

padding: 8px 0 5px 0;

margin-bottom: 1px;

font-size: 200%;

font-weight:bold;

position:relative;

left:184px;

top:-95px;

}

And finally, replace “Sign In” text in both CommonResouces files for HomeRealmDiscovery text label to be “Contoso Federation Services”.

3. STS Title. To hide it you can do the following:

a. In MasterPage.master page change the following code

<div class=”TextSizeXLarge”>

<asp:Label ID=”STSLabel” runat=”server”></asp:Label>

</div>

To look like this:

<div class=”STSTitleNotVisible”>

<asp:Label ID=”STSLabel” runat=”server”></asp:Label>

</div>

b. In StyleSheet.css create new code for STSTitleNotVisible to be this:

.STSTitleNotVisible

{

visibility:hidden;

}

4. To introduce new text in the main section update HomeRealmDiscovery.aspx file with new Label Texts and introduce that text to the CommonResouces files.

a. In HomeRealmDiscovery.aspx make <asp:Content section to look like this:

<asp:Content ID=”Content1″ ContentPlaceHolderID=”ContentPlaceHolder1″ Runat=”Server”>

<div class=”GroupXLargeMargin”>

<asp:Label Text=”<%$ Resources:CommonResources, HomeRealmSelectionText%>” runat=”server” />

</div>

<div class=”GroupXLargeMargin”>

<asp:Label Text=”<%$ Resources:CommonResources, HomeRealmSelectionTextTwo%>” runat=”server” />

</div>

<div class=”GroupXXLargeMargin”>

<asp:DropDownList ID=”PassiveIdentityProvidersDropDownList” DataTextField=”Name” DataValueField=”Id” runat=”server”></asp:DropDownList>

<asp:Button runat=”server” ID=”PassiveSignInButton” Text=”<%$ Resources:CommonResources, HomeRealmSignInButtonText%>” EnableViewState=”False”

OnClick=”PassiveSignInButton_Click” CssClass=”Resizable”/>

</div>

<div class=”GroupXLargeMargin”>

<asp:Label Text=”<%$ Resources:CommonResources, HomeRealmSelectionTextThree%>” runat=”server” />

<a href=”mailto:Helpdesk@contoso.com?subject=FEDERATION”>Helpdesk@contoso.com</a>

<asp:Label Text=”<%$ Resources:CommonResources, HomeRealmSelectionTextThreeHalf%>” runat=”server” />

</div>

<div class=”GroupXLargeMargin”>

<asp:Label Text=”<%$ Resources:CommonResources, HomeRealmSelectionTextFour%>” runat=”server” />

</div>

</asp:Content>

b. Add the following to the CommonResouces files:

<data name=”HomeRealmSelectionTextTwo” xml:space=”preserve”>

<value>NOTE: The following Identity Providers will let you into the application.</value>

</data>

<data name=”HomeRealmSelectionTextThree” xml:space=”preserve”>

<value>If your Organization is not listed, please send an e-mail to the contact at </value>

</data>

<data name=”HomeRealmSelectionTextThreeHalf” xml:space=”preserve”>

<value>and express your interest of your Organization becoming a member of the Federation Framework, and include the name of the application that you are trying to access in your e-mail.</value>

</data>

<data name=”HomeRealmSelectionTextFour” xml:space=”preserve”>

<value>If you believe that you have arrived at this page by accident, please close your web browser and try accessing the application webpage URL again in a new browser session.</value>

</data>

5. The button is moved to be at the same level as the drop down list. This is controlled by removing <div> tags that surround the button code in the HomeRealmDiscovery.aspx.

6. To control the border just change the style sheet .MainActionContainer with this details:

.MainActionContainer

{

padding: 5px 20px 5px 20px;

border: solid 3px #003300;

min-height: 150px;

position:relative;

top:-30px;

}

7. Finally, to add the logo do the following:

a. Modify web.config file by uncommenting code that specifies the name of the logo file and then place your logo file in the root folder of AD FS (Inetpub\adfs\ls\)

b. In MasterPage.master change the following code

<div class=”GroupXLargeMargin”>

<img src=”<%= logoPath %>” alt=”logo” />

</div>

To look like this:

<div class=”CustomLogo”>

<img src=”<%= logoPath %>” alt=”logo” />

</div>

c. And finally, add new code to the StyleSheet.css:

.CustomLogo

{

margin-top:25px;

}

After doing all these changes, the default looking page

Will look like this:

Easy, Breezy, Cover…. Hmm, page.

Till next time!