Skip Headers
Oracle® Adaptive Access Manager Developer's Guide
Release 10g (10.1.4.5)

Part Number E12052-03
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

4 Native Integration Java

This document provides information on the available APIs for integrations using Java. Refer to Chapter 2, "API Integration" for guidelines for integration options and flows.

4.1 Installation

The installation package will provide the required jars and property files. Sun Java 1.4 and above is supported for the integrations.

Property files of interest are listed below.

Table 4-1 Property Files of Interest

File name Description

bharosa_app.properties

This file is designated for installation-specific properties. Refer to the Oracle Adaptive Access Manager Installation and Configuration Guide for information on configuring Adaptive Risk Manager and Chapter 6, "Configuring Adaptive Strong Authenticator," for configuring Adaptive Strong Authenticator.

bharosa_client.properties

This file is designated for client side properties.

The sample file, bharosa_client.properites.sample, is provided with the installation package.

Copy bharosa_client.properites.sample to bharosa_client.properites. Update the properties as per your environment.

  1. Set the "vcrypt.tracker.soap.useSOAPServer" property. If SOAP is used, set the value to true. If static linking is used, set the value to false.

  2. Set the "vcrypt.tracker.soap.url" property to the Adaptive Risk Manager URL if "vcrypt.tracker.soap.useSOAPServer" is set to true. For example,

    vcrypt.tracker.soap.url=http://localhost:9090/oarm/services

  3. Set "bharosa.image.dirlist" if Adaptive Strong Authenticator is used. Refer to the Oracle Adaptive Access Manager Installation and Configuration Guide for more information on setting "bharosa.image.dirlist."

bharosa_common_keypad.properties

This file contains properties to customize various aspects of authenticators. This file is not to be modified by the clients.


4.2 Adaptive Risk Manager

Adaptive Risk Manager is a component of Oracle Adaptive Access Manager.

Adaptive Risk Manager provides APIs to

The sample application and the BharosaHelper class provide some of the usage scenarios.

For examples of usage scenarios and flows, refer to Chapter 2, "API Integration."

4.2.1 handleTrackerRequest

API handleTrackerRequest: API to capture fingerprint details and identify the device. Variations of the same API is provided to capture details with the time of the request. The time of request can be in the past.

  • public CookieSet handleTrackerRequest(String requestId, String remoteIPAddr, String remoteHost, String secureCookie, int secureClientType, String secureClientVersion, String digitalCookie, int digitalClientType, String digitalClientVersion, int fingerPrintType, String fingerPrint, int fingerPrintType2, String fingerPrint2);

  • public CookieSet handleTrackerRequest(String requestId, Date requestTime, String remoteIPAddr, String remoteHost, String secureCookie, int secureClientType, String secureClientVersion, String digitalSigCookie, int digitalClientType, String digitalClientVersion, int fingerPrintType, String fingerPrint, int fingerPrintType2, String fingerPrint2);

Table 4-2 API handleTrackerRequest Parameters

Parameter Description

requestId

The ID for the login session. The same ID is necessary for all the calls to the Oracle Adaptive Access Manager API for the login session.

remoteIPAddr

The IP from where the request came in. This is extracted from the HTTP request.

remoteHost

The host name from where the request came in. This is optional

secureCookie

The secure cookie. This is passed only if it is received from the browser

secureClientType

The secure cookie client type. This is an enum value defined to identify the client used for authentication.

secureClientVersion

The version of the secure cookie client. This is an optional parameter to specify the version of the client used

digitalCookie

The digital signature cookie. This could be the flash cookie. This parameter is sent only if it is sent by the browser

digitalClientType

The digital cookie client type. The type of flash client used. If not available, please use the value 0

digitalClientVersion

The version of the digital cookie client. The version of the flash client.

fingerPrintType

The type of finger printing. The value for defined in the properties file.

fingerPrint

The finger print. If it is browser characteristics, then the header is parsed into this string. This is the name value representation of the browser header information.

fingerPrintType2

This is used in case the same request has multiple finger prints. It is like a flash request. The value is defined in the properties file

fingerPrint2

The second finger print value. If it is from the flash, it is passed as it is. This is an optional parameter.

requestTime

The time when this request was made. Used by simulator


4.2.2 createTransaction

API createTransaction: API to create new transaction

  • public VCryptResponse createTransaction(TransactionCreateRequestData transactionCreateRequestData);

Table 4-3 API createTransaction Parameters

Parameter Description

TransactionCreateRequestData

Data object to create a new transaction. A description of the structure is as follows:

  • requestId is required to identify the user session

  • requestTime request time can be null. The server uses the current time if a null requestTime is sent

  • transactionKey is required data. It is the key to the transaction definition. This is the key used when creating a transaction definition

  • externalTransactionId is optional if there is external transaction Id. It can also be used to update the transaction later

  • status of the transaction can be null

  • The keys should map to the source keys defined in the transaction definition

  • BharosaException is thrown if fails validations

VCryptResponse

Response object. Make sure to check isSuccess() before obtaining the transaction Id.

getTransactionResponse() method provides the transaction id.


4.2.3 updateTransaction

API updateTransaction: API to update previously created transaction

  • public VCryptResponse updateTransaction(TransactionUpdateRequestData transactionUpdateRequestData);

Table 4-4 API updateTransaction Parameters

Parameter Description

TransactionUpdateRequestData

Data object to update transaction. Either transaction Id is returned during createTransaction API call or external transaction Id is sent during createTrasnaction API call to get the handle to the existing transaction. The description of the structure is as follows:

  • requestId is required to identify the user session

  • requestTime request time can be null. The server uses the current time if null requestTime is sent

  • transactionId id of the previously created transaction (createTransaction API call)

  • status of the transaction

  • The keys should map to the source keys defined in the transaction definition and can be null

  • analyzePatterns if true triggers pattern analysis

  • externalTransactionId external transaction id should be the same as the id provided during the transaction creation

  • BharosaException is thrown if fails validations

VCryptResponse

Response object. Make sure to check isSuccess() before obtaining the transaction Id.

getTransactionResponse() method provides transaction id.


4.2.4 handleTransactionLog

API handleTransactionLog: API to capture transaction details.

Note:

Deprecated as of 10.1.4.5.1, use createTransaction API.
  • public VCryptResponse handleTransactionLog(String requestId, Map[]);

  • public VCryptResponse handleTransactionLog(String requestId, Date requestTime, Map[] contextMap);

  • public VCryptResponse handleTransactionLog(String requestId, Date requestTime, Integer status, Map[] contextMap );

Table 4-5 API handleTransactionLog Parameters

Parameter Description

requestId

The ID for the login session. The same ID is necessary for all the calls to the Oracle Adaptive Access Manager API for the login session.

requestTime

The time when this request was made. Used by simulator

contextMap

The array of contextMap. Multiple transactions can be created with a single API call. It is expected to have "transactionType" key in each context map for the creation of the appropriate transaction.

status

The transaction status for this transaction, client specific transaction status.


4.2.5 updateTransactionStatus

API updateTransactionStatus: API to update the given transaction status and, if appropriate, trigger the pattern data analysis.

Note:

Deprecated as of 10.1.4.5.1, use updateTransaction API.
  • public VCryptResponse updateTransactionStatus(String requestId, long transactionId, int status);

  • public VCryptResponse updateTransactionStatus(String requestId, Date requestTime, long transactionId, int status);

  • public VCryptResponse updateTransactionStatus(String requestId, long transactionId, int status, Map[] contextMap);

  • public VCryptResponse updateTransactionStatus(String requestId, Date requestTime, long transactionId, int status, Map[] contextMap);

  • public VCryptResponse updateTransactionStatus(java.lang.String requestId, long transactionId, int status, boolean analyzePatterns)

  • public VCryptResponse updateTransactionStatus(java.lang.String requestId, java.util.Date requestTime, long transactionId, int status, java.util.Map[] contextMap, boolean analyzePatterns)

Table 4-6 API updateTransactionStatus Parameters

Parameter Description

requestId

The ID for the login session. The same ID is necessary for all the calls to the Oracle Adaptive Access Manager API for the login session.

requestTime

The time when this request was made. Used by simulator

contextMap

The array of contextMap. Multiple transactions can be created with a single API call. It is expected to have "transactionType" key in each context map for the creation of the appropriate transaction.

Status

The transaction status for this transaction, client specific transaction status.

transactionId

The ID of the transaction to be updated. If null, it uses the last transaction in the given session.

analyzePatterns

Boolean to indicate if the pattern analysis should be done. When passed in as true the pattern analysis is done for this transaction.


4.2.6 updateLog

API updateLog: API to update the user node log and, if required, to create the CookieSet also.

  • public CookieSet updateLog( String requestId, String remoteIPAddr, String remoteHost, String secureCookie, String digitalCookie, String groupId, String userId, String loginId, boolean isSecure, int result, int clientType, String clientVersion, int fingerPrintType, String fingerPrint, int digFingerPrintType, String digFingerPrint);

  • public CookieSet updateLog(String requestId, Date requestTime, String remoteIPAddr, String remoteHost, String secureCookie, String digitalCookie, String groupId, String userId, String loginId, boolean isSecure, int result, int clientType, String clientVersion, int fingerPrintType, String fingerPrint, int fingerPrintType2, String fingerPrint2);

Table 4-7 API updateLog Parameters

Parameter Description

requestId

The ID for the login session. The same ID is necessary for all the calls to the Oracle Adaptive Access Manager API for the login session.

remoteIPAddr

The IP from where the request came in. This is extracted from the HTTP request.

remoteHost

The host name from where the request came in. This is optional

secureCookie

The secure cookie. This is passed only if it is received from the browser

secureClientType

The secure cookie client type. This is an enum value defined to identify the client used for authentication.

secureClientVersion

The version of the secure cookie client. This is an optional parameter to specify the version of the client used

digitalCookie

The digital signature cookie. This could be the flash cookie. This parameter is sent only if it is sent by the browser

digitalClientType

The digital cookie client type. The type of flash client used. If not available, please use the value 0

digitalClientVersion

The version of the digital cookie client. The version of the flash client.

fingerPrintType

The type of finger printing. The value for defined in the properties file.

fingerPrint

The finger print. If it is browser characteristics, the header is parsed into this string. This is the name value representation of the browser header information.

digFingerPrintType

The type of the digital finger printing

digFingerPrint

The digital fingerprint

requestTime

The time when this request was made. Used by simulator

groupId

The groupId of this user. This is the primary group to which this user belongs to.

userId

The ID of the user. This is the primary key ID of the user. It should be null for users who are invalid.

loginId

The loginId used by the user for login in. This is mandatory parameter.

isSecure

Whether this node is secure and can be registered. This is to indicate the login is from a secure or registered device. If there is no concept of device, then send false value for this parameter.

result

The authentication result. This is the enumeration value of the authentication result.

clientType

This is an enum value defined to identify the client type used for authentication.

clientVersion

The version of the client. This is an optional parameter to specify the version of the client used


4.2.7 updateAuthStatus

API updateAuthStatus: API to update the User node log auth status and, if appropriate, trigger pattern data analysis.

  • public VCryptResponse updateAuthStatus(String requestId, int resultStatus, int clientType, String clientVersion);

  • public VCryptResponse updateAuthStatus(String requestId, Date requestTime, int resultStatus, int clientType, String clientVersion);

  • public VCryptResponse updateAuthStatus(java.lang.String requestId, int resultStatus, int clientType, java.lang.String clientVersion, boolean analyzePatterns)

  • public VCryptResponse updateAuthStatus(java.lang.String requestId, java.util.Date requestTime, int resultStatus, int clientType, java.lang.String clientVersion, boolean analyzePatterns)

Table 4-8 API updateAuthStatus Parameters

Parameter Description

requestId

The ID for the login session. The same ID is necessary for all the calls to the Oracle Adaptive Access Manager API for the login session.

requestTime

The time when this request was made. Used by simulator

resultStatus

The authentication result. This is the enumeration value of the authentication result

clientType

An enum value defined to identify the client type used for authentication.

clientVersion

An optional parameter to specify the version of the client used

analyzePatterns

Boolean to indicate if the pattern analysis should be done. When passed in as true the pattern analysis is done for this transaction.


upateAuthStatus API needs to be called when there is a change in the user's authentication status.

Prerequisite: Make sure to call updateLog before making changes to the authentication status.

The list of possible authentication status values are maintained on the server-side with "auth.status.enum". Make sure to match the status value with one of those values. The list of statuses can be installation-specific. You can add or remove the standard status definitions that came with the product by updating "auth.status.enum".

Scenarios:

  1. Send login status along with updateLog call

    1. updateLog API call takes status as one of the parameters, send login status with updateLog API, and avoid calling updateAuthStatus calls.

  2. Login and then update authentication status

    1. Set status to "pending" with updateLog API call

    2. Call updateAuthStatus with actual status value.

  3. Challenge flow

    1. Challenge is considered a second factor authentication. It is recommended to set the status to

      1. "Pending" before challenging

      2. After the user's response, set the status to "success" or "wrong_answer"

  4. Run rules

    1. Usually, there is no need to call update auth status after running the rules API. Run rules API internally handles known actions, "Block" and "Locked," and updates the authentication status appropriately.

4.2.8 processPatternAnalysis

API processPatternAnalysis: API to trigger the processing of data for pattern matching. This call will only trigger the processing of data for pattern matching. The last parameter transactionType can be used by authentication type user interactions, since auth (or login) are not first-class transactions.

  • public VCryptResponse processPatternAnalysis(java.lang.String requestId, long transactionId, int status, java.lang.String transactionType)

Table 4-9 processPatternAnalysis

Parameter Description

requestId

request Id

transactionId

Transaction Id to be updated.

status

New Status

transactionType

String that indicates the type of transaction. Has to be "auth" for authentication type. For other types it can be "bill_pay, ....",; basically the type name of the transaction.


4.2.9 markDeviceSafe

API markDeviceSafe: API to mark the device as safe for the user.

  • public boolean markDeviceSafe(String requestId, boolean isSafe);

Table 4-10 API markDeviceSafe Parameters

Parameter Description

requestId

The ID for the login session. The same ID is necessary for all the calls to the Oracle Adaptive Access Manager API for the login session.

isSafe

Is this device safe for the user


4.2.10 IsDeviceMarkedSafe

API IsDeviceMarkedSafe: API to verify that the device associated with this request is safe

  • public VCryptBooleanResponse IsDeviceMarkedSafe(String requestId);

Table 4-11 API IsDeviceMarkedSafe Parameters

Parameter Description

requestId

The ID for the login session. The same ID is necessary for all the calls to the Oracle Adaptive Access Manager API for the login session.


4.2.11 clearSafeDeviceList

API clearSafeDeviceList: API to clear the safe device list of the user associated with this request

  • public VCryptBooleanResponse IsDeviceMarkedSafe(String requestId);

Table 4-12 API clearSafeDeviceList Parameters

Parameter Description

requestId

The ID for the login session. The same Id is necessary for all the calls to Bharosa API for the login session.


4.3 Rules Engine

The Rules Engine component of Adaptive Risk Manager provides APIs for policy execution and enforcement.

The Rules Engine can be viewed as an enforcement component of the Adaptive Risk Manager. Based on the calling context, various policies and models configured by the administrators are evaluated and the results are provided.

4.3.1 processRules

API processRules: API to process policy sets for the given runtimes.

A Policy Set consists of policies and rules. The API processes the policy set for each runtime and returns VCryptRulesResult. There has to be at least one updateLog call before calling processRules.

  • public VCryptRulesResult processRules(String requestId, List runtimeTypes, Map contextMap);

  • public VCryptRulesResult processRules(String requestId, Date requestTime, List runtimeTypes, Map contextMap);

  • public VCryptRulesResult processRules(String requestId, Long transactionId, String extTransactionId, Date requestTime, List runtimeTypes, Map contextMap);

Table 4-13 API processRules Parameters

Parameter Description

requestId

The ID for the login session. The same ID is necessary for all the calls to the Oracle Adaptive Access Manager API for the login session.

runtimeTypes

The list of runtimes to be evaluated. Each runtime in the given list is evaluated and result is returned.

requestTime

The time when this request was made. Used by simulator

transactionId

Transaction Id, to be treated as the current transaction for this process rules call. Can be null, if no transaction Id is sent, API will check for extTransactionId, else will use the last transaction in the login session as current transaction.

extTransactionId

Handle to the external transaction id to be used as the current transaction. Optional, will use last transaction in the login session as the current transaction, if no transactionId or extTransactionId are sent.

contextMap

The data for the context. Rules in models can make decisions based on this data. Key, value pairs


4.3.1.1 Device ID Evaluation

Along with rule results, the Rules Engine component can return a Device Id. The Device Id that is returned by the Rules Engine API is an internal identifier within Adaptive Risk Manager. It is the same Id shown in Adaptive Risk Manager for the user session.

A sample algorithm to get the Device Id is shown below:

VCryptRulesResult rulesResult = new VCryptRulesEngineImpl().processRules(<params..>);
 
If (!rulesResult.getVCryptResponse().isSuccess()) {
 
     Logger.error("Error running rules " + rulesResult.getVCryptResponse().getErrorMessage());
 
}
 
Long deviceId = VCryptRulesResult#getDeviceId();
 

Troubleshooting:

  • Make sure the Adaptive Risk Manager version is 10.1.4.5 or above

  • The following property must be set to true for the Device Id to be captured.

    bharosa.tracker.send.deviceId=true
    

4.4 Customer Care

Customer Care provides APIs for limited customer care functionality, typically used in customer care portals. These APIs will not use audit feature and access control.

4.4.1 getFinalAuthStatus

API getFinalAuthStatus: API to return the final authentication status of a user given the user ID of the user. This method can only go back up to 30 days.

  • public VCryptIntResponse getFinalAuthStatus(String requestId, String userId);

Table 4-14 API getFinalAuthStatus Parameters

Parameter Description

requestId

requestId for tracking purpose

userId

Unique identifier to the user, can't be null


4.4.2 setTemporaryAllow

API setTemporaryAllow: This API call sets a temporary allow for the given user. A temporary allow can override the final rule action.

  • public VCryptResponse setTemporaryAllow(String customerId, int tempAllowType, Date expirationDate);

Table 4-15 API setTemporaryAllow Parameter

Parameter Description

customerId

Id of the customer

tempAllowType

Type of the temporary allow. The User Defined Enum for this type is customercare.case.tempallow.level.enum

expirationDate

Expiration date if the tempAllowType is "userset". Otherwise it can be null or empty.


4.4.3 cancelAllTemporaryAllows

API cancelAllTemporaryAllows: API to cancel any temporary allows associated with the customer ID.

  • public VCryptResponse cancelAllTemporaryAllows(String customerId);

Table 4-16 API cancelAllTemporaryAllows Parameters

Parameter Description

customerId

The ID of the customer


4.4.4 resetUser

API resetUser: API to reset all the profiles set for the user. This includes registration, questions, images and phrases, selected or assigned to the user

  • public VCryptResponse resetUser(String customerId);

Table 4-17 API resetUser Parameters

Parameter Description

customerId

The ID of the customer


4.4.5 getRulesData

API getRulesData: API to return all the rules executed for the given session ID, and provide basic information on what rules got triggered. It does not provide complete hierarchy information.

  • public VCryptSessionRuleData getRulesData(String requestId);

Table 4-18 API getRulesData Parameters

Parameter Description

requestId

requestId for logging and tracing with client requests in case of errors


4.4.6 getActionCount

API getActionCount: API to get the action count for the given actionEnumId and consult the configuration for the available action enums

  • public VCryptIntResponse getActionCount(String requestId, String customerId, Integer);

Table 4-19 API getActionCount Parameters

Parameter Description

requested

requestId for logging and tracing with client requests in case of errors

customerId

The unique identifier to the user, required

actionEnumId

actionEnum, required, rule.action.enum to be counted