| Oracle® Adaptive Access Manager Developer's Guide Release 10g (10.1.4.5) Part Number E12052-03 |
|
|
View PDF |
| Oracle® Adaptive Access Manager Developer's Guide Release 10g (10.1.4.5) Part Number E12052-03 |
|
|
View PDF |
This document provides information on the available APIs for integrations using Java. Refer to Chapter 2, "API Integration" for guidelines for integration options and flows.
The installation package will provide the required jars and property files. Sun Java 1.4 and above is supported for the integrations.
Property files of interest are listed below.
Table 4-1 Property Files of Interest
| File name | Description |
|---|---|
|
This file is designated for installation-specific properties. Refer to the Oracle Adaptive Access Manager Installation and Configuration Guide for information on configuring Adaptive Risk Manager and Chapter 6, "Configuring Adaptive Strong Authenticator," for configuring Adaptive Strong Authenticator. |
|
|
This file is designated for client side properties. The sample file, bharosa_client.properites.sample, is provided with the installation package. Copy bharosa_client.properites.sample to bharosa_client.properites. Update the properties as per your environment.
|
|
|
This file contains properties to customize various aspects of authenticators. This file is not to be modified by the clients. |
Adaptive Risk Manager is a component of Oracle Adaptive Access Manager.
Adaptive Risk Manager provides APIs to
collect/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
The sample application and the BharosaHelper class provide some of the usage scenarios.
For examples of usage scenarios and flows, refer to Chapter 2, "API Integration."
API handleTrackerRequest: API to capture fingerprint details and identify the device. Variations of the same API is provided to capture details with the time of the request. The time of request 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);
Table 4-2 API handleTrackerRequest Parameters
| Parameter | Description |
|---|---|
|
requestId |
The ID for the login session. The same ID is necessary for all the calls to the Oracle Adaptive Access Manager API for the login session. |
|
remoteIPAddr |
The IP from where the request came in. This is extracted from the HTTP request. |
|
remoteHost |
The host name from where the request came in. This is optional |
|
secureCookie |
The secure cookie. This is passed only if it is received from the browser |
|
secureClientType |
The secure cookie client type. This is an enum value defined to identify the client used for authentication. |
|
secureClientVersion |
The version of the secure cookie client. This is an optional parameter to specify the version of the client used |
|
digitalCookie |
The digital signature cookie. This could be the flash cookie. This parameter is sent only if it is sent by the browser |
|
digitalClientType |
The digital cookie client type. The type of flash client used. If not available, please use the value 0 |
|
digitalClientVersion |
The version of the digital cookie client. The version of the flash client. |
|
fingerPrintType |
The type of finger printing. The value for defined in the properties file. |
|
fingerPrint |
The finger print. If it is browser characteristics, then the header is parsed into this string. This is the name value representation of the browser header information. |
|
fingerPrintType2 |
This is used in case the same request has multiple finger prints. It is like a flash request. The value is defined in the properties file |
|
fingerPrint2 |
The second finger print value. If it is from the flash, it is passed as it is. This is an optional parameter. |
|
requestTime |
The time when this request was made. Used by simulator |
API createTransaction: API to create new transaction
public VCryptResponse createTransaction(TransactionCreateRequestData transactionCreateRequestData);
Table 4-3 API createTransaction Parameters
| Parameter | Description |
|---|---|
|
TransactionCreateRequestData |
Data object to create a new transaction. A description of the structure is as follows:
|
|
VCryptResponse |
Response object. Make sure to check isSuccess() before obtaining the transaction Id. getTransactionResponse() method provides the transaction id. |
API updateTransaction: API to update previously created transaction
public VCryptResponse updateTransaction(TransactionUpdateRequestData transactionUpdateRequestData);
Table 4-4 API updateTransaction Parameters
| Parameter | Description |
|---|---|
|
TransactionUpdateRequestData |
Data object to update transaction. Either transaction Id is returned during createTransaction API call or external transaction Id is sent during createTrasnaction API call to get the handle to the existing transaction. The description of the structure is as follows:
|
|
VCryptResponse |
Response object. Make sure to check isSuccess() before obtaining the transaction Id. getTransactionResponse() method provides transaction id. |
API handleTransactionLog: API to capture transaction details.
Note:
Deprecated as of 10.1.4.5.1, use createTransaction API.public VCryptResponse handleTransactionLog(String requestId, Map[]);
public VCryptResponse handleTransactionLog(String requestId, Date requestTime, Map[] contextMap);
public VCryptResponse handleTransactionLog(String requestId, Date requestTime, Integer status, Map[] contextMap );
Table 4-5 API handleTransactionLog Parameters
| Parameter | Description |
|---|---|
|
requestId |
The ID for the login session. The same ID is necessary for all the calls to the Oracle Adaptive Access Manager API for the login session. |
|
requestTime |
The time when this request was made. Used by simulator |
|
contextMap |
The array of contextMap. Multiple transactions can be created with a single API call. It is expected to have "transactionType" key in each context map for the creation of the appropriate transaction. |
|
status |
The transaction status for this transaction, client specific transaction status. |
API updateTransactionStatus: API to update the given transaction status and, if appropriate, trigger the pattern data analysis.
Note:
Deprecated as of 10.1.4.5.1, use updateTransaction API.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(java.lang.String requestId, long transactionId, int status, boolean analyzePatterns)
public VCryptResponse updateTransactionStatus(java.lang.String requestId, java.util.Date requestTime, long transactionId, int status, java.util.Map[] contextMap, boolean analyzePatterns)
Table 4-6 API updateTransactionStatus Parameters
| Parameter | Description |
|---|---|
|
requestId |
The ID for the login session. The same ID is necessary for all the calls to the Oracle Adaptive Access Manager API for the login session. |
|
requestTime |
The time when this request was made. Used by simulator |
|
contextMap |
The array of contextMap. Multiple transactions can be created with a single API call. It is expected to have "transactionType" key in each context map for the creation of the appropriate transaction. |
|
Status |
The transaction status for this transaction, client specific transaction status. |
|
transactionId |
The ID of the transaction to be updated. If null, it uses the last transaction in the given session. |
|
analyzePatterns |
Boolean to indicate if the pattern analysis should be done. When passed in as true the pattern analysis is done for this transaction. |
API updateLog: API to update the user node log and, if required, to create the CookieSet also.
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-7 API updateLog Parameters
| Parameter | Description |
|---|---|
|
requestId |
The ID for the login session. The same ID is necessary for all the calls to the Oracle Adaptive Access Manager API for the login session. |
|
remoteIPAddr |
The IP from where the request came in. This is extracted from the HTTP request. |
|
remoteHost |
The host name from where the request came in. This is optional |
|
secureCookie |
The secure cookie. This is passed only if it is received from the browser |
|
secureClientType |
The secure cookie client type. This is an enum value defined to identify the client used for authentication. |
|
secureClientVersion |
The version of the secure cookie client. This is an optional parameter to specify the version of the client used |
|
digitalCookie |
The digital signature cookie. This could be the flash cookie. This parameter is sent only if it is sent by the browser |
|
digitalClientType |
The digital cookie client type. The type of flash client used. If not available, please use the value 0 |
|
digitalClientVersion |
The version of the digital cookie client. The version of the flash client. |
|
fingerPrintType |
The type of finger printing. The value for defined in the properties file. |
|
fingerPrint |
The finger print. If it is browser characteristics, the header is parsed into this string. This is the name value representation of the browser header information. |
|
digFingerPrintType |
The type of the digital finger printing |
|
digFingerPrint |
The digital fingerprint |
|
requestTime |
The time when this request was made. Used by simulator |
|
groupId |
The groupId of this user. This is the primary group to which this user belongs to. |
|
userId |
The ID of the user. This is the primary key ID of the user. It should be null for users who are invalid. |
|
loginId |
The loginId used by the user for login in. This is mandatory parameter. |
|
isSecure |
Whether this node is secure and can be registered. This is to indicate the login is from a secure or registered device. If there is no concept of device, then send false value for this parameter. |
|
result |
The authentication result. This is the enumeration value of the authentication result. |
|
clientType |
This is an enum value defined to identify the client type used for authentication. |
|
clientVersion |
The version of the client. This is an optional parameter to specify the version of the client used |
API updateAuthStatus: API to update the User node log auth status and, if appropriate, trigger pattern data analysis.
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(java.lang.String requestId, int resultStatus, int clientType, java.lang.String clientVersion, boolean analyzePatterns)
public VCryptResponse updateAuthStatus(java.lang.String requestId, java.util.Date requestTime, int resultStatus, int clientType, java.lang.String clientVersion, boolean analyzePatterns)
Table 4-8 API updateAuthStatus Parameters
| Parameter | Description |
|---|---|
|
requestId |
The ID for the login session. The same ID is necessary for all the calls to the Oracle Adaptive Access Manager API for the login session. |
|
requestTime |
The time when this request was made. Used by simulator |
|
resultStatus |
The authentication result. This is the enumeration value of the authentication result |
|
clientType |
An enum value defined to identify the client type used for authentication. |
|
clientVersion |
An optional parameter to specify the version of the client used |
|
analyzePatterns |
Boolean to indicate if the pattern analysis should be done. When passed in as true the pattern analysis is done for this transaction. |
upateAuthStatus API needs to be called when there is a change in the user's authentication status.
Prerequisite: Make sure to call updateLog before making changes to the authentication status.
The list of possible authentication status values are maintained on the server-side with "auth.status.enum". Make sure to match the status value with one of those values. The list of statuses can be installation-specific. You can add or remove the standard status definitions that came with the product by updating "auth.status.enum".
Scenarios:
Send login status along with updateLog call
updateLog API call takes status as one of the parameters, send login status with updateLog API, and avoid calling updateAuthStatus calls.
Login and then update authentication status
Set status to "pending" with updateLog API call
Call updateAuthStatus with actual status value.
Challenge flow
Challenge is considered a second factor authentication. It is recommended to set the status to
1. "Pending" before challenging
2. After the user's response, set the status to "success" or "wrong_answer"
Run rules
Usually, there is no need to call update auth status after running the rules API. Run rules API internally handles known actions, "Block" and "Locked," and updates the authentication status appropriately.
API processPatternAnalysis: API to trigger the processing of data for pattern matching. This call will only trigger the processing of data for pattern matching. The last parameter transactionType can be used by authentication type user interactions, since auth (or login) are not first-class transactions.
public VCryptResponse processPatternAnalysis(java.lang.String requestId, long transactionId, int status, java.lang.String transactionType)
Table 4-9 processPatternAnalysis
| Parameter | Description |
|---|---|
|
requestId |
request Id |
|
transactionId |
Transaction Id to be updated. |
|
status |
New Status |
|
transactionType |
String that indicates the type of transaction. Has to be "auth" for authentication type. For other types it can be "bill_pay, ....",; basically the type name of the transaction. |
API markDeviceSafe: API to mark the device as safe for the user.
public boolean markDeviceSafe(String requestId, boolean isSafe);
API IsDeviceMarkedSafe: API to verify that the device associated with this request is safe
public VCryptBooleanResponse IsDeviceMarkedSafe(String requestId);
The Rules Engine component of Adaptive Risk Manager provides APIs for policy execution and enforcement.
The Rules Engine can be viewed as an enforcement component of the Adaptive Risk Manager. Based on the calling context, various policies and models configured by the administrators are evaluated and the results are provided.
API processRules: API to process policy sets for the given runtimes.
A Policy Set consists of policies and rules. The API processes the policy set for each runtime and returns VCryptRulesResult. There has to be at least one updateLog call before calling processRules.
public VCryptRulesResult processRules(String requestId, List runtimeTypes, Map contextMap);
public VCryptRulesResult processRules(String requestId, Date requestTime, List runtimeTypes, Map contextMap);
public VCryptRulesResult processRules(String requestId, Long transactionId, String extTransactionId, Date requestTime, List runtimeTypes, Map contextMap);
Table 4-13 API processRules Parameters
| Parameter | Description |
|---|---|
|
requestId |
The ID for the login session. The same ID is necessary for all the calls to the Oracle Adaptive Access Manager API for the login session. |
|
runtimeTypes |
The list of runtimes to be evaluated. Each runtime in the given list is evaluated and result is returned. |
|
requestTime |
The time when this request was made. Used by simulator |
|
transactionId |
Transaction Id, to be treated as the current transaction for this process rules call. Can be null, if no transaction Id is sent, API will check for extTransactionId, else will use the last transaction in the login session as current transaction. |
|
extTransactionId |
Handle to the external transaction id to be used as the current transaction. Optional, will use last transaction in the login session as the current transaction, if no transactionId or extTransactionId are sent. |
|
contextMap |
The data for the context. Rules in models can make decisions based on this data. Key, value pairs |
Along with rule results, the Rules Engine component can return a Device Id. The Device Id that is returned by the Rules Engine API is an internal identifier within Adaptive Risk Manager. It is the same Id shown in Adaptive Risk Manager for the user session.
A sample algorithm to get the Device Id is shown below:
VCryptRulesResult rulesResult = new VCryptRulesEngineImpl().processRules(<params..>);
If (!rulesResult.getVCryptResponse().isSuccess()) {
Logger.error("Error running rules " + rulesResult.getVCryptResponse().getErrorMessage());
}
Long deviceId = VCryptRulesResult#getDeviceId();
Troubleshooting:
Make sure the Adaptive Risk Manager version is 10.1.4.5 or above
The following property must be set to true for the Device Id to be captured.
bharosa.tracker.send.deviceId=true
Customer Care provides APIs for limited customer care functionality, typically used in customer care portals. These APIs will not use audit feature and access control.
API getFinalAuthStatus: API to return the final authentication status of a user given the user ID of the user. This method can only go back up to 30 days.
public VCryptIntResponse getFinalAuthStatus(String requestId, String userId);
API setTemporaryAllow: This API call sets a temporary allow for the given user. A temporary allow can override the final rule action.
public VCryptResponse setTemporaryAllow(String customerId, int tempAllowType, Date expirationDate);
Table 4-15 API setTemporaryAllow Parameter
| Parameter | Description |
|---|---|
|
customerId |
Id of the customer |
|
tempAllowType |
Type of the temporary allow. The User Defined Enum for this type is customercare.case.tempallow.level.enum |
|
expirationDate |
Expiration date if the tempAllowType is "userset". Otherwise it can be null or empty. |
API cancelAllTemporaryAllows: API to cancel any temporary allows associated with the customer ID.
public VCryptResponse cancelAllTemporaryAllows(String customerId);
API resetUser: API to reset all the profiles set for the user. This includes registration, questions, images and phrases, selected or assigned to the user
public VCryptResponse resetUser(String customerId);
API getRulesData: API to return all the rules executed for the given session ID, and provide basic information on what rules got triggered. It does not provide complete hierarchy information.
public VCryptSessionRuleData getRulesData(String requestId);
|
 Copyright © 2008, 2009, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|