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 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.
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 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."
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.
To call the OAAM APIs via SOAP instead of inproc, follow these steps in these sections.
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:
Select the row "oracle/wss_http_token_service_policy".
To disable SOAP Authentication:
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
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>
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:
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 |
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 |
createTransaction creates a new transaction.
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 The structure of this object is as follows:
|
VCryptResponse |
The response object; make sure to check |
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:
|
VCryptResponse |
The response object; make sure to check isSuccess() before obtaining the transaction ID with the method getTransactionResponse() |
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 |
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." |
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 |
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 |
getUserByLoginId returns the user details without the password and pin for the given customer and group.
public VCryptAuthUser getUserByLoginId(String loginId, String groupName);
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)
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. |
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 |
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." |
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 |
transactionType |
Indicates the type of the transaction; must be "auth" for authentication transactions; other transaction type values, such as "bill_payment", can be customized. |
markDeviceSafe marks the user device as safe.
public boolean markDeviceSafe(String requestId, boolean isSafe);
IsDeviceMarkedSafe 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 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.
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:
|
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.
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
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) ; }
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 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);
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 |
cancelAllTemporaryAllows cancels all temporary allows that have been set for a customer ID.
public VCryptResponse cancelAllTemporatyAllows(String customerId);
resetUser resets all the profiles that have been set for a customer, including registration, questions, images, and phrases.
public VCryptResponse resetUser(String customerId);
getRulesData returns all rules executed for the given session ID and provides information about the rules that were triggered.
public VCryptSessionRuleData getRulesData(String requestId);
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 |
Note:
For this API to work, the corresponding actionincrementCacheCounter
enum property needs to be set to true
.