Form Login Customization Troubleshooting
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.
The way form-login works is by injecting a small JavaScript by IAG into the form’s HTML. That JavaScript looks like this:
function WhaleSubmit() { formsCol = document.forms; if (formsCol.length == 1) { document.forms[0].submit(); } else { alert("more than one form"); } return false; } |
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 that part worked, but the user sees the form with the fields filled up by “whluser” and some password, this means the IAG engine correctly identified the form, but has been unable to submit it. This could be because the form itself has an unusual submit method. For example, many forms run some sanity JavaScript on submit or depend on some random click to do the submit instead of the common “submit” type button. There’s no generic solution for this, so the right way to go is to analyze the JavaScript code, and see what can be changed or bypassed. This is risky, as the JavaScript could be a security mechanism or add meta-data to the form that is not visible otherwise.
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.