Oracle® Fusion Middleware Developer's Guide for Oracle Adaptive Access Manager Release 11g (11.1.1) E15480-06 |
|
![]() Previous |
![]() Next |
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.
OAAM Server configuration is controlled through property files.
Configuration Files
Use the following property files to configure OAAM Server:
bharosa_server.properties
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 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.
In the deployed application, the bharosa_server.properties
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."
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.
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:
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 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:
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".
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
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.
/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 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
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:
body{ background-color:#ffffff; font-size:12px; color:#000000; font-family:arial,helvetica,sans-serif; margin:0px 0px 0px 0px }
Now to use your newly created file, you will add the following property to bharosa_server.properties:
bharosa.uio.appId1.custom.css=/client/app1/css/app1.css
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.
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
.
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 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.
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.
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
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.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=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, "Customizing Oracle Adaptive Access Manager."
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:
bharosa.uio.appId1.credentials.enum.profileid.enabled=false