OAAM_SAMPLE with different integration and/or deployment options

Multiple times in past, I have encountered questions/issues about OAAM_SAMPLE. So, thought to write a small post explaining how it can be used/configured to test (try out) different native integration options for OAAM.

The OAAM Sample application is for demonstration purposes to familiarize yourself with OAAM APIs. It is not intended to be used as production code since it only provides basic elements of API usage. If you are implementing a native integration, you can develop your application using the OAAM Sample application as a reference.

For understanding the Flow and OAAM APIs, it would be very helpful to play around with OAAM Sample Application. Following are the few use cases where OAAM Sample Application will be useful in performing proof of concepts around native integration of OAAM APIs with protected business application.

• To analyze behavior of OAAM APIs
• To analyze and develop Custom Fingerprinting
• To analyze and develop Custom Challenge Flow
• To analyze and develop flows around Virtual Authentication Devices, Knowledge-Based Authentication, and One-Time Password
• To analyze and develop integration of Client Applications with OAAM for Transactions/Entities

Through this post, I am intending to provide details about following integration and/or deployment scenarios. Considering the popularity and usage, Java based native integration/deployment options are mentioned here in this post.

• Integration Scenarios/Options
  • Native SOAP Integration
  • Native In-Proc (static linking) Integration
• Deployment Scenarios/Options
  • Native SOAP or In-Proc Integration using OAAM Shared Library on WebLogic
  • Native SOAP or In-Proc Integration on Non-WebLogic containers
  • Native Integration for Transactions / Entities

As example of native integration, OAAM Sample Application can be considered as protected application on which OAAM based risk evaluation and prevention is required.

Native In-Proc (static linking) Integration:

OAAM can be natively integrated with application(s) to provide extreme high performance and highly customizable security (risk evaluation and prevention). This native integration embeds OAAM in-process inside the protected applications. The application invokes the OAAM APIs directly to access risk and challenge flows. This integration involves inclusion of OAAM core libraries (Jar files) and properties files into protected application. As OAAM is embedded in application(s) for this integration, this would even require OAAM database access from protected applications.

Considering the performance (in compare to SOAP integration), In-Proc integration would be considered better but from the perspective of maintainability/patching, In-Proc integration would  be a bit complicated.

Native SOAP Integration:

Customers who have advanced requirements similar to native integration but who prefer to use SOAP web services instead of Java API integration directly can choose this option.

This is widely used integration option which involves inclusion of OAAM SOAP Client Library (Java/.Net Wrapper to invoke SOAP APIs) to have communication with OAAM Server for device fingerprinting, risk evaluation and KBA related activities.

OAAM_SAMPLE package is available from:

Brief instructions for setting up the OAAM Sample application are available from Developer’s Guide for OAAM. The most recent OAAM Sample Application that illustrates Java API integration can be downloaded from MOS. MOS Doc ID 1542025.1 is having reference to OAAM Sample package for 11.1.2.x and the same is used while writing this post.

Native SOAP Integration

Following are the few important aspects / configuration steps to understand and keep in mind for SOAP based native integration.

• OAAM Server (default name of managed server: oaam_server_server1 and the name of Enterprise Application oaam_server.ear) exposes WebServices for SOAP based integration.
• WSDL for the exposed WebServices can be found from http://<OAAM Server Host>:<Port>/oaam_server/services?wsdl
• As OAAM provides client library for native integration, it is highly advisable to use the same and avoid usage of WebServices directly (i.e. without using client library provided by OAAM).
• When OAAM Shared Library are not used, it would be advisable to replace oaam_soap_client.jar and bharosa_properties folder with files available from <IAM_ORACLE_HOME>/oaam/oaam_libs/jar/oaam_soap_client.jar and <IAM_ORACLE_HOME>/oaam/oaam_libs/war/oaam_native_lib.war/WEB-INF/classes/bharosa_properties.
• All the changes in configurable properties should be included in oaam_custom.properties. By default, there are lot of properties already set in oaam_custom.properties and some of them would be required to be corrected/deleted based on integration and deployment scenario.
• Based on following configurable property, OAAM SOAP Client would use WebLogic based SOAP Implementation. For usage of different SOAP Implementation (like AXIS), customized implementation of VCryptSOAP (like VCryptSOAPGenericImpl) would be required to be prepared and configured.
  • vcrypt.common.util.vcryptsoap.impl.classname=com.bharosa.vcrypt.common.impl.VCryptSOAPGenericImpl
• Same OAAM Client Library can be used for SOAP or In-Proc integration. To let OAAM Client Library know to use SOAP based integration, following properties are required to be set correctly in oaam_custom.properties:
  • vcrypt.tracker.soap.useSOAPServer=true
  • vcrypt.soap.disable=false
  • vcrypt.tracker.impl.classname=com.bharosa.vcrypt.tracker.impl.VCryptTrackerSOAPImpl
  • vcrypt.tracker.soap.url=http://host-name:port/oaam_server/services
• OAAM Client library can read configuration parameters from Database and Properties files. In most of the deployment scenarios, OAAM Sample will not be having access to Database. So to let OAAM Client know to read configurable parameters only from Properties Files, following properties are required to be set in oaam_custom.properties:
  • bharosa.config.impl.classname=com.bharosa.common.util.BharosaConfigPropsImpl
  • bharosa.config.load.impl.classname=com.bharosa.common.util.BharosaConfigLoadPropsImpl
• Default SOAP Implementation (VCryptSOAPGenericImpl) is designed to use BASIC (username and password) based HTTP Authentication. Following configurable properties are required to be set in oaam_custom.properties to have Authentication enabled for SOAP communication. Keystore related details are available from standard documentation : Setting Up Client Side Keystore to Secure the SOAP User Password.
  • 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>
  • vcrypt.soap.auth.keystoreFile=<Keystore File name which should be available from classpath. i.e. WEB-INF/classes>
• For configuring Authorization on OAAM Server side (exposing WebServices), details are available from post: How to secure Web Services exposed by OAAM Server.
• OAAM uses encryption/decryption for Configurable properties and some Database Tables/Columns. Algorithm and Implementation for such encryption/decryption is controlled by few configurable properties which will be first read during initialization of OAAM Client.
  • By default, required configuration for such encryption/decryption is read from CSF (which would have been initialized during first startup of OAAM Server/Admin). So, if the deployment of OAAM Sample application is on the same WebLogic Server domain where OAAM Server is running, then there should not be any “bharosa.cipher.encryption.algorithm.enum*” properties set in oaam_custom.properties.
  • But, if the deployment of OAAM Sample application is on a non-WebLogic Server or a non-Identity Access Management WebLogic Server domain, then following properties should be set in oaam_custom.properties:
    • bharosa.cipher.encryption.algorithm.enum.DESede_config.keyRetrieval.classname=com.bharosa.common.util.cipher.KeystoreKeyRetrieval
    • bharosa.cipher.encryption.algorithm.enum.DESede_config.keystoreFile=<Keystore File name which should be available from classpath. i.e. WEB-INF/classes>
    • bharosa.cipher.encryption.algorithm.enum.DESede_config.keystorePassword=<Java-keystore-password>
    • bharosa.cipher.encryption.algorithm.enum.DESede_config.aliasPassword=<Keystore-alias-password>
    • bharosa.cipher.encryption.algorithm.enum.DESede_db.keyRetrieval.classname=com.bharosa.common.util.cipher.KeystoreKeyRetrieval
    • bharosa.cipher.encryption.algorithm.enum.DESede_db.keystoreFile=<Keystore File name which should be available from classpath. i.e. WEB-INF/classes>
    • bharosa.cipher.encryption.algorithm.enum.DESede_db.keystorePassword=<Java-keystore-password>
    • bharosa.cipher.encryption.algorithm.enum.DESede_db.aliasPassword=<Keystore-alias-password>
• Based on the preference, EAR or WAR should be prepared including updated properties and library files.
• Based on the deployment scenario, there would be few more properties required to be updated. Such changes are mentioned in the sections below.

Considering/Understanding of above mentioned points and documentation should make the deployment of OAAM Sample easier.

Native In-Proc (static linking) Integration

Following are the few important aspects / configuration steps to understand and keep in mind for In-Proc (static linking) native integration.

• Same OAAM Sample package would be capable enough to work with SOAP or In-Proc integration. There would be changes required in configurable properties and libraries to use specific integration (SOAP or In-Proc) with OAAM Sample.
• With In-Proc integration, OAAM Client library will directly invoke Java APIs (without SOAP Client) and that would require Database access from OAAM Client. i.e. OAAM Client will need access to OAAM Core Libraries and Data Source. Considering such access, it would be advisable to use OAAM Shared Library and Data Source on WebLogic. If in-proc integration is used with non-weblogic container, OAAM Sample deployment would need to include changes in persistence (database access) layer and OAAM core libraries.
• All the changes in configurable properties should be included in oaam_custom.properties. By default, there are lot of properties already set in oaam_custom.properties and some of them would be required to be corrected/deleted based on integration and deployment scenario.
• Same OAAM Client Library can be used for SOAP or In-Proc integration. To let OAAM Client Library know to use In-Proc integration, following properties are required to be set correctly in oaam_custom.properties:
  • vcrypt.tracker.soap.useSOAPServer=false
  • vcrypt.soap.disable=true
• OAAM Client library can read configuration parameters from Database and Properties files. In In-Proc integration, OAAM Sample will be having access to Database and Properties files both. So, following properties should not be set in oaam_custom.properties:
  • bharosa.config.impl.classname
  • bharosa.config.load.impl.classname
• OAAM uses encryption/decryption for Configurable properties and some Database Tables/Columns. Algorithm and Implementation for such encryption/decryption is controlled by few configurable properties which will be first read during initialization of OAAM Client.
  • By default, required configuration for such encryption/decryption is read from CSF (which would have been initialized during first startup of OAAM Server/Admin). So, if the deployment of OAAM Sample application is on the same WebLogic Server domain where OAAM Server is running, then there should not be any “bharosa.cipher.encryption.algorithm.enum*” properties set in oaam_custom.properties.
  • But, if the deployment of OAAM Sample application is on a non-WebLogic Server or a non-Identity Access Management WebLogic Server domain, then following properties should be set in oaam_custom.properties:
    • bharosa.cipher.encryption.algorithm.enum.DESede_config.keyRetrieval.classname=com.bharosa.common.util.cipher.KeystoreKeyRetrieval
    • bharosa.cipher.encryption.algorithm.enum.DESede_config.keystoreFile=<Keystore File name which should be available from classpath. i.e. WEB-INF/classes>
    • bharosa.cipher.encryption.algorithm.enum.DESede_config.keystorePassword=<Java-keystore-password>
    • bharosa.cipher.encryption.algorithm.enum.DESede_config.aliasPassword=<Keystore-alias-password>
    • bharosa.cipher.encryption.algorithm.enum.DESede_db.keyRetrieval.classname=com.bharosa.common.util.cipher.KeystoreKeyRetrieval
    • bharosa.cipher.encryption.algorithm.enum.DESede_db.keystoreFile=<Keystore File name which should be available from classpath. i.e. WEB-INF/classes>
    • bharosa.cipher.encryption.algorithm.enum.DESede_db.keystorePassword=<Java-keystore-password>
    • bharosa.cipher.encryption.algorithm.enum.DESede_db.aliasPassword=<Keystore-alias-password>
• Based on the preference, EAR or WAR should be prepared including updated properties and library files.
• Based on the deployment scenario, there would be few more properties required to be updated. Such changes are mentioned in the sections below.

Considering/Understanding of above mentioned points and documentation should make the deployment of OAAM Sample easier.

Native SOAP or In-Proc Integration using OAAM Shared Library on WebLogic

Apart from the details mentioned above about SOAP or In-Proc integration, following are the few additionally important aspects / steps for deployment of OAAM Sample on WebLogic and to use specific integration for invocation of OAAM APIs.

• There are two versions (EAR and WAR) of OAAM Shared Library (oaam_native_lib) available from <IAM_ORACLE_HOME>/oaam/oaam_libs/ear or <IAM_ORACLE_HOME>/oaam/oaam_libs/war. Target for Shared Library should be updated correctly to make sure that OAAM Sample Application would be able to access that.
  • If OAAM Sample is packaged (and to be deployed) as WAR, WAR version of oaam_native_lib (<IAM_ORACLE_HOME>/oaam/oaam_libs/war/oaam_native_lib.war) should be deployed as shared library in WebLogic.
    • To use WAR version of Shared Library from OAAM Sample Web Application, 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>

  • If OAAM Sample is packaged (and to be deployed) as EAR, EAR version of oaam_native_lib (<IAM_ORACLE_HOME>/oaam/oaam_libs/ear/oaam_native_lib.ear) should be deployed as shared library in WebLogic.
    • To use WAR version of Shared Library from OAAM Sample Enterprise Application, 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>

• As Shared Library is including OAAM libraries/jars and properties, Sample application would NOT need to include any OAAM specific libraries/jars and properties files. Sample application would just need to include oaam_custom.properties in WEB-INF from OAAM Sample integration perspective.
• In case of In-Proc integration, Target for Data Source jdbc/OAAM_SERVER_DB_DS should also be updated correctly to make sure that OAAM Sample Application would be able to access that. If OAAM Sample is to be deployed on non-Identity Access Management WebLogic Server domain, creation of Data Source (with name jdbc/OAAM_SERVER_DB_DS) would be required to provide database access to In-Proc integration.
• If OAAM Sample is to be deployed on non-Identity Access Management WebLogic Server domain, values for following Keys in CSF (of WebLogic Domain for OAAM Sample) should exactly match with the values in CSF of Identity Access Management WebLogic Server domain.
• If OAAM Sample application is to be deployed on same domain as OAAM Server/Admin, it would be advisable to deploy OAAM Sample as EAR. Default installation of OAAM will include deployment of OAAM Shared Library (oracle.oaam.libs) as well and the Shared Library would be deployed as EAR. If OAAM Sample is deployed as WAR on the same domain, it would not be able to access EAR Shared Library.
• Following are the few properties which are updated in oaam_custom.properties to make OAAM Sample work with SOAP based integration.

  • 2c2
    < vcrypt.tracker.soap.url=http://${hostName}:${webapp_port}/oaam_server/services
    ---
    > vcrypt.tracker.soap.url=http://myhostedlinux:14300/oaam_server/services
    4c4
    < vcrypt.soap.auth=false
    ---
    > vcrypt.soap.auth=true
    9c9
    < vcrypt.soap.auth.username=dove
    ---
    > vcrypt.soap.auth.username=oaamsoap
    30c30
    < bharosa.image.dirlist=<Weblogic Folder>/Oracle_IDM1/oaam/oaam_images/
    ---
    > bharosa.image.dirlist=/scratch/orafmw/r2ps2/products/access/iam/oaam/oaam_images/

• Following are the few properties which are updated in oaam_custom.properties to make OAAM Sample work with In-Proc based integration.

  • 2c2
    < vcrypt.tracker.soap.url=http://${hostName}:${webapp_port}/oaam_server/services
    ---
    > #vcrypt.tracker.soap.url=http://iam11g.local:14300/oaam_server/services
    7,10c7,10
    < vcrypt.soap.auth.keystorePassword=ZG92ZTEyMzQ=
    < vcrypt.soap.auth.aliasPassword=ZG92ZTEyMw==
    < vcrypt.soap.auth.username=dove
    < vcrypt.soap.auth.keystoreFile=system_soap.keystore
    ---
    > #vcrypt.soap.auth.keystorePassword=ZG92ZTEyMzQ=
    > #vcrypt.soap.auth.aliasPassword=ZG92ZTEyMw==
    > #vcrypt.soap.auth.username=oaamsoap
    > #vcrypt.soap.auth.keystoreFile=system_soap.keystore
    13c13
    < vcrypt.common.util.vcryptsoap.impl.classname=com.bharosa.vcrypt.common.impl.VCryptSOAPGenericImpl
    ---
    > #vcrypt.common.util.vcryptsoap.impl.classname=com.bharosa.vcrypt.common.impl.VCryptSOAPGenericImpl
    16,19c16,19
    < vcrypt.soap.disable=false
    < vcrypt.tracker.soap.useSOAPServer=true
    < vcrypt.tracker.impl.classname=com.bharosa.vcrypt.tracker.impl.VCryptTrackerSOAPImpl
    < vcrypt.soap.call.timeout=10000
    ---
    > vcrypt.soap.disable=true
    > vcrypt.tracker.soap.useSOAPServer=false
    > #vcrypt.tracker.impl.classname=com.bharosa.vcrypt.tracker.impl.VCryptTrackerSOAPImpl
    > #vcrypt.soap.call.timeout=10000
    21,22c21,22
    < bharosa.config.impl.classname=com.bharosa.common.util.BharosaConfigPropsImpl
    < bharosa.config.load.impl.classname=com.bharosa.common.util.BharosaConfigLoadPropsImpl
    ---
    > #bharosa.config.impl.classname=com.bharosa.common.util.BharosaConfigPropsImpl
    > #bharosa.config.load.impl.classname=com.bharosa.common.util.BharosaConfigLoadPropsImpl
    30c30
    < bharosa.image.dirlist=<Weblogic Folder>/Oracle_IDM1/oaam/oaam_images/
    ---
    > bharosa.image.dirlist=/scratch/orafmw/r2ps2/products/access/iam/oaam/oaam_images/
    33,41c33,41
    < bharosa.cipher.encryption.algorithm.enum.DESede_config.keyRetrieval.classname=com.bharosa.common.util.cipher.KeystoreKeyRetrieval
    < bharosa.cipher.encryption.algorithm.enum.DESede_config.keystoreFile=system_config.keystore
    < bharosa.cipher.encryption.algorithm.enum.DESede_config.keystorePassword=ZG92ZTEyMzQ=
    < bharosa.cipher.encryption.algorithm.enum.DESede_config.aliasPassword=ZG92ZTEyMw==
    <
    < bharosa.cipher.encryption.algorithm.enum.DESede_db.keyRetrieval.classname=com.bharosa.common.util.cipher.KeystoreKeyRetrieval
    < bharosa.cipher.encryption.algorithm.enum.DESede_db.keystoreFile=system_db.keystore
    < bharosa.cipher.encryption.algorithm.enum.DESede_db.keystorePassword=ZG92ZTEyMzQ=
    < bharosa.cipher.encryption.algorithm.enum.DESede_db.aliasPassword=ZG92ZTEyMw==
    ---
    > #bharosa.cipher.encryption.algorithm.enum.DESede_config.keyRetrieval.classname=com.bharosa.common.util.cipher.KeystoreKeyRetrieval
    > #bharosa.cipher.encryption.algorithm.enum.DESede_config.keystoreFile=system_config.keystore
    > #bharosa.cipher.encryption.algorithm.enum.DESede_config.keystorePassword=ZG92ZTEyMzQ=
    > #bharosa.cipher.encryption.algorithm.enum.DESede_config.aliasPassword=ZG92ZTEyMw==
    > #
    > #bharosa.cipher.encryption.algorithm.enum.DESede_db.keyRetrieval.classname=com.bharosa.common.util.cipher.KeystoreKeyRetrieval
    > #bharosa.cipher.encryption.algorithm.enum.DESede_db.keystoreFile=system_db.keystore
    > #bharosa.cipher.encryption.algorithm.enum.DESede_db.keystorePassword=ZG92ZTEyMzQ=
    > #bharosa.cipher.encryption.algorithm.enum.DESede_db.aliasPassword=ZG92ZTEyMw==

Native SOAP or In-Proc Integration using OAAM Shared Library on Non-WebLogic containers

Apart from the details mentioned above about SOAP or In-Proc integration, following are the few additionally important aspects / steps for deployment of OAAM Sample on Non-WebLogic containers like Apache Tomcat and to use specific integration for invocation of OAAM APIs.

• As on Non-Weblogic containers, there would not be OAAM Shared Library available so all required OAAM Client Libraries (Jar files) and properties files should be included in the OAAM Sample Application.
• For In-Proc integration, OAAM Core Libraries (Jar files) and properties files should be included in the OAAM Sample Application.
• For In-Proc integration, there would be changes required in libraries, properties files and persistence.xml to make database accessible from OAAM Sample. Changes required for this would vary based on the Application Container. As example, following are the changes required in OAAM Sample to make it work with In-Proc integration from Non-Weblogic container like Apache Tomcat
  • Additional Changes in Properties (oaam_custom.properties):
    • oaam.db.toplink.useCredentialsFromCSF=false
    • oaam.csf.useMBeans=false
  • Changes in META-INF/persistence.xml:
    •             <property name=”eclipselink.jdbc.url” value=”jdbc:oracle:thin:@myhostedlinux:1521:iam111220″/>
    •             <property name=”eclipselink.jdbc.user” value=”AM_OAAM”/>
    •             <property name=”eclipselink.jdbc.password” value=”oracle123″/>
  • Inclusion of additional libraries (Jar files) in Classpath:
    • com.bea.core.antlr_2.7.7.jar, com.bea.core.apache.commons.collections_3.2.0.jar  , jps-api.jar, jps-manifest.jar, jps-az-management.jar, jps-platform.jar, jps-az-rt.jar, jps-se.jar, jacc-spi.jar, jps-ee.jar, jps-internal.jar, jps-common.jar, com.oracle.toplink_1.1.0.0_11-1-1-6-0.jar, eclipselink.jar, javax.persistence_1.1.0.0_2-0.jar, ojdbc6.jar, commons-codec-1.2.jar, drools-base-2.0-beta-21.jar, drools-core-2.0-beta-21.jar, drools-io-2.0-beta-21.jar, drools-java-2.0-beta-21.jar, drools-jsr94-2.0-beta-21.jar, drools-smf-2.0-beta-21.jar, groovy-all-1.6.3.jar, janino-2.0.16.jar, jsr94.jar, oaam_core.jar, oaam_native_wrapper.jar, oaam_uio.jar, etc…
  • Inclusion of additional configuration files in Classpath:
    • oaam_toplink_orm.xml and META-INF/persistence.xml

Native Integration for Transactions / Entities

With OAAM Sample Application, it’s very much easy to play around with OAAM APIs for Entities and Transactions. With changes in configurable properties, OAAM Sample will be able to render custom input forms for entities and transactions. Links available on the left side (after logging in successfully) are rendered based on the configurable properties.

Values for following enumerations in oaam_custom.properties are responsibile for rendering input pages for transactions and entities.

• tracker.entity.type.enum
• tracker.entity.form.enum.<xyz>.form_fields
• tracker.entity.form_field.<xyz>.enum
• tracker.transaction.type.enum
• tracker.transaction.form.enum.<xyz>.form_fields
• tracker.transaction.form_field.<xyz>.enum

All content listed on this page is the property of Oracle Corp. Redistribution not allowed without written permission