Performing Risk Evaluation

 
cara
 
When a user accesses your online application, the application forwards the request to RA for risk analysis. RA can evaluate risk for all users, whether they are first-time users (and therefore not "known" to RA) or if they are already enrolled with the RA system.
The Risk Evaluation Java API provides a programmable interface, which can be used by Java clients (such as Java Servlets and JSP pages) to send risk evaluation-related requests to Transaction Server. This API creates a request message that is sent to Transaction Server, receives the response, and packages it as return structures to be read by the client.
This topic provides an overview of how to use the Java API to perform risk evaluation and the methods and interfaces it implements. A description of the API interfaces and methods used to list and delete associations in the RA database is also provided. Each risk evaluation-related and association management task description is followed by a sample code snippet that you can use in your code to perform the task. The topic covers the following sub-topics:
2
Evaluating Risks and Performing Post-Evaluation
To evaluate the risk associated with a transaction and to perform the subsequent post-evaluation, you need to use the RiskXActionAPI interface (in the com.arcot.riskfortAPI package. This interface represents the client-side interface to Transaction Server’s risk evaluation functionality and exposes the supported API for risk evaluation workflows.
To evaluate risk of a transaction and perform post-evaluation tasks:
  1. Ensure that you have initialized the Risk Evaluation API by using the RiskFactory class.
    See Initializing the Risk Evaluation API for more information.
  2. If required, prepare the additional inputs for the transaction, by using the AdditionalInputs class in the com.arcot.riskfortAPI.AdditionalInputs package.
    See Preparing Additional Inputs for more information.
  3. Use the RiskFactory.getRiskXActionAPI() static method to obtain an object that implements the RiskXActionAPI interface.
    This method returns the RiskXActionAPI object created as a part of the RiskFactory API initialization.
  4. Use the RiskXActionAPI.evaluateRisk() method to obtain an object of the RiskAssessment class.
    This method requires the following input parameters:
    1. Define and set the CallerID string variable, which will be used by your application for tracking purposes across calls.
    2. Invoke the buildDeviceSignature() method by using a DeviceContext object to build the JSON signature that you built, as discussed in Collecting Device ID and DeviceDNA.
    3. Create a LocationContext object, and then invoke the LocationContext object's setIpAddress() method to set the IP address to that of the user's system.
    4. Create a UserContext object, and then use the UserContext object's setUserID() method to set a unique ID for the user.
    5. Create a TransactionContext object and, if required, set the necessary properties for the returned object by using the methods in this class (setAction() and setChannel()).
    6. If you are using extra information, then use the AdditionalInputs object that you created in Step 2. Set the necessary properties for the returned object by using the AdditionalInputs.put(name,value) method.
      These are additional inputs in form of name-value pairs. For example:
      MerchantID=id;MerchantCountry=country;MerchantName=name
  5. Obtain the resulting RiskAssessment RiskAdvice object by using the RiskAssessment.getRiskAdvice() method.
    If the advice is INCREASEAUTH, then your application
    must
    perform secondary authentication and pass the result of this authentication to RA by using the PostEvaluate() method.
  6. Finally, use the RiskXActionAPI.postEvaluate() method to determine the final outcome of the transaction and return a PostEvaluateResponse object.
    The postEvaluate() method updates the Device Signature information for the user, if it changed and creates or updates user-device associations, if required.
    You will need to pass the result of secondary authentication to the method, if you performed any.
  7. You can query the resulting PostEvaluateResponse object by using the PostEvaluateResponse.isAllowAdvised() method to:
    • Determine whether or not to permit the transaction to proceed.
    • Update the information related to the transaction in the RA database.
Handling Errors
Any errors that occurred during the execution of any of the Risk Evaluation API methods can result in one of the following two exceptions being thrown:
  • RiskException is thrown if the error occurred at Transaction Server-end. In this case, the SDK only "relays" the information to your code. The RiskException object has getReasonCode, getResponseCode, and getTransactionId members that contain the reason code, error code, and transaction identifier (generated at Transaction Server-end) associated with the error that occurred.
  • RFSDKException is, typically, thrown if the error occurred at the SDK-end. The RFSDKException object has getResponseCode and getTransactionId members that contain the error code and transaction identifier (generated at Transaction Server-end) associated with the error that occurred.
Sample Code for Risk Evaluation and Post Evaluation
Refer to Sample Code for a detailed working code sample.
You can use the following sample code snippet to understand how to implement the risk evaluation and post-evaluation capability of RA in your application code.
public static void sampleCode() { String propertyLocation= "/properties/riskfort.risk-evaluation.properties"; try { RiskFactory.initialize(propertyLocation); RiskXActionAPI riskXActionAPI = RiskFactory.getRiskXActionAPI(); String callerId; UserContext userContext = new UserContext(); LocationContext locationContext = new LocationContext(); DeviceContext deviceContext = new DeviceContext(); TransactionContext transactionContext = new TransactionContext(); AdditionalInputs additionalInputs = new AdditionalInputs(); // string used by the calling application for tracking across // calls callerId="MyApplicationTrackingId"; // Unique identifier for the user. In the case of a Bank it may be // user's bank account number // It may be name of the user in some other case. userContext.setUserId("USER1"); // IP address of the user's machine, typically, extracted from // the HTTP header locationContext.setIpAddress(InetAddress.getByName("10.150.1.1")); // JSON Signature comes from mfp_json.js, in this example the // signature is hard coded // for the sample use. String jsonSignature = "{\"navigator\":{\"platform\":\"Win32\",\"appName\":\"Netscape\",\"appCodeName\":\"Mozilla\",\"appVersion\":\"5.0 (Windows; en-US)\",\"language\":\"en-US\",\"oscpu\":\"Windows NT 5.0\",\"vendor\":\"\",\"vendorSub\":\"\",\"product\":\"Gecko\",\"productSub\":\"20070312\",\"securityPolicy\":\"\",\"userAgent\":\"Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US; rv:1.8.0.11) Gecko/20070312 Firefox/1.5.0.11\",\"cookieEnabled\":true,\"onLine\":true},\"plugins\":[{\"name\":\"Adobe Acrobat Plugin\",\"version\":\"7.00\"},{\"name\":\"Macromedia Director\",\"version\":\"10.1\"},{\"name\":\"Windows Media Player Plug-in Dynamic Link Library\",\"version\":\"\"},{\"name\":\"Macromedia Shockwave Flash\",\"version\":\"9.0\"},{\"name\":\"Java Virtual Machine\",\"version\":\"1.6.0\"}],\"screen\":{\"availHeight\":690,\"availWidth\":1024,\"colorDepth\":32,\"height\":768,\"pixelDepth\":32,\"width\":1024},\"extra\":{\"javascript_ver\":\"1.6\",\"timezone\":-330}}"; deviceContext.buildDeviceSignature(jsonSignature,null,null); String userDeviceId="GPXp+4e0hzzxzh6YLlPZqKgXCGbBXB8E0ghZnFXHq8o3HLRaww6c4g=="; // The device id collected from the user machine deviceContext.setDeviceID("HTTP_COOKIE", userDeviceId); // Providing the addition inputs. additionalInputs.put("MerchantID","id") ; additionalInputs.put("MerchantCountry","country") ; additionalInputs.put("MerchantName","name") ; transactionContext.setAction("Login"); RiskAssessment riskAssessment=null; riskAssessment = riskXActionAPI.evaluateRisk(callerId , deviceContext, locationContext , userContext, transactionContext, additionalInputs); boolean secondaryAuthenticationStatus = true; String associationName = "USER1inHomePC"; if (riskAssessment.getRiskAdvice().equals(RiskAssessment.RISK_ADVICE_INCREASEAUTH)) { // then you may ask for secondary authentication //if( secondaryAuthentication succeeded ) // secondaryAuthenticationStatus = true; //else // secondaryAuthenticationStatus = false } PostEvaluateResponse postEvaluateResponse = riskXActionAPI.postEvaluate(callerId, riskAssessment, secondaryAuthenticationStatus, associationName); if( postEvaluateResponse.isAllowAdvised() ) { //Allow the transaction to be completed } else { //Deny and terminate the transaction } } catch (IOException e) { //Looks like the property file location is not valid e.printStackTrace(); } catch (RiskException e) { //One of the RA API calls broke e.printStackTrace(); } }
Managing Associations
RA uniquely identifies a user as a valid user of your system by automatically associating (or binding) a user to the device that they use to access your application. This is referred to as an
association
(or device binding) in RA terminology. Users who are not bound are more likely to be challenged in order to be authenticated.
RA also allows users to be bound to more than one device. For example, a user can use a work and a home computer to access your application. Similarly, you can bind a single device to more than one user. For example, members of a family can use one computer to access your application.
You must discourage users from creating associations with publicly shared devices, such as systems in an Internet cafe or kiosk.
Association management includes:
  • Listing Associations
  • Deleting Associations
Listing Associations
To list all the stored associations for a specified user:
  1. Ensure that you have initialized the Risk Evaluation API by using the RiskFactory class.
    See Initializing the Risk Evaluation API for more information.
  2. If required, prepare the additional inputs for the transaction, by using the AdditionalInputs class in the com.arcot.riskfortAPI.AdditionalInputs package.
    See Preparing Additional Inputs for more information.
  3. Use the RiskFactory.getRiskXActionAPI() static method to obtain an object that implements the RiskXActionAPI interface.
    This method returns the RiskXActionAPI object created as a part of the RiskFactory API initialization.
  4. Define and set the CallerID string variable, which will be used by your application for tracking purposes across calls.
  5. Create a UserContext object, and then use the UserContext object's setUserID() method to set a unique ID for the user.
  6. Set the necessary properties for the returned object.
    For example, you can set the user ID by calling the UserContext.setUserId() method.
  7. Call the RiskXActionAPI.listAssociations() method to create a ListAssociationResponse object.
    The following code snippet shows the usage of the method to list all existing associations.
    public ListAssociationResponse listAssociations(java.lang.String callerId, UserContext userContext, AdditionalInputs additionalInputs) throws RFSDKException, RFSDKException
    The ListAssociationResponse.getAllAssociations() method returns an array of all known associations for the specified user.
Handling Errors
Any errors that occurred during the execution of any of the Risk Evaluation API methods can result in one of the following two exceptions being thrown:
  • RiskException is thrown if the error occurred at Transaction Server-end. In this case, the SDK simply "relays" the information to your code. The RiskException object has getReasonCode, getResponseCode,and getTransactionId members that contain the reason code, error code, and transaction identifier (generated at Transaction Server-end) associated with the error that occurred.
  • RFSDKException is, typically, thrown if the error occurred at the SDK-end. The RFSDKException object has getResponseCode and getTransactionId members that contain the error code and transaction identifier (generated at Transaction Server-end) associated with the error that occurred.
Deleting Associations
To delete the specified user-device association for a user:
  1. Ensure that you have initialized the Risk Evaluation API by using the RiskFactory class.
    See Initializing the Risk Evaluation API for more information.
  2. If required, prepare the additional inputs for the transaction, by using the AdditionalInputs class in the com.arcot.riskfortAPI.AdditionalInputs package.
    See Preparing Additional Inputs for more information.
  3. Use the RiskXActionAPI.evaluateRisk() method to obtain an object of the RiskAssessment class. Use the RiskFactory.getRiskXActionAPI() static method to obtain an object that implements the RiskXActionAPI interface.
    This method returns the RiskXActionAPI object created as a part of the RiskFactory API initialization.
  4. Define and set the CallerID string variable, which will be used by your application for tracking purposes across calls.
  5. Create a UserContext object, and then use the UserContext object's setUserID() method to set a unique ID for the user.
  6. Set the necessary properties for the returned object.
    For example, you can set the user ID by calling the UserContext.setUserId() method.
  7. Obtain a ListAssociationsResponse object by invoking RiskXActionAPI.listAssociations. Then invoke ListAssociationResponse's getAllAssociations() method. This method returns an array of type UserDeviceAssociation. You can use UserDeviceAssociation.getAssociationName() for each UserDeviceAssociation object to get the name of the association.
  8. Call the RiskXActionAPI.deleteAssociation() method to delete the association.
    The following code snippet shows the usage of the method to delete user-device associations.
    public DeleteAssociationResponse deleteAssociation(java.lang.String callerId, UserContext userContext, java.lang.String associationName, AdditionalInputs additionalInputs) throws RiskException, RFSDKException
    The DeleteAssociationResponse.DeleteAssociationResponse() method deletes the association for the user that you specified.
Handling Errors
Any errors that occurred during the execution of any of the Risk Evaluation API methods can result in one of the following two exceptions being thrown:
  • RiskException is thrown if the error occurred at Transaction Server-end. In this case, the SDK simply "relays" the information to your code. The RiskException object has getReasonCode, getResponseCode,and getTransactionId members that contain the reason code, error code, and transaction identifier (generated at Transaction Server-end) associated with the error that occurred.
  • RFSDKException is, typically, thrown if the error occurred at the SDK-end. The RFSDKException object has getResponseCode and getTransactionId members that contain the error code and transaction identifier (generated at Transaction Server-end) associated with the error that occurred.