7 Using the OAAM Extensions Shared Library to Customize OAAM

Shared libraries are collections of programming and data that multiple applications can use. They can permit applications to use memory efficiently by sharing common programming and resources.

The chapter provides information on how to customize Oracle Adaptive Access Manager by using the OAAM Extensions Shared Library. It contains the following sections:

7.1 About the OAAM Extensions Shared Library

The OAAM Extensions Shared Library is a collection of the following:

  • Property files

  • JSP files

  • CSS files

  • JAR files

  • Header file

  • Footer file

It allows a large number of customizations at once and enables you to customize resource bundles. You can also add custom files for use in branding such as Header, Footer, and CSS files. Figure 7-1 shows examples of custom files.

Figure 7-1 Custom Files

OAAM customization files are shown.

The OAAM Extensions Shared Library, oracle.oaam.extensions.war, is located in IAM_Home/oaam/oaam_extensions/generic. It is deployed in both the OAAM Server and OAAM Admin servers. By default oracle.oaam.extensions.war contains the MANIFEST.MF, which has the definition of the OAAM Extensions Shared Library.

7.2 Customizing or Extending OAAM By Editing Enums

You can manage the appearance and behavior of OAAM using properties called user-defined enumerations. Enumeration and their elements and properties can be edited an new enumerations can also be added to customize OAAM. User-defined enumerations are a collection of properties that represent a list of items. Each element in the list may contain several different attributes. The definition of a user-defined enum begins with a property ending in the keyword ".enum" and has a value describing the use of the user-defined enum. Each element definition then starts with the same property name as the enum, and adds on an element name and has a value of a unique integer as an ID. The attributes of the element follow the same pattern, beginning with the property name of the element, followed by the attribute name, with the appropriate value for that attribute.

The following is an example of an enum defining credentials displayed on the login screen of an OAAM Server implementation:

bharosa.uio.default.credentials.enum = Enum for Login Credentials
bharosa.uio.default.credentials.enum.companyid=0
bharosa.uio.default.credentials.enum.companyid.name=CompanyID
bharosa.uio.default.credentials.enum.companyid.description=Company ID
bharosa.uio.default.credentials.enum.companyid.inputname=comapanyid
bharosa.uio.default.credentials.enum.companyid.maxlength=24
bharosa.uio.default.credentials.enum.companyid.order=0
bharosa.uio.default.credentials.enum.username=1
bharosa.uio.default.credentials.enum.username.name=Username
bharosa.uio.default.credentials.enum.username.description=Username
bharosa.uio.default.credentials.enum.username.inputname=userid
bharosa.uio.default.credentials.enum.username.maxlength=18
bharosa.uio.default.credentials.enum.username.order=1

To override OAAM properties or extend OAAM, add the properties and enumerations to oaam_custom.properties and, when appropriate, client_resource_locale.properties. Localized properties are often duplicated in properties files and resource bundle files. Resource bundle values always take precedence over standard properties. Later, you will save these files to repackage in the OAAM Extensions Library.

Elements that are localized need to be changed through the OAAM Extensions Library because making changes with the OAAM Admin Console properties editor will have no effect. These elements are:

  • Names

  • Descriptions

  • User facing text

7.3 Adding Customizations Using the OAAM Extensions Shared Library

This section provides instructions for adding customizations to Oracle Adaptive Access Manager.

The main steps are:

  1. Extract the OAAM Extensions Shared Library WAR file.

  2. Create an OAAM Extensions Shared Library WAR file with new and edited files.

  3. Deploy the WAR file as a library using the WebLogic Administration Console.

7.3.1 Note About Access Manager and OAAM Integration and Customization

Ensure the property bharosa.uio.proxy.mode.flag is set as appropriate.

The default for the property bharosa.uio.proxy.mode.flag is false. If you are using an UIO proxy deployment, the property should be set to true. To configure custom branding for multitenancy with the OAAM Proxy, the property bharosa.uio.proxy.mode.flag must be set to true.

If you are adding customizations and also configuring integration with Oracle Access Management Access Manager 11g using the TAP scheme, the property must be set as false. Setting the property to true causes OAAM and Access Manager integration using TAP to fail with the following message:

Sorry, the identification you entered was not recognized.

7.3.2 Step 1 Extract the OAAM Extensions Shared Library

To extract the OAAM Extensions Shared Library, proceed as follows:

  1. Create a work folder named oaam_extensions.

    The folder can be created anywhere if it is outside the installation folder.

  2. Extract the oracle.oaam.extensions.war file into the work folder.

    In the oaam_extensions folder, you should see the following subfolders:

    • META-INF

    • WEB-INF

    • WEB-INF\lib

    • WEB-INF\classes

7.3.3 Step 2 Create a MANIFEST.MF File

In the META-INF folder, create a file named MANIFEST.MF and ensure it contains the following lines:

Extension-Name: oracle.oaam.extensions
Implementation-Version:99.9.9.9.9
Specification-Version:99.9.9.9.9

The specification version and implementation version must be more than the versions in the file currently. For example, if the implementation version in the file is 11.1.1.3.0, you could change it to 99.9.9.9.9. Errors are thrown if the version is not incremented.

7.3.4 Step 3 Compile Custom Java Classes

Compile custom java classes that extend or implement Oracle Adaptive Access Manager classes, adding the JAR files from the ORACLE_IDM_HOME\oaam\cli\lib folder to the build class path.

7.3.5 Step 4 Add Custom Files

Add the custom files as described:

  1. Add the custom JAR files to the oaam_extensions\WEB-INF\lib folder. For example, oaam_core.jar.

  2. Add or modify the properties in oaam_custom.properties and save the file to the oaam_extensions\WEB-INF\classes\bharosa_properties directory.

  3. Add custom JSP files directly to oaam_extensions.

  4. Add the client_resource_locale.properties file as described in Section 8.4.4, "Customizing Content and Messaging in User Interface Branding."

  5. Add Header and Footer files as described in Section 8.4.2, "Customizing Headers and Footers in User Interface Branding."

  6. Add the CSS file as described in Section 8.4.3, "Modifying User Interface Styles in User Interface Branding."

  7. Add custom virtual authentication device related images to the oaam_extensions\WEB-INF\classes\bharosa_properties directory.

7.3.6 Step 5 Repackage the OAAM Extensions Shared Library Into a New WAR File

Repackage the OAAM Extensions Shared Library, oracle.oaam.extensions.war, from the parent folder of oaam_extensions using the command:

jar -cvfm oracle.oaam.extensions.war oaam_extensions/META-INF/MANIFEST.MF -C  oaam_extensions/ .

Note:

Note that there is a dot at the end of the command.

This command recreates the WAR file with the MANIFEST.MF file. The custom JAR files, CSS the new WAR file.

7.3.7 Step 6 Verify If the Repackaged WAR File Contains the Custom JAR Files

Verify that the repackaged WAR file contains the custom JAR files. Use the following command to view its contents:

jar tvf oracle.oaam.extensions.war

7.3.8 Step 7 Stop All Managed Servers

Stop all managed servers if they are running:

MW_HOME/user_projects/domains/domain_name/bin/stopManagedWeblogic.sh
  oaam_admin_server1
MW_HOME/user_projects/domains/domain_name/bin/stopManagedWeblogic.sh
  oaam_server_server1

7.3.9 Step 8 Start the WebLogic Administration Server

Start the WebLogic Administration Server:

MW_HOME/user_projects/domains/domain_name/bin/startWeblogic.sh

7.3.10 Step 9 Log In to the WebLogic Administration Console

Start the WebLogic Server where Oracle Adaptive Access Manager is deployed and log in to the WebLogic Administration Console:

http://hostname:port/console

7.3.11 Step 10 Deploy the New OAAM Extensions Shared Library

Deploy the new oracle.oaam.extensions.war file as a shared library with oaam_server_server1 and oaam_admin_server1 as target applications.

  1. Navigate to Domain Environment > Deployments and lock the console.

  2. Click the Install button.

  3. Browse to the location of the oracle.oaam.extensions.war file and select it by clicking the option next to the WAR file and clicking Next.

  4. Ensure Install this deployment as a library is selected and click Next.

  5. Select deployment targets, oaam_admin_server1 and oaam_server_server1.

  6. Click Next again to accept the defaults in this next page and then click Finish.

  7. Click the Save button and then Activate Changes.

  8. Start the OAAM Admin and OAAM managed servers.

    MW_HOME/user_projects/domains/domain_name/bin/startManagedWeblogic.sh
  oaam_admin_server1
MW_HOME/user_projects/domains/domain_name/bin/startManagedWeblogic.sh
  oaam_server_server1

7.3.12 Step 11 Test the Functionality

Test the custom functionality and make sure files added to oracle.oaam.extensions.war are used by Oracle Adaptive Access Manager applications.