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:
The Oracle Adaptive Access Manager Shared Library is the Java SDK for integrating with Oracle Adaptive Access Manager. This is deployed in OAAM Server when you install the Oracle Adaptive Access Manager 11g applications. In OAAM Server contains this shared library, oracle.oaam.libs.
To use the Oracle Adaptive Access Manager Shared Library, 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 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 or WEB-INF\classes\bharosa_properties file of the application.
For instructions on customizing, extending, or overriding Oracle Adaptive Access Manager properties, refer to Chapter 12, "Customizing Oracle Adaptive Access Manager."
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 with Oracle Adaptive Access Manager."
The following sections provide details of the following important methods:
Captures fingerprint details and identify 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 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 |
|
secureClientVersion |
The version of the client; optional |
|
digitalCookie |
The digital signature cookie; can be the flash cookie; 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; can be the version of the flash client |
|
fingerPrintType |
The type of fingerprinting; defined in the properties file |
|
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; defined in the properties file; optional |
|
fingerPrint2 |
The second fingerprint value; optional |
|
requestTime |
The time at which the request was made |
public VCryptResponse createTransaction(
TransactionCreateRequestData transactionCreateRequestData);
Table 4-2 createTransaction Parameter and Returned Value
| Parameter | Description |
|---|---|
|
TransactionCreateRequestData |
The object to create a new transaction; it throws the exception BharosaException if it fails validation. The structure of this object is as follows:
|
|
VCryptResponse |
The response object; make sure to check isSuccess() before obtaining the transaction ID with the method getTransactionResponse() |
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 createTrasnaction. it throws the exception BharosaException if it fails validation. The structure of this object is as follows:
|
|
VCryptResponse |
The response object; make sure to check isSuccess() before obtaining the transaction ID with the method getTransactionResponse() |
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 |
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 whose 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." |
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 |
|
clientType |
An enumeration value indicating the client type used for authentication |
|
clientVersion |
The version of the client; optional |
|
fingerPrintType |
The type of fingerprinting; defined in the properties file |
|
fingerPrint |
The fingerprint; if it describes browser characteristics, then the header is parsed into this string; it represents the browser header information |
|
digFingerPrintType |
The type of the digital fingerprinting |
|
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 |
Return the user details without the password and pin for the given customer and group.
public VCryptAuthUser getUserByLoginId(String loginId, String groupName);
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 login 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 boolean isSuccess() {
return this.success;
}
public String getResponseCode() {
return this.responseCode;
}
public String getErrorMessage() {
return this.errorMessage == null ? "" : this.errorMessage;
}
public String getErrorMessageRBKey() {
return this.errorMessageRBKey;
}
public String[] getErrorMessageParams() {
return this.errorMessageParams;
}
public Date getTimeStamp() {
return this.timeStamp;
}
public String getServer() {
return this.server;
}
public Map getExtendedDataMap() {
return (extendedDataMap == null) ?
Collections.EMPTY_MAP :
Collections.unmodifiableMap(extendedDataMap);
}
public String getExtendedMap(String key) {
Map map = getExtendedDataMap();
if (map != null) {
return (String) map.get(key);
}
return null;
}
public String getSessionId() {
return sessionId;
}
public TransactionResponse getTransactionResponse() {
return transactionResponse;
}
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-8 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 |
|
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." |
Triggers the data pattern processing.
public VCryptResponse processPatternAnalysis(String requestId,
long transactionId,
int status,
String transactionType);
Table 4-9 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 param is required. |
|
status |
A value of the user-defined enumeration |
|
transactionType |
Indicates the type of the transaction; must be "auth" for authentication transactions; other transaction type values, such as "bill_payment", can be customized. |
Marks the user device as safe.
public boolean markDeviceSafe(String requestId, boolean isSafe);
Returns a value indicating whether the user device associated with a request is safe.
public VCryptBooleanResponse IsDeviceMarkedSafe(String requestId);
The Rules Engine is the part of the Adaptive Risk Manager that enforces policies at checkpoint. Adaptive Risk Manager 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.
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);
Table 4-13 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 |
|
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 |
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 = VCryptRulesResult#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
With property bharosa.tracker.sendLocationData=true set, location 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) ;
}
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:
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);
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-15 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 |
Cancels all temporary allows that have been set for a customer ID.
public VCryptResponse cancelAllTemporatyAllows(String customerId);
Resets all the profiles that have been set for a customer, including registration, questions, images, and phrases.
public VCryptResponse resetUser(String customerId);
Returns all rules executed for the given session ID, and provides some information about what rules were triggered.
public VCryptSessionRuleData getRulesData(String requestId);