Quick Review of Challenge Handlers in MobileFirst Foundation 8.0
Nathan Hazout May 07, 2018MobileFirst_Platform Security
Challenge handlers have changed between 8.0 beta and 8.0 GA. If you have used challenge handlers in previous versions of MobileFirst Foundation (previously Worklight/MobileFirst Platform Foundation), it is worth going over this quick review of challenge handlers, to understand the new APIs and the different types of challenge handlers. If you are an on-premise 8.0 customer or Mobile Foundation service customer, then read further to learn about challenge handlers in Mobile Foundation.
What is a challenge handler
When trying to access a protected resource, the client may be faced with a challenge. A challenge is a question, a security test, a prompt by the server to make sure you are allowed to access this resource.
Most commonly, this challenge is a request for credentials, such as a username and password.
In your client code, this challenge must be handled by an object called a challenge handler. It is important to note that once a challenge is received, it cannot be ignored. You must answer it, or cancel it. Ignoring a challenge may lead to unexpected behavior.
There are two types of challenge handlers:
In most cases, the challenge will be sent by a Security Check. Whenever a challenge is sent by a security check, it must be handled by a
SecurityCheckChallengeHandlerused to be called a
WLChallengeHandlerprior to 8.0 GA.
The incoming challenge is matched to your challenge handler using the security check name. It is important to register your challenge handler with the correct security check name. If the framework does not find any matching challenge handler, an error will be thrown and your application may not work as expected.
When the framework finds the matching challenge handler, it will call its
This needs to end either with a
submitChallengeAnswer or a
cancel call, in order to tell the framework that you are done with this challenge.
In 8.0 GA, the
submitFailureAPI was renamed to
Read more about
SecurityCheckChallengeHandler on the credentials validation tutorials.
In some cases, the challenge may be sent by a third party gateway. For example if your resource is protected by a reverse proxy such as DataPower, which sends a custom login form to the client. Whenever a challenge is sent by a gateway, it must be handled by a
GatewayChallengeHandlerused to be called a
ChallengeHandlerprior to 8.0 GA.
A gateway challenge does not follow the protocol defined by MobileFirst Foundation, as it is generated outside of it. While registering a
GatewayChallengeHandler requires a name (just like
SecurityCheckChallengeHandler), this name is not used to match the challenge to a challenge handler. Because of this, is it your responsibility to determine whether the incoming response is a challenge and to match it to the correct challenge handler.
This is done by implementing the
canHandleResponse method of
GatewayChallengeHandler. The framework will call this method for almost every incoming response the client receives. Whenever
true, the framework will call
handleChallenge and wait for you to finish handling this challenge.
canHandleResponseused to be named
isCustomResponseprior to 8.0 GA.
Because the challenge is custom, the framework has no way to automatically know that you finished handling the challenge. You must tell the framework by calling either
GatewayChallengeHandlerin the API documentation.
For an example using DataPower, see DataPower Integration.
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.