You can 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:
The most recent OAAM Sample Application that illustrates Java API integration can be downloaded from My Oracle Support document ID 1351899.1.
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.
The high-level steps of the integration process is as follows:
Create a WebLogic Web application (WAR
) or enterprise application (ear
).
Add reference to the OAAM SDK Shared Library (oracle.oaam.libs
) to the WebLogic deployment descriptor.
Implement the application that calls the OAAM APIs.
Add the application JAR files and other files.
Package the application, deploy it and test it.
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>
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>
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."
This section contains instructions to integrate OAAM using the In-Proc method.
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>
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.
Set up OAAM Data Source with the JNDI name as jdbc/OAAM_SERVER_DB_DS
and point it to the OAAM database.
This section contains instructions to integrate OAAM using the SOAP method. In the SOAP service wrapper API integration, the application communicates with Oracle Adaptive Access Manager using Web services.
Out-of-the-box, OAAM publishes Web services at the URL: /oaam_server/services
. Starting with OAAM 11g Release 2 (11.1.2.0.0), the default mechanism to secure OAAM Web Services is by using Oracle Web Services Manager (OWSM) policies. Configuration of OWSM policies for authentication (HTTP Basic authentication with username and password request) and authorization (user's membership in configured group of users) is covered in this section. Authentication checks whether the passed user credentials are correct and authorization checks whether user is allowed to access the requested resource based on the user's membership in a group, for example, the user/group in the WebLogic embedded user store. Oracle Web Services Manager (OWSM) policies manage SOAP authentication and authorization through Oracle Enterprise Manager Fusion Middleware Control.
OAAM Web Services can be protected by Oracle Web Services Manager (OWSM) using the policy oracle/wss_http_token_service_policy
. The wss_http_token_service_policy
policy enforces authentication and uses the credentials in the HTTP header to authenticate users. SOAP requests would be authenticated (HTTP Basic authentication) against the configured realm (users in WebLogic embedded user store).
To set up the Oracle Web Services Manager (OWSM) Policy to set HTTP Basic Authentication on /oaam_server/services
follow these steps:
Log in to Oracle Enterprise Manager Fusion Middleware Control using the URL http://weblogic-admin-hostname:port/em
.
Under weblogic_domain, select the domain and select oaam_server_server1 and right-click and select the Web Services option.
Click Attach Policies.
Select all the rows corresponding to OAAM Web Services and click the Next button
To enable SOAP Authentication:
Select the row oracle/wss_http_token_service_policy.
To disable SOAP Authentication:
Select the rows oracle/no_authentication_service_policy and oracle/no_authorization_service_policy.
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.
Click the Attach button in the next page.
Restart OAAM Server if required.
By performing the authentication configuration in this section, OAAM Web Services can be accessed by any valid username/password present in a configured realm, for example, all the user credentials which can pass authentication, can access OAAM Web Services.
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 order for that user to have permissions to perform operations on the web services, the user should be added to a group that can access the OAAM web services.
To secure web services, you must create a user with valid credentials who belongs to a group that can access URL: /oaam_server/services
.
In a WebLogic deployment, this SOAP user can be stored and managed within the WebLogic security realm.
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)
To create the user and group, proceed as follows:
Using the WebLogic console, create a group in configured realm. For example, OAAM_WebServices_Group
.
Create a user and associate the user with the group created in Step 1.
Update the user for group membership.
Using the Oracle Web Services Manager (OWSM) policy oracle/binding_authorization_permitall_policy
, authorization can be configured for OAAM Web Services. The binding_authorization_permitall_policy
policy provides simple permission-based authorization for the request based on the authenticated user at the SOAP binding level. This policy ensures that the user has permission to perform an operation. This policy should follow an authentication policy where the user is established and can be attached to Web Service Endpoints.
Log in to Oracle Enterprise Manager Fusion Middleware Control using the URL
http://weblogic-admin-hostname:port/em
Expand the WebLogic Domain.
Right-click the domain hosting OAAM Server, Web Services, and Policies.
Select oracle/binding_authorization_permitall_policy.
Click Edit, and then the Settings tab.
Select Selected Roles from Authorization Setting.
Click Add (plus sign) and move the group to Roles Selected To Add list, and then click OK. The group was created in Section 4.3.2, "Creating User and Group."
Click Save to save the policy.
To make sure that above policy configuration is working as expected, set property active.protocol
to remote
. The value for the property can be checked by navigating to domain hosting OAAM Server, right clicking Web Services, Platform Policy Configuration, and Policy Accessor Properties.
Attach the authorization policy to the Web Service Endpoints.
Note: To get list of Web Service Endpoints exposed by OAAM Server on Enterprise Manager, go to Fusion Middleware Control, Identity and Access. Expand OAAM, then oaam_server, and right-click Web Services.
Log in to Oracle Enterprise Manager Fusion Middleware Control using the URL
http://weblogic-admin-hostname:port/em
Under weblogic_domain, select the domain and select oaam_server_server1 and right-click and select the Web Services option.
Click Attach Policies.
Select all the rows corresponding to OAAM Web Services and click the Next button
Select the row oracle/binding_authorization_permitall_policy.
Click the Next button.
Click the Attach button in the next page.
Restart OAAM Server if required.
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:
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 OAAM Web Services Group role/group).
Copy sample.config_3des_input.properties
to soap_3des_input.properties
.
cp sample.config_3des_input.properties 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. For example, #Welcome1 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
Set ORACLE_MW_HOME
and JAVA_HOME
and source setCliEnv.sh
.
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==
Write down the Keystore password and Alias Password printed on the screen. You will need to add these to oaam_custom.properties
.
Add the following properties with the encoded passwords (from step 5) and the authentication user name to oaam_custom.properties
.
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 keystore password used to open the system_soap.keystore vcrypt.soap.auth.aliasPassword - Base64 encoded password to the alias used to retrieve the key stored in the keystore vcrypt.soap.auth.username - Username of the SOAP user configured for accessing the SOAP services vcrypt.soap.auth.keystoreFile - Filename of the keystore (should be system_soap.keystore)
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.
Copy your system_soap.keystore
to application
/WEB-INF/classes
(classpath of the native client deployment).
Delete both the soap_key.file
and soap_3des_input.properties
files.
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
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.
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.addQuestion adds a new question for the specified user.
public boolean addQuestion(java.lang.String loginId, java.lang.String questionText, java.lang.String answerText)
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 |
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.
cancelAllTemporaryAllows
cancels all temporary allows that have been set for a customer ID.
public VCryptResponse cancelAllTemporatyAllows(String customerId);
clearSafeDeviceList
clears the user safe device list of the user associated with a request.
public VCryptBooleanResponse clearSafeDeviceList(String requestId);
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; If requestId is not supplied, OAAM server will create one; however, if requestId is supplied and then if the OAAM server cannot find one, then an error is returned. |
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 |
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: |
commitBatchSize |
Determines the number of entities which must be committed together. Default and minimum value is |
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: |
|
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 The structure of this object is as follows:
|
VCryptResponse |
The response object; make sure to check |
createUser
creates an user in the authentication database.
public VCryptAuthUser createUser (VCryptAuthUser user)
deleteQuestion
deletes the question for the specified user.
public boolean deleteQuestion(java.lang.String loginId, java.lang.String question)
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-11 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 |
Note:
For this API to work, the corresponding actionincrementCacheCounter
property must be set to true
.getCaption
gets a caption for the user.
public java.lang.String getCaption(java.lang.String loginId)
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);
getImage
gets the imagePath
for the user.
public java.lang.String getImage(java.lang.String loginId)
The generateOTP() API has been deprecated in the OAAM JAVA and SOAP APIs. Please use the getOTPCode() API instead when writing your production code. For details on how to use the getOTPCode() API, see the Oracle Fusion Middleware Java API Reference for Oracle Adaptive Access Manager.
getRulesData
returns all rules executed for the given Session ID and provides information about the rules that were triggered.
public VCryptSessionRuleData getRulesData(String requestId);
getSecretQuestion
gets a secret question for the user.
public VCryptQuestion getSecretQuestion(java.lang.String loginId)
getSignOnQuestions
gets all the secret questions available for the user.
public VCryptQuestion getSignOnQuestions(java.lang.String loginId)
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. |
getUserByLoginId
returns the user details without the password and PIN for the given customer and group.
public VCryptAuthUser getUserByLoginId(String loginId, String groupName);
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-19 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 |
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
It is recommended to use |
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 |
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-20 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 |
status |
The transaction status |
IsDeviceMarkedSafe
returns a value indicating whether the user device associated with a request is safe.
public VCryptBooleanResponse IsDeviceMarkedSafe(String requestId);
markDeviceSafe
marks the user device as safe.
public boolean markDeviceSafe(String requestId, boolean isSafe);
processPatternAnalysis
triggers the data pattern processing.
public VCryptResponse processPatternAnalysis(String requestId, long transactionId, int status, String transactionType);
Table 4-23 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 |
status |
A value of the user-defined enumeration |
transactionType |
Indicates the type of the transaction; must be |
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.
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-24 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 |
|
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:
|
contextDataMap |
A list of key-value pairs identifying the context data. The |
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.
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
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
.
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) ; }
resetUser
resets all the profiles that have been set for a customer, including registration, questions, images, and phrases.
public VCryptResponse resetUser(String customerId);
You can use the searchEntityByKey
API to find entities based on its key attributes.
public VCryptObjectResponse<EntityHeader> searchEntityByKey(EntityData entityData);
Parameter | Description |
---|---|
entityData |
EntityData object with |
VCryptObjectResponse |
Contains EntityHeader object which is the entity object on |
setCaption
sets a new caption for the specified user.
public boolean setCaption(java.lang.String loginId, java.lang.String caption)
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
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
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-30 setTemporaryAllow Parameters
Parameter | Description |
---|---|
customerId |
The customer ID |
tempAllowType |
The type of the temporary allow; the user-defined enumeration for this type is c |
expirationDate |
The expiration date, if the |
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-31 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 |
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 |
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-32 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 |
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
It is recommended to use |
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
It is recommended to use |
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 |
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-33 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 The structure of this object is as follows:
|
VCryptTrackerInstance |
The response object; make sure to check |
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-34 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 |
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." |