Implementing form-based authenticators

You can authenticate users of mobile applications by using a login form.

About this task

In form-based authentication, if an application tries to access a protected resource, the server returns the HTML code of a login form. Even though a form of this kind is most suited to desktop and web environments (where you display the returned login form), you can also use form-based authentication in mobile applications.

The fully qualified Java™ class name of the form-based authenticator is: com.worklight.core.auth.ext.FormBasedAuthenticator.

This authenticator type presents a login form to the user. The login form must contain j_username and j_password fields , the j_security_check submit action, and the POST submit method.

A login module validates the credentials that are provided. If the login fails, the user is redirected to an error page.

Parameters

The form-based authenticator has the following parameters:

Parameter	Description
login-page	Path to a user-defined login page template, relative to the web application context under the conf directory. A sample login.html template file is provided under this directory when you create a MobileFirst project. The authenticator renders the login page template with the error messages. To display the error message, use the placeholder `${errorMessage}` in the login page template.
auth-redirect	Path to a user-defined login page (html/jsp) relative to the web application context. IBM MobileFirst™ Platform Foundation redirects to the page when the user credentials are needed.

Both the login-page and auth-redirect parameters are optional, but if you decide to use them, use either one or the other. You cannot use them together. You can also use neither. In this case, IBM MobileFirst Platform Foundation uses its default login page template.

Flow: The following diagram illustrates the flow in the form-based authentication process:

Figure 1. Form-based authentication process

Procedure

Configure the authenticationConfig.xml file. For more information, see The authentication configuration file.
Code the server side. To work, the form-based authenticator must be associated with a login module. MobileFirst Studio provides several predefined login modules. For an example, see Non-validating login module.
Note: If you want to protect an adapter procedure with form-based authentication, you must declare it in the adapter XML file. See the example in this page.
Code the client side.
You must declare a challenge handler in the application to handle challenges from the form-based configured realm. The following sample shows one way to implement a challenge handler class:
```
var sampleAppRealmChallengeHandler = WL.Client.createChallengeHandler("SampleAppRealm");
```
The challenge handler must implement the following functions:
- isCustomResponse: this function is called each time that a response is received from the server. It is used to detect whether the response contains data that is related to this challenge handler. It must return either true or false. Here is a simple example:
```
sampleAppRealmChallengeHandler.isCustomResponse = function(response) {
  return false;
};
```
- handleChallenge: this function is used to perform required actions, such as hide application screen and show login screen. handleChallenge is called by the framework, if isCustomResponse returns true. Here is a simple implementation, as an example:
```
sampleAppRealmChallengeHandler.handleChallenge = function(response) {
};
```
The challenge handler can also optionally implement the following, additional functions:
- submitLoginForm: this function sends the collected credentials to a specific URL. You can also specify request parameters, headers, and callback.
- submitSuccess: this function notifies the MobileFirst framework that the authentication finished successfully. The MobileFirst framework then automatically issues the original request that triggered the authentication.
- submitFailure: this function notifies the MobileFirst framework that the authentication process failed to finish. The MobileFirst framework then disposes of the original request that triggered the authentication.

Example

The following example demonstrates how to implement a simple form-based authentication mechanism that is based on a user name and a password. In the example, an adapter procedure is protected by a form-based authenticator, and when the user attempts to call the procedure from the application, the login form is displayed and the authentication process starts.

Configuration of the authenticationConfig.xml file

<securityTests>
  <customSecurityTest name="DummyAdapter-securityTest">
    <test isInternalUserID="true" realm="SampleAppRealm"/>
  </customSecurityTest>
</securityTests>

<realms>
  <realm name="SampleAppRealm" loginModule="StrongDummy">
    <className>com.worklight.core.auth.ext.FormBasedAuthenticator</className>
      <parameter name="login-page" value="login.html"/>
  </realm>
</realms>

<loginModules>
  <loginModule name="StrongDummy">
    <className>com.worklight.core.auth.ext.NonValidatingLoginModule</className>
  </loginModule>
</loginModules>

Coding the server side

Perform the following steps:

Create a MobileFirst adapter.
Add a procedure and protect it with the custom security test that you created earlier. The implementation can return some hard-coded value, for example:
```
<procedure name="getSecretData" securityTest="DummyAdapter-securityTest"/>
```

Coding the client side

Perform the following steps:

Create a MobileFirst application.
Create a challenge handler in the application, to handle challenges from the SampleAppRealm realm, for example:
```
var sampleAppRealmChallengeHandler = WL.Client.createChallengeHandler("SampleAppRealm");
```
Implement the mandatory isCustomResponse and handleChallenge functions (and other, optional functions) of the challenge handler, as described previously.

What to do next

For a more extensive example of implementing form-based authentication, see the Form-based authentication tutorials on the Developer Center website.