Article By: Tiffany Kongpachith
Corporations can sometimes want to have their own custom login page with their own branding, their own layout for the authentication look and feel, provide any embedded links for redirections, as well as still give the user the Single Sign-On experience. If companies already have Symantec SiteMinder in place as a part of their ecosystem, then users may have already experienced the default HTML forms-based authentication. However, to incorporate the SSO experience with Symantec SiteMinder, you must include the SiteMinder directives as a part of your custom login page code. This can be easily executed by using the default HTML forms template (login.fcc) to extrapolate the contents within to structure how the login page will look.
This document will provide the necessary steps and information to ensure that the business gets the look and feel that they want when users are presented to authenticate on the login screen, as well as ensure SiteMinder contents are involved. Custom login pages can be created as a HTML or JSP file.
Prerequisites
- SiteMinder Policy Server has been fully installed and configured.
- SiteMinder Administrative User Interface (UI) has been fully installed and configured or the user/developer that will manipulate the custom login page has access to the Admin UI to create the necessary SiteMinder objects to protect the web page.
- Should be a web server present that will be hosting the SiteMinder Agent on the front-end.
- A SiteMinder Web Agent or Access Gateway Agent has been fully installed on a web server, configured, and registered to the Policy Server.
- Have the general idea of what the custom login page will look like to suit business standards.
- The user that will manipulate the login page to knows what directory that the login.fcc file is located –
Windows: (${webagent_home}\samples\forms)
UNIX: (${webagent_home}/samples/forms)
- The user responsible for creating the login form understands HTML and JSP formatting.
Step 1 – Obtain the SiteMinder Default HTML Form Template File (Login.fcc)
- Upon installing, configuring, and registering the SiteMinder Web Agent and Access Gateway, the Agents are supplied with forms in the ${webagent_home}\samples\forms directory.
- Navigate to the /forms directory.
- Locate the login.fcc file and save a copy of the file in preparations to build out the custom login page.
Step 2 – View Contents of the Login.fcc File
Open the login.fcc file with a text editor (i.e. Notepad or Notepad++) to view the contents.
| <!– SiteMinder Encoding=UTF-8; –>
@username=%USER% @smretries=0 <html> <head> <meta http-equiv=”Content-Type” content=”text/html;charset=$$SMENC$$”> <title>SiteMinder Password Services</title> <!– Cross-frame scripting prevention: This code will prevent this page from being encapsulated within HTML frames. Remove, or comment out, this code if the functionality that is contained in this SiteMinder page is to be included within HTML frames. –> <STYLE> html { display : none ; visibility : hidden; } </STYLE> <SCRIPT> if( self == top ) { document.documentElement.style.display = ‘block’ ; document.documentElement.style.visibility = ‘visible’ ; } else { top.location = self.location ; } </SCRIPT> <SCRIPT LANGUAGE=”JavaScript”> function resetCredFields() { document.Login.PASSWORD.value = “”; } function submitForm() { document.Login.submit(); } </SCRIPT> </head> <body BGCOLOR=”#ffffff” TEXT=”#000000″ onLoad = “resetCredFields();”> <!– Customer Brand –> <IMG alt=Logo src=”/siteminderagent/dmspages/CATechnologies_logo.png”> <form NAME=”Login” METHOD=”POST”> <INPUT TYPE=HIDDEN NAME=”SMENC” VALUE=”$$SMENC$$”> <INPUT type=HIDDEN name=”SMLOCALE” value=”US-EN”> <center> <!– outer table with border –> <table width=”50%” height=200 border=1 cellpadding=0 cellspacing=0 > <tr> <td> <!– Login table –> <table WIDTH=”100%” HEIGHT=200 BGCOLOR=”#FFEFD5″ border=0 cellpadding=0 cellspacing=0 > <tr> <td ALIGN=”CENTER” VALIGN=”CENTER” HEIGHT=40 COLSPAN=4 NOWRAP BGCOLOR=”#FFDAB9″> <font size=”+1″ face=”Arial,Helvetica”> <b>Please Login</b></font> </td> </tr> <tr> <td colspan=4 height=10> <font size=1> </font> </td> </tr> <tr> <td WIDTH=20 > </td> <td ALIGN=”LEFT” > <b><font size=-1 face=”arial,helvetica” > Username: </font></b> </td> <td ALIGN=”LEFT” > <input type=”text” name=”USER” size=”30″ style=”margin-left: 1px”> </td> <td WIDTH=20 > </td> </tr> <tr> <td colspan=4 height=10> <font size=1> </font> </td> </tr> <tr> <td WIDTH=20 > </td> <td > <b><font size=-1 face=”arial,helvetica” > Password: </font></b> </td> <td ALIGN=”left” > <input type=”password” name=”PASSWORD” size=”30″ style=”margin-left: 1px”> </td> <td WIDTH=20 > </td> </tr> <tr> <td colspan=4 height=10> <font size=1> </font> </td> </tr> <tr> <td colspan=4 NOWRAP WIDTH=”50%” HEIGHT=”25″ align=”CENTER”> <input type=hidden name=target value=”$$target$$”> <input type=hidden name=smquerydata value=”$$smquerydata$$”> <input type=hidden name=smauthreason value=”$$smauthreason$$”> <input type=hidden name=smagentname value=”$$smagentname$$”> <input type=hidden name=postpreservationdata value=”$$postpreservationdata$$”> <input type=”button” value=”Login” onClick=”submitForm();”> </td> </tr> <tr> <td colspan=4 height=5> <font size=1> </font> </td> </tr> </table> </td> </tr> </table> </form></center> <script language=”javascript”> document.forms[“Login”].elements[“USER”].focus(); </script> </body> </html> |
Play by Play of the Login.fcc File:
FCC Directives
Notice at the top of the file contains the @username, @smretries, and @smerrorpage.
- Username is the name for the login user.
- Smretries indicates the number of times a browser can try to log in.
- Smerrorpage indicates that if an error is presented on a POST to the custom form, the user browser is redirected to this page. If this special value is not specified in a .fcc file, the system uses the .unauth file that is associated with the .fcc file as the error page.
| <!– SiteMinder Encoding=UTF-8; –>
@username=%USER% @smretries=0 @smerrorpage= |
The first part of the FCC contains directives during a POST operation on the .fcc file. The directives are never passed to the client. They must be at the beginning of the file and are of the form: @name=value.
SiteMinder JavaScript Code
The next section of the login.fcc file to focus when creating your custom login page would be the SiteMinder JavaScript Code.
| <!– Cross-frame scripting prevention: This code will prevent this page from being encapsulated within HTML frames. Remove, or comment out, this code if the functionality that is contained in this SiteMinder page is to be included within HTML frames. –>
<STYLE> html { display : none ; visibility : hidden; } </STYLE> <SCRIPT> if( self == top ) { document.documentElement.style.display = ‘block’ ; document.documentElement.style.visibility = ‘visible’ ; } else { top.location = self.location ; } </SCRIPT> <SCRIPT LANGUAGE=”JavaScript”> function resetCredFields() { document.Login.PASSWORD.value = “”; } function submitForm() { document.Login.submit(); } </SCRIPT> |
As well as the JavaScript shown at the bottom portion of the login.fcc which indicates the action of submission when the user clicks the button “Login” to send the request over:
| <script language=”javascript”>
document.forms[“Login”].elements[“USER”].focus(); </script> |
The JavaScript code implies that the code functionality contains SiteMinder and its actions which MUST be included in custom login page.
Login Form POST Action
Next, the POST Action section can be customizable to suit for the look, feel, and branding that the client wants to see when presented by a SiteMinder protected resource/application.
This is essentially the “login box” where the user will enter their Username and Password in the designated fields as well as a Login or Submit button present.
| <!– outer table with border –>
<table width=”50%” height=200 border=1 cellpadding=0 cellspacing=0 > <tr> <td> <!– Login table –> <table WIDTH=”100%” HEIGHT=200 BGCOLOR=”#FFEFD5″ border=0 cellpadding=0 cellspacing=0 > <tr> <td ALIGN=”CENTER” VALIGN=”CENTER” HEIGHT=40 COLSPAN=4 NOWRAP BGCOLOR=”#FFDAB9″> <font size=”+1″ face=”Arial,Helvetica”> <b>Please Login</b></font> </td> </tr> <tr> <td colspan=4 height=10> <font size=1> </font> </td> </tr> <tr> <td WIDTH=20 > </td> <td ALIGN=”LEFT” > <b><font size=-1 face=”arial,helvetica” > Username: </font></b> </td> <td ALIGN=”LEFT” > <input type=”text” name=”USER” size=”30″ style=”margin-left: 1px”> </td> <td WIDTH=20 > </td> </tr> <tr> <td colspan=4 height=10> <font size=1> </font> </td> </tr> <tr> <td WIDTH=20 > </td> <td > <b><font size=-1 face=”arial,helvetica” > Password: </font></b> </td> <td ALIGN=”left” > <input type=”password” name=”PASSWORD” size=”30″ style=”margin-left: 1px”> </td> <td WIDTH=20 > </td> </tr> <tr> <td colspan=4 height=10> <font size=1> </font> </td> </tr> <tr> <td colspan=4 NOWRAP WIDTH=”50%” HEIGHT=”25″ align=”CENTER”> <input type=hidden name=target value=”$$target$$”> <input type=hidden name=smquerydata value=”$$smquerydata$$”> <input type=hidden name=smauthreason value=”$$smauthreason$$”> <input type=hidden name=smagentname value=”$$smagentname$$”> <input type=hidden name=postpreservationdata value=”$$postpreservationdata$$”> <input type=”button” value=”Login” onClick=”submitForm();”> </td> </tr> <tr> <td colspan=4 height=5> <font size=1> </font> </td> </tr> </table> </td> </tr> </table> </form></center> |
SiteMinder Localization Parameters and Directives
Let us expand more on the following SiteMinder directives and localization parameters:
These localization parameters come with the default settings per your set location. In this case, the United States so the SMLOCALE is set to “US-EN” while the default encoding language is UTF-8. These parameters are embedded by default.
However, the SiteMinder directives that are embedded in the login form will have dynamic values for each input name.
| <tr>
<td colspan=4 NOWRAP WIDTH=”50%” HEIGHT=”25″ align=”CENTER”> <input type=hidden name=target value=”$$target$$”> <input type=hidden name=smquerydata value=”$$smquerydata$$”> <input type=hidden name=smauthreason value=”$$smauthreason$$”> <input type=hidden name=smagentname value=”$$smagentname$$”> <input type=hidden name=postpreservationdata value=”$$postpreservationdata$$”> <input type=”button” value=”Login” onClick=”submitForm();”> </td> </tr> |
Likewise, where the dynamic values indicated with $$ in front and after the variable for a custom login page, the value should equal quotation marks (“”) for a dynamic source of input. These directives MUST be incorporated when setting up a custom login page.
The target value can be specified with a full URL (absolute path) to the location of where the protected resource is that is hosting it or used as another source for redirection or you may enter a relative path to the resource if present on the web server.
For example: <input type=hidden name=target value=”https://google.com/images”>
OR <input type=hidden name=target value=”/Headers.asp”>
(Remember: The resource Headers.asp put be present on the web server if you chose this route to display the contents on the web page after authentication)
Step 3 – Setup the SiteMinder Objects Prior to Custom Login Page
- Login to the SiteMinder Administrative User Interface (UI) and enter the administrator credentials.
- Assuming that the web server has been fully installed and configured.
- Assuming that the SiteMinder Web Agent has already been installed and configured; proceed with verifying that the Agent is present under Infrastructure > Agent > Agents.
- Ensure that the Agent that is going to be protecting the web page also is correlated to its own Agent Configuration Object (ACO). Define at least the #DefaultAgentParameter to associate which Agent will be the one to initiate protection.
- Once those two objects have been verified that they have been created and are present in the Admin UI; next, create a Domain for the application/website that will be hosting the custom login page.
- Create the Domain.
- Associate the necessary User Directory that will be tied to the Domain so that correlative users will have the ability to authenticate against the login page.
- Create the necessary protected resources (Realms) for your application/web page.
- Assign the correct Web Agent Actions (Rule set) for the users to be allowed.
- Lastly, create a Policy within the Domain to give the necessary Authorization actions between the Users from the User Directory associated and the protected resources/realms.
- Lastly, Submit the Domain settings to complete the creation of SiteMinder objects for that specified application/web page.
Step 4 – Creating a Custom Login Page with SiteMinder Login.fcc Contents
- First, determine as the user or developer for the custom login page what type of platform. For example, whether to create the login page as HyperText Markup Language (HTML) or JavaServer Pages (JSP).
- Secondly, locate the install directories of the web server.
Note: These install directories will be where the user creates and saved their webpage (.html or .jsp) so the web server can host and display the page when accessing on a browser. In addition to this, if any references to images or links – those items must be present in the install directory of the web server in order for the web server to source the contents and display the items on the web browser for the page.
For example:
A. Internet Information Services (IIS)’s install directory would be C:\inetpub\wwwroot
B. Apache Tomcat’s install directory would be C:\Program Files\Apache Software Foundation\Tomcat [Version number]\ webapps\ROOT)
- Thirdly, enter and structure the contents of how or what you want the look and feel of the web page to be presented as either HTML or JSP when accessing the resource from a web browser.
- Lastly, the user will need to incorporate the SiteMinder contents into your custom login page:
- FCC directives
- JavaScript Code
- Login Form POST Action
- Localization Parameters
Note: All SiteMinder contents will be included in either HTML or JSP format. This does not change.
Example of a Custom Login Page (.jsp):
Example of a Custom Login Page (.html):
Summary of Setting Up Custom Login Page Using Symantec Siteminder Directives
To create your own custom login page but still want to use SiteMinder is simple. The user has full range of flexibility on how they want their login page to look like. However, the most important contents to include are the SiteMinder FCC Directives, JavaScript Codes, POST Action for the Form to submit to SiteMinder Policy Server, and the Localization Parameters.
Refer back to the examples from the HTML or JSP perspectives. Notice the contents within are slightly different based on customization and customer branding, however, the SiteMinder contents remain the same between the two.
As long as those contents are present in the custom login page then the page will act the same behavior as the SiteMinder Default HTML Form Template upon a user attempting to authenticate again their designated resource/page protected by SiteMinder.
Looking for additional help with Symantec Siteminder directives? ISX Consulting is an elite IAM security firm that offers boundless expertise in a range of cybersecurity and business process services, including Symantec Siteminder. Take your interoperability to the next level, and contact an ISX consultant today.
Leave a Reply