Oracle 9iAS Portal Developer Kit
Securing Web Providers

OVERVIEW

This document describes the different techniques that are available to secure web providers (version 9.0.2). These techniques are used to achieve the following aims:

- User authentication - used to verify the identity of a user when they first log in to a Portal instance
- Access restriction - used to restrict a user's access to certain portlets or providers
- Portal authentication - used to verify that a message received by a provider comes from a trusted Portal instance, thereby preventing unauthorized invocation of web provider APIs
- Protection against 'spoofing' - used to prevent an unauthorized entity from resending intercepted messages (spoofing)
- Message encryption - by encrypting a provider message, its contents can only be decrypted for use by the intended message recipient

The methods described may be used individually or they may be combined depending on the level of security required. The following table summarizes the different methods and their intended aims.

| Security Feature
Portal security | Security Managers | Portal Server Authentication | Message Authentication | Secure Socket Layer
Security Measure | User authentication | x |  |  |  |
Access restriction | x | x |  |  |
Portal authentication |  |  | x | x |
Prevent unauthorized replay of intercepted messages |  |  |  | x |
Message encryption |  |  |  |  | x

User authentication

When a user first logs in to a Portal instance they must enter their password to verify their identity before they are allowed access. This is done by the SSO server and is covered in the Portal security section.

Access restriction

The aim here is to limit a user's access to those portlets for which they are authorized. There are two main ways of doing this.

- Portal security - having verified a user's identity when they log in, Portal access control lists (ACLs) are used to restrict their access to certain Portal content - in this case portlets and/or providers.
- Security managers - used at the portlet definition and instance level to specify whether a given user may use a portlet, access is granted based on the user details.

These methods do not check the authenticity of messages being received by a provider and so are not suitable on their own for securing access to a remote web provider.

Portal authentication

The following two methods allow a provider to verify that an incoming request is from a trusted source.

- Portal server authentication - access to a web provider may be limited to recognized machines. This method works on the IP address or the host name of an incoming HTTP message. Restricting access to recognized machines reduces the chances of a ' denial of service' attack - where a server is flooded with requests from a rogue machine with the aim of degrading its performance or stopping it altogether.
- Message authentication - by appending digital signatures based on a shared key to web provider messages, their authenticity may be confirmed. The signature includes a time stamp to reduce the chance of a message being illegally recorded in transit and resent.

These methods help to verify that messages being received by a provider come from a valid source but do not prevent data being read. It is still possible to send faked messages (although message authentication can be used to make this difficult).

Secure communication

- Secure Socket Layer - using the SSL protocol, messages may be strongly encrypted to protect the data therein. This is the most secure technique, but has the highest performance overhead.

Summary of Portal-provider communication

The diagram below shows the elements that are relevant to the techniques discussed in this document. There are two sorts of messages handled by the provider. The first type is SOAP (an XML messaging standard) running on top of HTTP for communication between a Portal instance and a provider. Next, there are show requests, which are simply HTTP POST messages, from the middle-tier page assembly component (Parallel Page Engine or PPE) to which the provider responds with HTML content. An Oracle 9iAS Web Cache instance in front of a web provider may be used to cache the responses to show requests, thereby improving the response time of subsequent identical show requests. SOAP requests are not cached.

SECURITY FEATURES

The following sections describe each method that may be used for securing communication with a web provider in more detail.

Portal security

When a user first logs in to a Portal instance, they are authenticated by an Oracle Single Sign-On server instance. Access to portal objects may be restricted to certain users or user groups using Access Control Lists (ACLs). This is done by moving to the appropriate object (e.g. provider, page or portlet) in the Portal Navigator and following the 'Grant Access' link.

Using this method offers the advantages of centralized creation and maintenance of users and user groups and their access rights. Additional security checks may be implemented using security managers at the web provider.

Drawbacks

Portal security makes no assumptions about the protection of the web provider and does not protect the web provider in any way. It simply eliminates the need to for the web provider to determine user authorization. Additional means of protecting access to web provider are discussed in the following sections.

Security managers

These are implemented within a web provider and are used to verify that given users may access portlet instances. They work at the portlet level, i.e. each portlet may have its own security manager. By implementing a security manager, content may only be retrieved from a portlet if user details are supplied that pass the authorization logic defined by the security manager. If no security manager is used any username may be passed in, even fictitious names that are not even portal users or have not been authenticated by a portal.

Security manager implementations extend the abstract class:

oracle.portal.provider.v2.security.PortletSecurityManager

The default implementation supplied with the PDK is:

oracle.portal.provider.v2.security.AuthLevelSecurityManager

It uses the authorization level parameter of the incoming Portal message to decide whether the user has access to a portlet. The levels of authorization are:

- Strong - user has been authenticated by the SSO server in the current Portal session, i.e. the user has logged in to the Portal instance with a valid username/password combination, and is calling the portlet in the context of that session.
- Weak - a previously strongly authenticated user returns to view a Portal page without having an active Portal session. A persistent cookie (persisted by the user's browser) indicates to Portal that in some previous session the user had logged in by supplying a valid username/password combination
- Public - a user has not logged in within the context of the current Portal session, and does not have a persistent cookie to indicate that such a state previously existed.

Configuration of security managers

An article fully describing how to build a portlet using the security manager may be found here.

A security manager for a portlet is defined in the provider's configuration file. The following example shows a stock portlet using AuthLevelSecurityManager to verify that the user is authorized to use this portlet. The securityLevel tag may be set to 'strong', 'weak' or 'public'.

>     <Directory />
>     <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
>     <?providerDefinition version="3.1"?>

>     <provider class="oracle.portal.provider.v2.DefaultProviderDefinition">
>        <session>true</session>
>        <portlet class="oracle.portal.provider.v2.DefaultPortletDefinition">
>           <id>1</id>
>           <name>StockPortlet</name>
>           <title>Stock portlet example</title>
>           <shortTitle>Stock portlet</shortTitle>
>           <description>A portlet to show stock prices</description>
>           <timeout>10000</timeout>
>           <timeoutMessage>Stock portlet timed out</timeoutMessage>
>           <acceptContentType>text/html</acceptContentType>
>           <showEdit>true</showEdit>
>           <showEditToPublic>false</showEditToPublic>
>           <showEditDefault>true</showEditDefault>
>           <renderer class="oracle.portal.provider.v2.render.RenderManager" >
>               <contentType>text/html</contentType>
>               <autoRedirect>true</autoRedirect>
>               <showPage>/htdocs/stockportlet/stockshow.jsp</showPage>
>               <editPage>/htdocs/stockportlet/stockedit.jsp</editPage>
>           </renderer>
>           <securityManager class="oracle.portal.provider.v2.security.AuthLevelSecurityManager"/>
>               <securityLevel>strong</securityLevel>
>           </securityManager>
>        </portlet>
>     </provider>

The following errors will be returned if an illegal operation is performed on a portlet.

Error type | Error message | When the error might occur
SOAP Exception | registerPortlet failed: user is not authorized to use this portlet. | Provider registration
SOAP Exception | copyPortlet failed: user is not authorized to use this portlet. | When a page is copied
SOAP Exception | deregisterPortlet failed: user is not authorized to use this portlet. | Deleting a Portal page or deregistering the provider to which the portlet belongs
HTML message returned to PPE | showPortlet failed. User <name>" is not authorized to use this portlet | During a show request

Drawbacks

Most security manager implementations will use the authorization level or some other user specific element in an incoming message. A check of this type could be bypassed by an entity imitating a portal instance.

Portal server authentication

One way to prevent unauthorized access to providers is to restrict access to the provider to known client machines at the server level. This method goes some way towards defending against denial of service attacks.

In the Oracle HTTP Server this is achieved using the allow and deny directives in the httpd.conf file to control access to client machines based on their host names or IP addresses. If host names are used as discriminators the server needs to look them up on its Domain Name Server which will add extra overhead to the processing of each request. Using the IP address will prevent this but the IP address of a remote client may change without warning.

Configuration of Portal server authentication

The following code in httpd.conf would restrict access to one Web Cache instance with the host name my.webcachehost.com and one database server with the name company.portal.com running a portal instance.

>     <Directory />
>         order deny,allow
>         deny from all
>         allow from my.webcachehost.com company.portal.com
>     </Directory>

The following does the same but uses IP addresses instead of host names.

>     <Directory />
>         order deny,allow
>         deny from all
>         allow from <middle_tier_IP_address> <portal_IP_address>
>     </Directory>

Drawbacks

This technique only goes some way towards stopping denial of service attacks. Web Cache does not support the idea of Portal server authentication. So even if a provider running behind a Web Cache restricts access to certain database clients and Web Cache instances it can not stop unauthorized client machines sending show requests via Web Cache. Similarly, if the PPE sending the requests is not restricted to trusted client machines (by being only accessible to users inside a company firewall, for example) the web provider will still be indirectly open to this sort of attack.

Restricting access to certain IP addresses and host names may be circumvented by sending messages to a provider containing fake IP addresses and host names. This is tricky to do effectively since return messages go to the machine whose IP address has been copied, but it can still cause problems.

Message authentication

The PDK supports message authentication so that access may be limited to a specified provider instance or group of provider instances. A provider is registered with a secret shared key known only to the Portal and provider administrators.

The Portal instance sends a digital signature, calculated using a Hashed Message Authentication Code (HMAC) algorithm, with each message to a provider. A provider may authenticate the message by checking the signature using its own copy of the shared key. This technique may be used in Secure Socket Layer communication with a provider instead of client certificates.

SOAP and show requests use this mechanism in slightly different ways.

SOAP messages

A Portal instance calculates a signature based on user information, a shared key and a time stamp. The signature and time stamp are then sent as part of the SOAP message. The time stamp is based on UTC (coordinated universal time, the scientific name for Greenwich Mean Time) so that timestamps can be used in messages between computers in different timezones.

When the provider receives this message it will generate its own copy of the signature. If the signatures agree, it will then compare the message time stamp with the current time. If the difference between the two is within an acceptable value the message is considered authentic and is processed accordingly. If there is an error in the authentication process, one of the following SOAP exceptions are returned to the Portal. How these are displayed to the user will depend on what type of request is being sent.

Fault type | Error | Meaning
Authentication.InvalidChecksum | Message checksum is invalid | Signature in the incoming request does not match that calculated by the provider.
| No checksum in SOAP message | No signature parameter in the incoming request to a provider using client message authentication. Most likely cause: No shared key entered when the provider was registered.
Authentication.InvalidTimestamp | Message timestamp is invalid | Timestamp parameter in the incoming message is either outside the allowed tolerance or contains illegal characters.
| No timestamp in SOAP message | No timestamp parameter in the incoming request to a provider using client message authentication.

The time stamp comparison is used to reduce the chance of messages being captured in transit and re-sent by unauthorized users. The smaller the time window, the less likely this is to happen. This time window is set at the provider.

Show messages

These are sent from the PPE and are used to retrieve portlet content.

Prior to a show request being made, a SOAP call is made to establish a session between the Portal and provider. This is authenticated as described in the section above. During this call a signature cookie is generated at the provider and returned to the Portal to be used in ensuing show requests. For each show request the provider checks that the cookie matches the one that it generated in the earlier SOAP request. If the provider session timeout elapses, another SOAP call to establish a session is made and a new signature cookie is generated.

The reason for authenticating show requests using a signature cookie is to allow authentication in combination with invalidation based caching where portlet contents are stored in a Web Cache instance in front of the web provider. In this case, subsequent identical show calls will retrieve the cached content. The signature cookie is used as part of the cache key so the show call must include the same signature cookie to retrieve cached content.

The following errors will be returned to the PPE if there is an error in the authentication process and should be shown to the user in the portlet content.

Error | Meaning
No checksum in SHOW request | Incoming show request has no checksum parameter. Most likely cause: No shared key entered when the provider was registered.
Provider session has timed out - log out and back in again to re-establish | The provider session used to store authentication information no longer exists. Caused by: Session timing out Provider being reset between an initSession call and a show call Provider registered with no session information selected

Configuration of message authentication

Provider side configuration

Two JNDI variables exist for the configuration of message authentication for each provider, these are as follows:

`oracle.portal.<<providerName>>.sharedKey
oracle.portal.<<providerName>>.maxTimeDifference`

Where `<<providerName>>` is the name of the particular provider.

You can set the values for these variables through the environment section for the PDK Java in Oracle Enterprise Manager (OEM), or by directly editing orion-web.xml if OEM is not available. For more information on setting deployment properties in the PDK, see the installation instructions for the PDK-Java.

The sharedKey variable represents the shared key for the provider and is a string between 10 and 30 characters long. If no key is entered the provider will not perform message authentication.

The maxTimeDifference variable represents the maximum allowed time difference in milliseconds, and provides a value of 2 hours by default in the JNDI deployment properties. The fact that this variable has a value by default doesn't matter if you don't want your provider to perform message authentication as it is not performed unless a shared key has been set. You can set this property to have a time difference value that you require (in milliseconds), up to a maximum value of around 24 days, which is far greater than should be needed be any HMAC configuration.

A couple of basic principles apply in the choice of configuration parameters. The shorter the maximum allowed time difference between sender and receiver, the less chance that a message may be intercepted en-route to the provider and re-sent. Also, the longer a shared key is, the more difficult it is for someone to work it out if they do manage to intercept a message.

The provider session timeout specifies the length of time for which a signature cookie is valid. The smaller this value is, the more often a new signature cookie is created and, therefore, the more secure the content. The session timeout is specified in seconds and is set in the web provider's configuration file, WEB-INF/web.xml. The tags are applied at the web application level. The following snippet would set the session timeout to 30 minutes.

>         <session-config>
>             <session-timeout>1800</session-timeout>
>         </session-config>

Portal side configuration

In addition to the normal provider registration steps:

- During provider registration enter the shared key value in the connection page of the provider registration wizard.
- Select the 'user' radio button in the 'User/Session' section and select 'Once Per User Session' or 'Always' from the 'Login Frequency' drop-down box. This enables the use of cookies between the Portal and provider. If this is not done the authentication of show requests will not work.

Drawbacks

A single provider instance can not support more than one shared key. This could cause security and administration problems if several clients sharing a provider use the same key. For instance, if one copy of the shared key is compromised in some way the provider administrator has to create a new key and then get it to all of the Portal clients who then have to update their provider definition. The way around this is to deploy different provider services, specifying a unique shared key for each service. Each provider service has its own deployment properties file so that each service is configured independently of the others. The overhead of deploying multiple provider services within the same provider adapter is relatively small.

In a provider which does not have a Web Cache instance in front of it, this use of the same signature cookie over the lifetime of a provider session means there is a trade off between performance in terms of speed and the security provided by authenticating the requests. The signature cookie value is only calculated once after the initial SOAP request establishes the session with the provider. The shorter the provider session timeout, the more often a signature will be calculated providing greater security against a show request being resent illegally. However, the SOAP request required to establish a session between a Portal instance incurs a time penalty.

In a provider which is using Web Cache to cache show request responses, there is a similar trade-off. Cached content is secured in the sense that incoming requests must include the signature cookie to retrieve it but caching content for an extended period of time will leave the provider open to illegal show requests.

While the signature element provides protection against interception and resending of messages it does nothing to prevent interception and reading of message contents. Messages are still transmitted in plain text. If you are concerned about the content of messages being read by unauthorized people, you should use message authentication in conjunction with SSL.

Secure socket layer

Normal communication between a Portal and provider uses HTTP - a network protocol that transmits data as plain text using TCP as the transport layer. It is possible for an unauthorized agent to read an intercepted message. HTTPS uses an extra secured layer (SSL) on top of TCP to secure communication between a client and a server.

Each entity (for example, a Web Cache instance) receiving a communication using SSL has a freely available public key and a private key known only to the entity itself. Any messages sent to an entity are encrypted with its public key. A message encrypted by the public key may only be decrypted by the private key so that even if a message is intercepted by a felonious third party it can not be decrypted.

Certificates are used to sign communications, thereby ensuring that the public key that is used does in fact belong to the correct entity. These are issued by trusted third parties, Certification Authorities (CA), e.g. Verisign. They contain an entity's name, public key and other security credentials and are installed on the server end of a SSL communication to verify the identity of the server. Client certificates may also be installed on the client to verify the identity of a client but this is not supported in Portal 9.0.2. Message authentication may be used instead.

Oracle Wallet Manager is the application used to manage public key security credentials. It is used to generate public/private key pairs, create a certificate request to a CA and then install the certificate on a server.

Configuration of SSL

When a provider is registered from a Portal instance only one url is entered, so either HTTP or HTTPS may be used, not a combination of both.

Each port on each server that may be used to receive SSL messages must have a server side certificate installed, i.e. the Web Cache instance (if any) in front of the web provider and the server which hosts the provider. The certificate installed on a server port ensures that communication between two points is encrypted but does not authenticate the source of a message. Message authentication should be used as well to fully secure communication between a trusted Portal instance and a provider.

For more details on SSL configuration in the Portal infrastructure refer to:

- Oracle9iAS Portal Configuration Guide

For more information on the wallet manager and configuring Web Cache to use SSL, refer to:

- Oracle Wallet Manager appendix in the Oracle Internet Directory Administrator's Guide (Oracle9i Application Server Documentation Library)
- Oracle9iAS Web Cache Administration and Deployment Guide (Oracle9i Application Server Documentation Library)

The only extra step required to configure a web provider to use SSL is to add a parameter to the provider web application configuration file, web.xml, that lists one or more secure ports to be used by the provider. The example below specifies that ports 433 and 434 are to be used for secure communication with the web provider. Only one port may be needed, the example demonstrates the syntax for multiple entries.

>     <init-param>
>       <param-name>httpsports</param-name>
>       <param-value>433:434</param-value>
>     </init-param>

SUMMARY

A number of methods have been described in this document for securing web providers, any combination of which may be used depending on the environment in which the web provider is installed. The choice of techniques is affected by a number of factors including the effort required to install and maintain them and any performance overhead that they may impose on a provider.

User authentication and access restriction methods are used to ensure that only authorized users have access to certain portlets. Portal server authentication and message authentication come into play to ensure that a provider only receives messages from trusted sources and that the messages are not resent illegally. Using one or more user authorization techniques in addition to SSL and message authentication provides the greatest level of security.