C Integrating JavaServer Pages with Oracle Portal

Oracle Portal gives you the ability to create various kinds of Web pages. You can supplement this ability with JavaServer Pages (JSPs).

This appendix describes how you can secure Oracle Portal to allow access to only approved JSPs, and prevent unauthorized access by JSPs to portlet content. It also describes the steps required to allow access for protected external JSPs that require login.

The following topics are covered in this appendix:

Using the JavaServer Page Configuration File
Setting Up a JAZN File for External Communication

C.1 Using the JavaServer Page Configuration File

Because almost any JSP using the tag library can request Oracle Portal portlet content, there is a need for a secure way to ensure that only approved JSPs obtain access. You can control this through two mechanisms:

The <portal:usePortal> tag in the JSP
An external JSP configuration file

The configuration file identifies the Oracle Portal instances, and page groups within those instances, to which an external JSP is allowed access.

See Section C.1.1, "Contents of Your JavaServer Page Configuration File" for the specific coding requirements of the configuration file.

Your completed configuration file must then be identified to Oracle Portal. See Section C.1.3, "Location of Your JavaServer Page Configuration File" for an explanation of the step.

This section contains the following sub-sections:

Contents of Your JavaServer Page Configuration File
Example JavaServer Page Configuration File
Location of Your JavaServer Page Configuration File
External JavaServer Page Login

C.1.1 Contents of Your JavaServer Page Configuration File

The required tags are:

<jps>
<portal>
<database>
<url>
<cookie>
<pageGroups>
<pageGroup>

C.1.1.1 The <jps> Tag

The <jps> tag is a container tag that provides a list of Oracle Portal instances to which external JSPs can have access.

Opening tag

<jps version="1.0">

Version must be set to 1.0 for the current Oracle Portal release.

Closing tag

</jps>

C.1.1.2 The <portal> Tag

The <portal> tag describes an individual Oracle Portal instance.

Opening tag: <portal name="MyPortal" default="true">
Closing tag: </portal>

Table C-1 The <portal> Tag's Attributes

Attribute	Value
`name`	Any descriptive name given to an Oracle Portal instance. The name must be unique within the configuration file.
`default`	A `true` or `false` flag indicating whether this portal is the default instance that is used if a usePortal tag does not specify a portal name. If you provide no value, default is set to `false`.

Only one default portal is allowed for each configuration file.

C.1.1.3 The <database> Tag

The <database> tag provides database connection information about a given Oracle Portal instance. For example:

<database data-source="jdbc/MyPortal"/>

The data-source attribute value is the name of the data source, which must be specified in the data-sources.xml file located in the J2EE_HOME/config directory.

Here is an example of a data-source definition:

<data-source
   class="com.evermind.sql.DriverManagerDataSource"
   name="MyPortal"
   location="jdbc/MyPortal"
   xa-location="jdbc/xa/MyPortal"
   ejb-location="jdbc/MyPortal"
   connection-driver="oracle.jdbc.driver.OracleDriver"
   username="portal_app"
   password="portal_app"
   url="jdbc:oracle:thin:@xyz.oracle.com:1521:orcl"
   inactivity-timeout="30"
/>

The username and password attributes must be set to the Oracle Portal application schema user name and password.

C.1.1.4 The <url> Tag

The <url> tag provides connection information to the Oracle Portal instance. For example:

<url protocol="http" host="defg.oracle.com" port="7500" path="portal/pls/portal"/>

Table C-2 The <url> Tag's Attributes

Attribute	Value
`protocol`	The name of the protocol used to connect to the Oracle Portal instance. Currently, only HTTP and HTTPS protocols are supported. If you do not specify a protocol attribute, the default will be `http`.
`host`	The computer name for the Oracle Portal middle tier.
`port`	Port number. If no port is specified, the default number will be `80`.
`path`	For this release, path must be set to `/portal/pls/<PORTAL-DAD-NAME>`.

C.1.1.5 The <cookie> Tag

The <cookie> tag describes the Oracle Portal cookie. For example:

<cookie name="portal" maxAge="-1" path="/" domain=".oracle.com"/>

Table C-3 The <cookie> Tag's Attributes

Attribute	Value
`name`	The name of the cookie. This must be the same as the Oracle Portal instance cookie name. name is a required attribute of the cookie tag.
`maxAge`	The maximum age of the cookie, specified in seconds. Specify a value of `-1` if you want the cookie to persist until browser shutdown. maxAge is a required attribute of the cookie tag.
`path`	The path on the server to which the browser returns this cookie. path is a required attribute of the cookie tag.
`domain`	This attribute should be specified only if changes were made to the SSO portlet cookie configuration. See the SSO documentation.

C.1.1.6 The <pageGroups> Tag

The <pageGroups> tag forms a container for the pageGroup tags. This tag has no attributes.

Opening tag: <pageGroups>
Closing tag: </pageGroups>

C.1.1.7 The <pageGroup> Tag

The <pageGroup> tag describes each individual page group's properties. For example:

<pageGroup name="JPSDemo" key="welcome" default="true"/>

Table C-4 The <pageGroup> Tag's Attributes

Attribute	Value
`name`	The page group name. This must be the name given to the page group when it was created in Oracle Portal.
`key`	The page group's key. The value must match the Access Key value that was assigned to the page group in Oracle Portal. (Note that a page group identified here must have JSP Access enabled.)
`default`	A flag set to `true` or `false` indicating whether or not this page group is the default page group within this Oracle Portal instance. A default page group is the one used in the usePortal tag if no page group name is supplied. If no value provided for default in this pageGroup tag, it will be set to `false`.

Only one default page group is allowed for each portal instance.

C.1.2 Example JavaServer Page Configuration File

The following is an example of a JSP configuration file:

Example C-1 Example JavaServer Page Configuration File

<jps version="1.0">
   <portal name="MyPortal" default="true">
      <database data-source="jdbc/MyPortal"/>
      <url host="xyz.oracle.com" port="7500" path="/portal/pls/portal"/>
      <cookie name="portal" maxAge="-1" path="/" />
      <pageGroups>
         <pageGroup name="JPSDemo"  key="welcome" default="true"/>
         <pageGroup name="JPSDemo2" key="welcome" default="false"/>
      </pageGroups>
   </portal>
   <portal name="AnotherPortal">
      <database data-source="jdbc/AnotherPortal"/>
      <url protocol="http" host="abc.oracle.com" port="8888"
         path="/portal/pls/portal90"/>
      <cookie name="portal90" maxAge="-1" path="/" />
      <pageGroups>
         <pageGroup name="JPSDemo"  key="welcome"/>
         <pageGroup name="JPSDemo1"  key="welcome1"/>
         <pageGroup name="JPSDemo2"  key="welcome2"/>
         <pageGroup name="JPSDemo3"  key="welcome3"/>
         <pageGroup name="JPSDemo4"  key="welcome4"/>
      </pageGroups>
   </portal>
</jps>

C.1.3 Location of Your JavaServer Page Configuration File

Your JavaServer page configuration file can have any other name, and can be located anywhere in the file system.

You specify the location using a context parameter in the web.xml file, which is located in the directory DOMAIN_HOME\servers\WLS_PORTAL\tmp\_WL_user\portal\dir_name\war\WEB-INF.

The context parameter in the web.xml file is:

<context-param>
   <param-name>oracle.webdb.service.ConfigLoader</param-name>
   <param-value>/WEB-INF/wwjps.xml</param-value>
      <description>This parameter specifies the location of the JPS
         configuration file</description>
</context-param>

C.1.4 External JavaServer Page Login

External JSPs can be categorized by their login requirements:

Public JSPs, which do not require login (or to which users log in through the Oracle Portal login link)
Protected JSPs, which do require login

Protected external JSPs have additional setup requirements. These are explained in the next section.

C.2 Setting Up a JAZN File for External Communication

The following steps are required only for protected external JSPs. That is, external JSPs that require login.

In the external JSPs, if you need to log in to the portal, you need to use the following tag syntax:

<portal:usePortal id="AnyPortal" pagegroup="AnyPageGroup" login="true" />

When you execute this JSP, you will be redirected to OracleAS Single Sign-On if you are not already logged on. To make this work, look at the following sections:

Setting Up mod_osso (if not already set up)
Setting Up JAZN with LDAP

C.2.1 Setting Up mod_osso

By default, your Oracle HTTP Server is registered with OracleAS Single Sign-On. If that has been changed, and re-registration is necessary, refer to the Oracle Application Server Single Sign-On Administrator's Guide.

C.2.2 Setting Up JAZN with LDAP

JAZN is the internal name for a Java Authentication and Authorization Service (JAAS) provider. JAAS is a Java package that enables applications to authenticate and enforce access controls upon users. The use of JAZN in Oracle Portal is limited to the authentication of external JSPs.

Confirm that the JAZN is working with the LDAP. (You can use the demo provided by the JAZN.)

Do the following additional step:

Go to DOMAIN_HOME\servers\WLS_PORTAL\tmp\_WL_user\portalTools_11.1.1.1.0\124k5v\META-INF\orion-application.xml and add the following:
```
<jazn provider="LDAP" location="ldap://<OIDHOST>:389" default-realm="oracle">
<jazn-web-app auth-method="SSO" />
</jazn>
```

Port number 389 is a default port for LDAP servers. However, any other port can be assigned. Contact your Oracle Internet Directory Administrator to obtain <host> and <port> information.