Custom Form Login SSO how-to

One of the most important abilities of IAG is the single sign on, which lets connecting users access to internal applications without having to re-type their username and password. IAG contains multiple SSO mechanisms, but on some occasions, one might be required to create a custom one. The process of creating a custom login is thoroughly documented in Appendix C of the advanced user guide (Page 381), as well as here (https://technet.microsoft.com/en-us/library/dd282925.aspx), but here’s a summary of this procedure that should be easier to follow for creating simple customizations.

The 1st step is to gather some details about the application. The details are:

1. Application Type. This parameter was selected when the application was initially published on IAG. To find it, look at the list of applications on the portal, and check what appears in “application type”

clip_image002

2. The internal URL of the login page.

3. The name of the username and password fields in the HTML form. For example:

<form id="quick" method="get" action="/dosearch.action">

<fieldset>

<legend>Quick Search</legend>

<input id="quick-search-query" type="text" accessKey="q" autocomplete="off" name="queryString" size="25"/>

<div class="form-block"><p><div class="steplabel" style="width: 150px;"><u>U</u>sername: </div>

<input type="text" name="uname" tabindex="1" accesskey="U" size="30"><br/></p>

<p><div class="steplabel" style="width: 150px;"><u>P</u>assword: </div>

<input type="password" name="pword" tabindex="2" accesskey="P" size="30">

<br/></p>

Using these details, a custom XML file needs to be created, and placed on the server. The syntax of the file is this:

<WHLFILTFORMLOGIN ver="1.0">

<APPLICATION>

<APPLICATION_TYPE>TYPE from step 1</APPLICATION_TYPE>

<USAGE description="form_login">

<PRIMARY_HOST_URL>URL from Step 2</PRIMARY_HOST_URL>

<SCRIPT_NAME source="data_definition">WhaleSubmitStandard</SCRIPT_NAME>

<USER_AGENT>

<AGENT_TYPE search="group">all_supported</AGENT_TYPE>

<POLICY>multiplatform</POLICY>

<SCRIPT_NAME source="data_definition">WhaleHandler</SCRIPT_NAME>

</USER_AGENT>

<MULTIPLE_LOGIN>true</MULTIPLE_LOGIN>

<LOGIN_FORM>

<NAME>loginform</NAME>

<METHOD>POST</METHOD>

<CONTROL handling="dummy_value">

<TYPE>USER_NAME</TYPE>

<NAME>Username field name from step 3</NAME>

<DEF_VALUE>whaleusr</DEF_VALUE>

</CONTROL>

<CONTROL handling="dummy_value">

<TYPE>PASSWORD</TYPE>

<NAME> Password field name from step 3</NAME>

<DEF_VALUE>whlpass</DEF_VALUE>

</CONTROL>

</LOGIN_FORM>

</USAGE>

</APPLICATION>

</WHLFILTFORMLOGIN>

When filling the URL portion, keep in mind that IAG uses RegEx to match URLs, so it would generally be a good idea to feed in a general mask, with RegEx parameters. For example, the URL https://crmserver/userenv/login.asp should be input as .*userenv/login\.asp

In the above example, we substitute .* for the server name, as “.*” in RegEx means “everything and anything”. Later, we slash-out the dot before asp, because a dot is an operator in RegEx.

Another thing to take into account is the Multiple Login parameter. In the above example, I’ve set it to TRUE, which means that the form will be submitted anytime the user goes to the same page. The purpose of this is to meet situations in which a user logs out of the application, goes back to the IAG portal, and then re-launches the application. Setting the value to FALSE would not re-submit the form. Setting it to TRUE is usually a good idea, although in some cases, an application uses the same URL for multiple functions, and then setting the multiple login to true would cause IAG to try to re-submit the page every time.

Once the data has been filled out, save the file under the folder c:\whale-com\e-Gap\von\conf\wizarddefaults\FormLogin and name the file FormLogin.xml. Activate the IAG configuration, checking the option to apply changes made to external configuration files. This is all it takes!