Oracle9iAS Portal Developer Kit (PDK)
An Overview of Password Authenticated Applications

Introduction

This article provides an overview of password authenticated Applications in the Portal Development kit. It will describe authentication terminology, the components used for password authentication and available techniques for providers (version 9.0.2).

It is assumed that the reader has also read An Overview of Portlet Security which describes a range of security features on securing Portal providers and has wider scope than this document.

Authentication

Applications can be registered with the Single Sign-On Server in two different ways.

• Partner Application is an Application where the user is authenticated by Single Sign-On Server
• External Application is an Application where the user is authenticated by some third part application but the application username and password are stored by the Single Sign-On Server.

Providers

A provider is an application that you register with Oracle9iAS Portal. Each provider manages a set of portlets. Portlets act as windows into your application, display summary information, and provide a way to access the full functionality of the application. Portlets expose application functionality directly in the portal or provide "deep links" that take you to the application itself to perform a task. Since portlets format information for display in a web page the underlying application does not need to be web enabled to be integrated with Oracle9iAS Portal.

Oracle9iAS Portal supports two types of providers, Web Providers and Database providers. Most of the following document about password protection applies equally to either type of provider unless otherwise stated.

Providers don't need to do user authentication. It is possible for a provider to determine if the user is logged into Portal or not and this is sufficient information for some applications. If authenticated users are required by an application there are two basic types of provider application. Each type is suitable for certain situations or scenarios. The types are:

• Partner Application Provider - A partner application provider is a provider that integrates with a partner application.
• External Application Provider - An external application provider is a provider that integrates with an external application
  • URL services Provider - A URL Services Provider is a provider that allows you to create portlets by accessing existing content using a URL.

Partner Application

Partner applications are applications that are tightly integrated with the Oracle9iAS Single Sign-On Server. When a user attempts to access a partner application, the partner application delegates the authentication of the user to the Oracle9iAS Single Sign-On Server. Once a user is authenticated (i.e. has provided a valid username and password) for one partner application, the user does not need to provide a username or password when accessing other partner applications that share the same Single Sign-On Server instance. The Single Sign-On Server determines that the user was successfully authenticated and indicates successful authentication to the new partner application. A partner application provider is a provider that integrates with a partner application.

Authentication Overview

Authentication of users in partner applications is somewhat different than in conventional applications. Partner applications delegate user authentication to the Single Sign-On Server. If the user has not been authenticated, the Single Sign-On Server displays a login page prompting the user to enter a username and password. The login page submits the username and password back to the Single Sign-On Server.

If successfully authenticated, the Single Sign-On Server creates a special cookie containing information about the user. For security, the Single Sign-On Server encrypts the contents of the cookie. The cookie is sent back to the user’s browser, but is scoped so that it is only visible to the Single Sign-On Server. It is not passed to other listeners. After creating the cookie, the Single Sign-On Server re-directs the web browser to the "success URL" specified by the partner application. At this point, the partner application creates an application session cookie which contains information the application needs to re-establish the session later. The contents may be encrypted using Single Sign-On SDK. Upon making subsequent requests to the partner application, the partner application detects the presence of the partner application session cookie and from the cookie knows that the user is already authenticated.

If the user later accesses another partner application, that application looks for its application specific session cookie. If the cookie is not found the application redirects the request to the Single Sign-On Server as described previously. However, this time the Single Sign-On Server detects the presence of the user’s Single Sign-On Server cookie. This indicates that the user is already authenticated so the Single Sign-On Server redirects the browser to the "success URL" of the second partner application without prompting the user to enter a username and password again. At this point, the partner application creates its own application specific session cookie.To secure the application session cookies, the content may be encrypted using Single Sign-On SDK.

Advantages

1. Provides the tightest integration with Oracle9iAS Portal and Oracle9iAS Single Sign-On Server.
2. Provides the best Single Sign-on experience to users.
3. The application and the portal share the same user repository. This reduces user maintenance.
4. Provides the most secure form of integration because usernames and passwords are not transmitted between the portal and the provider.

Disadvantages

1. The application must share the same user repository as the portal even though the application’s user community may be a subset of the portal user community. This is a minor issue because the portal pages that expose the application can easily be restricted to the application’s user community.
2. The application can only be tightly integrated to one Single Sign-On Server

Implementation Techniques

To make an application a Partner application use either Mod_osso or Single Sign-On SDK

• Mod_osso is a general purpose Oracle Http Server module which is a Partner Application to a Single Sign-On Server. Once configured it can protect access to url's to only authenticated users and handles the redirection to the Single Sign-On Server, creation of cookies etc. Any application whose urls are protected by mod_osso are effectively a partner application.
• Single Sign-On SDK is a group of packages that can be used by an application to become a Partner Application. There is also some java wrapper classes that call these packages so they can be called from an application written in java.

Mod_osso

Mod_osso is a general purpose Oracle HTTP Server Module which can be used to protect access to parts of a web server. This module is a partner application. It uses Oracle Single Sign-On Server to do the authentication. The module does all the communication and handling of cookies between the Oracle HTTP Server and the Oracle Single Sign-On Server. If mod_osso is configured to protect urls of a web application then that web application is effectively a partner application.

Oracle Portal is also a partner application and uses Oracle Single Sign-On Server to authenticate users. Provided Oracle Portal and mod_osso are configured to use the same Oracle Single Sign-On Server then when the user is authenticated by Oracle Portal or a web application the user can access the other application without having to login again.

Advantages

1. Simple to set up.
2. No additional code is needed in the application.
3. mod_osso generates a partner application cookie and does all the cookie handling.
4. Secures the partner application and deep links from the partner application provider.

Disadvantages

1. Can only be used with web applications

Single Sign-On SDK

The Single Sign-On SDK is available for programmers to be able to integrate their application with a Single Sign-On Server. This SDK consists of a number of database packages that communicate with the Single Sign-On server when an application wants a user to be authenticated. These packages can be used to make an application a partner application. There are methods available to encrypt/decrypt information which can be used to secure information stored in the application cookie. Also contained with the Single Sign-On SDK are some java class wrappers to the PLSQL packages enabling java applications to become either partner or external applications.

Oracle Portal is also a partner application and uses Oracle Single Sign-On Server to authenticate users. Provided Oracle Portal and the Single Sign-On SDK are configured to use the same Oracle Single Sign-On Server then when the user is authenticated by Oracle Portal or an application the user can access the other application without having to login again.

Advantages

1. Can be used to create either a partner application or an external application.
2. Provides utilities to encrypt/decrypt cookies.

Disadvantages

1. Requires changes to the application code
2. The application must be written using a technology that can be easily integrated with Java or PL/SQL
3. All entry points to the partner application that need to be secure needs to be able to call the Single Sign-On SDK if a partner application cookie is not found and the user needs to be authenticated.
   

External Application

Applications that manage the authentication of users can be loosely integrated with the Oracle9iAS Single Sign-On Server by registering the applications as external applications.

Authentication Overview

When a user who has been previously authenticated by the Single Sign-On Server accesses an external application for the first time, the Single Sign-On Server attempts to authenticate the user with the external application. The authentication is performed by submitting an HTTP request that combines the registration information and the user’s username and password for the application. If the user has not yet registered their username and password for the external application, the Single Sign-On Server prompts the user for the required information before making the authentication request. When a user supplies a username and password for an external application, the Single Sign-On Server maps the new username and password to the user’s portal username and stores them. They will be used the next time the user needs authenticating with the external application.

An external application provider is a provider that integrates with an external application. Ideally the external application should have an authentication API you can call from your provider.

Advantages

1. Allows integration with many Single Sign-On Servers. However, if there is a "preferred" Single Sign-On Server, the application could be integrated as a partner application of that Single Sign-On Server and an external application of other Single Sign-On Servers.
2. Provides a Single Sign-On experience for users. However, users still need to maintain different usernames and passwords. In addition, the external application username mapping must be maintained.
3. Allows integration with multiple portals independent of their user repositories and Single Sign-On Servers.

Disadvantages

1. External applications do not share the same user repository as the portal. There is additional maintenance of user information.
2. The username and password must be transmitted to the provider. This approach is not as secure as a partner application.
3. The application must be written using a technology that can be easily integrated with Java or PL/SQL.

Partner Application Provider

Partner application providers expose Portlets which integrate a partner application content with Portal. The partner application provider "trusts" the portal to authenticate the user on the provider’s behalf. This is possible because the portal is, itself, a partner application.

Partner application providers must trust the portal to authenticate the user in this way because the provider cannot perform the authentication itself. Authenticating the user directly requires the provider to redirect the browser to the Single Sign-On Server and provide success and failure URLs. This is not possible due to the Provider architecture. The primary reason for this is that the authentication occurs in response to an API call from the portal to the provider. The Single Sign-On Server cannot imitate that call upon successful authentication to the initSession()/dologin() method to complete its normal processing.

Authentication

Logical steps for "deep links" protected by mod_osso

A portlet may show links to an application called "deep links". If these urls are protected by mod_osso making the application a partner application.

1. An authenticated portal user clicks on a "deep link" of a portlet to a Partner application.
2. The request goes direct (not via Portal) from the browser to the host where it is intercepted by mod_osso. Mod_osso determines if the mod_osso cookie exists. If it does it goes to step 5. If not it redirects via the browser to the login server
3. The login server determines if a SSO cookie exist, which it does because the user has already logged into Portal. The contents of the cookie are checked and the success url is called with a token.
4. Mod_osso uses the token to generate a mod_osso cookie and redirects via the browser to the original url.
5. Mod_osso passes the url onto the application

logical steps using Single Sign-On SDK

1. An authenticated portal user requests a portal page that contains a portlet from the partner application. Portal calls the partner provider’s initSession()/dologin() method.
2. The partner application provider checks for the existence of a partner application session cookie. If a cookie does not exist, the provider creates one. If the cookie already exists, the provider does not need to do anything.
3. The provider optionally encrypts the contents of the new partner application cookie.
4. The cookie is returned to the portal and is sent to the provider on subsequent requests to view portlets.

Portlet show mode

logical steps using Single Sign-On SDK

1. A user submits a request for a portal page containing the partner application provider’s portlet.
2. Upon receiving the request to view the portlet in SHOW mode, the provider determines if the partner application cookie exists indicating that the user is already authenticated. If the cookie does not exist then the provider should return content saying the user is not authenticated.
3. Optionally the partner application decrypts the partner application cookie using the Single Sign-On SDK.
4. The partner application provider locates the application session cookie and extracts the user’s username from the cookie. If the portlet could display sensitive information, the portlet should verify the privileges of the user before displaying any sensitive content. Note: At this point, the partner application session cookie should always exist. The portlet generates the portlet header.
5. The partner application gathers information and either returns it to the portlet for formatting or formats it and writes the formatted output directly to the HTTP Response stream.
6. If information returned by the partner application needs formatting, the portlet formats the information and writes it to the HTTP Response stream. After writing the portlet content, the portlet completes the operation by generating the portlet footer.

External Application Provider

External applications are stand alone applications, which typically have their own concept of a user's identity. This identity is different to the same user's identity in Oracle Portal, as defined by the Single Sign-On (SSO) Server. Such applications are integrated with the SSO Server as 'External Applications'. For each user, the SSO Server stores user name mappings, passwords and any other credentials required to authenticate the user in each external application. This allows Portal to hand a user over to an external application transparently, without requiring them to log in themselves.

An external application can be exposed as a provider using the PDK, so that it may be accessed from a portlet on a Portal page. External Application Providers is only available to web providers.

Authentication

The key to external application authentication is the ExternalPrincipal object. This object encapsulates all the information regarding the external application and the mapped user. Most external applications only require the mapped username and password to authenticate the user. The remaining information is provided for completeness, and for the few external applications whose only method of authentication is via a URL.

The ExternalPrincipal object contains the following information:

1. Mapped user name – The username of the current portal user in the external application. This is the username the user enters when the user creates the external application user mapping in the Single Sign-On Server.
2. Password – The password of the current portal user in the external application. This is the password the user enters when the user creates the external application user mapping in the Single Sign-On Server.
3. Authentication URL – The URL used by the Single Sign-On Server to perform authentication.
4. Authentication Method (GET/POST) – The HTTP method that should be used when submitting a request to the Authentication URL.
5. Optional name/value pairs – Additional name/value pairs as specified in the external application registration.

logical steps using Single Sign-On SDK

1. An authenticated portal user requests a portal page that contains a portlet from the external application.
2. The portal calls the provider’s initSession() passing an ExternalPrincipal object as one of the parameters.
3. The initSession() method extracts the necessary information from the ExternalPrincipal object and calls an appropriate API to authenticate the user. The actual API called and the parameters required depend on the external application.
4. If authentication is successful, the initSession() method establishes a provider session for the user. At this point, information may be stored in the servlet session indicating that the user has been successfully authenticated. Additional cookies may also be created if they are needed by the external application to identify an authenticated user. Any cookies created in initSession() are returned to the portal and passed back to the provider when subsequent requests are made.
   If authentication fails in the initSession() this information is returned to the portal. Upon detecting the Authentication failure, the portal generates a portlet that contains an error message and a link to the Single Sign-On Server page where the user can update mapping information (username and password) for the external application. Subsequent attempts to authenticate the user repeat the preceding steps until authentication is successful.

Portlet show mode

logical steps using Single Sign-On SDK

1. User submits a request for a portal page containing the external application provider’s portlet.
2. Upon receiving the request to view the portlet in SHOW mode, the portlet verifies the identity of the portal user by calling to one or more external application methods.
3. The external application verifies the identity of the portal using information from one or more of the following sources. The actual source depends on the implementation of initSession().
   • External provider’s session
   • Cookies created by the external application provider or external application
   • Information stored in a user session maintained independently by the external application
   • Parameters from the SHOW request (_mapped_name)
4. After authenticating the current user, the portlet renders the portlet header and makes one or more calls to the external application for the content that is to be rendered by the portlet.
5. The external application gathers information and either returns it to the portlet for formatting or formats it and writes the formatted output directly to the HTTP Response.
6. If information returned by the external application needs formatting, the portlet formats the information and writes it to the HTTP Response. After writing the portlet content, the portlet writes the portlet footer.

URL Services Provider

A URL Services Provider is a provider that allows you to create portlets by accessing existing content using a URL. Since a URL is used to access the content the technology used to generate the content is not important. The resulting content, which most likely represents a complete HTML page (including HTML headers), can be clipped or filtered. Using filters, you can eliminate the parts of the page you do not want to display in your portlet. This is only available for web providers.

Authentication

URL Services performs authentication using a similar approach to the Single Sign-On Server, leveraging the external application functionality and password store to maintain user mappings. The authentication procedure involves constructing an appropriate Login URL for the external application and submitting a request to that URL using the mapped username and password from the password store. Any cookies that are returned in response to the authentication request are saved and sent back to the remote application with all subsequent requests.

logical steps

1. User views a portal page containing a portlet from the URL Services provider. Since this is the first time the user views a portlet from the URL Services Provider in the current portal session, the provider’s initSession() method is called to establish a provider session.
2. The URL Services provider establishes a provider session between the portal and the provider. It then uses the authentication information specified in the provider definition file and constructs a login URL for the remote application. The login URL is constructed using the base login URL for the application, the portal user’s mapped username/password (which is obtained from the Single Sign-On Server) and any additional application specific parameters. Having constructed the URL, the URL Services Provider submits an HTTP request using the URL.
3. The remote application receives an HTTP request and processes the request. The processing that occurs at this point is entirely dependent on the remote application which can be thought of as a “black box” when using URL Services.
4. If any cookies are created in response to the request they are returned to the URL provider and stored in the provider session. They can then be used in subsequent requests to the remote application.

Portlet show mode

Portlet rendering with URL Services is similar to authentication in that the remote application is treated as a black box. The authentication overview describes how a URL is constructed and an HTTP request is submitted to authenticate a user with the remote application. Rendering content is very similar. A URL is submitted to the remote application and the content generated by the remote application is captured for display in the form of a portlet.

However, content from a web application cannot be included in a portlet because a portlet represents a fragment of a page whereas the content returned by the remote application is formatted as an entire page. Also, you may not want to display all the content returned by the remote application. You may be interested in only a fraction of the page. To resolve this problem, the content is filtered before it is included in the portlet.

URL Services currently provides two filters you can use, one for HTML content and one for XML. The URL Services framework also includes a simple interface you can implement to create your own filters if the basic ones do not meet your needs.

logical steps

1. A user requests a portal page containing a portlet from a URL Services provider.
2. The portlet renders the portlet header and then constructs a URL to retrieve the content from the remote application. Any cookies returned during the authentication sequence are sent with the request so the remote application can re-attach to the user’s session in the remote application.
3. The remote application re-attaches to the remote application session that is established during the authentication sequence and proceeds to generate the content. The content is returned to the URL Services provider as an HTTP response in the same format as returned to a regular web browser.
4. Convert any relative hyperlinks to absolute links from the content from the remote application. This is necessary because the user’s browser reads the completed page from the portal, not from the remote application. This means any links in the content must be absolute links back to the remote application. Once the links are converted, the content is streamed though the specified filter.
5. The filter processes the content according to the rules of the filter. The minimum requirement for filtering HTML content is to remove all the HTML headers along with the opening and closing <html> and <body> tags so the content can be included in a table cell. This is a requirement for all portlet content regardless of the source.
6. The portlet streams the content back to the portal and renders the portlet footer.