How to Build a URL-Based SSL Portlet

Oracle Application Server Portal Developer Kit
How to Build a URL-Based SSL Portlet

Creation Date:	November 13, 2003
Status:	Production
Version:	PDK Release 9.0.4

Introduction
Assumptions
Pre-Installation
Creating an XML provider definition
Building the SSL portlet
Troubleshooting

Introduction

Note: URL-based portlets enable you to expose content from external websites as portlets using a manual, XML file-based approach. However, if you are targeting your provider to be registered with OracleAS Portal 9.0.2 or later, the recommended approach to perform the same task is to use the Web Clipping Portlet. To find out about using Web Clipping or how to migrate your URL-based portlet to Web Clipping, go to the OmniPortlet and Web Clipping area of Portal Center.

In the article, How to Build a URL-Based Portlet, you learned how to create a portlet that displayed the content of a URL-based application.á The example used in that article was Google.com.á The PDK-URL Services also enables you to create URL-based portlets that display the content of URLs secured by SSL (Secure Sockets Layer protocol).

This article shows you how to create a URL-based SSL portlet.á The example used in this article is the Online payments website (https://www.paypal.com).

Assumptions

You have successfully installed the PDK framework and samples by following the article Installing the PDK Framework and Samples.
You have successfully installed the URL-based portlets runtime and samples by following the article Installing the URL-based portlet samples.

Pre-Installation

Make sure the following jar files are located in ORACLE_HOME/jlib folder. Copy them to OC4J_HOME/lib folder.

http_client.jar
javax-ssl-1_2.jar
jssl-1_2.jar

Note : OC4J_HOME corresponds to the directory where OC4J is installed. For example D:\Oracle\OC4J\ in case of NT. In case OC4J standalone version, these files are location under D:\Oracle\OC4J\jlib directory, assuming OC4J.zip was extracted to D:\Oracle directory.

You must also make sure that the appropriate SSL library is configured in the operating system path.

For Windows NT/2000:
Add njssl9.dll to the OS path.á For example,
```
set path=%path%;{ORACLE_HOME}/lib
```

For Solaris:

Add libnjssl9.so to the LD_LIBRARY_PATH.á For example,

setenv LD_LIBRARY_PATH {ORACLE_HOME}/lib:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH

Note : Oracle 8.1.7 DB installation contains njssl8.dll (in case of NT) and libnjssl8.so (in case of Solaris) in ORACLE_HOME/bin directory. Please rename them to njssl9.dll and libnjssl9.so respectively and add their location to the system path as described above.

Creating an XML provider definition

This section explains how to create an XML provider definition for your URL-based portlet provider.á You can configure provider-specific information like portlet title and portlet description in the XML file.á This XML file is also where you specify the URL that gets displayed in your portlet.

Using a text editor, create a new XML provider definition.á

You may use the sample below (you must change the httpProxyHost, httpProxyPort, httpsProxyHost and httpsProxyPort values to your own proxy server and port; if you do not need a proxy server then remove those tags).á Further, SSL specific information is specified through a wallet, created using Oracle Wallet Manager. The wallet can be exported in text format and used by JavaSSL. The exported text file contains the user certificate, followed by the private key, the certificate chain, and any other trusted certificates. Follow the viewlet to learn how to create wallets and export them to text files.

Please refer to the article Understanding the provider.xml for PDK-URL Services for an explanation of the required XML tags and their functions.

<?xml version="1.0" encoding="UTF-8"?>
<?providerDefinition version="3.1"?>
<provider class="oracle.portal.provider.v2.http.URLProviderDefinition">
  <providerInstanceClass>oracle.portal.provider.v2.http.URLProviderInstance</providerInstanceClass>
  <session>true</session>
  <proxyInfo class="oracle.portal.provider.v2.ProxyInformation">
    <httpProxyHost>www-proxy.us.oracle.com</httpProxyHost>
    <httpProxyPort>80</httpProxyPort>
  </proxyInfo>
  <httpsProxyInfo class="oracle.portal.provider.v2.ProxyInformation">
    <httpsProxyHost>www-proxy.us.oracle.com</httpsProxyHost>
    <httpsProxyPort>80</httpsProxyPort>
  </httpsProxyInfo>
  <portlet class="oracle.portal.provider.v2.http.URLPortletDefinition">
    <id>1</id>
    <name>SSL Portlet</name>
    <title>Paypal HTTPS Portlet</title>
    <description>This portlet is to test URL-based portlets using paypal</description>
    <timeout>100</timeout>
    <timeoutMessage>SSL portlet timed out</timeoutMessage>
    <showEdit>false</showEdit>
    <showEditDefault>false</showEditDefault>
    <showPreview>false</showPreview>
    <showDetails>false</showDetails>
    <hasHelp>false</hasHelp>
    <hasAbout>false</hasAbout>
    <acceptContentType>text/html</acceptContentType>
    <registrationPortlet>false</registrationPortlet>
    <accessControl>public</accessControl>
    <renderer class="oracle.portal.provider.v2.render.RenderManager">
    <showPage class="oracle.portal.provider.v2.render.http.URLRenderer">
        <contentType>text/html</contentType>
        <pageUrl>https://www.paypal.com</pageUrl>
        <walletLocation>D:\pdk\wallet\wallet.txt</walletLocation>
        <walletPassword>welcome</walletPassword>
        <filterType>text/html</filterType>
        <filter class="oracle.portal.provider.v2.render.HtmlFilter">
          <headerTrimTag>&lt;body</headerTrimTag>
          <footerTrimTag>/body></footerTrimTag>
          <convertTarget>true</convertTarget>
        </filter>
      </showPage>
    </renderer>
    <securityManager class="oracle.portal.provider.v2.security.URLSecurityManager">
      <authorizType>public</authorizType>
    </securityManager>
  </portlet>

</provider>

Save the file as "provider.xml", making sure not to overwrite one of the PDK sample files of the same name.á

Building the SSL Portlet

At this point, you are ready to build your SSL portlet. The steps required to build the SSL portlet are the same steps as those described in the article, How to Build a URL-Based Portlet. Proceed by following all of the steps in that article, using https://www.paypal.com for the value of the pageUrl tag in the provider.xml file. You should then be able to deploy and register your SSL portlet in the exact same manner as the Google.com portlet described in the How to Build a URL-Based Portlet article.

Troubleshooting

Following are the frequently encountered problems and their solutions. These exceptions and errors will be logged into the JPDK log file present in OC4J_HOME/application-deployments/jpdk/application.log file.

java.lang.UnsatisfiedLinkError: no njssl9 in java.library.path

Make sure njssl9.dll file is in the system path. Please see above to learn how to do it.

java.io.IOException: javax.net.ssl.SSLException: SSL handshake failed: X509CertChainInvalidErr

Most probable reason could be invalid location of wallet. Make sure you have correctly exported wallet and specified its location through <walletLocation> tag. Verify <walletPassword> as well. It can also occur when the site being viewed uses a certificate signed by a CA, who is not present in the Wallet's Trusted List of CAs. Solution is to install the certificate available through the site and add it to the trusted certificate list in Wallet Manager.

Revision History:

Revision No	Last Update	Description
1.0	October 28, 2002	Created
1.1	November 13, 2003	Added Web Clipping note

Oracle Corporation
World Headquarters
500 Oracle Parkway
Redwood Shores, CA 94065, USA
http://www.oracle.com/

Worldwide Inquiries:
1-800-ORACLE1
Fax 650.506.7200

Oracle Application Server Portal Developer Kit How to Build a URL-Based SSL Portlet