GatewayChallengeHandler Class Reference
| Inherits from | BaseChallengeHandler : NSObject |
| Conforms to | WLDelegate |
| Declared in | GatewayChallengeHandler.h |
Overview
You use this base class to create custom challenge handlers when using gateways. You must extend this class to implement your own challenge handler logic. You use this class to create custom user authentication with external gateways.
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_NAMEParameters
- response
The WLResponse to be tested.
Declared In
GatewayChallengeHandler.hhandleChallenge:
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 *)responseParameters
- response
The WLResponse to be handled.
Declared In
GatewayChallengeHandler.hinitWithGatewayName:
Initialize a challenge handler for the specific gateway.
- (id)initWithGatewayName:(NSString *)gatewayNameParameters
- gatewayName
an arbitrary name for the challenge handler.
Declared In
GatewayChallengeHandler.honFailure:
This method is the failure delegate for submitLoginForm
- (void)onFailure:(WLFailResponse *)responseParameters
- 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, you 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.honSuccess:
This method is the success delegate for submitLoginForm
- (void)onSuccess:(WLResponse *)responseParameters
- 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, you 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.hsubmitLoginForm:requestParameters:requestHeaders:requestTimeoutInMilliSeconds:requestMethod:
You use this method to send collected credentials to a specific URL. You can also specify request parameters, headers, and timeout.
- (void)submitLoginForm:(NSString *)requestUrl requestParameters:(NSDictionary *)parameters requestHeaders:(NSDictionary *)headers requestTimeoutInMilliSeconds:(int)timeout requestMethod:(NSString *)methodParameters
- 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 you 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 you must override the onSuccess / onFailure methods.
Declared In
GatewayChallengeHandler.hsubmitSuccess:
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 *)responseParameters
- response
The received WLResponse.
Declared In
GatewayChallengeHandler.h