I have been asked several times over the years if there is a way to customize the following error message a User is presented in their Internet browser when the WebGate fails to contact any of the Access Servers.
Oracle Access Manager Operation Error
The WebGate plug-in is unable to contact any Access Servers.
Contact your website administrator to remedy this problem.
Though this error is without a doubt accurate, many clients would rather display something a little more friendly or have other reasons to change it. Interestingly this error has been the same message going back to the early days of OAM when it was still Oblix. Incidently there is a great My Oracle Support document 555137.1 that provides steps on how to customize the error message, but it refers to OAM 10g. So this begs the question will this work with the newer OAM 11g, and more specifically 11g WebGates. I am here to say, “Yes it does”, I have tested this and this article covers this option and a bit more.
Lets Get Some Questions Out of the Way
I have been asked if there are alternate ways of customizing the error message. For example if using Apache or OHS, why not put a customized message in the ErrorDocument 500 inside the httpd.conf file; http://httpd.apache.org/docs/2.2/mod/core.html - error document. Good question because the WebGate does use a parameter HTMLpage500 so you would think it can just be as simple as modifying the 500 error. However I tried and this does not work and for good reasons. The WebGate becomes the main gatekeeper, so if it cannot communicate to any Access Servers to make security decisions it will basically shutdown and reject all traffic to make sure nothing is compromised hence why it immediately lets people know the OAM Access Servers are down…do something!!
Then what about telling a load balancer in front of the web servers that have the WebGates to redirect to an alternate place? One problem is the load balancer is not intelligent enough to know if the WebGate is down. Another is if you could redirect, how is security taken care of? It is not as simple as it sounds.
At this point the best option is to leverage the article I mentioned, I feel this option is the best right now and it is not that complicated to implement. So let's move on and find out how to do it.
How to Create Your Custom Error Page
As I mentioned earlier, there is an article OAM 10g: How To Display A Custom Error Page When the Access Server Is Down? / WebGate Plug-in is Unable to Contact any Access Servers (Doc ID 555137.1), which I spent a lot of time validating that it works for 11g WebGates, and as I said it does. Though I don't really provide any additional ways that the article shows on how to generate a custom error message, I do go a little beyond the article and explain an easy way to make the custom message. So lets get into it now.
1. Update the WebGate.xml file message tag ErrEngineDown
The key to this customization is updating a file called WebGate.xml. It is located in the WebGate install path under <WebGate install path>/wg1_home/webgate/ohs/lang/en-us. Now I used “en-us” for English, but if your environment requires a different language, look under “/lang/” and you will see other languages and within each language is a WebGate.xml file. So make sure the correct WebGate.xml file is being updated. Use an editor and open the WebGate.xml file and search for ErrEngineDown. Now change the default ErrEngineDown message “The WebGate plug-in is unable to contact any Access Servers.” with the custom message you want. This text will be output to the error page when the WebGate cannot contact any of the Access Servers for some reason. Be sure to make a backup of the original WebGate.xml file in case you need to revert back.
The key to this customization is updating a file called WebGate.xml. It is located in the WebGate install path under <WebGate install path>/wg1_home/webgate/ohs/lang/en-us. Now I used “en-us” for English, but if your environment requires a different language, look under “/lang/” and you will see other languages and within each language is a WebGate.xml file. So make sure the correct WebGate.xml file is being updated. Use an editor and open the WebGate.xml file and search for ErrEngineDown. Now change the default ErrEngineDown message “The WebGate plug-in is unable to contact any Access Servers.” with the custom message you want. This text will be output to the error page when the WebGate cannot contact any of the Access Servers for some reason. Be sure to make a backup of the original WebGate.xml file in case you need to revert back.
2. Make your HTML Custom Error Page
Next there is another message tag inside the WebGate.xml file called HTMLpage500. This tag can actually hold a real HTML page that will be displayed for the end user, so it is a lot more flexible. So the best thing is to create some basic HTML you want the custom page to display, and note if possible try to avoid images. If you require images the reference to the images will need to point to some other external web server because when the OAM servers are down, the WebGate will basically not even let the web server work because it is trying to stop anyone from getting in; this is a security feature by design. So go ahead and create the HTML page you want to display for the end user. Note toward the end of this article there is a neat little trick you can do.
Next there is another message tag inside the WebGate.xml file called HTMLpage500. This tag can actually hold a real HTML page that will be displayed for the end user, so it is a lot more flexible. So the best thing is to create some basic HTML you want the custom page to display, and note if possible try to avoid images. If you require images the reference to the images will need to point to some other external web server because when the OAM servers are down, the WebGate will basically not even let the web server work because it is trying to stop anyone from getting in; this is a security feature by design. So go ahead and create the HTML page you want to display for the end user. Note toward the end of this article there is a neat little trick you can do.
3. Convert the HTML to XML
Now in the previous step you created some custom HTML page, but before you insert this custom message into the WebGate.xml it needs to be converted to XML. To better understand, the less than sign < needs to be converted to < and a greater than sign > needs to be converted to >. This certainly could tediously be done manually, but a much easier way is take the HTML, copy and paste it into this online HTML to XML converter https://sites.google.com/site/infivivek/resourse-centre/online-resources/html-to-xml-converter, click the Convert button, and whala you have XML. Once you have the XML version of the HTML, copy it and go to the next step.
Now in the previous step you created some custom HTML page, but before you insert this custom message into the WebGate.xml it needs to be converted to XML. To better understand, the less than sign < needs to be converted to < and a greater than sign > needs to be converted to >. This certainly could tediously be done manually, but a much easier way is take the HTML, copy and paste it into this online HTML to XML converter https://sites.google.com/site/infivivek/resourse-centre/online-resources/html-to-xml-converter, click the Convert button, and whala you have XML. Once you have the XML version of the HTML, copy it and go to the next step.
4. Update the WebGate.xml file message tag HTMLpage500 with the new XML.
The custom HTML page created earlier that was converted to XML can now be pasted into the WebGate.xml file. Edit the WebGate.xml file and search for HTMLpage500. Just like the ErrEngineDown message value, you will replace the default message with the XML copied from the previous step. This XML will be presented by the WebGate when the Access Servers are unavailable as an HTML page. Be sure to save the WebGate.xml file.
The custom HTML page created earlier that was converted to XML can now be pasted into the WebGate.xml file. Edit the WebGate.xml file and search for HTMLpage500. Just like the ErrEngineDown message value, you will replace the default message with the XML copied from the previous step. This XML will be presented by the WebGate when the Access Servers are unavailable as an HTML page. Be sure to save the WebGate.xml file.
5. Restart the Web Server
For the WebGate.xml file to take affect restart the web server.
For the WebGate.xml file to take affect restart the web server.
6. Repeat
Since each web server will have its own WebGate install, you will need to repeat the same process above and update each WebGate.xml. Alternatively an easier option is to simply copy the WebGate.xml file to the other WebGate install locations, there is no path reference to the install so copying the file is a safe and easy option. Your WebGate install may be installed in a common mount If using a UNIX operating system and if that is true you may not need to copy or update the WebGate.xml file across several web servers.
Since each web server will have its own WebGate install, you will need to repeat the same process above and update each WebGate.xml. Alternatively an easier option is to simply copy the WebGate.xml file to the other WebGate install locations, there is no path reference to the install so copying the file is a safe and easy option. Your WebGate install may be installed in a common mount If using a UNIX operating system and if that is true you may not need to copy or update the WebGate.xml file across several web servers.
7. Test the Custom Message by shutting down the OAM Access Servers
Finally we need to make sure it works. To test the custom message, login to a WebGate protected application or page. Then shut down all the OAM Access Servers so that the WebGate will act on this error. Once all the Access Servers are down, refresh the browser and you should see the new custom message. If not, review the WebGate oblog.log file to see if there are any errors that can help troubleshoot, or make sure the WebGate.xml file is correct.
Finally we need to make sure it works. To test the custom message, login to a WebGate protected application or page. Then shut down all the OAM Access Servers so that the WebGate will act on this error. Once all the Access Servers are down, refresh the browser and you should see the new custom message. If not, review the WebGate oblog.log file to see if there are any errors that can help troubleshoot, or make sure the WebGate.xml file is correct.
Another HTMLpage500 option
The MOS article 555137.1 has a good option that adds a little META http-equiv=”REFRESH” method redirect, which redirects in zero seconds the browser to an alternate web page all together. This trick will work on all web browsers. However It would require an alternate web server that is running, and that web server could not have a WebGate because if it did that web server would also stop serving up HTML content. It is a clever option and certainly something worth thinking about.
Optional Actual HTML
<HTML>
<HEAD>
<TITLE>OAM Engine Down</TITLE>
<meta http-equiv="REFRESH" content="0;url=http://www.oracle.com/index.html">
</HEAD>
<BODY>
</BODY>
</HTML>
<HEAD>
<TITLE>OAM Engine Down</TITLE>
<meta http-equiv="REFRESH" content="0;url=http://www.oracle.com/index.html">
</HEAD>
<BODY>
</BODY>
</HTML>
Converted HTML to XML
<HTML>
<HEAD>
<TITLE>OAM Engine Down</TITLE>
<meta http-equiv="REFRESH" content="0;url=http://www.oracle.com/index.html">
</HEAD>
<BODY>
</BODY>
</HTML>
<HEAD>
<TITLE>OAM Engine Down</TITLE>
<meta http-equiv="REFRESH" content="0;url=http://www.oracle.com/index.html">
</HEAD>
<BODY>
</BODY>
</HTML>
In summary, this solution will provide a working option to create a custom error page when the OAM Access Servers are down. Feel free to play around with different messages and most of all test them to make sure they work. Enjoy!
Posts
No comments:
Post a Comment
Note: Only a member of this blog may post a comment.