Client security APIs

Learn about the MobileFirst security client APIs for issuing resource requests and handling security challenges.

OAuth resource-request APIs

IBM MobileFirst™ Platform Foundation provides two alternative sets of OAuth client APIs for accessing protected resources:

The WLResourceRequest class is a high-level API that encapsulates the OAuth flow for accessing a protected resource, and handles the required interaction with the authorization and resource servers. See the documentation of this class for your development platform and programming language.
- For Objective-C, see WLResourceRequest.
- For Java™, see WLResourceRequest.
- For JavaScript, see WLResourceRequest.
- For C#, see WLResourceRequest.
The WLAuthorizationManager class is a low-level API for managing the OAuth interaction between the client and the authorization server. In addition, you need to write the code for interacting with the resource server. Sample custom resource-request implementations, which use the WLAuthorizationManager class, are provided to help get your started. See the documentation of this class and the provided sample for your development platform and programming language:
- For Objective-C, see WLAuthorizationManager and Objective-C custom resource-request implementation sample.
- For Java, see WLAuthorizationManager and Java custom resource-request implementation sample.
- For JavaScript, see WLAuthorizationManager and JavaScript custom resource-request implementation sample.
- For C#, see WLAuthorizationManager and C# custom resource-request implementation sample.

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).