6 Using Forms Services with Oracle Application Server Single Sign-On

This chapter contains the following sections:

• Section 6.1, "Overview"

• Section 6.2, "Available Features with OracleAS Single Sign-On, Oracle Internet Directory and Forms"

• Section 6.4, "Enabling OracleAS Single Sign-On for an Application"

• Section 6.2.4, "Support for Database Password Expiration for Forms Running with OracleAS Single Sign-On"

• Section 6.6, "Authentication Flow"

6.1 Overview

Oracle Application Server Single Sign-On enables an application to authenticate users by means of a shared authentication token or authentication authority. For example, a user authenticated for one application is automatically authenticated for all other applications within the same authentication domain.

Oracle Application Server Forms Services applications can run in a Single Sign-on environment using Oracle Single Sign-On Server and Oracle Internet Directory to store user name and password information. OracleAS Single Sign-On is designed to work in Web environments where multiple Web-based applications are accessible from a Browser. Without OracleAS Single Sign-On, each user must maintain a separate identity and password for each application they access. Maintaining multiple accounts and passwords for each user is unsecured and expensive.

Note: Single Sign-on is not available with the Oracle Application Server Forms and Reports Services installation type. See the Oracle Application Server Forms and Reports Installation Guide for information on how to use an OracleAS Infrastructure.

The OracleAS Single Sign-On Server can be used to enable OracleAS Single Sign-On for other applications that are not Oracle products, like, for example, custom built J2EE applications.

Oracle Forms applications seamlessly integrate into a company's OracleAS Single Sign-On architecture based on Oracle Single Sign-On Server and the Oracle Internet Directory. Oracle Application Server Forms Services provides out-of-the box support for Single Sign-on for as many Forms applications as run by the server instance with no additional coding required in the Forms application.

6.2 Available Features with OracleAS Single Sign-On, Oracle Internet Directory and Forms

The following features and enhancements are available with this release of OracleAS Forms Services:

• Section 6.2.1, "Dynamic Resource Creation When A Resource Is Not Found In Oracle Internet Directory"

• Section 6.2.2, "Support for Default Preferences in Oracle Internet Directory to Define Forms Resources"

• Section 6.2.3, "Support for Dynamic Directives With Forms and OracleAS Single Sign-On"

• Section 6.2.4, "Support for Database Password Expiration for Forms Running with OracleAS Single Sign-On"

6.2.1 Dynamic Resource Creation When A Resource Is Not Found In Oracle Internet Directory

A user connects to Forms and is authenticated by mod_osso in combination with the OracleAS Single Sign-On Server and Oracle Internet Directory. Once the user is authenticated, the user is directed to the Forms Servlet which takes the user's request information containing the OracleAS Single Sign-On user name. The user name and the application name build a unique pair that identifies the user's resource information for this application in Oracle Internet Directory.

When an authenticated Forms user has neither the resource for a particular application that is being requested nor a default resource in Oracle Internet Directory, then the user is redirected to a Oracle Internet Directory/DAS page to dynamically create them. After creating the resource, the user is redirected back to the original Forms request URL.

The way Forms Services handles the missing resource information is customizable by the application or Forms Services administrator. The following options are available:

• Allow dynamic resource creation (default)

• Redirect the user to a pre-defined URL as specified by the ssoErrorUrl parameter

• Display the Forms error message

The redirection URL is provided by the system administrator in the Forms configuration files and should be either absolute or relative.

6.2.2 Support for Default Preferences in Oracle Internet Directory to Define Forms Resources

In previous releases, Forms uses resources added to each individual user account using the Oracle Delegated Administration Services. This implementation means that even if users share a common resource, it needs to be implemented for each user, no matter if there are 10 of them or 10,000.

In this Forms release, Forms and application administrators can define common used resources as default resources using the Oracle Internet Directory preferences. An administrator creates a resource once and all user accounts automatically inherit this resource to be used within Forms.

6.2.3 Support for Dynamic Directives With Forms and OracleAS Single Sign-On

Enforcing OracleAS Single Sign-On in Forms is now done within the formsweb.cfg file. There is now a new OracleAS Single Sign-On parameter, ssoMode, to indicate when a custom application requires OracleAS Single Sign-On authentication.

This parameter allows a Forms Services instance to handle both application types, public and OracleAS Single Sign-On protected Forms. Because OracleAS Single Sign-On is configured in the formsweb.cfg file, Enterprise Manager Application Server Control Console can read and write the single OracleAS Single Sign-On parameter.

6.2.4 Support for Database Password Expiration for Forms Running with OracleAS Single Sign-On

In previous releases of Oracle Forms, password changes between Oracle Forms and an Oracle database would be successful, but these changes (including expirations) would not propagate to Oracle Internet Directory.

Now in OracleAS Forms Services, if the database password has expired and the Forms Services application, running in OracleAS Single Sign-On mode, is used to renew it, then the new password entered by the user is used to update the Resource Access Descriptor (RAD) in Oracle Internet Directory for this application. This feature ensures that OracleAS Single Sign-On with Forms continues working even when a database password was changed. However, if password changes are made in SQL*PLUS, and not in Oracle Forms, then the database connect string is not updated in Oracle Internet Directory.

6.3 OracleAS Single Sign-On Components Used By Oracle Forms

The following software components in OracleAS are involved when running Forms applications in OracleAS Single Sign-On mode:

• Oracle Application Server Single Sign-On Server - an authentication Service in Oracle Application Server that uses Oracle Internet Directory to store user names and passwords

• mod_osso - The HTTP module mod_osso simplifies the authentication process by serving as the sole partner application to the Oracle Application Server Single Sign-On server, rendering authentication transparent for Oracle Application Server applications. OracleAS Forms Services and OracleAS Reports Services use mod_osso to register as a partner application to the Oracle Application Server Single Sign-On Server

• Oracle Internet Directory - A LDAP v3 compliant directory server that stores user login information. An LDAP server is a special database that is optimized for read access.

• Forms Servlet - The OracleAS Forms Services component that accepts the initial user request to start a Forms application. The Forms Servlet detects if an application requires OracleAS Single Sign-On, directs the request to the OracleAS Single Sign-On Server and accesses the Oracle Internet Directory to obtain the database connect information.

• formsweb.cfg - The Forms configuration file that contains the parameters to enable a Forms application for OracleAS Single Sign-On. The formsweb.cfg file is located in the forms/server directory of an Oracle Application Server installation.

6.4 Enabling OracleAS Single Sign-On for an Application

Oracle Forms applications are configured using a central configuration file, the formsweb.cfg file in the forms/server directory. The formsweb.cfg file can be edited by using Enterprise Manager Application Server Control Console, which Oracle recommends.

OracleAS Single Sign-On and error handling are defined by the following parameters in the formsweb.cfg file:

• ssoMode [true|false]

• ssoDynamicResourceCreate [true|false]

• ssoErrorUrl [String URL]

• ssoCancelUrl [String URL]

These Oracle Forms parameters in the formsweb.cfg file can be set in the "User Parameter" section, to make them the default behavior for all Forms applications run by the server, and in a "Named Configuration", making the settings valid for a particular application only. A OracleAS Single Sign-On definition overrides the same definition set in the User Parameter section.

6.4.1 ssoMode

The ssoMode parameter enables an Forms Services application for OracleAS Single Sign-On. By default, Oracle Forms applications are not configured to run in OracleAS Single Sign-On mode. The ssoMode parameter can be set in two places in the formsweb.cfg file. Setting ssoMode as a system parameter with a value of true allows all applications to run in OracleAS Single Sign-On mode by this Forms Services instance. Setting the ssoMode parameter in a named configuration of an Oracle Forms application enables or disables OracleAS Single Sign-On only for this particular application:

[myApp]
form=myFmx
ssoMode=true

To enable OracleAS Single Sign-On for an application: 

1. Start the Enterprise Manager Application Server Control Console.

2. Select Forms.

3. Select the Configuration tab.

4. Select the radio button next to the configuration section for your application and click Edit.

5. In the Name field, enter ssoMode.

6. In the Value field, enter true.

7. Click Add New Parameter.

8. Click Apply to update the formsweb.cfg file

   Single sign-on is now enabled for the selected application.

To disable OracleAS Single Sign-On for an application: 

1. Start the Enterprise Manager Application Server Control Console.

2. Select Forms.

3. Select the Configuration tab.

4. Select the radio button next to the configuration section for your application and click Edit.

5. Select the radio button next to the ssoMode parameter.

6. In the Value column, enter false.

7. Click Apply.

   Single sign-on is now disabled for the selected application.

6.4.2 ssoDynamicResourceCreate

The ssoDynamicResourceCreate parameter is set to true by default which allows the user to create a Resource Access Descriptor (RAD) entry in Oracle Internet Directory to run the application if this resource entry does not exist. The Web page that displays is a standard form provided by the Oracle Delegated Administration Services. This Web page is not customizable as it is not owned by Oracle Forms.

Allowing dynamic resource creation simplifies Oracle Internet Directory administration because there is no longer the need for an administrator to create user RAD information in advance. The ssoDynamicResourceCreate parameter can be set as a system parameter in the formsweb.cfg file or as a parameter of a named configuration. Because the default is set to true, this parameter may be used in a named configuration for a specific application to handle a missing RAD entry differently from the default.

Note that configuring an application as OracleAS Single Sign-On enabled with the value of the ssoDynamicResourceCreate parameter set to false, while not specifying a value for the ssoErrorURL, will cause Oracle Forms to show an error message if no RAD resource exists for the authenticated user and this application.

Since not all administrators want their users to create resources for themselves (and potentially raising issues with Oracle Internet Directory), these parameters allow administrators to control Oracle Internet Directory resource creation. Although the default behavior is to direct users to an HTML form that allows them to create the resource, the administrator can change the setting and redirect the user to a custom URL.

For the configuration section for the Forms application, you'll need to set these parameters:

[myApp]
form=myFmx
ssoMode=true
ssoDynamicResourceCreate=false

For information about setting these parameters through Enterprise Manager Application Server Control Console, see Chapter 4.3.3, "Managing Parameters".

6.4.3 ssoErrorURL

The ssoErrorURL parameter allows an administrator to specify a redirection URL that handles the case where a user RAD entry is missing for a particular application. This parameter only has effect if the ssoDynamicResourceCreate parameter is set to false, which disables the dynamic resource creation behavior. The ssoErrorURL parameter can be defined as a system parameter and as a parameter in a named configuration section. The URL can be of any kind of application, a static HTML file, or a custom Servlet (JSP) application handling the RAD creation, as in the example below.

[myApp]form=myFmxssoMode=truessoDynamicResourceCreate=falsessoErrorURL=http://myServ.com:7779/servlet/handleCustomRADcreation.jsp…

6.4.4 ssoCancelUrl

The ssoCancelURL parameter is used in combination with the dynamic RAD creation feature (ssoDynamicResourceCreate= true) and defines the URL that a user is redirected to if he presses the cancel button in the HTML form that is used to dynamically create the RAD entry for the requested application.

6.4.5 Accessing Single Sign-on Information From Forms

Optionally, if you need to work with OracleAS Single Sign-On authentication information in a Forms application, the GET_APPLICATION_PROPERTY() built-in can be used to retrieve the following OracleAS Single Sign-On login information: OracleAS Single Sign-On user ID, the user distinguished name (dn), and the subscriber distinguished name (subscriber dn)

authenticated_username := get_application_property('sso_userid') ;userDistinguishedName := get_application_property('sso_usrdn') ;subscriberName := get_application_property('sso_subdn') ;formsAppEntity := get_application_property('sso_formsid');config := get_application_property('config').

Note: config can be obtained even in non-SSO mode

6.5 Integrating Oracle Forms and Reports

Oracle Reports is installed with OracleAS Single Sign-On enabled.

The best practice for Oracle Forms applications calling integrated Oracle Reports is to use the Oracle Forms Built-in, RUN_REPORT_OBJECT.

When requesting a report from a OracleAS Single Sign-On protected Oracle Forms application, the authenticated user's OracleAS Single Sign-On identity is implicitly passed to the Reports Server with each call to RUN_REPORT_OBJECT Built-in. The OracleAS Single Sign-On identity is used to authenticate the user to the Reports Server for further authorization checking, if required.

A Forms application running in non-OracleAS Single Sign-On mode can run a report on a Single Sign-on secured Reports Server, but fails if the Reports Server requires authorization. Also users must provide their OracleAS Single Sign-On credentials when retrieving the Reports output on the Web.

For more information about integrating Oracle Forms and Oracle Reports, see the white paper Integrating Oracle Forms 10g and Oracle Reports 10g at Oracle Technology Network http://www.oracle.com/technology/products/forms/.

6.6 Authentication Flow

The following is the authentication flow of OracleAS Single Sign-On support in Oracle Forms the first time the user requests an application URL that is protected by Oracle Application Server Single Sign-On:

Figure 6-1 Authentication Flow for First Time Client Request

1. The user requests a Forms URL similar to http(s)://<hostname>:<port>/forms/frmservlet?config=<application>&...

2. The Forms Servlet redirects the user to the OracleAS Single Sign-On server.

3. The user provides user name and password through Login form.

4. The password is verified through Oracle Internet Directory (LDAP Server).

5. The user gets redirected to the URL with sso_userid information.

6. Forms Servlet gets the database credentials from Oracle Internet Directory.

7. Forms Servlet sets the user ID parameter in the Runform session and the applet connects to the Forms Listener Servlet.

8. Forms Servlet starts the Forms Server.

The following is the authentication flow of Oracle Application Server Single Sign-On support in OracleAS Forms Services when a user, authenticated through another Partner Application, requests an application that is protected by Oracle Application Server Single Sign-On.

Figure 6-2 Authentication Flow for Subsequent Client Requests

1. The user requests Forms URL.

2. Forms Servlet redirects the user to the OracleAS Single Sign-On Server.

3. The user gets redirected to the URL with sso_userid information.

4. Forms Servlet gets the database credentials from Oracle Internet Directory.

5. Forms Servlet sets the user ID parameter in the Runform session and the applet connects to the Forms Listener Servlet.

6. Forms Servlet starts the Forms Server.