8 Customizing the OAAM Server

This chapter provides information on customizing the client-facing OAAM Server Web application. The OAAM UIO Proxy offers multifactor authentication to Web applications without requiring any change to the application code. The OAAM Server configuration is specific to the UIO Proxy deployment. Refer to the architectural diagram (Figure 8-1) for the components involved.

The user interface provided by the OAAM Server Web application can be easily customized to achieve the look and feel of the customer applications. This chapter is intended for integrators who install and configure OAAM Server to support one or more Web application authentication and user registration flows.

This chapter contains the following sections:

Architecture
Tips for Customizing the OAAM Server Web Application
OAAM Properties
Overriding Existing User-Defined Enums
Disabling Elements
Customizing the OAAM Server for Multiple Applications
Customizing the Appearance of OAAM Server
Questions/Answers About User Interface Customization

8.1 Architecture

Figure 8-1 shows the UIO Proxy deployment.

Figure 8-1 Universal Installation Deployment

The OAAM Server proxy intercepts the HTTP traffic between the client (browser) and the server (Web application) and performs appropriate actions, such as redirecting to OAAM Server, to provide multifactor authentication and authorization. OAAM Server in turn communicates with OAAM Admin to assess the risk and takes the appropriate actions, such as permitting the login, challenging the user, blocking the user, and other actions.

8.2 Tips for Customizing the OAAM Server Web Application

As you plan to customize the web user interface, keep the following points in mind:

When customizing, you often copy files that are installed with OAAM into a directory in which you can modify them. By modifying files in this directory, you prevent your modifications from being overwritten when the software is upgraded.
When configuring the web application, use bharosa_server.properties. The file should contain:
- Client-configured properties (any properties that have been customized for a specific deployment)
- UIO Proxy system /device configurations. These properties deal with the structural changes in the overall application. It is where the header, footer, and CSS properties are located.
In the deployed application, the bharosa_server.properties file is located in the web-inf/classes directory.
When adapting the OAAM deployment to a particular language, use client_resource_<locale>.properties where <locale> is the locale string for which you wish to use the custom values (en, es, and others). The file should contain
- Client-configured properties that are configurable for each locale being supported. <locale> is the locale string for which you wish to use the custom values (en, es, and others).
- UIO Proxy messaging and page content configuration. For example, page titles, links at the bottom of the pages, page messages, error message, and confirmation messages.
The client_resource_<locale>.properties is created by the administrator customizing the application to contain locale-specific properties.

For instructions on customizing, extending, or overriding Oracle Adaptive Access Manager properties, refer to Chapter 7, "OAAM Extensions and Shared Library to Customize OAAM."

8.3 OAAM Properties

You can manage the appearance and behavior of OAAM using user-defined enumerations. 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.

8.3.1 Enum Example

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

This set of properties defines one user-defined enum that contains two elements, each of which with five attributes. The "name" and "description" attributes are required to define any user-defined enum, other attributes are defined and used as needed by each individual use of a user-defined enum.

8.3.2 Overriding Existing User-Defined Enums

Overriding existing user-defined enums has some special cases. You may override any existing enum element's attribute value of the default application ID just as you would any other property, but to change the value of an element's attribute in a single application using an appId, you must create the entire enum in that application using the appropriate appId.

For example, using the User Defined Enum defined in Section 8.3.1, "Enum Example," if you wanted to change "Company ID" to "Profile ID" for only one application (appId1), you would need to modify the enum:

bharosa.uio.appId1.credentials.enum = Enum for Login Credentials
bharosa.uio.appId1.credentials.enum.profileid=0
bharosa.uio.appId1.credentials.enum.profileid.name=ProfileID
bharosa.uio.appId1.credentials.enum.profileid.description=Profile ID
bharosa.uio.appId1.credentials.enum.profileid.inputname=profileid
bharosa.uio.appId1.credentials.enum.profileid.maxlength=20
bharosa.uio.appId1.credentials.enum.profileid.order=0
bharosa.uio.appId1.credentials.enum.username=1
bharosa.uio.appId1.credentials.enum.username.name=Username
bharosa.uio.appId1.credentials.enum.username.description=Username
bharosa.uio.appId1.credentials.enum.username.inputname=userid
bharosa.uio.appId1.credentials.enum.username.maxlength=18
bharosa.uio.appId1.credentials.enum.username.order=1

For instructions on customizing, extending, or overriding Oracle Adaptive Access Manager properties or enums, refer to Chapter 7, "OAAM Extensions and Shared Library to Customize OAAM."

8.3.3 Disabling Elements

To disable any already defined element in a user-defined enum, simply add an "enabled" attribute with a value of "false". Using the appId1 credentials enum from Section 8.4, "Overriding Existing User-Defined Enums," you would add the following line to remove "Profile ID" from the elements used by the application:

bharosa.uio.appId1.credentials.enum.profileid.enabled=false

8.4 Overriding Existing User-Defined Enums

bharosa.uio.appId1.credentials.enum = Enum for Login Credentials
bharosa.uio.appId1.credentials.enum.profileid=0
bharosa.uio.appId1.credentials.enum.profileid.name=ProfileID
bharosa.uio.appId1.credentials.enum.profileid.description=Profile ID
bharosa.uio.appId1.credentials.enum.profileid.inputname=profileid
bharosa.uio.appId1.credentials.enum.profileid.maxlength=20
bharosa.uio.appId1.credentials.enum.profileid.order=0
bharosa.uio.appId1.credentials.enum.username=1
bharosa.uio.appId1.credentials.enum.username.name=Username
bharosa.uio.appId1.credentials.enum.username.description=Username
bharosa.uio.appId1.credentials.enum.username.inputname=userid
bharosa.uio.appId1.credentials.enum.username.maxlength=18
bharosa.uio.appId1.credentials.enum.username.order=1

For instructions on customizing, extending, or overriding Oracle Adaptive Access Manager properties or enums, refer to Chapter 7, "OAAM Extensions and Shared Library to Customize OAAM."

8.5 Disabling Elements

bharosa.uio.appId1.credentials.enum.profileid.enabled=false

8.6 Customizing the OAAM Server for Multiple Applications

Multitenancy refers to a principle in software architecture where a single instance of the software runs on a server, serving multiple client organizations. With a multitenant architecture, each client organization feels as if they are working with a separate customized application instance.

You can configure the OAAM Server to support one or more Web application authentication and user registration flows. The OAAM Server configuration is specific to the UIO Proxy deployment. The OAAM UIO Proxy offers multifactor authentication to Web applications without requiring any change to the application code.

Figure 8-2 Universal Installation Deployment

The UIO Proxy can be placed in front of multiple applications and customized to work with each one as required.

To ensure that a customer's data is unique from that of other customers, an Application ID for the client application is mapped to an Organization ID. An Organization ID identifies what tenant applications a user utilizes.

The initial steps to configure and customize OAAM Server are:

Determine the application ID of each application being secured.
Assign default user groups for each application being secured.

8.6.1 Determining the Application ID

Determine how many applications are to be configured and assign each application an Application ID. This Application ID is the same one used to configure the Proxy (see Chapter 6, "Oracle Adaptive Access Manager Proxy"). In many cases applications are referred to internally by some name or abbreviation, so an integrator configuring OAAM Server might want to use that name. For an example, if the client has two applications, one wholesale banking application and one retail banking application, the integrator might choose to use wholesale and retail as the Application IDs for the two applications.

This Application ID is the same one used to configure the Proxy (see Chapter 6, "Oracle Adaptive Access Manager Proxy").

The Proxy will send the AppId to OAAM Server as needed via an HTTP header. This AppId is then used to determine which configuration is used when displaying pages to the client. OAAM Server is configured by a set of properties which will be discussed in more detail later.

An example of how AppId is used to define a property in the OAAM server is shown:

bharosa.uio.appId1.default.user.group=app1Group

The bold "appId1" is the location in the property where the AppId is used to configure application specific values.

8.6.2 Determining Default User Groups

Each application can be configured to have a unique default user group. This is the group that a user of that application will be associated with as their Organization ID when the user is first created in the Oracle Adaptive Access Manager database. The Organization ID is used when a user attempts to log in to the application and user data is loaded from the database.

An example of how Organization ID is used in a property definition is shown as follows:

bharosa.uio.appId1.default.user.group=app1Group
bharosa.uio.appId2.default.user.group=app2Group

In the example, two Organization IDs are defined to two different applications. The application with an AppId of "appId 1" has been assigned the Organization ID of "app1Group" and the application with an AppId of "appId2" has been assigned the Organization ID of "app2Group".

8.6.3 Configuring Application Properties

An application in OAAM Server is made up of a grouping or set of properties. You can configure OAAM Server properties on a global or application specific level.

OAAM Server property names are prefixed with bharosa.uio. They are followed by the Application ID or default if the setting is global.

Property definitions that start with bharosa.uio.default apply to all Application IDs unless overridden by a more specific value.

In the following example, default is used instead of the appId to designate the property as a global default. The property is used across all applications of the OAAM Server installation unless a specific application has another location specified.

bharosa.uio.default.header = /globalcustomHeader.jsp
bharosa.uio.default.footer = /globalcustomFooter.jsp

The default properties for the path to the custom header and footer are:

bharosa.uio.default.header = path_to_custom_header.jsp
bharosa.uio.default.footer = path_to_custom_footer.jsp

An application-level property is one that only effects a single application when there are more than one application defined in the properties.

In the following example, app1 uses an application-level defined header and footer file, but app2 uses an application-level defined footer but a global or default defined header file.

bharosa.uio.default.header = /globalcustomHeader.jsp
bharosa.uio.default.footer = /globalcustomFooter.jsp
bharosa.uio.app1.header = /app1customHeader.jsp
bharosa.uio.app1.footer = /app1customFooter.jsp
bharosa.uio.app2.footer = /app2customFooter.jsp

8.6.4 Property Extension

In addition to configuring properties for each application, you can configure a set of properties that several applications have in common. You can then extend that set to customize the parameters that differ between the set of applications.

If you were to configure three applications that all use a single footer, but each has a unique header, you can include the following properties:

bharosa.uio.myAppGroup.footer = /myAppGroup/customFooter.jsp
 
bharosa.uio.appId1.extends=myAppGroup
bharosa.uio.appId1.header=/client/app1/customHeader.jsp
 
bharosa.uio.appId2.extends=myAppGroup
bharosa.uio.appId2.header==/client/app2/customHeader.jsp
 
bharosa.uio.appId3.extends=myAppGroup
bharosa.uio.appId3.header==/client/app3/customHeader.jsp

8.7 Customizing the Appearance of OAAM Server

This section describes how to customize the appearance of the OAAM user interface in a Web browser.

The OAAM Server user interface branding is customized in several ways.

Custom header / footer files
Custom CSS file
Custom properties for page content and messaging

8.7.1 Customizing Headers and Footers

You can create custom header and footer files for the applications being secured. The header and footer files are JSP files and can contain any HTML or JSP code required to replicate the look of the application being secured.

Create a work folder called oaam_extensions. (The folder can be created anywhere if it is outside the installation folder.)
Locate oracle.oaam.extensions.war in the following directory:
```
IAM_Home/oaam/oaam_extensions/generic
```
Extract oracle.oaam.extensions.war in the oaam_extensions folder.
In the oaam_extensions folder, create the following subfolders:
```
/client/app1/
/client/app1/images/
```
Create a customHeader.jsp and customFooter.jsp inside the client/app1/ folder.

The header (customHeader.jsp) and footer (customFooter.jsp) files should contain only content HTML, all page related tags (<html>, <head>, <body>, and so on) are already provided by OAAM Server.

As a simple example, a header and footer are created that contain a single image each, to be used as the header and footer of an application called "appId1".

Copy the following code into customHeader.jsp for the header.
```
/client/app1/customHeader.jsp
     <img src="client/app1/images/customHeader.jpg" alt="Welcome to App1"/>
```
Copy the following code into customFooter.jsp for the footer.
```
/client/app1/customFooter.jsp
     <img src="client/app1/images/customFooter.jpg" alt="App1 Footer"/>
```
These files will be deployed in the "/client/app1/" directory within the Web application.
Add associated files to the client/app1 folder as needed.

For example, the customHeader.jpg and customFooter.jpg image files referenced by customHeader.jsp and customFooter.jsp.
```
/client/app1/images/customHeader.jpg
/client/app1/images/customFooter.jpg
```
Open the bharosa_server.properties file in the WEB-INF/classes/bharosa_properties directory of the oracle.oaam.extensions.war file.
To associate these header and footer files with the application, add the following properties to bharosa_server.properties and save it to oaam_extensions/WEB-INF/classes/bharosa_properties.
```
bharosa.uio.appId1.header = /client/app1/customHeader.jsp
bharosa.uio.appId1.footer = /client/app1/customFooter.jsp
```
Repackage 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 new JSP files, referenced images, and added properties in bharosa_server.properties are included in the new WAR file.
Shut down the OAAM Admin and OAAM Server managed servers.
Start the WebLogic Server where Oracle Adaptive Access Manager is deployed and log in to the WebLogic Administration Console.
Navigate to Domain Environment > Deployments and lock the console.
Click the Install button.
Browse to the location of the oracle.oaam.extensions.war file and select it by clicking the radio button next to the .war file and clicking Next.
Ensure Install this deployment as a library is selected and click Next.
Select OAAM Admin and OAAM Server servers as deployment targets.
Click Next again to accept the defaults in this next page and then click Finish.
Click the Save button and then Activate Changes.
Start the OAAM Admin and OAAM Server managed servers.

8.7.2 Modifying User Interface Styles

You can create a custom Cascading Style Sheet (CSS) to create a custom user interface. The CSS file provides control over backgrounds, font colors and sizes, and so on. The default CSS file, oaam_uio.css, is located in the css directory. You can override the styles in this CSS file using a custom CSS file. Use the file for an application or at a global level. Refer to Section 8.6.3, "Configuring Application Properties."

For example, to override the font-family of the default body style definition:

Create a work folder called oaam_extensions.

The folder can be created anywhere if it is outside the installation folder.
Locate oracle.oaam.extensions.war, which is located in the IAM_Home/oaam/oaam_extensions/generic directory.
Explode oracle.oaam.extensions.war into the oaam_extensions folder.
Create the client/app1/css directory.
Create an app1.css file.

Add the following code to the app1.css file.

body{
    background-color:#ffffff;
    font-size:12px;
    color:#000000;
    font-family:arial,helvetica,sans-serif;
    margin:0px 0px 0px 0px
}

Change Helvetica to the primary font-family you want to use for your appId1 application.
Add the file to the /client/app1/css directory.
Open the bharosa_server.properties file in the WEB-INF/classes/bharosa_properties directory of the oracle.oaam.extensions.war file.
To use the newly created file, set the following property in bharosa_server.properties:
```
bharosa.uio.appId1.custom.css=/client/app1/css/app1.css
```

Repackage 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/ .

Shut down the OAAM Admin and OAAM Server managed servers.
Start the WebLogic Server where Oracle Adaptive Access Manager is deployed and log in to the Oracle WebLogic Administration Console.
Navigate to Domain Environment > Deployments and lock the console.
Click the Install button.
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.
Ensure Install this deployment as a library is selected and click Next.
Select OAAM Admin and OAAM Server servers as deployment targets.
Click Next again to accept the defaults in this next page and then click Finish.
Click the Save button and then Activate Changes.
Start the OAAM Admin and OAAM Server managed servers.

Any style defined in the oaam_uio.css in the OAAM Server ear file can be overridden in this manner if required.

8.7.3 Customizing Content and Messaging

You can customize content and messaging of the OAAM server pages by adding properties to the client_resource_locale.properties file.

Some customizable items, like page title and message, are applicable for each page. While other items, like login blocked message, are specific to a particular page.

To customize content and messaging:

Create a work folder called oaam_extensions. (The folder can be created anywhere if it is outside the installation folder.)
Locate oracle.oaam.extensions.war, which is located in the IAM_Home/oaam/oaam_extensions/generic directory.
Explode oracle.oaam.extensions.war into the oaam_extensions folder.
Create a client_resource_locale.properties file in oaam_extensions\WEB-INF\classes.
Add the customized message to this file.

For example, to change the page title on the login page for the appId1 application, add the following line to client_resource_locale.properties:
```
bharosa.uio.appId1.signon.page.title=Welcome to App1, please sign in. 
```
For example, to customize the error message displayed when a user has been blocked by security rules, add the following line to client_resource_locale.properties:
```
bharosa.uio.appId1.login.user.blocked = You are not authorized to login. Please contact customer service at 1-888-555-1234.
```

Repackage 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/ .

Shut down all managed servers.
Start the WebLogic Server where Oracle Adaptive Access Manager is deployed and log in to the Oracle WebLogic Administration Console.
Navigate to Domain Environment > Deployments and lock the console.
Click the Install button.
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.
Ensure Install this deployment as a library is selected and click Next.
Select OAAM Admin and OAAM Server servers as deployment targets.
Click Next again to accept the defaults in this next page and then click Finish.
Click the Save button and then Activate Changes.
Start the OAAM Admin and OAAM Server managed servers.

8.8 Questions/Answers About User Interface Customization

A few troubleshooting tips for user interface customization are provided below:

Question: I have added the following entries to bharosa_server.properties in the OAAM extensions shared library:
```
bharosa.uio.default.header = /customHeader.jsp
bharosa.uio.default.footer = /customFooter.jsp
```
OAAM server is picking up the default header and footer and not the one I specified in the extensions library.

Answer: The custom header / footer files should have a unique name as OAAM Server pulls from the web application first. For example, customHeader.jsp and customFooter.jsp.
Question: Why is the OAAM Server not picking up the css changes in OAAM extensions shared library?

Answer: The property "bharosa.uio.default.custom.css" should be set to a css file that is added to the extensions library. That css file can override any existing CSS definitions in the base application (defined by oaam_uio.css).
Question: How do struts_config_extension.xml and tiles-def-extension.xml work in customization?

Answer: The OAAM extensions shared library has a struts-config-extension.xml and tiles-def-extension.xml in the WEB-INF directory. Any values added to these will augment or override the ones already defined by struts-config.xml and tiles-def.xml in the application.

For example, to use a customized jsp (customUserPreferences.jsp) in place of the base file (userPreferences.jsp), add the following to tiles-def-extension.xml:
```
<definition name="userPreferences" extends="bharosa.uio.baseLayout">
   <put name="body" value="/customUserPreferences.jsp"/> 
</definition> 
```