Form-based authentication in native Android applications

improve this page | report issue


This tutorial explains how to implement the client-side of form-based authentication in native Android.
Prerequisite: Make sure that you read the Form-based authentication tutorial first.

Implementing the client-side authentication

Challenge Handler

  • Create a MyChallengeHandler class as a subclass of ChallengeHandler.
    public class AndroidChallengeHandler extends ChallengeHandler
  • Call the super method:
    public AndroidChallengeHandler(String realm) {
  • Add an implementation of the following ChallengeHandler methods to handle the form-based challenge:
    1. isCustomResponse method:
      The isCustomResponse method is invoked each time a response is received from the MobileFirst 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.
      The default login form that returns from the MobileFirst Server contains the j_security_check string. If the response contains the string, the challenge handler returns true.
      public boolean isCustomResponse(WLResponse response) {
          if (response == null || response.getResponseText() == null ||
                  response.getResponseText().indexOf("j_security_check") == -1) {
              return false;
          return true;
    2. handleChallenge method:
      If isCustomResponse returns true, the framework calls the handleChallenge method. This function is used to perform required actions, such as hiding the application screen and showing the login screen.
      public void handleChallenge(WLResponse response){
          if (!isCustomResponse(response)) {
          } else {
              cachedResponse = response;
              Intent login = new Intent(parentActivity, LoginFormBasedAuth.class);
              parentActivity.startActivityForResult(login, 1);
    3. onSuccess and onFailure methods:
      At the end of the authentication flow, onSuccess or onFailure will be triggered
      Call the submitSuccess method in order to inform the framework that the authentication process completed successfully and for the onSuccess handler of the invocation to be called.
      Call the submitFailure method in order to inform the framework that the authentication process failed and for the onFailure handler of the invocation to be called.
      public void onFailure(WLFailResponse response) {
      public void onSuccess(WLResponse response) {


When the user taps to submit the credentials, you need to call the submitLoginForm method in order to send the j_security_check string and the credentials to the MobileFirst Server.
For example, in here we implemented a submitLogin method that called by the MainActivity after the login process is completed.

public void submitLogin(int resultCode, String userName, String password, boolean back){
    if (resultCode != Activity.RESULT_OK || back) {
    } else {
        HashMap<String, String> params = new HashMap<String, String>();
        params.put("j_username", userName);
        params.put("j_password", password);
        submitLoginForm("/j_security_check", params, null, 0, "post");

The Main Activity

In the sample project, in order to trigger the challenge handler we use the WLClient invokeProcedure method.
The protected procedure invocation triggers MobileFirst Server to send the challenge.

  • Create a WLClient instance and use the connect method to connect to the MobileFirst Server:
    final WLClient client = WLClient.createInstance(this);
    client.connect(new MyConnectionListener());
  • In order to listen to incoming challenges, make sure to register the challenge handler by using the registerChallengeHandler method:
    challengeHandler = new AndroidChallengeHandler(this, realm);
  • Invoke the protected adapter procedure:
    URI adapterPath = new URI("/adapters/AuthAdapter/getSecretData");
    WLResourceRequest request = new WLResourceRequest(adapterPath,WLResourceRequest.GET);
    request.send(new MyResponseListener());

Sample application

Click to download the MobileFirst project.
Click to download the Native project.

  • The FormBasedAuth project contains a MobileFirst native API that you can deploy to your MobileFirst server.
  • The FormBasedAuthAndroid project contains a native Android application that uses a MobileFirst native API library.
  • Make sure to update the file in the native project with the relevant server settings.


Inclusive terminology note: The Mobile First Platform team is making changes to support the IBM® initiative to replace racially biased and other discriminatory language in our code and content with more inclusive language. While IBM values the use of inclusive language, terms that are outside of IBM's direct influence are sometimes required for the sake of maintaining user understanding. As other industry leaders join IBM in embracing the use of inclusive language, IBM will continue to update the documentation to reflect those changes.
Last modified on November 09, 2016