5 Configuring and Administering External Applications

This chapter describes how to configure external applications for single sign-on support. These are Web applications that are not modified to delegate authentication to the single sign-on server. Configuring a Web application as an external application enables it to be single sign-on enabled without having to change its interface. See "External Applications" in Chapter 1 for more about these applications.

The chapter contains the following topics:

Using the Interface to Deploy and Manage External Applications
Proxy Authentication for Basic Authentication Applications

5.1 Using the Interface to Deploy and Manage External Applications

The Administer External Applications page, accessible as a link on the SSO Server Administration page, is used to add, edit, or delete external applications. Once you add these applications, users can access them in the External Applications portlet of OracleAS Portal. This portlet can be added to your Portal page after OracleAS is installed. See the chapter about viewing and customizing pages in Oracle Application Server Portal User's Guide.

This section covers the following topics:

Adding an External Application
Editing an External Application
Storing External Application Credentials in the Single Sign-On Database

5.1.1 Adding an External Application

Clicking the Add External Application link takes you to the Create External Application page. This page contains the following headings and fields:

Table 5-1 External Application Login

Field	Description
Application Name	Enter a name that identifies the external application. This is the default name for the external application.
Login URL	Enter the URL to which the HTML login page for the external application is submitted for authentication. This, for example, is the login URL for Yahoo! Mail: http://login.yahoo.com/config/login?6p4f5s403j3h0
Username/ID Field Name	Enter the term that identifies the user name or user ID field of the HTML login form for the application. You find this term by viewing the HTML source of the form. (See the example after the steps immediately following). This field is not applicable if you are using basic authentication.
Password Field Name	Enter the term that identifies the password field of the HTML login form for the application. You find this term by viewing the HTML source of the form. (See the example after the steps immediately following). This field is not applicable if you are using basic authentication.

Table 5-2 Authentication Method

Field	Description
Type of Authentication Use	Use the pulldown menu to select the form submission method for the application. This method specifies how message data is sent by the browser. You find this term by viewing the HTML source for the login form. Select one of the following three methods: POST: Posts data to the single sign-on server and submits login credentials within the body of the form. GET: Presents a page request to a server, submitting the login credentials as part of the login URL. Basic authentication: Submits the login credentials in the application URL, which is protected by HTTP basic authentication. Notes: Basic authentication uses pop-up windows, which by default are blocked by Windows XP, service pack 2. If you use this service pack, make sure that you reconfigure browser settings to display the window for the single sign-on login page. Use the pop-up blocker item in the Tools menu of Internet Explorer. Other browsers and browser plugins are able to block popups. Mozilla is one of these. Make sure that these do not block the single sign-on login page. If you use Internet Explorer 5.0 or a later version, basic authentication may not work with external applications. This version of Internet Explorer includes Microsoft MS04-004 Cumulative Security Update (832894). See this link for a workaround: http://support.microsoft.com

Field

Description

Type of Authentication Use

Use the pulldown menu to select the form submission method for the application. This method specifies how message data is sent by the browser. You find this term by viewing the HTML source for the login form. Select one of the following three methods:

POST: Posts data to the single sign-on server and submits login credentials within the body of the form.

GET: Presents a page request to a server, submitting the login credentials as part of the login URL.

Basic authentication: Submits the login credentials in the application URL, which is protected by HTTP basic authentication.

Notes:

Basic authentication uses pop-up windows, which by default are blocked by Windows XP, service pack 2. If you use this service pack, make sure that you reconfigure browser settings to display the window for the single sign-on login page. Use the pop-up blocker item in the Tools menu of Internet Explorer.

Other browsers and browser plugins are able to block popups. Mozilla is one of these. Make sure that these do not block the single sign-on login page.
If you use Internet Explorer 5.0 or a later version, basic authentication may not work with external applications. This version of Internet Explorer includes Microsoft MS04-004 Cumulative Security Update (832894). See this link for a workaround:
```
http://support.microsoft.com
```

Table 5-3 Additional Fields

Field	Description
Field Name	Enter the name of any additional fields on the HTML login form that may require user input to log in. This field is not applicable if you are using basic authentication.
Field Value	Enter a default value for a corresponding field name value, if applicable. This field is not applicable if you are using basic authentication.

Use the following steps to add an external application:

From the Administer External Applications page, select Add External Application.

The Create External Application page appears.
In the External Application Login field, enter the name of the external application and the URL to which the HTML login form is submitted. If you are using basic authentication, enter the protected URL.
If the application uses HTTP POST or HTTP GET authentication, in the User Name/ID Field Name field, enter the term that identifies the user name or user ID field of the HTML login form. You can find the name by viewing the HTML source of the login form.

If the application uses the basic authentication method, the User Name/ID Field Name field should be empty.
If the application uses HTTP POST or HTTP GET authentication, in the Password Field Name field, enter the term that identifies the password field of the application. See the HTML source of the login form.

If the application uses the basic authentication method, the Password Field Name field should be empty.
In the Additional Fields field, enter the name and default values for any additional fields on the HTML login form that may require user input.

If the application uses the basic authentication method, these fields should be empty.
Select the Display to User check box to allow the default value of an additional field to be changed by the user on the HTML login form.
Click OK. The new external application appears under the Edit/Delete External Application heading on the Administer External Applications page, along with the other external applications.
Click the application link to test the login.

The following example shows the source of the values that are used for Yahoo! Mail.

<form method=post action="http://login.yahoo.com/config/login?6p4f5s403j3h0" autocomplete=off name=a> 
...
<td><input name=login size=20 maxlength=32></td> 
.... 
<td><input name=passwd type=password size=20 maxlength=32></td> 
...
<input type=checkbox name=".persistent" value="Y" >Remember my ID & password 
...
</form>

The source provides values for the following:

http://login.yahoo.com/config/login?6p4f5s403j3h0

Username/ID Field Name: login
Password Field Name: passwd
Type of Authentication Used: POST
Field Name: .persistent Y
Field Value: [off]

Note:

If you change the host name of the AS middle tier, you must manually update the Login URL field for external applications on this middle tier. You do this on the Edit External Application page, described in the next section.

5.1.2 Editing an External Application

Clicking the pencil icon next to an application takes you to the Edit External Application page, where you can edit the values that you entered when you added the application. When you are finished editing, click Apply to enter the changes and to redisplay the page with the updated values.

5.1.3 Storing External Application Credentials in the Single Sign-On Database

Each external application expects to receive a user name and password each time the user logs in to the application. To enable single sign-on to these applications, users are given the option of storing their credentials in the single sign-on database when they log in.

If single sign-on users are logging in to an external application for the first time, they are presented with the External Application Login page. After entering credentials, they can select the check box Remember My Login Information for This Application. If they choose this option, the next time they access the application, the single sign-on server logs in on their behalf.

Figure 5-1 reproduces the External Application Login page.

Figure 5-1 External Application Login Page

Description of "Figure 5-1 External Application Login Page"

Note:

If you change your password, you must also update the password on the External Application Login page. If you neglect to do so, this page returns an error message when you try to log in.
Your password cannot contain the following characters: &, {, }, <, >, ", ', (, and ).

5.2 Proxy Authentication for Basic Authentication Applications

The standard way to access external applications enabled by single sign-on is through the External Applications portlet of OracleAS Portal, an SDK-enabled partner application. Applications accessed in this way can be configured for GET, POST, or basic authentication.

An alternative method is to use the Oracle HTTP Server as a secure proxy for applications that reside on a separate Web server. This method involves configuring the modules mod_osso and mod_proxy to support single-sign-on-enabled basic authentication. The advantage of the proxy approach is that it eliminates the brief screen flicker that occurs when external applications are accessed in the standard way.

This section contains the following topics:

Configuring the Oracle HTTP Server as a Proxy for Basic Authentication
Configuration Requirements
Configuration Steps

5.2.1 Configuring the Oracle HTTP Server as a Proxy for Basic Authentication

Configured correctly, authentication to mod_osso-enabled external applications is similar to what it is for partner applications: mod_osso intercepts a URL request and redirects it to the single sign-on server. Figure 5-2 illustrates the process.

Figure 5-2 Authentication Flow Using mod_osso/mod_proxy

Description of "Figure 5-2 Authentication Flow Using mod_osso/mod_proxy "

The single sign-on user requests an external application by selecting a bookmark or by entering a virtual URL. This URL enables the Oracle HTTP Server to intercept the request.
mod_osso adds an authentication header to the intercepted request and retrieves the user's credentials from the single sign-on server.
mod_osso sets the header value with the user's credentials, retrieved from the single sign-on server. mod_osso then passes this header to mod_proxy.
mod_proxy passes the user's credentials—in the form of a basic authentication header—to the real URL. mod_proxy does this by using directives that map the virtual URL to the real URL.

5.2.2 Configuration Requirements

The following criteria must be met before the Oracle HTTP Server can be configured for basic authentication to legacy applications:

The application to be proxied must be registered as a basic authentication application with the single sign-on server. See "Adding an External Application" for instructions.
The Oracle HTTP Server must have mod_osso installed and enabled.
The Oracle HTTP Server must have the default mod_proxy installed and enabled.
If the Web server that hosts the external application uses the Oracle HTTP Server as a proxy, the Web server must not have mod_osso enabled.

5.2.3 Configuration Steps

To configure the Oracle HTTP Server for basic authentication to external applications, complete these steps:

Add the section that follows to mod_osso.conf on the application tier. The file is at ORACLE_HOME/Apache/Apache/conf.
```
<IfModule mod_proxy.c>
<Location /application_virtual_path>
   require valid-user
   AuthType Basic
   OssoLegacyApp on | off
</Location>

ProxyPass /application_virtual_path/ http://host:port/application_real_ path/
ProxyPassReverse /application_virtual_path/ http://host:port/application_real_path/
</IfModule>
```
The OssoLegacyApp directive indicates whether the protected URL is a legacy application. If the directive is missing or is set to off, the code that retrieves the application user name and password from the single sign-on database is not executed. The two mod_proxy directives ProxyPass and ProxyPassReverse map the virtual URL to the real URL.
Add this line to httpd.conf:
```
Listen 5000
```
This parameter instructs mod_osso to use the non-SSL port 5000 to access information about external applications.

Restart the Oracle HTTP Server:

ORACLE_HOME/opmn/bin/opmnctl restartproc process-type=HTTP_Server

Update the Distributed Cluster Management schema:
```
ORACLE_HOME/dcm/bin/dcmctl updateConfig -v -d
```

Note:

The directory where the virtual URL resides need not be specified. For convenience, this URL may consist of only the application name.
If SSL is enabled, substitute https for http in the real URL of the application.