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:

About the Oracle Adaptive Access Manager Shared Library
About VCryptResponse
Oracle Adaptive Access Manager APIs
Rules Engine
Customer Care

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 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.2 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.3 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, "Customizing Oracle Adaptive Access Manager."

4.2 OAAM Java InProc Integration

Follow these steps:

Make sure you have set the reference to OAAM shared library "oracle.oaam.libs".
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.
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

Setup SOAP User on WebLogic Server and OWSM Policy

Out-of-the-box, OAAM publishes Web services at the URL: /oaam_server/services. This URL is protected with HTTP Basic authentication.

Create a user that will be used for SOAP authentication, and add that user in the proper group. This user can access this URL. The user must be in the OAAMSOAPServicesGroup group.

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

Log in to Enterprise Manager using the URL http://weblogic-admin-hostname:port/em.
Under weblogic_domain, select the domain and select oaam_server_server1 under that and right click and select the 'Web Services' option.
Click the "Attach Policies" link in top right area.
Select all the rows corresponding to OAAM Web Services and click the Next button
To enable SOAP Authentication:
1. Select the row "oracle/wss_http_token_service_policy".
To disable SOAP Authentication:
1. Select the rows "oracle/binding_authorization_permitall_policy", "oracle/no_authentication_service_policy", "oracle/no_authorization_service_policy" and click the Next button
Click the Attach button in the next page.
Restart OAAM Server if required.

Client Side Keystore to secure the SOAP User password

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

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).
Copy sample.soap_3des_input.properties to soap_3des_input.properties.

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=

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==

Note down the Keystore password and Alias Password print on the screen. You will need to add these to bharosa_server.properties.
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.
Copy your system_soap.keystore to the following directories:
- <application>/WEB-INF/classes/bharosa_properties (classpath of the native client deployment)
- <OAAM application>/bharosa_properties
Delete both the soap_key.file and soap_3des_input.properties files.

Add the following properties with the encoded passwords (from step 5) and the authentication username 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:

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 with Oracle Adaptive Access Manager."

The following sections provide details of the following important methods:

handleTrackerRequest
createTransaction
updateTransaction
handleTransactionLog
updateTransactionStatus
updateLog
updateAuthStatus
processPatternAnalysis
markDeviceSafe
IsDeviceMarkedSafe
clearSafeDeviceList

4.5.1 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-1 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.2 createTransaction

createTransaction creates a new transaction.

public VCryptResponse createTransaction(
                  TransactionCreateRequestData transactionCreateRequestData);

Table 4-2 createTransaction Parameter and Returned Value

Parameter Description

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()`

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.3 updateTransaction

updateTransaction updates a previously created transaction.

public VCryptResponse updateTransaction(
                    Transaction UpdateRequestData transactionUpdateRequest Data);

Table 4-3 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()

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.4 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-4 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.5 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-5 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."

4.5.6 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-6 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 `digFingerPrintTyp`e, 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.7 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-7 getUserByLoginId

Parameter	Description
loginId	The ID used by the user to login in
groupName	The group name

4.5.8 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-8 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.9 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-9 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.10 processPatternAnalysis

processPatternAnalysis triggers the data pattern processing.

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

Table 4-10 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.11 markDeviceSafe

markDeviceSafe marks the user device as safe.

public boolean markDeviceSafe(String requestId, boolean isSafe);

Table 4-11 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.12 IsDeviceMarkedSafe

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

public VCryptBooleanResponse IsDeviceMarkedSafe(String requestId);

Table 4-12 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.13 clearSafeDeviceList

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

public VCryptBooleanResponse clearSafeDeviceList(String requestId);

Table 4-13 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.6 Rules Engine

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.

The following section provides details of the method processRules and on how to get the device ID.

4.6.1 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-14 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

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.
The result of each checkpoint evaluation is stored into ResultMap with CheckPointId as the key and VCryptRulesResult as the value.
The ResultMap is then set onto VCryptRulesResult.
VCryptRulesResult is returned as the result of processRules() method.
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.7 Customer Care

Customer Care provides APIs typically used in customer care portals; these APIs do not use audit or access control.

The following sections provide details of the following important methods of this interface:

getFinalAuthStatus
setTemporaryAllow
cancelAllTemporaryAllows
resetUser
getRulesData
getActionCount

4.7.1 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-15 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.7.2 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-16 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.7.3 cancelAllTemporaryAllows

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

public VCryptResponse cancelAllTemporatyAllows(String customerId);

Table 4-17 cancelAllTemporaryAllows Parameters

Parameter	Description
customerId	The customer ID

4.7.4 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-18 resetUser Parameters

Parameter	Description
customerId	The customer ID

4.7.5 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-19 getRulesData Parameters

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

4.7.6 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-20 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.