Custom Authenticator and Login Module in native iOS applications

improve this page | report issue
This tutorial explains how to implement the client-side of custom authenticator and login module in native iOS.
Prerequisite: Make sure that you read Custom Authenticator and Login Module first.

Implementing the client-side authentication

Create a native iOS application and add the MobileFirst native APIs as explained in Configuring a native iOS application with the MobileFirst Platform SDK.


In your storyboard, add a ViewController containing a login form.

Challenge Handler

  • Create a MyChallengeHandler class as a subclass of ChallengeHandler.
    @interface MyChallengeHandler : ChallengeHandler
  • Call the initWithRealm method:
    @implementation MyChallengeHandler
    //...<br />
        self = [self initWithRealm:@"CustomAuthenticatorRealm"];
        return self;
  • Add implementation of the following ChallengeHandler methods to handle the custom authenticator and login module 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.

      @implementation MyChallengeHandler
      -(BOOL) isCustomResponse:(WLResponse *)response {
          if(response && [response getResponseJson]){
              if ([[response getResponseJson] objectForKey:@"authStatus"]) {
                  NSString* authRequired = (NSString*) [[response getResponseJson] objectForKey:@"authStatus"];
                  return ([authRequired compare:@"required"] == NSOrderedSame);
          return false;
    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.

      @implementation MyChallengeHandler
      -(void) handleChallenge:(WLResponse *)response {
          NSLog(@"A login form should appear");
          LoginViewController* loginController = [ instantiateViewControllerWithIdentifier:@"LoginViewController"];
          loginController.challengeHandler = self;
          [ pushViewController:loginController animated:YES];
    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.

      @implementation MyChallengeHandler
      -(void) onSuccess:(WLResponse *)response {
          NSLog(@"Challenge succeeded");
          [ popViewControllerAnimated:YES];
          [self submitSuccess:response];
      -(void) onFailure:(WLFailResponse *)response {
          NSLog(@"Challenge failed");
          [self submitFailure:response];


In your login View Controller, when the user taps to submit the credentials, call the submitLoginForm method to send the credentials to the MobileFirst Server.

@implementation LoginViewController
- (IBAction)login:(id)sender {
        requestParameters:@{@"username": self.username.text, @"password": self.password.text}

Registering the challenge handler

Before calling the protected adapter, in order to listen to incoming challenges, make sure to register the challenge handler by using the registerChallengeHandler method of the WLClient class.

[[WLClient sharedInstance] registerChallengeHandler:[[MyChallengeHandler alloc] initWithViewController:self] ];

Sample application

Click to download the Studio project.
Click to download the Obj-C project.
Click to download the Swift project.


Last modified on November 09, 2016