In the article How to Build a URL-Based Portlet, you learnt how to create a portlet that displayed the content of a URL-based application.  The example used in that article was Google.com.  However, often, you may wish to create a URL-based portlet that retrieves its content from an external application that is protected.  In other words, the URL you wish to display in your portlet may require you to enter specific user credentials.  With PDK-URL Services, you can create URL-based portlets that provide single sign-on to external applications requiring user credentials.

This article shows you how to create a URL-based portlet with single sign-on to an external application requiring user credentials.  The example used in this article is MyYahoo! Weather.  This example uses cookie-based sign-in.  If the URL you are using uses a different sign-in mechanism (i.e., basic authentication), please refer to the appropriate article.

ASSUMPTIONS

1. You have successfully installed the PDK-Java runtime and samples by following the article Installing the PDK-Java Framework and Samples.

2. You have successfully installed the PDK-URL Services runtime and samples by following the article Installing the URL Services Samples article.

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.

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

   You may use the sample below (you must change the httpProxyHost and httpProxyPort values to point to your own proxy server and port).  Note that the pageUrl tag specifies the URL that gets displayed in the portlet.  Also note that the authType sub-tag specifies the type of authentication this application uses.  Please refer to the article Understanding provider.xml for PDK-URL Services for an explanation of the required XML tags and their functions:

   <?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?> <?providerDefinition version="2.0"?> <provider class="oracle.portal.provider.v1.http.URLProvider" session="true"> <session>true</session> <authentication class="oracle.portal.provider.v1.http.Authentication"> <authType>ExternalApp</authType> <errorPageMessages>Invalid Yahoo ID/Password.</errorPageMessages> </authentication> <proxyInfo class="oracle.portal.provider.v1.http.ProxyInformation"> <httpProxyHost>www-proxy.us.oracle.com</httpProxyHost> <httpProxyPort>80</httpProxyPort> </proxyInfo> <portlet class="oracle.portal.provider.v1.http.URLPortlet" version="1"> <id>1</id> <name>Yahoo Weather Portlet</name> <title>Yahoo Weather Portlet</title> <description>This portlet is to test Integration services using weather.yahoo.com</description> <timeout>100</timeout> <timeoutMessage>yahoo timed out</timeoutMessage> <acceptContentType>text/html</acceptContentType> <showEdit>false</showEdit> <showEditToPublic>false</showEditToPublic> <showEditDefault>false</showEditDefault> <showPreview>false</showPreview> <showDetails>false</showDetails> <hasHelp>false</hasHelp> <hasAbout>false</hasAbout> <renderer class="oracle.portal.provider.v1.RenderManager"> <contentType>text/html</contentType> <showPage class="oracle.portal.provider.v1.http.URLRenderer"> <contentType>text/html</contentType> <charSet>ISO-8859-1</charSet> <pageUrl>http://weather.yahoo.com/</pageUrl> <filter class="oracle.portal.provider.v1.http.HtmlFilter"> <headerTrimTag>&lt;body</headerTrimTag> <footerTrimTag>/body></footerTrimTag> </filter> </showPage> </renderer> </portlet> </provider>

2. Save the file as "provider.xml", making sure not to overwrite one of the PDK-Java or PDK-URL Services sample files of the same name. 

   Remember the name of the directory where the file is saved as you will need this later. For example:  C:\myyahoo\provider.xml

CONFIGURING YOUR WEBSERVER

These steps describe how to configure the Oracle HTTP Server only. If you are using a third party listener, please take the appropriate steps.

1. Stop the Oracle HTTP Server.

2. Open the configuration file zone.properties

3. Under the Servlet Aliases section, register an alias, myyahoo, for a new instance of the Provider Adapter servlet.  This servlet will use the XML provider definition you have just created.

   For example, add the line:

   servlet.myyahoo.code=oracle.portal.provider.v1.http.HttpProvider
   

4. Under the Aliased Servlet Init Parameters section, add settings for the provider_root and sessiontimeout parameters, making sure that provider_root points to the directory where you saved your provider.xml file.

   For example, add the line:

   servlet.myyahoo.initArgs=provider_root=C:\myyahoo,sessiontimeout=1800000,debuglevel=1

   Note: If the debuglevel parameter is set to 1, you will activate a special "test page" feature which allows you to ensure that your provider is configured properly before you try and register it with a portal.

5. Save zone.properties.

6. Start the Oracle HTTP Server.

7. Access your provider's test page by entering into a browser the URL for the aliased servlet you just set up.  For example:

   http://host.domain:port/servlet/myyahoo

   Note: You will use this URL later when you register the provider on a portal.  

8. Review the test page which displays information about your provider.  If the test page is not displayed, carefully review the previous configuration steps.

CREATING THE EXTERNAL APPLICATION

You now need to create a new external application in Oracle9iAS Portal for the MyYahoo! Weather Portlet.  This external application will map any given portal user to a desired MyYahoo! account so that every portal user can have single sign-on access to MyYahoo!  To perform these steps go to the Administer tab, then click Administer External Applications.  In the Administer External Applications screen, click Add External Application.

1. In the "Application Name" box, type the name of the External Application as you want it to appear to the user (e.g., MyYahoo!)

2. In the "Login URL" box, enter the URL for the login page of the External Application.  You can find this by going to the External Application login page, typing control-U to show the HTML source for page, and scrolling through the page until you find the login URL.  In the case of MyYahoo!, this value is
   http://login.yahoo.com

3. In the "User Name/ID Field Name" box, type the name of the login field in the application Login page. You can obtain this from the Login page source as in step 2.  In the case of MyYahoo! the value of this field is login. 

4. In the "Password Field Name" type the name of the password field in the application Login page.  You can obtain this field from the login page   source as in step 2.  In the case of MyYahoo! the value of this field is passwd. 

5. Under "Authentication Method" specify whether the application uses GET or POST authentication. MyYahoo! uses POST.

6. Once you have completed these steps, click "OK" to add the External Application.

REGISTERING THE PROVIDER

Now that you have successfully tested your new alias.  You will need to register a new provider that calls this alias.  To perform these steps, go to the Oracle9iAS Portal Administer tab, then click Add a Portlet Provider.

1. Register your new Provider:

   1. Name:  MyYahooProvider

   2. Display Name:  My Yahoo Provider

   3. Provider ID: Leave blank, it will automatically be generated

   4. Timeout:  100

   5. Timeout Message:  My Yahoo! Portlet Timed Out

   6. Implementation Style:  Web

   7. Register on Remote Nodes: No

   8. Provider Login Frequency:  Once per User Session

   9. URL:  http://host.domain:port/servlet/myyahoo

   10. Check the following radio button: The user's identity needs to be mapped to a different name in the Web provider's application, and/or the Web provider requires an external application login for establishment of a browser session. If selecting this option, specify the external application ID below.

   11. Click the list of values box next to the External Application ID. Select MyYahoo! External Application

2. Click OK.

ADDING THE PORTLET TO A PAGE

Now add your new portlet to a page.  If you have not already entered your Yahoo! credentials into the Login Server, you will see a message telling you to Update Login Information.  Click the link to enter your Yahoo! account username and password.  After entering your credentials, you will see the Yahoo! Weather portlet.

Now that you have successfully built your own External Application portlet using PDK-URL services, please look for future articles that will guide you through adding services to your portlet such as SSL handling, inline rendering of links, parameter passing, etc.

Here are some reference articles to help you better understand the architecture and technical details of PDK-URL Services:

• A Primer on PDK-URL Services 

• Understanding PDK-URL Services Runtime

• Understanding provider.xml for PDK-URL Services

Revision History:

• November 2001