Configure the MobileFirst Server for Trusteer

Configure the MPF Server to use Trusteer -generated data to protect resources.

We must update authenticationConfig.xml.to configure the server to use the MobileFirst Trusteer realm.

1. Add the login module definition to the <loginModules> element in the server's authenticationConfig.xml file. The following example uses a login module called trusteerFraudDetectionLogin:

   <loginModules>
   ...
     <loginModule name="trusteerFraudDetectionLogin">
       <className>com.worklight.core.auth.ext.TrusteerLoginModule</className>
     </loginModule>
   ...
   </loginModules>

2. Add the realm definition to the <realms> element in the server's authenticationConfig.xml file. The following example uses a realm called wl_basicTrusteerFraudDetectionRealm:

   <realms>
   ...
     <realm name="basicTrusteerFraudDetectionRealm" loginModule="trusteerFraudDetectionLogin">
       <className>com.worklight.core.auth.ext.TrusteerAuthenticator</className>
         <parameter name="rooted-device" value="block"/>
         <parameter name="device-with-malware" value="block"/>
         <parameter name="rooted-hiders" value="block"/>
         <parameter name="unsecured-wifi" value="alert"/>
         <parameter name="outdated-configuration" value="alert"/>
     </realm>
   ...
   </realms>

   The possible values for Trusteer realm parameters are described in Table 1.

   Value	Description
   block	Access fails.
   alert	Access is permitted and IBM recommends to issue a warning.
   accept	Access is permitted.

   The error codes that have been defined for Trusteer correspond to the parameters in the realm. See Table 2.

   Code	Description	Corresponding parameter
   TAS_ROOT	Indicates that the device is rooted (Android) or jailbroken (iOS).	rooted-device
   TAS_MALWARE	Indicates that the device contains malware. Currently financial malware is detected, but will be expanded to all malware.	device-with-malware
   TAS_ROOT_EVIDENCE	Indicate that the device contains root hider applications that hide the fact that the device is rooted/jailbroken.	rooted-hiders
   TAS_WIFI	Indicates that the device is currently connected to an unsecured Wi-Fi.	unsecured-wifi
   TAS_OUTDATED	Indicates that Trusteer SDK configuration has not updated for some time, meaning that it did not connect to the Trusteer server.	outdated-configuration
   TAS_INVALID_HEADER	Indicates that the format of the Trusteer header is invalid.	-
   TAS_NO_HEADER	Indicates that the Trusteer SDK is not installed, or has failed to initialize.	-

3. Define a security test in the <securityTest> element in authenticationConfig.xml. For Trusteer, it could be:

   <customSecurityTest name="TrusteerTest">
     <test realm="wl_basicTrusteerFraudDetectionRealm" isInternalUserID="true" step="1"/>
     ...
   </customSecurityTest>

4. Use the security test to protect a resource. For example, we can protect an application's environment completely with that security test by adding the securityTest attribute to the environment's element in authenticationConfig.xml.

   <iPhone version="1.0" securityTest="TrusteerTest">
     ...
   </iPhone>

   This definition requires every iPhone device that connects to the server through the application to log in to the TrusteerTest security test.

5. Use the same security test, another option is to protect a MobileFirst adapter procedure. . If we have an adapter procedure named GetSecretData, we can protect it in the XML configuration file of the adapter by adding the <realms> attribute to the <procedure>:
   <procedure name="GetSecretData" securityTest="TrusteerTest" />

6. Create a challenge handler for the MobileFirst app to handle Trusteer challenges. The following samples are samples of simple challenge handlers:

   JavaScript

   var trusteerChallengeHandler = WL.Client.createWLChallengeHandler("wl_basicTrusteerFraudDetectionRealm");
   trusteerChallengeHandler.handleFailure = function(error) {
     //Note: error object includes array of alerts (same values as error.reason) from the //Trusteer authenticator and can be accessed via error.alerts
     WL.SimpleDialog.show("Error", "Operation failed. Please contact customer support (reason code: " + error.reason + ")",   [{text:"OK"}]); 
   }; 
   //In case authenticator succeeds, there may still be alerts that developer should notify the user about:
   trusteerChallengeHandler.processSuccess = function(identity){
     var alerts = identity.attributes.alerts;  //Array of alerts codes
     if(alerts.length > 0) {
       WL.SimpleDialog.show("Warning", "Please note that the device is : " + alerts,  [{text:"OK"}]); 
   }
   

   Java

   public class TrusteerChallengeHandler extends WLChallengeHandler {
     
     private static Logger logger = Logger.getInstance(TrusteerChallengeHandler.class.getSimpleName()); 
     public TrusteerChallengeHandler(String realmName) {  super(realmName);   }
       @Override 
       public void handleSuccess(JSONObject identity) { 
         try { 
           JSONArray alerts = identity.getJSONObject("attributes").getJSONArray("alerts");
           if(alerts.length() > 0) { 
             logger.warn ("TrusteerChallengeHandler.handleSuccess with alerts: " + alerts); 
             //todo: display message to the user 
           } 
         } catch (Exception e) { 
           logger.error("Unexpected error: " + e); 
         } 
       }    
       @Override   
       public void handleFailure(JSONObject error) { 
         try { 
           String errorReason = error.getString("reason"); 
           logger.error("TrusteerChallengeHandler.handleFailure: " + errorReason + "(" + error + ")"); 
           String msg = "Trusteer fraud detection failed due to " + errorReason; 
           JSONArray alerts = error.getJSONArray("alerts"); 
           if(alerts.length() > 0) { 
             logger.warn ("TrusteerChallengeHandler.handleSuccess with alerts: " + alerts); 
             //todo: We also have alerts... 
           } 
           //todo: display error message to user 
         } catch (Exception e) {
         logger.warn ("Unexpected error: " + e); 
         }     
       } 
       @Override
       public void handleChallenge(JSONObject challenge) {
         //Nothing to do... 
       } 
   }
   // Register the newly created challenge handler for the Trusteer realm:
   WLClient.getInstance().registerChallengeHandler(
     new TrusteerChallengeHandler("wl_basicTrusteerFraudDetectionRealm")
   );
   

   Objective-C

   // Assuming we have added a Trusteer realm to the authentication configuration file of 
   // the server, we can register a challenge handler to receive the responses from 
   // the authenticator.
   // Create a class that extends WLChallengeHandler:
   #import "WLChallengeHandler.h"
   @interface TrusteerChallengeHandler : WLChallengeHandler
   @end
   // Register the newly created challenge handler for the Trusteer realm:
   [[WLClient sharedInstance] registerChallengeHandler:
   [[TrusteerChallengeHandler alloc] initWithRealm:@"
   wl_basicTrusteerFraudDetectionRealm"]];
   // If we have set one of the realm options to block, a blocking event will trigger handleFailure.
   @implementation TrusteerChallengeHandler
   //...
   -(void) handleFailure: (NSDictionary *)failure{
      NSLog(@"Your request could not be completed. Reason code: %@",  failure[@"reason"]);
   }
   //...
   @end
   // If the have set one of the realm options to alert, we can catch the alert event 
   // by implementing the handleSuccess method.
   @implementation TrusteerChallengeHandler
   //...
   -(void) handleSuccess:(NSDictionary *)success{
       NSArray* alerts = success[@"attributes"][@"alerts"];
       if(alerts && alerts.count){
           for(NSString* alert in alerts){
               NSLog(@"This device is %@", alert);
           }
       }
   }
   //...
   @end
   

Parent topic: MobileFirst security overview