4 Natively Integrating OAAM with 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 chapter 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 an Oracle WebLogic Server instance where the integrated application is deployed. Make sure the Oracle WebLogic Server instance is part of the same WebLogic Server 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 the 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 JAR files and other 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 oaam_custom.properties and place that file in the WEB-INF\classes directory of the native Web application.

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

4.2 OAAM Java In-Proc 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 oaam_custom.properties and place that file in the WEB-INF\classes directory 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

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. Oracle Web Services Manager (OWSM) policies manage SOAP authentication through Oracle Enterprise Manager Fusion Middleware Control.

4.3.1 Set Up SOAP Security

To use SOAP authentication (call the OAAM APIs through SOAP instead of in-proc), follow the steps in the subsequent sections.

Create a SOAP User on the Oracle 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 oaam_custom.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 Oracle Web Services Manager (OWSM) Policy to set HTTP Basic Authentication on /oaam_server/services follow these steps:

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

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

  3. Click Attach Policies.

  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. Write down the Keystore password and Alias Password printed on the screen. You will need to add these to oaam_custom.properties.

  7. Save the system_soap.keystore file in your source code control system. Ensure you take adequate security precaution while handling this file. The file contains critical password information. Ensure 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 that is 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 oaam_custom.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 oaam_custom.properties

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

vcrypt.common.util.vcryptsoap.impl.classname=
com.bharosa.vcrypt.common.impl.VCryptSOAPGenericImpl
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
vcrypt.tracker.soap.url=http://<host-name>:<port>/oaam_server/services
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:

  • Collect and track information from the client application

  • Capture user login information, user login status, and various attributes of the user session to determine device and location information

  • Collect transaction details

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

Note:

isElementInList(), getListElements() and updateList() APIs do not support update/actions on the "alert group" lists.

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 authentication 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 is necessary for all the calls to Bharosa API for the login session.


4.5.6 createOAAMSession

A Session ID is required for the creation and update of transactions. If a Session ID is not available, you must call the createOAAMSession API to create the OAAM session. After obtaining the Session ID from the session, you can call the CreateTransaction API to create a transaction.

When you create a session, you specify values in the createOAAMSession request and then call the API.

createOAAMSession(String requestId, Date requestTime, OAAMUserData user,
OAAMIPData ip, 
List<OAAMDeviceFingerprintData> cookieList, OAAMSessionData sessionData)

Table 4-6 createOAAMSession Parameters

Parameter Description

requestId

requestId identifies the user session; required

requestTime

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

user

User is the OAAM user

ip

The user session's IP address

cookieList

List of cookies stored in the session

sessionData

Data from the session


4.5.7 createOrUpdateEntities

You can use the createOrUpdateEntities API to perform the following tasks:

  • Create and update entities

  • Replace and merge attribute values during an entity update

public VCryptObjectResponse<VCryptObjectResponse<EntityHeader>[]>
createOrUpdateEntities(EntityData[] entityRequestData,boolean isReplaceEntity, int
commitBatchSize, String requestId);

Table 4-7 Create or Update Entities API

Parameter Description

entityRequestData

Array of EntityData objects. An EntityData object contains the information required to create one entity. For details on EntityData.java, see the Oracle Fusion Middleware Java API Reference for Oracle Adaptive Access Manager.

isReplaceEntity

Flag to determine replacement or merging of attributes on update of entity. Default value: FALSE which denotes merge.

commitBatchSize

Determines the number of entities which must be committed together. Default and minimum value is 1

requestId

Value to identify the session. The value is sent by the client. If the client does not set this value then OAAM generates a dummy number

VCryptObjectResponse:

SUCCESS on successful execution of API (there is no database or connection error) and at least one entity is created

response.getObject() returns Array object containing VCryptObjectResponse for individual entities. Each response object contains an EntityHeader object on SUCCESS. Query for response.isSuccess(). (true for SUCCESS and false for ERROR).

ERROR if no entity is created.

response.getObject() returns object containing VCryptObjectResponse. Each response object contains error message on ERROR.


4.5.8 createTransaction

A Session ID is required for the creation of transactions. If a Session ID is not available, you must call the createOAAMSession API to create the OAAM session. After obtaining the Session ID from the session, you can call the createTransaction API to create the transaction.

createTransaction creates a new transaction.

public VCryptResponse createTransaction(
TransactionCreateRequestData trxUpdData =
                new TransactionCreateRequestData(sessionId,
                                                 requestTime,
                                                 transactionDefKey,
                                                 externalTransactionId,
                                                 trxStatus, trxDataMap, 
                                                 analyzePatterns);
                response =
                    VCryptTrackerUtil.getVCryptTrackerInstance().createTransaction(trxUpdData);
 
 
        
            TransactionResponse transResponse = response.getTransactionResponse();
                Long transId = null;
                if (transResponse != null){
                    transId = transResponse.getTransactionId();
                }

Table 4-8 createTransaction Parameter and Returned Value

Parameter Description

TransactionCreateRequestData

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

The structure of this object is as follows:

  • sessionID identifies the user session; required

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

  • transactionDefKey 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.

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

  • trxDataMap 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

  • 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."

VCryptResponse

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


4.5.9 createUser

createUser creates an user in the authentication database.

public VCryptAuthUser createUser (VCryptAuthUser user) 

Table 4-9 createUser

Parameter Description

User

Authenticated user. Returns the newly created authenticated user.


4.5.10 deleteQuestion

deleteQuestion deletes the question for the specified user.

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

Table 4-10 deleteQuestion

Parameter Description

loginId

The user login ID

question

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


4.5.11 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-11 generateOTP

Parameter Description

requestId

OAAM Request ID

challengeType

OAAM Challenge Type configured by the user defined enum: bharosa.uio.default.challenge.type.enum. For information on configuring challenge type, see Section 16.7, "Register 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.12 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-12 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 property must be set to true.

4.5.13 getCaption

getCaption gets a caption for the user.

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

Table 4-13 getCaption

Parameter Description

loginId

The login id of the user. Returns caption string


4.5.14 getFinalAuthStatus

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

public VCryptIntResponse getFinalAuthStatus(String requestId, String userId);

Table 4-14 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.15 getImage

getImage gets the imagePath for the user.

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

Table 4-15 getImage

Parameter Description

loginId

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


4.5.16 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-16 getRulesData Parameters

Parameter Description

requestId

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


4.5.17 getSecretQuestion

getSecretQuestion gets a secret question for the user.

public VCryptQuestion getSecretQuestion(java.lang.String loginId) 

Table 4-17 getSecretQuestion

Parameter Description

loginId

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


4.5.18 getSignOnQuestions

getSignOnQuestions gets all the secret questions available for the user.

public VCryptQuestion getSignOnQuestions(java.lang.String loginId)   

Table 4-18 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 sets to display to user and the second dimension denotes the number of questions in each question set.


4.5.19 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-19 getUserByLoginId

Parameter Description

loginId

The ID used by the user to login in

groupName

The group name


4.5.20 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-20 handleTrackerRequest Parameters

Parameter Description

requestId

The login session ID; this is the ID that is necessary 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 the 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.21 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-21 handleTransactionLog Parameters

Parameter Description

requestId

The login session ID; this is the ID that is necessary 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.22 IsDeviceMarkedSafe

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

public VCryptBooleanResponse IsDeviceMarkedSafe(String requestId);

Table 4-22 IsDeviceMarkedSafe Parameters

Parameter Description

requestId

The login session ID; this is the ID that is necessary in all API calls for the login session


4.5.23 markDeviceSafe

markDeviceSafe marks the user device as safe.

public boolean markDeviceSafe(String requestId, boolean isSafe);

Table 4-23 markDeviceSafe Parameters

Parameter Description

requestId

The login session ID; this is the ID that is necessary in all API calls for the login session

isSafe

Indicates whether this user device is safe


4.5.24 processPatternAnalysis

processPatternAnalysis triggers the data pattern processing.

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

Table 4-24 processPatternAnalysis Parameters

Parameter Description

requestId

The login session ID; this is the ID that is necessary in all API calls for the login session

transactionId

The identifier of the transaction. For authentication type of data can pass 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.25 processRules

The Rules Engine is the part of the OAAM that enforces policies at checkpoint. OAAM includes APIs to evaluate policies that return results depending on the calling context.

A Session ID is required for the creation of transactions. If a Session ID is not available, you must call the createOAAMSession API to create the OAAM session. The Session ID is necessary in all API calls for the login session.

processRules processes policy sets for the passed checkpoints.

          VCryptRulesResult ruleResult =
            VCryptTrackerUtil.getVCryptRulesEngineInstance().processRules(
                                           sessionId,
                                           transId, 
                                           externalTransactionId, 
                                           requestTime,
                                           runtimeList,
                                           contextDataMap);

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

Table 4-25 processRules Parameters

Parameter Description

sessionId

The login session ID; this is the ID that is necessary in all API calls for the login session

transId

The transaction session ID; this is the ID that is necessary in all API calls for the transaction session

externalTransactionId

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

requestTime

The time at which the request was made

runtimeTypes

The list of checkpoints to be evaluated; each checkpoint in this list is evaluated. The runtimeTypes is a singleton list of Integer type.

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

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

contextDataMap

A list of key-value pairs identifying the context data. The contextDataMap in this API is to provide any additional parameters that are needed for rules processing. For example, to verify if the IP has changed during the session, then you can provide the IP in the contextDataMap of the Process Rules API and OAAM can compare the new IP against the original IP that was used during create/update transaction.


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, ensure 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.26 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-26 resetUser Parameters

Parameter Description

customerId

The customer ID


4.5.27 searchEntityByKey

You can use the searchEntityByKey API to find entities based on its key attributes.

public VCryptObjectResponse<EntityHeader> 
   searchEntityByKey(EntityData entityData);

Table 4-27 searchEntityByKey

Parameter Description

entityData

EntityData object with entityName and entityDataMap containing key(s) and value(s) of primary key attributes of the entity to be searched based on the ID scheme

VCryptObjectResponse

Contains EntityHeader object which is the entity object on SUCCESS or error message on ERROR


4.5.28 setCaption

setCaption sets a new caption for the specified user.

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

Table 4-28 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.29 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-29 setImage

Parameter Description

loginId

The login ID of the user

imagePath

Path to the image file.


4.5.30 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-30 setPassword

Parameter Description

loginId

The login ID of the user

password

New password to set

passwordStatus

Status of the password


4.5.31 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-31 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.32 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; ensure 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 you can only use the values of this enumeration 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-32 updateAuthStatus Parameters

Parameter Description

requestId

The login session ID; this is the ID that is necessary 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.33 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-33 updateLog Parameters

Parameter Description

requestId

The login session ID; this is the ID that is necessary 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 the 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 the 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.34 updateTransaction

Both Session ID and Transaction ID are required to update transactions. If a Session ID is not available, you must call the createOAAMSession API to create the OAAM session. The Session ID is required by the createTransaction API. You must call the createTransaction API to create a Transaction ID before you can call the updateTransaction API to update the transaction.

updateTransaction updates a previously created transaction.

      TransactionUpdateRequestData trxUpdData =
new TransactionUpdateRequestData(sessionId,
 requestTime,
 transactionId,
 new Integer(trxStatus),
 trxDataMap,
 Boolean.TRUE);
    response =
    VCryptTrackerUtil.getVCryptTrackerInstance().updateTransaction(trxUpdData);
    

Table 4-34 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 causes the exception BharosaException if it fails validation.

The structure of this object is as follows:

  • sessionId identifies the user session; required

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

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

  • trxStatus, the status of the transaction. The possible values are as follows:

    • success=1

    • block=2

    • reject=3

    • wrong_answer=4

    • pending=99

  • trxDataMap 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.

VCryptTrackerInstance

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


4.5.35 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-35 updateTransactionStatus Parameters

Parameter Description

requestId

The login session ID; this is the ID that is necessary 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."