In a recent blog article, I wrote about form-login and how to create a custom one. Later on I thought it might be a good idea to details a little bit about the form-login mechanism, and how it works, which could be helpful in troubleshooting this if it does not work. Often times, one might write the custom XML file, but not be sure why it’s not working, with the result being an endless loop of trial-and-error.
formsCol = document.forms;
if (formsCol.length == 1)
alert("more than one form");
This function is set to run as soon as the form loads. IAG also looks throughout the HTML for the form fields that have been identified by the customized SSO file (FormLogin.xml), and injects the strings “whluser” and “whlpass” into them. When that form is received by the browser, it already has these strings in the user and pass fields, and the submit function. There’s also a piece of script to launch that function. The function enumerates the forms found in the page, and if it finds only one, it does a SUBMIT on it. If it finds more than one form, it will show a pop-up with the error “more than one form”. The form submit would typically be pretty fast, but usually not fast enough so that the user doesn’t see what’s happening.
Once the form has been submitted, it goes through the engine again, where the fields are replaced by the actual username and password of the user, which the IAG knows because that user has logged in earlier. These are sent to the backend server and the application logs in.
A typical problem with this is a mis-configuration that prevents IAG from identifying the right form. Key factors for success there are the application type and URL, and those often fail because of lack of understanding of how RegEx works.
If you have identified changes that need to be made to the form, an AppWrap can help you along. Using AppWrap, you can make any changes you want to the form, including removing code or changing it completely. AppWrap is a tool with very few limitations, and as can be expected, this has some risks. Before making any changes with AppWrap (detailed in page 219 of the Advanced User Guide), be sure that you fine-tune it well enough so that it affects JUST your login form, and no other pieces or pages.
If the form submit does seem to go through, but brings up an authentication error, this might be related to the way IAG caches the user’s credentials. For example, some apps require the username to be in the format of a domain\user, as opposed to just the username. This can also be worked out, but that’s beyond the scope of this blog entry – this is addressed in the user guide.