Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Adaptive Access Manager
11g Release 1 (11.1.1)

Part Number E15480-08
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

4 Integrating Native Java Applications

This chapter explains how to integrate Java applications with Oracle Adaptive Access Manager Server using the Oracle Adaptive Access Manager Java API. This integration is supported for applications written in Java 1.4 or higher.

This section contains the following sections:

4.1 About the Oracle Adaptive Access Manager Shared Library

The Oracle Adaptive Access Manager Shared Library is the Java SDK for integrating with Oracle Adaptive Access Manager. This has to be deployed and targeted into the WebLogic Managed Server where the integrated application is deployed. Make sure the WebLogic Managed Server is part of the same WebLogic domain where OAAM is deployed.

4.1.1 Overview of the Integration Process

The high-level steps of the integration process is as follows:

  1. Create a Weblogic Web application (war) or enterprise application (ear).

  2. Add reference to OAAM SDK Shared Library (oracle.oaam.libs) to the WebLogic deployment descriptor

  3. Implement the application that calls the OAAM APIs.

  4. Add the application jars and files.

  5. Package the application, deploy it and test it.

4.1.2 Using Oracle Adaptive Access Manager Shared Library in Web Applications

Deploy the OAAM Web Applications Shared library <IAM_HOME>/oaam/oaam_libs/war/oaam_native_lib.war as a library.

To use the Oracle Adaptive Access Manager Shared Library in Web applications, you must refer to the shared library by adding the following entry to your WebLogic deployment descriptor file, weblogic.xml:

<library-ref>
       <library-name>oracle.oaam.libs</library-name>
</library-ref>

4.1.3 Using Oracle Adaptive Access Manager Shared Library in Enterprise Applications

Deploy the OAAM Enterprise Applications Shared library <IAM_HOME>/oaam/oaam_libs/ear/oaam_native_lib.ear as a library.

To use the Oracle Adaptive Access Manager Shared Library in Enterprise applications, you must refer to the shared library by adding the following entry to your WebLogic deployment descriptor file, weblogic-application.xml:

<library-ref>
       <library-name>oracle.oaam.libs</library-name>
</library-ref>

4.1.4 Customizing/Extending/Overriding Oracle Adaptive Access Manager Properties

To override any Oracle Adaptive Access Manager properties or extend Oracle Adaptive Access Manager enumerations, add those properties and enumerations to bharosa_server.properties and place that file in WEB-INF\classes folder of the native web application.

For instructions on customizing, extending, or overriding Oracle Adaptive Access Manager properties, refer to Chapter 7, "OAAM Extensions and Shared Library to Customize OAAM."

4.2 OAAM Java InProc Integration

This section contains instructions to integrate OAAM using the In-Proc method.

  1. Make sure you have set the reference to OAAM shared library "oracle.oaam.libs".

    To use the Oracle Adaptive Access Manager Shared Library in Web applications, you must refer to the shared library by adding the following entry to your WebLogic deployment descriptor file, weblogic.xml:

    <library-ref>
           <library-name>oracle.oaam.libs</library-name>
    </library-ref>
    

    To use the Oracle Adaptive Access Manager Shared Library in Enterprise applications, you must refer to the shared library by adding the following entry to your WebLogic deployment descriptor file, weblogic-application.xml:

    <library-ref>
           <library-name>oracle.oaam.libs</library-name>
    </library-ref>
    
  2. To override any Oracle Adaptive Access Manager properties or extend Oracle Adaptive Access Manager enumerations, add those properties and enumerations to bharosa_server.properties and place that file in the WEB-INF\classes folder of the native web application.

  3. Set up OAAM Data Source with the JNDI name as "jdbc/OAAM_SERVER_DB_DS" and point it to the OAAM database.

4.3 OAAM SOAP Integration

To call the OAAM APIs via SOAP instead of inproc, follow these steps in these sections.

4.3.1 Set up SOAP Security

SOAP provides a standard XML structure for sending and receiving Web service requests and responses over the Internet.

Users of SOAP services can be authenticated by supplying credentials through a secure channel. SOAP authentication is managed by Oracle Web Services Manager (OWSM) policies through Enterprise Manager.

Create a SOAP User on the WebLogic Server

The SOAP authentication is implemented using a user name and password. This user name and password must be associated with a user that is accessible to the application server. In a WebLogic deployment, this user can be stored and managed within the WebLogic security realm. You will create a SOAP user that will be used for SOAP authentication, and add that user in the proper group, OAAMSOAPServicesGroup.

OAAM clients are configured to use this user name and password when invoking web services through the following bharosa_server.properties properties:

vcrypt.soap.auth.keystorePassword - Base64 encoded Password used to open the system_soap.keystore
vcrypt.soap.auth.aliasPassword - Base64 encoded Password used to retrieve the key stored in the keystore
vcrypt.soap.auth.username - Username of the SOAP user
vcrypt.soap.auth.keystoreFile - Filename of the keystore (should be system_soap.keystore)

The parameters are explained later in this section.

Set Up Oracle Web Services Manager (OWSM) Policies

Out-of-the-box, OAAM publishes Web services at the URL: /oaam_server/services. This URL is protected with HTTP Basic authentication. The SOAP user can access this URL.

To set up the OWSM Policy to set HTTP Basic Authentication on /oaam_server/services follow these steps:

  1. Log in to Enterprise Manager using the URL http://weblogic-admin-hostname:port/em.

  2. Under weblogic_domain, select the domain and select oaam_server_server1 under that and right-click and select the Web Services option.

  3. Click the Attach Policies link in top right area.

  4. Select all the rows corresponding to OAAM Web Services and click the Next button

  5. To enable SOAP Authentication:

    1. Select the row "oracle/wss_http_token_service_policy".

  6. To disable SOAP Authentication:

    1. Select the rows oracle/no_authentication_service_policy and oracle/no_authorization_service_policy.

    2. Click the Next button.

      If you disable the SOAP Web Service authentication on the server (which is by default enabled), the client can use the web service without having been authenticated.

  7. Click the Attach button in the next page.

  8. Restart OAAM Server if required.

Client Side Keystore to Secure the SOAP User Password

Web Services/SOAP clients need to send the user name and password for successful communication with OAAM web services.

To set up security for Native Client web services:

  1. In the $ORACLE_HOME/oaam/cli directory, create a file, for example, soap_key.file, and enter the HTTP authentication user password in it. (The password from the user that was added to the OAAMSOAPServicesGroup role/group).

  2. Copy sample.config_3des_input.properties to soap_3des_input.properties.

    cp sample.config_3des_input.properties soap_3des_input.properties
    
  3. Update soap_3des_input.properties with the keystore password, the alias password, and password file.

    #This is the password for opening the keystore. 
    keystorepasswd= 
     
    #This is the password reading alias (key) in the keystore 
    keystorealiaspasswd= 
     
    #File containing from key. Please note, keys in AES could be binary. Also note algorithms like 3DES require minimum 24 characters in the key 
    #keyFile=soap_key.file 
    keyFile=
    
    keystorefilename=system_soap.keystore
    keystorealias=vcrypt.soap.call.passwd
    
  4. Set ORACLE_MW_HOME and JAVA_HOME and source setCliEnv.sh.

  5. Generate the keystore.

    • For Unix/Linux, run

      $JAVA_EXE -Djava.security.policy=conf/jmx.policy -classpath $CLSPTH com.bharosa.vcrypt.common.util.KeyStoreUtil updateOrCreateKeyStore readFromFile=soap_3des_input.properties
      
    • For Windows, run

      genkeystore.cmd soap_3des_input.properties
      

    If the KeyStore command was successful, you will see output similar to the following:

    updateOrCreateKeyStore done!
    Keystore file:system_soap.keystore,algorithm=DESede
    KeyStore Password=ZG92ZTEyMzQ=
    Alias Password=ZG92ZTEyMw==
    
  6. Note down the Keystore password and Alias Password print on the screen. You will need to add these to bharosa_server.properties.

  7. Save the system_soap.keystore file in your source code control system. Please take adequate security precaution while handling this file. The file contains critical password information. Make sure that only authorized personnel have read access to this file. If you lose it, Oracle Adaptive Access Manager will not be able to recover data encrypted.

  8. Copy your system_soap.keystore to <application>/WEB-INF/classes (classpath of the native client deployment).

  9. Delete both the soap_key.file and soap_3des_input.properties files.

  10. Add the following properties with the encoded passwords (from step 5) and the authentication user name to bharosa_server.properties.

    vcrypt.soap.auth.keystorePassword=<base64 encoded keystore password>
    vcrypt.soap.auth.aliasPassword=<based64 encoded password to the alias>
    vcrypt.soap.auth.username=<user configured for accessing the soap services>
    vcrypt.soap.auth.keystoreFile=system_soap.keystore
    

4.3.2 Set SOAP Related Properties in bharosa_server.properties

Set the following properties in bharosa_server.properties of the native application:

Specify SOAP Class

Set the vcrypt.common.util.vcryptsoap.impl.classname property.

This setting specifies for the application which libraries to use when creating SOAP messages to exchange with the OAAM services.

The available option is:

com.bharosa.vcrypt.common.impl.VCryptSOAPGenericImpl

Specify SOAP Server Side URL

Set the vcrypt.tracker.soap.url property:

vcrypt.tracker.soap.url=http://host-name:port/oaam_server/services

This setting is the location of the web services with which the application will communicate.

For example,

vcrypt.tracker.soap.url=http://localhost:14300/oaam_server/services/

Specify SOAP Call Timeout

Set the vcrypt.soap.call.timeout property in milliseconds.

For example,

vcrypt.soap.call.timeout=10000

Other Properties

vcrypt.tracker.impl.classname=
com.bharosa.vcrypt.tracker.impl.VCryptTrackerSOAPImpl
vcrypt.user.image.dirlist.property.name=bharosa.image.dirlist
bharosa.config.impl.classname=com.bharosa.common.util.BharosaConfigPropsImpl
bharosa.config.load.impl.classname=
com.bharosa.common.util.BharosaConfigLoadPropsImpl
vcrypt.tracker.soap.useSOAPServer=true
vcrypt.soap.disable=false
vcrypt.soap.auth.keystoreFile=system_soap.keystore
 
 
# Environment specific values need to be replaced below this line
bharosa.image.dirlist=absolute_folder_path_where_oaam_images_are_available
 
# If SOAP Authentication is enabled, then the following have to be set
# otherwise just set the property vcrypt.soap.auth=false 
vcrypt.soap.auth=true 
vcrypt.soap.auth.keystorePassword=Java_keystore_password
vcrypt.soap.auth.aliasPassword=Keystore_alias_password
vcrypt.soap.auth.username=SOAP_User_name

4.4 About VCryptResponse

VCryptResponse contains information about the status of the processing. It contains useful information if the status of the processing was "Success" (isSuccess). If there were an error, it also contains error codes. It can also contain other payload information in the form of extended data maps. You can use these features of VCryptResponse depending on your requirements for integration.

4.5 Oracle Adaptive Access Manager APIs

Oracle Adaptive Access Manager provides APIs to:

For descriptions of all authentication scenarios and typical flows, see Chapter 2, "Natively Integrating with Oracle Adaptive Access Manager."

4.5.1 addQuestion

addQuestion adds a new question for the specified user.

public boolean addQuestion(java.lang.String loginId, java.lang.String questionText, java.lang.String answerText)

Table 4-1 addQuestion

Parameter Description

loginId

The ID used by the user to login in

questionText

New question to be added. Overrides if the same question is already set for this user. Returns whether the operation was success or failure

answerText

Answer for the question


4.5.2 authenticatePassword

authenticatePassword authenticates the password.

public VCryptAuthResult authenticatePassword(java.lang.String loginId, java.lang.String password, int authSessionType, int clientType, java.lang.String clientVersion, java.lang.String ipAddress, int fingerPrintType, java.lang.String fingerPrint)

Returns VCryptAuthResult object

Table 4-2 authenticatePassword

Parameter Description

loginId

The ID used by the user to login in

password

New password to set

clientType

An enumeration value indicating the client type used for authentication

clientVersion

The version of the client; optional

authSessionType

Reason for authentication

ipAddress

IP address of the user device

fingerPrintType

Type of fingerprinting

fingerPrint

Fingerprint


4.5.3 authenticateQuestion

authenticateQuestion authenticates question or answer.

public VCryptAuthResult authenticateQuestion(java.lang.String loginId, java.lang.Long authSessionId, java.lang.String answer, java.lang.String ipAddress, int fingerPrintType, java.lang.String fingerPrint)

Returns VCryptAuthResult describing result of authentication attempt.

Table 4-3 authenticateQuestion

Parameter Description

loginId

The ID used by the user to authenticate answer

authSessionId

Id of the auth session

answer

The answer given by the user.

ipAddress

IP address of the user device

fingerPrintType

Type of fingerprinting

fingerPrint

Fingerprint


4.5.4 cancelAllTemporaryAllows

cancelAllTemporaryAllows cancels all temporary allows that have been set for a customer ID.

public VCryptResponse cancelAllTemporatyAllows(String customerId);

Table 4-4 cancelAllTemporaryAllows Parameters

Parameter Description

customerId

The customer ID


4.5.5 clearSafeDeviceList

clearSafeDeviceList clears the user safe device list of the user associated with a request.

public VCryptBooleanResponse clearSafeDeviceList(String requestId);

Table 4-5 clearSafeDeviceList Parameters

Parameter Description

requestId

The ID for the login session. The same ID should be used for all the calls to Bharosa API for the login session.


4.5.6 createUser

createUser creates an user in the authentication database.

public VCryptAuthUser createUser (VCryptAuthUser user) 

Table 4-6 createUser

Parameter Description

User

Auth user. Returns the newly created AuthUser.


4.5.7 createTransaction

createTransaction creates a new transaction.

public VCryptResponse createTransaction(
                  TransactionCreateRequestData transactionCreateRequestData);

Table 4-7 createTransaction Parameter and Returned Value

Parameter Description

TransactionCreateRequestData

The object to create a new transaction; it throws the exception BharosaException if it fails validation.

The structure of this object is as follows:

  • requestId identifies the user session; required

  • requestTime is the time of the request; can be null; if null, the server uses the current time

  • transactionKey is the key to the transaction definition; used to create a transaction definition; required

  • externalTransactionId is used to correlate the application transaction with the corresponding OAAM Transaction. It can also be used to update the transaction.

  • status is the transaction status; can be null. The corresponding enum name is tracker.transaction.status.enum.

  • contextMap is the map of key-value pairs. Keys of this map should exactly match the Internal ID of the related Source Data of the Transaction Definition. The value should be always a java String value. If the value is a Date value then it should be in the format yyyy-MM-dd'T'HH:mm:ss.SSSz"

VCryptResponse

The response object; make sure to check isSuccess() before obtaining the transaction ID with the method getTransactionResponse()


4.5.8 deleteQuestion

deleteQuestion deletes the question for the specified user.

public boolean deleteQuestion(java.lang.String loginId, java.lang.String question)  

Table 4-8 deleteQuestion

Parameter Description

loginId

The user login ID

question

The question to be deleted. Returns whether the operation was success or failure.


4.5.9 generateOTP

VcryptTrackerImpl::generateOTP returns OTP code based on the following properties (to determine length of code returned and characters to use in creating OTP code)

bharosa.uio.default.otp.generate.code.length

bharosa.uio.default.otp.generate.code.characters

Example code for API use is in the OAAM example application available on Oracle by Example.

(String requestId, String challengeType, String appId)

Table 4-9 generateOTP

Parameter Description

requestId

OAAM Request ID

challengeType

OAAM Challenge Type configured by the user defined enum: bharosa.uio.default.challenge.type.enum. For more information, refer to Section 11.7, "Registering SMS Processor to Perform Work for Challenge Type."

appId

An application identifier used to look up properties based on application. If no application specific properties are required, an empty string, null, or "default" can be passed.


4.5.10 getActionCount

getActionCount gets the number of actions for a given actionEnumId from the configured action enumerations.

public VCryptIntResponse getActionCount(String requestId, Sting customerId, Integer actionEnumId);

Table 4-10 getActionCount Parameters

Parameter Description

requestId

The request ID (used in logging and tracing client requests in case of error)

customerId

The customer ID

actionEnumId

An integer identifying an actionEnum; required. The corresponding enum name is rule.action.enum.


Note:

For this API to work, the corresponding action incrementCacheCounter enum property needs to be set to true.

4.5.11 getCaption

getCaption gets a caption for the user.

public java.lang.String getCaption(java.lang.String loginId)

Table 4-11 getCaption

Parameter Description

loginId

The login id of the user. Returns caption string


4.5.12 getFinalAuthStatus

getFinalAuthStatus returns the final authentication status of a user. The status can be no more than 30- day old.

public VCryptIntResponse getFinalAuthStatus(String requestId, String userId);

Table 4-12 getFinalAuthStatus Parameters

Parameter Description

requestId

The request ID (used in logging and tracing client requests in case of error)

userId

The ID uniquely identifying the user; cannot be null


4.5.13 getImage

getImage gets the imagePath for the user.

public java.lang.String getImage(java.lang.String loginId)

Table 4-13 getImage

Parameter Description

loginId

The login id of the user. Returns path to the image


4.5.14 getRulesData

getRulesData returns all rules executed for the given session ID and provides information about the rules that were triggered.

public VCryptSessionRuleData getRulesData(String requestId);

Table 4-14 getRulesData Parameters

Parameter Description

requestId

The request ID (used in logging and tracing client requests in case of error)


4.5.15 getSecretQuestion

getSecretQuestion gets a secret question for the user.

public VCryptQuestion getSecretQuestion(java.lang.String loginId) 

Table 4-15 getSecretQuestion

Parameter Description

loginId

The login id of the user to authenticate. Returns object containing the question to ask


4.5.16 getSignOnQuestions

getSignOnQuestions gets all the secret questions available for the user.

public VCryptQuestion getSignOnQuestions(java.lang.String loginId)   

Table 4-16 getSignOnQuestions

Parameter Description

loginId

The login id of the user to authenticate. Returns The 2-D array object containing the questions to ask. First dimension denotes the number of (configurable) question pick sets to display to user and the second dimension denotes the number of questions in each pick set.


4.5.17 getUserByLoginId

getUserByLoginId returns the user details without the password and pin for the given customer and group.

public VCryptAuthUser getUserByLoginId(String loginId, String groupName);

Table 4-17 getUserByLoginId

Parameter Description

loginId

The ID used by the user to login in

groupName

The group name


4.5.18 handleTrackerRequest

handleTrackerRequest captures fingerprint details and identifies the device; it may also capture fingerprint details for a given request time, which 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);

The returned object has functions to access its contents. They are:

public String getFlashCookie()
public String getSecureCookie()
public String getRequestId()
public VCryptResponse getVCryptResponse()

Table 4-18 handleTrackerRequest Parameters

Parameter Description

requestId

The login session ID; this is the ID that should be used in all API calls for the login session

remoteIPAddr

The IP from where the request came; extracted from the HTTP request

remoteHost

The host name from the machine where the request came; optional

secureCookie

The secure cookie; passed only if it is received from a browser

secureClientType

An enumeration value that identifies the type of client used for authentication. The corresponding enum name is auth.client.type.enum.

secureClientVersion

The version of the client; optional

digitalCookie

The digital signature cookie; it can be the flash cookie; it is passed only if it is sent by a browser

digitalClientType

The digital client type that specifies the type of flash client used; if not available, use the value 0

digitalClientVersion

The version of the digital client; it can be the version of the flash client

fingerPrintType

Refer to the OAAM enum vcrypt.fingerprint.type.enum for a list of valid values. Currently the enum has following values:

  • browser=1

  • flash=2

It is recommended to use 1 (for browser) as the value of fingerPrintType as this parameter corresponds to the browser fingerprint type

fingerPrint

The fingerprint; if it describes browser characteristics, then the header is parsed into this string; it represents the browser header information

fingerPrintType2

Used in case the same request has multiple fingerprints; it is defined in the properties file; optional

fingerPrint2

The second fingerprint value; optional

requestTime

The time at which the request was made


4.5.19 handleTransactionLog

handleTransactionLog captures transaction details.

Note:

Deprecated as of 10.1.4.5.1; instead, use the method createTransaction.

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

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

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

Table 4-19 handleTransactionLog Parameters

Parameter Description

requestId

The login session ID; this is the ID that should be used in all API calls for the login session

requestTime

The time at which the request was made

contextMap

An array of contextMaps; multiple transactions can be created with a single call; it expects to find a transactionType key in each context map of the array

status

The transaction status


4.5.20 IsDeviceMarkedSafe

IsDeviceMarkedSafe returns a value indicating whether the user device associated with a request is safe.

public VCryptBooleanResponse IsDeviceMarkedSafe(String requestId);

Table 4-20 IsDeviceMarkedSafe Parameters

Parameter Description

requestId

The login session ID; this is the ID that should be used in all API calls for the login session


4.5.21 markDeviceSafe

markDeviceSafe marks the user device as safe.

public boolean markDeviceSafe(String requestId, boolean isSafe);

Table 4-21 markDeviceSafe Parameters

Parameter Description

requestId

The login session ID; this is the ID that should be used in all API calls for the login session

isSafe

Indicates whether this user device is safe


4.5.22 processPatternAnalysis

processPatternAnalysis triggers the data pattern processing.

public VCryptResponse processPatternAnalysis(String requestId, 
                                             long transactionId, 
                                             int status,
                                             String transactionType);

Table 4-22 processPatternAnalysis Parameters

Parameter Description

requestId

The login session ID; this is the ID that should be used in all API calls for the login session

transactionId

The identifier of the transaction. For authentication type of data this is ignored. (It can be passed in as "null"). For pattern processing of transaction data this parameter is required.

status

A value of the user-defined enumeration auth.status.enum. If the value of the status is the value corresponding to a Success value in the enum, pattern analysis will be performed; otherwise, it will not be performed.

transactionType

Indicates the type of the transaction; must be "auth" for authentication transactions; other transaction type values, such as "bill_payment", can be customized.


4.5.23 processRules

processRules processes policy sets for the passed checkpoints.

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

processRules calls the methods related to the Rules Engine, gets an instance of the Rules Engine by calling the method VCryptTrackerUtil.getVCryptRulesEngineInstance().

Table 4-23 processRules Parameters

Parameter Description

requestId

The login session ID; this is the ID that should be used in all API calls for the login session

runtimeTypes

The list of checkpoints to be evaluated; each checkpoint in this list is evaluated. The runtimeTypes is a singleton list of Integer type. Refer to the "Information about execution of multiple checkpoints in the processRules() method" section below.

For example, to run a pre-authentication checkpoint, create the following list:

List PRE_AUTH_RUNTIME_LIST = Collections.singletonList(new Integer(1));

requestTime

The time at which the request was made

contextMap

A list of key-value pairs identifying the context data; rules in policies can make decisions based on this data


Information about execution of multiple checkpoints in the processRules() method

  1. The order of checkpoint evaluation is based on the order of those in the List. The OAAM Rules Engine iterates over the list of checkpoints and evaluates one checkpoint at a time.

  2. The result of each checkpoint evaluation is stored into ResultMap with CheckPointId as the key and VCryptRulesResult as the value.

  3. The ResultMap is then set onto VCryptRulesResult.

  4. VCryptRulesResult is returned as the result of processRules() method.

  5. If there is a failure in execution of any checkpoint, the corresponding VCryptRulesResult in ResultMap will capture that information, but the execution of other checkpoints is not impacted. However, if there is a system failure, then the result of processRules() itself will have the details of the error.

It is recommended to test the success status of result from processRules() method before the caller tries to fetch result of each checkpoint execution.

Getting Device ID

In addition to rule results, the Rules Engine can return a device ID, an internal identifier identical to the user session.

The following code sample illustrates how to get a device ID:

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

When getting a device ID, make sure that:

  • The Oracle Adaptive Access Manager version is 10.1.4.5 or above

  • The property bharosa.tracker.send.devideId is set to true, so the device ID can be captured:

    bharosa.tracker.send.deviceId=true
    

Valid Checkpoints

For list of valid checkpoints, refer to the OAAM enumeration profile.type.enum. For example profile.type.enum.preauth=1 indicates that the Pre-Authentication checkpoint is indicated using the numeric value 1.

Location and Device Data

With property bharosa.tracker.sendLocationData=true set, location (city, state, country names) and device data is returned when processRules API is called.

VCryptRulesResult rulesResult = processRules(/*params*/);
VCryptResponse response = rulesResult.getVCryptResponse();
If (response.isSuccess()) {
 
    String ipAddress = response.getExtendedMap(VCryptResponse.DATA_REMOTE_IP_ADDRESS) ;
    String deviceId= response.getExtendedMap(VCryptResponse.DATA_DEVICE_ID) ;
 
    // if interested in city, state, country
    String city = response.getExtendedMap(VCryptResponse.DATA_CITY_NAME) ;
    String state = response.getExtendedMap(VCryptResponse.DATA_STATE_NAME ;
    String country = response.getExtendedMap(VCryptResponse.DATA_COUNTRY_NAME) ;
}

4.5.24 setCaption

setCaption sets a new caption for the specified user.

public boolean setCaption(java.lang.String loginId, java.lang.String caption)

Table 4-24 setCaption

Parameter Description

loginId

The login id of the user.

caption

New caption to set. Returns whether the operation was success or failure


4.5.25 setImage

setImage sets a new image for the user.

public boolean setImage(java.lang.String loginId, java.lang.String imagePath)

Returns whether the operation was success or failure

Table 4-25 setImage

Parameter Description

loginId

The login id of the user.

imagePath

Path to the image file.


4.5.26 setPassword

setPassword sets a new password for the specified user.

public boolean setPassword(java.lang.String loginId, java.lang.String password, int passwordStatus)

Returns whether the operation was success or failure

Table 4-26 setPassword

Parameter Description

loginId

The login id of the user.

password

New password to set

passwordStatus

Status of the Password


4.5.27 setTemporaryAllow

setTemporaryAllow sets a temporary allow for a user. A temporary allow can override the final rule action.

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

Table 4-27 setTemporaryAllow Parameters

Parameter Description

customerId

The customer ID

tempAllowType

The type of the temporary allow; the user-defined enumeration for this type is customercare.case.tempallow.level.enum

expirationDate

The expiration date, if the tempAllowType is "userset"; otherwise null or empty


4.5.28 resetUser

resetUser resets all the profiles that have been set for a customer, including registration, questions, images, and phrases.

public VCryptResponse resetUser(String customerId);

Table 4-28 resetUser Parameters

Parameter Description

customerId

The customer ID


4.5.29 updateAuthStatus

updateAuthStatus updates the user authentication status and, if appropriate, it triggers pattern data processing. This method must be called when there is a change in the user authentication status; make sure that, before calling updateAuthStatus, the application calls updateLog.

The list of authentication status values are specified in the user-defined enumeration auth.status.enum; you can add or remove items to this enumeration, as appropriate to your application, but only values of this enumeration can be used to identify an authentication status.

The following scenarios describe alternative ways to handle updating a user login (authentication) status:

  • Pass the login status in the updateLog call; this scenario avoids calling updateAuthStatus altogether.

  • Allow the user to log in before setting the login status; in this scenario, first pass status pending in the updateLog call, then process the login data, and then pass the appropriate status in the updateAuthStatus call.

  • If your application flow includes challenging the user, then first set the status to pending, then pose the challenge questions, and then, depending on the answers, reset the status to success or wrong_answer.

  • Typically, there is no need to call updateAuthStatus after invoking the rules engine, since this engine includes setting the authentication status as part of running the rules.

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(String requestID, 
                                       int resultStatus, 
                                       int clientType,
                                       String clientVersion,
                                       boolean analyzePatterns);
public VCryptResponse updateAuthStatus(String requestID, 
                                       Date requestTime,
                                       int resultStatus, 
                                       int clientType,
                                       String clientVersion
                                       boolean analyzePatterns);

Table 4-29 updateAuthStatus Parameters

Parameter Description

requestId

The login session ID; this is the ID that should be used in all API calls for the login session

requestTime

The time at which the request was made

resultStatus

A value of the user-defined enumeration auth.status.enum

clientType

An enumeration value indicating the client type used for authentication

clientVersion

The version of the client; optional

analyzePatterns

Boolean to indicate if pattern processing should be performed. When the value is passed in as "true," the pattern processing is performed for the transaction if the "resultStatus" value is "success."


4.5.30 updateLog

updateLog updates the user log and, if required, creates a CookieSet.

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-30 updateLog Parameters

Parameter Description

requestId

The login session ID; this is the ID that should be used in all API calls for the login session

remoteIPAddr

The IP from where the request came; extracted from the HTTP request

remoteHost

The host name from where the request came; optional

secureCookie

The secure cookie; passed only if it is received from a browser

digitalCookie

The digital signature cookie; can be the flash cookie; passed only if it is sent by a browser

groupId

The ID of the group this user belongs to

userId

The user ID; this is the primary ID key for the user; for invalid users, it is null

loginId

The ID used by the user to login in; required

isSecure

A Boolean indicating whether this node is secure and can be registered; it also indicates that the login is from a secure or registered device; if there is no concept of device, then set to false

result

A value of the user-defined enumeration auth.status.enum

clientType

An enumeration value indicating the client type used for authentication. The corresponding enum name is auth.client.type.enum.

clientVersion

The version of the client; optional

fingerPrintType

Refer to the OAAM enum vcrypt.fingerprint.type.enum for a list of valid values. Currently the enum has following values:

  • browser=1

  • flash=2

It is recommended to use 1 (for browser) as the value of fingerPrintType as this parameter corresponds to browser fingerprint type.

fingerPrint

The fingerprint; if it describes browser characteristics, then the header is parsed into this string; it represents the browser header information

digFingerPrintType

Refer to the OAAM enum vcrypt.fingerprint.type.enum for list of valid values. Currently the enum has following values:

  • browser=1

  • flash=2

It is recommended to use 2 (for flash) as the value of digFingerPrintType, as this parameter corresponds to flash fingerprint type.

digFingerPrint

The digital fingerprint

requestTime

The time at which the request was made

fingerPrintType2

Used in case the same request has multiple fingerprints; defined in the properties file; optional

fingerPrint2

The second fingerprint value; optional


4.5.31 updateTransaction

updateTransaction updates a previously created transaction.

public VCryptResponse updateTransaction(
                    Transaction UpdateRequestData transactionUpdateRequest Data);

Table 4-31 updateTransaction Parameter and Returned Value

Parameter Description

TransactionUpdateRequestData

The object to update a transaction; a handle to the transaction to be updated is either the transaction ID returned by the method createTransaction, or the external transaction ID passed to the method createTransaction. it throws the exception BharosaException if it fails validation.

The structure of this object is as follows:

  • requestId, identifies the user session; required

  • requestTime, the time of the request; can be null; if null, the server uses the current time

  • transactionId ID, the ID returned by a previous call to createTransaction

  • status, the transaction status

  • analyzePatterns, Boolean to indicate if pattern processing should be performed. When the value is passed in as "true," the pattern processing is performed for the transaction if the "resultStatus" value is "success."

  • externalTransactionId is used to correlate the application transaction with the corresponding OAAM Transaction. It can also be used to update the transaction.

  • contextMap is a map of key-value pairs. Keys of this map should exactly match the "Internal ID" of the related "Source Data" of the Transaction Definition. The value should be always a java String value. If the value is a Date value then it should be in the format "yyyy-MM-dd'T'HH:mm:ss.SSSz".

VCryptResponse

The response object; make sure to check isSuccess() before obtaining the transaction ID with the method getTransactionResponse()


4.5.32 updateTransactionStatus

updateTransactionStatus updates a transaction status and, if appropriate, triggers the data pattern processing.

Note:

Deprecated as of 10.1.4.5.1; instead, use the method updateTransaction.

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(String requestId, long transactionId, int status, boolean analyzePatterns);

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

Table 4-32 updateTransactionStatus Parameters

Parameter Description

requestId

The login session ID; this is the ID that should be used in all API calls for the login session

requestTime

The time at which the request was made

contextMap

An array of contextMaps; multiple transactions can be created with a single call; it expects to find a transactionType key in each context map of the array

Status

The transaction status

transactionId

The ID of the transaction with status to update; if null, it uses the last transaction in the given session

analyzePatterns

Boolean to indicate if pattern processing should be performed. When the value is passed in as "true," the pattern processing is performed for the transaction if the "resultStatus" value is "success."