Oracle9iAS Portal Developer Kit
How to Build a URL-Based Portlet with Single Sign-On to an Application Using Basic Authentication

In the article How to Build a URL-Based Portlet with Single Sign-On to an External Application, you learnt how to create a URL-based portlet that provided single sign-on to an external application requiring user credentials. The example used in that article was MyYahoo! Weather. PDK-URL Services also enables you to create URL-based portlets that provide single sign-on to URL applications that use basic authentication.

This article shows you how to create a URL-based portlet with single sign-on to an external application requiring basic authentication. The example used in this article is Oracle MetaLink.

### 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.

### 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 under the authentication 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 = 'UTF-8'?>
       <?providerDefinition version="2.0"?>

       <provider class="oracle.portal.provider.v1.http.URLProvider">
          <session>true</session>
          <authentication class="oracle.portal.provider.v1.http.Authentication">
             <authType>basic</authType>
          </authentication>
          <proxyInfo class="oracle.portal.provider.v1.http.ProxyInformation">
             <httpProxyHost>www-proxy.us.oracle.com</httpProxyHost>
             <httpProxyPort>80</httpProxyPort>
          </proxyInfo>
          <httpsProxyInfo class="oracle.portal.provider.v1.http.ProxyInformation">
             <httpsProxyHost>www-proxy.us.oracle.com</httpsProxyHost>
             <httpsProxyPort>80</httpsProxyPort>
          </httpsProxyInfo>
          <portlet class="oracle.portal.provider.v1.http.URLPortlet">
             <id>1</id>
             <name>MetalinkPortlet</name>
             <title>Metalink Portlet</title>
             <description>This portlet displays an 3rd Party Application which uses Basic Authentication as a portlet.  The 3rd party application is Oracle Metalink</description>
             <timeout>100</timeout>
             <timeoutMessage>Metalink 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>
             <renderer class="oracle.portal.provider.v1.RenderManager">
                <showPage class="oracle.portal.provider.v1.http.URLRenderer">
                   <contentType>text/html</contentType>
                   <pageUrl>http://metalink.oracle.com/metalink/plsql/sit_main.showSitemap?p_showTitle=0</pageUrl>
                   <filter class="oracle.portal.provider.v1.http.HtmlFilter">
                      <headerTrimTag>&lt;body</headerTrimTag>
                      <footerTrimTag>/body></footerTrimTag>
                      <useAuthLinks>true</useAuthLinks>
                   </filter>
                </showPage>
             </renderer>
             <securityManager class="oracle.portal.provider.v1.http.URLSecurityManager">
                <authorizType>public</authorizType>
             </securityManager>
          </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:\basicauth\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, metalink, 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.metalink.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.metalink.initArgs=provider_root=C:\basicauth,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/metalink

   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 Oracle MetaLink Portlet. This external application will map any given portal user to a desired Oracle MetaLink account so that every portal user can have single sign-on access to Oracle MetaLink. To perform these steps go to the Oracle9iAS Portal 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., Oracle MetaLink)

2. In the "Login URL" box, enter the URL for the External Application. This URL will be protected by basic authentication. For example, in the case of Oracle MetaLink, you could use:
   http://metalink.oracle.com/metalink/plsql/sit_main.showSitemap?p_showTitle=0

3. Leave the "User Name/ID Field Name" box blank.

4. Leave the "Password Field Name" box blank.

5. Under "Authentication Method" specify BASIC AUTHENTICATION.

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: MetaLinkBasicAuthProvider

   2. Display Name: MetaLink Basic Authentication Provider

   3. Timeout: 100

   4. Timeout Message: Basic Auth Portlet Timed Out

   5. Implementation Style: Web

   6. Provider Login Frequency: Once Per User Session

   7. Check the following box: Require session specific information such as session id, user, and login time. This field is relevant only for Web providers.

   8. URL: http://host.domain:port/servlet/metalink

   9. 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.

   10. Click on the list of values box next to the External Application ID. Select the Oracle MetaLink 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 MetaLink credentials into the Login Server, you will see a message telling you to Update Login Information. Click the link to enter your MetaLink account username and password. After entering your credentials you will see the MetaLink portlet.

Now that you have successfully built your own Basic Authentication 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