Oracle Access Manager Error page customised

WebCenter Portal is usually integrated with Oracle Access Manager (OAM) to manage its authentication. This integration has several advantages such as enabling Single Sign On (SSO) across all Oracle products, but it may cause some problems to end users.

Issue

Recently, a client with a private users area received complaints regarding an unexpected error page been displayed in Portal. Even a user tweeted that page tagging the company, so the problem was considered critical to the top management. The page was the following standard unfriendly OAM error page:

The URL was: /oam/server/auth_cred_submit.

Firstly, we tried to reproduce the issue, which was not easy because users did not remember the actions they performed. After some testing, the issue was reproduced:

1. Access protected URL.
2. Portal application login page is displayed.
3. Introduce valid credentials.
4. Portal home page is accessed.
5. Click browser Back button.
6. OAM error page appears.

We tried to map that URL (auth_cred_submit) as an error by web server configuration, but that was not a solution because it was actually the URL that performs login too.

The explanation of this error is:

• The login page submits the "request_id" or the "OAM_REQ" value sent by OAM when redirecting to the external login page. 
• When user introduces credentials and click login, a value for request_id is set into the HTTP Header.
• The back button does not reset the values already set via cookie or Header information into the browser. 
• The second time "auth_cred_submit" is accessed, the values from the previous login are sent to the server, which interprets them as invalid because are from a different session. 

So Oracle Support was contacted about this problem. If that page could not be avoided, at least we wanted to have it customised.

Solution

 

Apparently, that OAM page cannot be customised, but the engineer managed to reproduce the issue and built an effective workaround. It involves deploying a custom pages application in OAM application server.

1. Copy oamcustompages.war file in a local machine. This file is located in the following path: $IDM_HOME/oam/server/tools/custompages/
2. Unpack this war file.
3. Navigate to the "pages" folder inside the uncompressed war and create a page named: Error.html. That page would contain the HTML code to be displayed in the reproduced scenario, so it should include the cient look&feel.
4. Other pages in that folder may be deleted.
5. Compress the folders back to oamcustompages.war. Then rename that file, i.e. oamcustompages1.war.
6. Deploy the war in the application server where OAM is running. For information about deploying an application to WebLogic Server, check this link.
7. OAM Custom Pages must be updated using WLST:
   7.1 Start WebLogic Scripting Tool (WLST) in OAM Oracle home, located under the installation folder: /Oracle_IDM1/common/bin).
   
   7.2. Connect to the Weblogic AdminServer as the Weblogic Administration User.
   For instance:
   wls:/offline> connect();
   Please enter your username [weblogic] :weblogic
   Please enter your password [welcome1] :Oracle
   Please enter your server URL [t3://localhost:7001] :t3://oamadminserver.oracle.com:7001
   
   7.3. Execute the following WLST command:
   updateCustomPages(pageExtension ="html", context="/oamcustompages1");
   
   Where context is the name assigned to the war file in step 5.
   You should receive the following message: "Custom page configuration updated successfully"
   
   8. Test the scenario. A new error message should be displayed, defined in Error.html file.

This solution works perfectly for our scenario, but we also wanted to avoid displaying an error page to the final users. So Error.html was modified to add a javascript redirect to OAM logout page:

<meta http-equiv="refresh" content="0;url=/../oam/server/logout?end_url=/myApp">

As this content is in the page header, as soon as it starts loading, user is redirected to logout page, where session cookie (OAMAuthnCookie_) is removed. Eventually, the login page is displayed to the user, this is specified by the URL parameter end_url. So customers would not even see the error page.

References

Oracle Service Request: SR 3-10186096271 : OAM how to avoid auth_cred_submit page to be displayed to users
Installing and Configuring OAM with WebCenter Portal
Benefits of Oracle Access Manager
Deploying Applications to WebLogic Server
WebLogic Scripting Tool Command Reference 
Enabling Error Page Customization
Using meta refresh to create an instant client-side redirect
Configuring Centralized Logout for OAM 11g

Forcing maintenance page in WebCenter

When a WebCenter environment requires a shutdown or a restart, it is advisable to present a friendly error page instead of the traditional "Failure of server Apache bridge". This can be easily achieved by implementing a static html page and configuring OHS. This can be applied to other applications too.

The maintenance page could have a html structure similar to the web template, or it could just be an image with a friendly message. For example, maintenance.html could be defined as follows:

<!doctype html>

<html>

<head>

<meta charset="utf-8">

<meta http-equiv="X-UA-Compatible" content="IE=edge">

</head>

<body>

    <div>

        <img src="/Static/ClientPages/img/Maintenance.jpg">                   

    </div>   

</body>

</html>

Once page is uploaded to the server, some code must be inserted inside the OHS virtual host element in the configuration file (mod_wl_ohs.conf). For instance, the following code redirect all the OHS requests to the plain maintenance page.

RewriteEngine On

RewriteCond %{SCRIPT_FILENAME} !/Static/ClientPages/*

RewriteRule ^.*$ /Static/ClientPages/maintenance.html [R=503,L]

Header Set Cache-Control "max-age=0, no-store"

After that, OHS instance needs to be restarted using the opmnctl command.

Also, it is interesting to set error pages to different HTTP status codes. The following lines force the display of error and maintenance pages depending on the type of errror: Internal server error (500) or Service unavailable (503).

ErrorDocument 500 /Static/ClientPages/error.html

ErrorDocument 503 /Static/ClientPages/maintenance.html

Other options are:

• IP exceptions: It is possible to set IP exceptions to the redirect operation, that could be developers' addresses.

           RewriteCond %{REMOTE_ADDR} !^123\.456\.789\.000

• Checking first if the maintenance page exists.

           RewriteCond /Static/ClientPages/maintenance.html -f

• External switch to enable and disable maintenance: OHS redirects to maintenance pages if a file exists.

           RewriteCond /Static/ClientPages/maintenance.enable -f

These options are well explained in this post.

References:

Redirect Site to Maintenance Page using Apache and HTAccess
Setting a WebCenter Maintenance Page
HTTP status codes
Apache mod_rewrite