Form-based authentication is similar to a web application in which the users have to fill out a login form in order to access a secured or protected resource. Worklight provides a similar authentication mechanism in which the server returns the HTML of a login form whenever an application tries to access a protected resource.
The Worklight application that uses form-based authentication must use a login module to validate the received credentials.
Declare the security realm with the name myFormBasedAppRealm as follows:
<realm name="myFormBasedAppRealm" loginModule="myFormBasedAppLoginModule"> <className>com.worklight.core.auth.ext.FormBasedAuthenticator</className> </realm>
Now define the login module with the name myFormBasedAppLoginModule as we used the same for the loginModule attribute value to define the realm:
<loginModule name="myFormBasedAppLoginModule"> <className>com.worklight.core.auth.ext.NonValidatingLoginModule</className> </loginModule>
Declare the security test name with the name myFormBasedAppSecurityTest, and define the declared realm under the test tag:
<customSecurityTest name="myFormBasedAppSecurityTest">
<test realm="myFormBasedAppRealm" isInternalUserID="true"/>
</customSecurityTest>Now creating a challenge handler for form-based authentication is similar to the previous example with few changes to handle the challenge for form-based authentication. Following is the code to create form-based authentication:
var sampleAppRealmChallengeHandler = WL.Client.createChallengeHandler("myFormBasedAppRealm"); //line # 01
sampleAppRealmChallengeHandler.isCustomResponse = function(response) {
if (!response || response.responseText === null) {
return false;
}
var indicatorIdx = response.responseText.search('j_security_check'),
if (indicatorIdx >= 0){
return true;
}
return false;
};
sampleAppRealmChallengeHandler.handleChallenge = function(response) {
$('#MainAppBody').hide();
$('#AuthBody').show();
$('#passwordInputField').val(''),
};
sampleAppRealmChallengeHandler.submitLoginFormCallback = function(response) {
var isLoginFormResponse = sampleAppRealmChallengeHandler.isCustomResponse(response);
if (isLoginFormResponse){
sampleAppRealmChallengeHandler.handleChallenge(response);
} else {
$('#MainAppBody').show();
$('#AuthBody').hide();
sampleAppRealmChallengeHandler.submitSuccess();
}
};
$('#loginButton').bind('click', function () {
var reqURL = '/j_security_check';
var options = {};
options.parameters = {
j_username : $('#usernameInputField').val(),
j_password : $('#passwordInputField').val()
};
options.headers = {};
sampleAppRealmChallengeHandler.submitLoginForm(reqURL, options, sampleAppRealmChallengeHandler.submitLoginFormCallback);
});
$('#cancelButton').bind('click', function () {
sampleAppRealmChallengeHandler.submitFailure();
$('#MainAppBody').show();
$('#AuthBody').hide();
});If you see, we have first created an instance of a challenge handler as we did in adapter-based authentication. After that, in the isCustomResponse function, we search for the j_security_check string. If it exists, it means a login form has been sent by the server and the challenge handler will return true.
- The following line shows:
var isLoginFormResponse = sampleAppRealmChallengeHandler.isCustomResponse(response);
- The callback function will check the response for the containing server challenge again. If the challenge is found, the
handleChallenge()function is invoked again. - The
handleChallenge()function will again show a login form to the user to re-enter the correct credentials. - Otherwise,
sampleAppRealmChallengeHandler.submitSuccess();will be called to let the Worklight framework know that the challenge has been handled successfully, and it can proceed with the original request of the user.
If the user wants to terminate the authentication validation process and also wants to reject the original request that had triggered the authentication, he or she has to call sampleAppRealmChallengeHandler.submitFailure();.