GatewayChallengeHandler Class Reference

Inherits from BaseChallengeHandler : NSObject
Conforms to WLDelegate
Declared in GatewayChallengeHandler.h


Overview

We use this base class to create custom challenge handlers when using gateways. You must extend this class to implement your own challenge handler logic. We use this class to create custom user authentication with external gateways.


Tasks


Instance Methods


canHandleResponse:NS_SWIFT_NAME:

This method must be overridden by extending the GatewayChallengeHandler class. In most cases, you call this method to test whether there is a custom challenge to be handled in the response. If this method returns YES, IBM MobileFirst Platform calls the handleChallenge method.

- (BOOL)canHandleResponse:(WLResponse *)response NS_SWIFT_NAME


Parameters

response

The WLResponse to be tested.


Declared In

GatewayChallengeHandler.h


handleChallenge:

IBM MobileFirst Platform must call this method whenever isCustomResponse returns a YES value. You must implement this method. This method must handle the challenge, for example to show the login screen.

- (void)handleChallenge:(WLResponse *)response


Parameters

response

The WLResponse to be handled.


Declared In

GatewayChallengeHandler.h


initWithGatewayName:

Initialize a challenge handler for the specific gateway.

- (id)initWithGatewayName:(NSString *)gatewayName


Parameters

gatewayName

an arbitrary name for the challenge handler.


Declared In

GatewayChallengeHandler.h


onFailure:

This method is the failure delegate for submitLoginForm

- (void)onFailure:(WLFailResponse *)response


Parameters

response

The received fail response.


Discussion

This method is called when a response does not have a 200 HTTP status code. This method does not indicate whether the challenge was successful or not. In some cases onFailure is an indication of a normal challenge handling sequence.

An example of when the onFailure method is called is when a 401 Unauthorized response is received.

A successful handshake can entail several 401 response iterations and therefore several onFailure calls. This behavior is all part of the normal handshake between two parties that are trying to establish identity. IBM MobileFirst Platform handles the handshakes for core challenges iteratively until all of the credentials are established and the necessary challenges are processed.

This is a good place to check whether the response is a custom response and handle it accordingly. If the response is not a custom response, we can call submitSuccess to indicate that all is good from your challenge handler’s perspective, and that IBM MobileFirst Platform can handle the response instead.


Declared In

GatewayChallengeHandler.h


onSuccess:

This method is the success delegate for submitLoginForm

- (void)onSuccess:(WLResponse *)response


Parameters

response

The received response.


Discussion

This method is called when a successful HTTP response is received (200 OK). This method does not indicate whether the challenge was successful or not. A 200 HTTP response can flow back indicating problems with authentication on the server or requesting additional information.

Some examples of a 200 HTTP response are as follows:

  • First init request returns a normal 200 HTTP response that requests a pkms login form Authentication failed on the server.
  • A 200 HTTP response, indicating that the account is locked on the server due to too many failed login attempts.

This is a good place to check whether the response is a custom response and handle it accordingly. If the response is not a custom response, we can call submitSuccess to indicate that all is good from your challenge handler’s perspective, and that IBM MobileFirst Platform can handle the response instead.

Note: IBM MobileFirst Platform does not attempt to determine what the 200 response means.


Declared In

GatewayChallengeHandler.h


submitLoginForm:requestParameters:requestHeaders:requestTimeoutInMilliSeconds:requestMethod:

We use this method to send collected credentials to a specific URL. We can also specify request parameters, headers, and timeout.

- (void)submitLoginForm:(NSString *)requestUrl requestParameters:(NSDictionary *)parameters requestHeaders:(NSDictionary *)headers requestTimeoutInMilliSeconds:(int)timeout requestMethod:(NSString *)method


Parameters

requestUrl

Absolute URL if the user sends an absolute url that starts with http:// or https:// Otherwise, URL relative to the IBM MobileFirst Platform Server

parameters

The request parameters

headers

The request headers

timeout

o supply custom timeout, use a number over 0. If the number is under 0, IBM MobileFirst Platform uses the default timeout, which is 10,000 milliseconds.

method

The HTTP method that we must use. Acceptable values are GET, POST.The default value is POST.


Discussion

The success/failure delegate for this method is the instance itself, which is why we must override the onSuccess / onFailure methods.


Declared In

GatewayChallengeHandler.h


submitSuccess:

You must call this method when the challenge is answered successfully, for example after the user successfully submits the login form. Then, this method sends the original request. Calling this method informs IBM MobileFirst Platform that the challenge was successfully handled. This method can also be used to inform IBM MobileFirst Platform that the response that was received is not a custom response that your challenge handler can handle. In this case, control is returned to IBM MobileFirst Platform, to handle the response.

- (void)submitSuccess:(WLResponse *)response


Parameters

response

The received WLResponse.


Declared In

GatewayChallengeHandler.h


© Copyright IBM Corp. 2017