Client security APIs

OAuth resource-request APIs

Challenge-handler APIs

The client application uses challenge handlers to handle the client-side security logic and the related user interaction, and respond to security challenges. See OAuth scopes, security checks, and challenge handlers. You must implement and register a challenge handler for each custom security check that is applicable to your application (namely, security checks that are used to protect resources that are required by the application). In addition, you can customize the default MobileFirst challenge handler for displaying the user interface (UI) of the mobile-application management features (see Mobile-application management).

Creating a challenge handler

When communicating directly with MobileFirst Server, create a MobileFirst security-check challenge handler:

• In iOS Objective C or Swift code, create a class that extends the SecurityCheckChallengeHandler class.
• In Android Java code, create a class that extends the SecurityCheckChallengeHandler class.
• In Windows C# code, create a class that extends the Worklight.SecurityCheckChallengeHandler class.
• In web application or cross-platform (hybrid) Cordova application JavaScript code, call the WL.Client method createSecurityCheckChallengeHandler (which both creates and registers the challenge handler).

In gateway topologies, create a custom gateway challenge handler:

• In iOS Objective C or Swift code, create a class that extends the GatewayChallengeHandler class.
• In Android Java code, create a class that extends the GatewayChallengeHandler class.
• In Windows C# code, create a class that extends the GatewayChallengeHandler class.
• In web application or cross-platform (hybrid) Cordova application JavaScript code, call the WL.Client method createGatewayChallengeHandler (which both creates and registers the challenge handler).

Registering a challenge handler

Use the relevant API to register your challenge handler:

• In iOS Objective C or Swift code, call the WLClient method registerChallengeHandler.
• In Android Java code, call the WLClient method registerChallengeHandler.
• In Windows C# code, call the WorklightClient method RegisterChallengeHandler. See C# client-side API for Windows 10 Universal Windows Platform and Windows 8 Universal apps.
• In web application or cross-platform (hybrid) Cordova application JavaScript code, call the WL.Client method createSecurityCheckChallengeHandler or createGatewayChallengeHandler (which both creates and registers the challenge handler).

The security-challenge object

The security challenge is passed to the application within a JSON object that contains data pairs of a security-check name and an optional JSON object with additional data (or null if no additional data is required):

{
  "challenges": {
    "SecurityCheck1":null,
    "SecurityCheck2":{
      "PropertyName": "PropertyValue"
    [...]
    }
  }
}

Sample implementations and guidelines

You can find sample challenge-handler implementations and related development guidelines in the following IBM MobileFirst Platform Foundation Development Center tutorials. See the relevant tutorial for your development platform.

• The CredentialsValidationSecurityCheck tutorials demonstrate how to implement a challenge handler for the CredentialsValidationSecurityCheck security-check base class (see The security-check base and sample classes).
• The UserAuthenticationSecurityCheck tutorials demonstrate how to implement a challenge handler for the UserAuthenticationSecurityCheck security-check base class (see The security-check base and sample classes).