12 Creating Deployment-Specific Pages

OracleAS Single Sign-On provides a framework for integrating deployment-specific login, change password, and single sign-off pages with the single sign-on server. This means that you can tailor these pages to your UI look and feel and globalization requirements, using any suitable Web technology. We recommend, however, that you use JavaServer (JSP) pages. The sample pages provided with the product have been integrated using the same framework.

This chapter contains the following topics:

How the Single Sign-On Server Uses Deployment-Specific Pages
How to Write Deployment-Specific Pages
Page Error Codes
Adding Globalization Support
Guidelines for Deployment-Specific Pages
Installing Deployment-Specific Pages
Examples of Deployment-Specific Pages

12.1 How the Single Sign-On Server Uses Deployment-Specific Pages

The process that enables single sign-on pages can be summarized in a few steps:

The user requests a partner application and is redirected to the single sign-on server.
If the user is not authenticated, the single sign-on server either redirects the user to the sample login page or, if configured to use a deployment-specific page, redirects the user to this page. As part of the redirection, the server passes to the page the parameters contained in Table 12-1.
The user submits the login page, passing the parameters contained in Table 12-2 to the authentication URL:
```
http://sso_host:sso_port/pls/orasso/orasso.wwsso_app_admin.ls_login
```
or
```
https://sso_host:sso_ssl_port/pls/orasso/orasso.wwsso_app_admin.ls_login
```
At least two of these parameters, ssousername and password, appear on the page as modifiable fields.
If the user's password is not set to expire soon, and the single sign-on server successfully verifies the user name and password, the server redirects the user to the success URL of the application. If authentication fails, the server redirects the user back to the login page and displays an error message.
If the user's password is set to expire soon, the single sign-on server presents the change password page instead of the login page. Again, if the server is configured to use a deployment-specific change password page, it redirects the user to the URL for this page, passing to the page the parameters contained in Table 12-3.

Note:
In step 5, the same conditions apply if the directory administrator forces the user to change the password, password expiration notwithstanding.

The user submits the change password page, entering her old password, new password, and new password confirmation. The page passes the parameters contained in Table 12-4 to the change password URL:
```
http://sso_host:sso_port/sso/ChangePwdServlet
```
or
```
https://sso_host:sso_ssl_port/sso/ChangePwdServlet
```
If an error occurs, the single sign-on server redirects the user to the change password page and displays an error message. See "Change Password Page Behavior" in Chapter 3 for a detailed discussion of conditions under which errors may occur.

If the password change is successful, the user is redirected to the partner application URL that triggered the authentication request.
To finish the single sign-on session, the user clicks Logout in the partner application he or she is working in. This act calls application logout URLs in parallel, logging the user out from all accessed applications and ending the single sign-on session.
The user is redirected to the single sign-on server, which presents the single sign-off page. If the server is configured to use a deployment-specific page, it redirects the user to the URL for this page, passing to the page the parameters contained in Table 12-5.
The user can click Return on the single sign-off page to return to the application from which logout was initiated.

Note:

The change password page can be used to change a password only when the password is about to expire. The UI for Oracle Delegated Administration Services can be used for this purpose at any time. See "Change Password Page Behavior" in Chapter 3 for more about this topic.

12.2 How to Write Deployment-Specific Pages

The URLs for login, change password, and single sign-off pages must accept the parameters described in the tables that follow if these pages are to function properly.

This section contains the following topics:

Login Page Parameters
Forgot My Password
Change Password Page Parameters
Single Sign-Off Page Parameters

12.2.1 Login Page Parameters

The URL for the login page must accept the parameters listed in Table 12-1.

Table 12-1 Login Page Parameters Submitted to the Page by the Single Sign-On Server

Parameter	Description
site2pstoretoken	Contains the authentication request token for login processing.
ssousername	Contains the username.
p_error_code	Contains the error code in the form of a string. Passed when an error occurs during authentication.
p_cancel_url	Contains the URL to redirect to if the user clicks Cancel—if such a button exists on the login page. This URL points to the home URL of the partner application from which login was initiated.
locale	User's language preference (optional). Must be in ISO format. For example, French is `fr-fr`. For more about this parameter, see "Adding Globalization Support".

The login page must pass the parameters listed in Table 12-2 to the authentication URL:

http://sso_host:sso_port/pls/orasso/orasso.wwsso_app_admin.ls_login

Table 12-2 Login Page Parameters Submitted by the Page to the Single Sign-On Server

Parameter	Description
site2pstoretoken	Contains the redirect URL information for login processing.
ssousername	Contains the username. Must be UTF-8 encoded.
password	Contains the password entered by the user. Must be UTF-8 encoded.
subscribername	The subscriber nickname when realms are enabled. Must be UTF-8 encoded. Note: This field is required on the login page only when multiple realms are enabled in the single sign-on server.
locale	User's language preference (optional). Must be in ISO format. For example, French is `fr-fr`. For more about this parameter, see "Adding Globalization Support".
v	Contains the page version. Recommended but optional. If the parameter is passed, its value must be `v1.4`.

The login page must have at least two fields: a text field with the parameter name ssousername and a password field with the parameter name password. The values are submitted to the authentication URL. The login page must also include site2pstoretoken as a hidden parameter. It must submit this parameter to the login URL.

In addition to submitting these parameters, the login page is responsible for displaying appropriate error messages, as specified by p_error_code, redirecting to p_cancel_url if the user clicks Cancel.

12.2.2 Forgot My Password

When building your login page, you may want to configure it with a link that enables users to reset their passwords . This URL can go either to the home page for Oracle Delegated Administration Services or to the Forgot My Password link within Oracle Delegated Administration Services. Users who click the Forgot My Password link are challenged with a question. They must successfully answer this question before their password is reset.

Oracle Delegated Administration Services is generally available on the same computer as OracleAS Single Sign-On at a URL of the following form:

http://sso_host:sso_port/oiddas/

To learn how the Forgot My Password link is used to reset passwords, see the chapter about the Oracle Internet Directory Self-Service Console in Oracle Identity Management Guide to Delegated Administration.

12.2.3 Change Password Page Parameters

The URL for the change password page must accept the parameters listed in Table 12-3.

Table 12-3 Change Password Parameters Submitted to the Page

Parameter	Description
p_username	Contains the user name to be displayed somewhere on the page.
p_subscribername	The subscriber nickname when hosting is enabled. Note: This field is required on the login page.
p_error_code	Contains the error code, in the form of a string, if an error occurred in the prior attempt to change the password.
p_done_url	Contains the URL of the appropriate page to return to after the password is saved.
site2pstoretoken	Contains the `site2pstoretoken` that is required by the `LS_LOGIN` routine if the password has expired or is about to expire.
p_pwd_is_exp	Contains the flag value indicating whether the password has expired or is about to expire. The value can be either `WARN` or `FORCE`. See Table 12-6 for the associated error codes.
locale	User's language preference (optional). Must be in ISO format. For example, French is `fr-fr`. For more about this parameter, see "Adding Globalization Support".

The change password page must pass the parameters listed in Table 12-4 to the change password URL:

http://sso_host:sso_port/sso/ChangePwdServlet

Table 12-4 Change Password Page Parameters Submitted by the Page

Parameter	Description
p_username	Contains the user name to be displayed somewhere on the page. Should be posted as a hidden field by the change password page. Must be UTF-8 encoded.
p_old_password	Contains the user's old password. Must be UTF-8 encoded.
p_new_password	Contains the user's new password. Must be UTF-8 encoded.
p_new_password_confirm	Contains the confirmation of the user's new password. Must be UTF-8 encoded.
p_done_url	Contains the URL of the appropriate page to return to after the password is saved.
p_pwd_is_exp	Contains the flag value indicating whether the password has expired or is about to expire. The value can be either `WARN` or `FORCE`. See Table 12-6 for the associated error codes.
site2pstoretoken	Contains the redirect URL information for login processing.
p_action	Commits changes. The values must be either `OK` (commit) or `CANCEL` (ignore).
p_subscribername	Contains the user name to be displayed somewhere on the page.
p_request	Protected URL requested by the user.
locale	User's language preference (optional). Must be in ISO format. Example: French is `fr-fr`. See "Adding Globalization Support".

The change password page must have at least three password fields: p_old_password, p_new_password, and p_new_password_confirm. The page should submit these fields to the change password URL.

The page should also submit p_done_url as a hidden parameter to the change password URL. In addition, it should display error messages according to the value of p_error_code.

12.2.4 Single Sign-Off Page Parameters

The URL for the single sign-off page must accept the parameters listed in Table 12-5.

Table 12-5 Parameters Submitted to the Single Sign-Off Page

Parameter	Description
p_app_name[1. . .n]	Contains the application name to be displayed on the page. The variable `n` stands for the number of partner applications participating in single sign-off.
p_app_logout_url[1. . .n]	Contains the application logout URL. The variable `n` stands for the number of partner applications participating in single sign-off.
p_done_url	Contains the return URL. This URL returns users to the application from which they initiated logout.
locale	User's language preference in ISO format. Sent only if the user does not pass the same value during login.

12.3 Page Error Codes

URLs for login and change password pages must accept the process errors described in the tables that follow if these pages are to function properly.

12.3.1 Login Page Error Codes

The login page must process the error codes listed in Table 12-6.

Table 12-6 Login Page Error Codes

Value of p_error_code	Corresponding error
acct_lock_err	The user has committed too many login failures.
pwd_expiry_warn_err	The user's password is about to expire.
pwd_exp_err	The user's password has already expired.
pwd_force_change_err	The user must change his or her password.
pwd_grace_login_err	The user's password falls within the grace login period.
null_uname_pwd_err	The user did not type in a username.
auth_fail_exception	Authentication has failed.
null_password_err	The user did not type in a password.
sso_cookie_expired_err	The login cookie has expired. The user must log in again.
unexpected_exception	An unexpected error occurred during authentication.
unexp_err	Unexpected error.
internal_server_err	Internal server error.
internal_server_try_again_err	Internal server error. Try again.
gito_err	User's session has expired because of inactivity. User must log in again.
par_login_err	User must sign on again to gain access to the application.
cert_auth_err	Certificate sign-on has failed. User should check that the certificate is valid or should contact the administrator.
userid_mismatch	The user ID presented during a forced authentication does not match the user ID in the current single sign-on session.

12.3.2 Change Password Page Error Codes

The change password page must process the error codes listed in Table 12-7.

Table 12-7 Change Password Page Error Codes

Value of p_error_code	Corresponding Error
confirm_pwd_fail_txt	The old and the new password do not match.
pwd_expiry_warn_err	The password is about to expire.
pwd_force_change_err	The password must be changed before the user can proceed.
pwd_grace_login_err	The password has expired, but a grace login is permitted.
account_deactivated_err	The user account is disabled.
act_lock_err	The user account is locked.
pwd_illegal_value	The password contains an illegal value.
pwd_in_history	The password is in the password history.
pwd_min_length	The password does not meet the minimum length requirement.
pwd_numeric	The password does not meet the numeric character requirement.

12.4 Adding Globalization Support

The OracleAS Single Sign-On framework enables you to globalize deployment-specific pages to fit the needs of your deployment. When deciding what language to display the page in, you can adopt different strategies. Two are presented here.

12.4.1 Deciding What Language to Display the Page In

This section explains how to use either the HTTP Accept-Language header or deployment page logic to choose a language to display.

12.4.1.1 Use the Accept-Language Header to Determine the Page

Browsers enable end users to decide the language (locale) they would like to view their Web content in. The browser sends the language that the user chooses to the server in the form of the HTTP Accept-Language header. The logic of the deployment-specific page must examine this header and render the page accordingly. When it receives this page, the single sign-on server takes note of the header value for Accept-Language and sends it to partner applications when it propagates the user's identity. Note that, although many partner applications enable users to override this header, the single sign-off page appears in the language established at sign-on. The net effect is a consistent session language for all partner applications.

The Accept-Language header is the preferred mechanism for determining the language preference. A major benefit of this approach is that end users have typically already set their language preference while browsing other Web sites. The result is browsing consistency between these pages and single sign-on pages.

12.4.1.2 Use Page Logic to Determine the Language

Although Oracle recommends the approach described in the preceding section, you may choose to implement globalization based on mechanisms that extend or override the language preference set in the browser. You may, for instance, do one of the following:

Display a list of languages on the login page and allow the user to select from this list. As a convenience to the user, you can make this selection persistent by setting a persistent cookie.
Render the page in one, fixed language. This method is appropriate when you know that the user population is monolingual.
Obtain language preferences from a centralized application repository or a directory. A centralized store for user and system preferences and configuration data is ideal for storing language preferences.

If you use page logic to set language preferences, the page must propagate this information to the single sign-on server. The server must propagate this information to partner applications. The net result is a consistent globalization experience for the user. Your page must pass the language in ISO-639 format, using the locale parameter (Table 12-2) in the login form. A number of sites contain a full list of ISO-639 two-letter language codes. Here is one of them:

http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt

Here is a site that contains a full list of ISO-3166 two-letter country codes:

http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html

Note:

In the event that the locale parameter is passed to the single sign-on server (Table 12-1), the parameter value is sent to mod_osso. mod_osso prefixes this value to the HTTP Accept-Language header before passing the header to partner applications.

12.4.2 Rendering the Page

Once it determines the end-user's locale, the deployment-specific page must use the corresponding translation strings to render the page. To learn how to store and retrieve these strings, see the chapter about locale awareness in Oracle Application Server Globalization Guide. You may also want to consult standard documents about Java development. Here are two links:

Java Internationalization Guide:

http://java.sun.com/j2se/1.4.2/docs/guide/intl/index.html

General link for Java documentation:
```
http://java.sun.com/j2se/1.4.2/docs
```

12.5 Guidelines for Deployment-Specific Pages

When implementing deployment-specific pages, observe the following guidelines:

Oracle recommends that login and change password pages be protected by SSL.
The login and change password pages must code against cross-site scripting attacks.
The login and change password pages must have auto-fill and caching set to off. This prevents user credentials from being saved or cached in the browser. Here is an example of the AutoComplete tag:
```
<FORM NAME="foo" AutoComplete="off" METHOD="POST" ACTION="bar">
```
Oracle recommends that you configure your login page to display a banner that warns against unauthorized access. You may, for example, want to use the following text or a variant thereof:
```
Unauthorized use of this site is prohibited and may subject you to civil and criminal prosecution.
```
Deploy the login and change password pages on the computer that hosts the single sign-on server. This makes it easier to detect false versions of these pages.

12.6 Installing Deployment-Specific Pages

Use the policy.properties file to install deployment-specific login and change password pages. Use the WWSSO_LS_CONFIGURATION_INFO$ table to install the deployment-specific single sign-off page.

12.6.1 Using policy.properties to Install Login and Change Password Pages

To install your own login and change password pages, edit the following parameters in ORACLE_HOME/sso/conf/policy.properties:

#Custom login page link
loginPageUrl = login_page_URL

#Custom change password page link
chgPasswordPageUrl = change_password_page_URL

Finally, restart the single sign-on server:

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

12.6.2 Using policy.properties to Install Wireless Login and Change Password Pages

OracleAS Wireless has its own framework for integrating deployment-specific wireless login and change password pages. The procedure for installing these pages is similar to that used to install standard pages (section immediately preceding). First, go to ORACLE_HOME/sso/conf/policy.properties; then edit (add) the following parameters:

#Wireless login page link
wirelessLoginPageUrl = wireless_login_page_url
wirelessChgPasswordPageUrl = change_password_page_URL

Finally, restart the single sign-on server:

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

12.6.3 Using WWSSO_LS_CONFIGURATION$ to Install the Single Sign-Off Page

The WWSSO_LS_CONFIGURATION_INFO$ table in the single sign-on schema contains the LOGIN_URL column. Use this column to enable the single sign-off page.

LOGIN_URL contains three values separated by a space. The first two values are reserved for backward compatibility. Do not edit these values. The third value specifies the single sign-off page. If you are installing your own single sign-off page, you must modify this last value:

On the database where the single sign-on server is installed, log in to the single sign-on schema using SQL*Plus:
```
ORACLE_HOME/bin/sqlplus orasso/password
```
See Appendix B to learn how to obtain the password for the single sign-on schema.
Update LOGIN_URL. To replace the sample page with your own page, update the third value in the column. In the following example, single_signoff.jsp is the deployment-specific page.
```
UPDATE WWSSO_LS_CONFIGURATION_INFO$
SET LOGIN_URL='UNUSED UNUSED http://server.domain[:port]/single_signoff.jsp';
COMMIT;
```
To revert to the Oracle page, simply restore the original value:
```
UPDATE WWSSO_LS_CONFIGURATION_INFO$
SET LOGIN_URL='UNUSED UNUSED UNUSED';
COMMIT;
```
Note:
The first two values must be UNUSED.

12.7 Examples of Deployment-Specific Pages

The ipassample.jar file contains the files login-ex.jsp, password-ex.jsp, and signoff-ex.jsp. You may customize these to suit your deployment. If you want to use these files, see "Obtaining the Sample Files" in Chapter 2.

12.7.1 Using Custom Classes

In general, customized deployment-specific pages must operate with the current versions of component classes in use by OC4J_SECURITY. If your custom application needs to use a different version of a given class, you must deploy that class in a separate OC4J instance and not in the OC4J_SECURITY instance.

For example, if your deployment requires the use of custom log4j classes that conflict with the versions in use by OC4J_SECURITY, start a separate OC4J_SECURITY instance that uses a local log4j jar file containing the custom classes.

WARNING:

Replacing the classes used by OC4J_SECURITY with custom versions may render OracleAS Single Sign-On or other Oracle Application Server components unusable.