Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Adaptive Access Manager
Release 11g (11.1.1)

Part Number E15480-06
Go to Documentation Home
Go to Book List
Book List
Go to Table of Contents
Go to Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Go to next page
PDF · Mobi · ePub

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:

8.1 Architecture

Figure 8-1 shows the UIO Proxy deployment.

Figure 8-1 Universal Installation Deployment

This diagram shows a UIO 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 OAAM Server Settings

OAAM Server configuration is controlled through property files.

Configuration Files

Use the following property files to configure OAAM Server:

In the deployed application, the file is located in the web-inf/classes directory.

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, "Customizing Oracle Adaptive Access Manager."

8.3 Determining Application ID and User Group

The initial steps to configure and customize OAAM Server are:

  1. Determine the application ID of each application being secured.

  2. Assign default user groups for each application being secured.

8.3.1 Determining the Application ID

The UIO Proxy can be placed in front of multiple applications, and customized to work with each one as required. Determine how many applications are to be configured, 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.

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 in a property definition is shown as follows:

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

8.3.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 first created in the Oracle Adaptive Access Manager database. Similarly, it will be the Organization ID used to attempt to load user information from the database when a user attempts to log in to the application.

As used in the previous example the property for Organization ID appears as follows:

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.4 Customizing User Interface Branding

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

8.4.1 Custom Header / Footer

OAAM Server provides the ability to create custom header and footer files for applications being secured. The header and footer files are JSP and can contain any HTML or JSP code required to replicate the look of the application being secured. All the customer resources (JSP files, image files, HTML, and others) should be copied into the deployed application directories along with the OAAM Server Web application.

The header (header.jsp) and footer (footer.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 a file called header.jsp for the header.

        <img src="/client/app1/images/header.jpg" alt="Welcome to App1"/>

Copy the following code into a file called footer.jsp for the footer.

       <img src="/client/app1/images/footer.jsp" alt="App1 Footer"/>

These files will be housed in the "/client/app1/" directory within the Web application.

To associate these files with the application you would add the following properties to client_resource_<locale>.properties:

bharosa.uio.appId1.header = /client/app1/header.jsp
bharosa.uio.appId1.footer = /client/app1/footer.jsp

8.4.2 Custom CSS

OAAM Server styles are controlled through a single CSS file, bharosa_uio.css, located in the css directory. These styles can be overridden by including a custom CSS file. Much like the header and footer example show previously, you can create your own file and include that file on an application or global level through properties. Refer to Section 8.5, "Configuring Application Properties."

In this example you will override the font-family of the default body style definition.

The body style in bharosa_uio.css is defined as follows:

    margin:0px 0px 0px 0px

Now to use your newly created file, you will add the following property to


In this case, all you did was change Helvetica to the primary font-family in your "appId1" application. Any style defined in bharosa_uio.css can be overridden in this manner if required.

8.4.3 Custom Content and Messaging

OAAM Server pages have a variety of content and messaging sections. These sections can be customized by properties in client_resource_<locale>.properties. 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 change the page title on the login page in the example "appId1" application, you would add the following line to client_resource_<locale>.properties.

To change the page title on the login page in the example "appId1" application, you would add the following line to client_resource_<locale>.properties. to App1, please sign in.

The contents of error messages are also controlled in the same way. In the following example you will customize the error message displayed when a user has been blocked by security rules.

bharosa.uio.appId1.login.user.blocked = You are not authorized to login. Please contact customer service at 1-888-555-1234.

8.5 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.

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

For example,

# Global or Default header and footer definitions
# - Apply to all applications that don't specifically define their own
bharosa.uio.default.header = /globalHeader.jsp
bharosa.uio.default.footer = /globalFooter.jsp
# Application specific definitions
# - These values override the default settings
bharosa.uio.app1.header = /app1Header.jsp
bharosa.uio.app1.footer = /app1Footer.jsp
bharosa.uio.app2.footer = /app2Footer.jsp

In this 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.

The bharosa.uio.default.header property, shown as follows, defines the location of the header file.

bharosa.uio.default.header = /globalHeader.jsp

The property is used across all applications of the OAAM Server installation unless the specific application has another location specified.

In the case shown, "default" is used instead of the Application ID to designate the property as a global default. If the same property is not defined for an application; then, this value will be used.

8.5.1 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/footer.jsp

8.5.2 User-Defined Enums

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.description=Company ID

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.5.3 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.5.2, "User-Defined Enums," 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.description=Profile ID

For instructions on customizing, extending, or overriding Oracle Adaptive Access Manager properties or enums, refer to Chapter 7, "Customizing Oracle Adaptive Access Manager."

8.5.4 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.5.3, "Overriding Existing User-Defined Enums," you would add the following line to remove "Profile ID" from the elements used by the application: