6 Configuring OAAM Server

This chapter provides information on customizing the client-facing OAAM Server Web application. The Oracle Adaptive Access Manager Universal Installation Option offers multifactor authentication to Web applications without requiring any change to the application code. The OAAM Server configuration is specific to the Universal Installation Option deployment. Refer to the architectural diagram (Figure 6-1) for the components involved.

The user interface provided by the OAAM Server Web application can be easily customized to achieve the look-n-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

• OAAM Server Settings

• Determining Application ID and User Group

• Customizing User Interface Branding

• Configuring Application Properties

6.1 Architecture

Figure 6-1 shows an Oracle Adaptive Access Manager Universal Installation Option deployment.

Figure 6-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.

6.2 OAAM Server Settings

OAAM Server configuration is controlled through property files.

Configuration Files

Use the following property files to configure OAAM Server:

• bharosa_server.properties or bharosauio_client.properties

  • for client-configured properties (any properties that have been customized for a specific deployment)

  • for Universal Installation Option 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.

• client_resource_<locale>.properties where <locale> is the locale string for which you wish to use the custom values (en, es, and others)

  • for 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).

  • for Universal Installation Option messaging and page content configuration. For example, page titles, links at the bottom of the pages, page messages, error message, and confirmation messages.

In the deployed application, the bharosa_server.properties and bharosauio_client.properties files are 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 12, "Customizing Oracle Adaptive Access Manager."

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

6.3.1 Determining the Application ID

The Universal Installation Option 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 5, "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 we will discuss in more detail later. An example of how AppId is used in a property definition is shown as follows:

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.

6.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 looks 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".

6.4 Customizing User Interface Branding

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

6.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>, etc) are already provided by OAAM Server. As a simple example we will create a header and footer 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.

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

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

/client/app1/footer.jsp
       <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 we 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

6.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 6.5, "Configuring Application Properties."

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

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

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

Now to use our newly created file, we will add the following property:

bharosa.uio.appId1.custom.css=/client/app1/css/app1.css

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

6.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 our example "appId1" application, we would add the following line to client_resource_<locale>.properties.

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

bharosa.uio.appId1.signon.page.title=Welcome to App1, please sign in.

The contents of error messages are also controlled in the same way. In the following example we 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.

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

6.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
 
bharosa.uio.appId1.extends=myAppGroup
bharosa.uio.appId1.header=/client/app1/header.jsp
 
bharosa.uio.appId2.extends=myAppGroup
bharosa.uio.appId2.header==/client/app2/header.jsp
 
bharosa.uio.appId3.extends=myAppGroup
bharosa.uio.appId3.header==/client/app3/header.jsp

6.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=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.

6.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 6.5.2, "User-Defined Enums," if we wanted to change "Company ID" to "Profile ID" for only one application (appId1), we would need to do the following:

For example, using the User Defined Enum, if we wanted to change "Company ID" to "Profile ID" for only one application (appId1), we would need to do the following:

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

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

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