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:
Figure 8-1 shows the UIO Proxy 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.
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."
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.
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.
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."
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
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."
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
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.
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.
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.
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.
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".
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
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
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
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.
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.
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.
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>