Skip Headers
Oracle® Application Server Single Sign-On Administrator's Guide
10g (10.1.4.0.1)

Part Number B15988-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

12 Creating Deployment-Specific Pages

Oracle Application Server 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.

Oracle recommends that you use JavaServer (JSP) pages. Other Web technologies may provide inconsistent results. PLSQL pages are not supported. Sample pages are provided with the product. The Oracle Application Server Single Sign-On product ships with sample pages that are designed for testing with the Oracle Application Server.

This chapter contains the following topics:

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

The process that enables single sign-on pages can be summarized as follows:

  1. The user requests a partner application and is redirected to the single sign-on server.

  2. If the user is not authenticated, the single sign-on server redirects the user to the sample login page or to a deployment-specific page. As part of the redirection, the server passes to the page the parameters contained in Table 12-1.

  3. The user submits the login page, passing the parameters contained in Table 12-2 to the authentication URL:

    http://sso_host:sso_port/sso/auth
    
    

    or

    https://sso_host:sso_ssl_port/sso/auth
    
    

    At least two of these parameters, ssousername and password, appear on the page as modifiable fields.

  4. 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.

  5. 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.

  6. 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.

  7. 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.

  8. 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:

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/sso/auth

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 /sso/auth login URL 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-8 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-8 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.2.5 External Application Login Page Parameters

The URL for external application login pages must accept the parameters listed in Table 12-6.

Table 12-6 Parameters Submitted to the External Application Login Page

Parameter Description

ID

The external application ID. This ID appears on the Administer External Application page. For each external application configured in OracleAS Single Sign-On, a unique ID is generated. This ID is the primary key in the external application-related tables. The external application login page must pass this ID back to the application.

p_app_name

Contains the application name to be displayed on the page. This is the name for the external application that was provided when the application was configured in OracleAS Single Sign-On.

extappfieldname1..9

Extra field names. Each external application can have up to nine extra fields associated with it. These fields can be visible or non-visible. Visible fields appear on the external application login page, and the user can change the default value of the field. The non-visible field values are also submitted to the external application, but the user cannot change their value. For example, for an application that has login, password, and locale fields, you can add an field named LO with a value of FR. See "Adding an External Application" on page 5-1 for details.

extappfieldvalue1..9

Extra field values.

extappfielddisplay1..9

Extra field visibility (true or false). Determines if the field is visible to the user and is modifiable (true) or if the field has a fixed value (false).

mode

This parameter may or may not be passed to the custom login page. If it is passed to the login page, it must be submitted with its value set to modify. This indicates to the single sign-on application controller that the external application login page has been called from the portal to update the user's credentials in the database.

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.

done

The URL to which the response must be redirected after the user's credentials have been updated. This is used with modify mode.


This page must be able to submit the parameters shown in Table 12-7 using the POST method to the external application login controller:

Table 12-7 Parameters the External Application Login Page Submits to the Application

Parameter Description

ID

The external application ID.

p_app_username

Contains the user name of the person logging in to the application.

p_app_pwd

The password that the user submits.

p_remember_credentials

Flag that indicates to the external application login controller if the application user name and password must be saved to the database.

extappfieldname1..9

Extra field names. See Table 12–6 for details.

extappfieldvalue1..9

Extra field values.

extappfielddisplay1..9

Extra field visibility (true/false). See Table 12–6 for details.

p_change_password

A true/false flag that indicates to the external application login controller if the mode is set to change password.

mode

This parameter may or may not be passed to the custom login page. If it is passed to the login page, it must be submitted with its value set to modify. This indicates to the single sign-on application controller that the external application login page has been called from the portal to update the user's credentials in the database.

done

The URL to which the response must be redirected after the user's credentials have been updated.


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-8.

Table 12-8 Login Page Error Codes

Value of p_error_code Corresponding message and description
acct_lock_err

Description: The user has committed too many login failures.

Message: "Your account is locked. Please notify the system administrator."

pwd_exp_err

Description: The user's password has already expired.

Message: "Your password has expired. Please contact the administrator to reset it."

null_uname_pwd_err

Description: The user left the user name field blank.

Message: "You must enter a valid user name."

auth_fail_exception

Description: Authentication has failed.

Message: "Authentication failed. Please try again."

null_password_err

Description: The user left the password field blank.

Message: "You must enter your logon password."

sso_forced_auth

Description: The application requires authentication.

Message: "The application you are trying to access requires you to sign in again even if you have signed in previously."

unexpected_exception

Description: An unexpected error occurred during authentication.

Message: "An unexpected error occurred. Please try again."

unexp_err

Description: Unexpected error.

"Unexpected Error. Please contact Administrator."

internal_server_err

Description: Internal server error report.

Message: "Internal Server Error. Please contact Administrator."

internal_server_try_again_err

Description: Internal server error report with "try again" prompt.

Message: "Internal Server Error. Please retry the operation."

internal_server_try_later_err

Description: Internal server error report with "try later" prompt.

Message: "Internal Server Error. Please try the operation later."

gito_err

Description: Inactivity timeout. User must log in again.

Message: "Your Single Sign_on session has expired. For your security, your session expires after some duration of inactivity. Please sign in again."

cert_auth_err

Description: Certificate sign-on has failed. User should check that the certificate is valid or should contact the administrator.

Message: "Certificate-based sign in failed. Please ensure that you have a valid certificate or contact the administrator."

session_exp_error

Desscription: Single sign-on session time limit reached.

Message: "Your Single Sign-On session has expired. For your security, your session expires after the specified amount of time. Please sign in again."

userid_mismatch

Description: The user ID presented during a forced authentication does not match the user ID in the current single sign-on session.

Message: "The user name submitted for authentication does not match the user name present in the existing Single Sign-On session."


12.3.2 Post-Login Messages

The messages listed in Table 12-9 appear after the user authenticates. They are processed by the login page but may appear with the password change page.

Table 12-9 Post-Login Messages

Value of p_error_code Corresponding message and description
pwd_expiry_warn_err

Description: The user's password will expire soon.

Message: "Your password is about to expire. Please change it."

pwd_force_change_err

Description: The user's password has expired and the user is expected to change it.

Message: "You must change your password before you can continue."

pwd_grace_login_err

Description: The user's password has expired, but a grace period is in effect for resetting it.

Message: "Your password has expired. You are now in the grace login period. Please change your password."


12.3.3 Change Password Page Error Codes

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

Table 12-10 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.

null_new_pwd_err

The user did not enter a new password.

null_old_pwd_err

The user did not enter the old password.

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.

acct_lock_err

The user account is locked.

pwd_illegal_value

The password contains an illegal value.

pwd_in_history_err

The password is in the password history.

pwd_min_length_err

The password does not meet the minimum length requirement.

pwd_numeric

The password does not meet the numeric character requirement.


12.3.4 Change External Application Login Page Error Codes

The external application login page must process the error codes listed in Table 12-10.

Table 12-11 External Application Login Page Error Codes

Value of p_error_code Corresponding Error
eapp_name_null

The user ID is missing.

eapp_pwd_null

The password is missing.

ext_app_not_found

The external application cannot be identified.


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 strategies are presented in the following sections.

For a complete list of the language codes supported, see Appendix A in Oracle Application Server Globalization Guide at the following URL:

http://www.oracle.com/technology/documentation/index.html

From the landing page for the URL, click a link for the OracleAS Single-Sign on documentation, then click the View Library link to view the library for the appropriate release.

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:

12.5 Guidelines for Deployment-Specific Pages

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

12.6 Installing Deployment-Specific Pages

Use the policy.properties file to install deployment-specific login and change password pages.

12.6.1 Using policy.properties to Install Login, Single Sign-Off, and Change Password Pages

You can configure login, single sign-off, and change password pages.

To install your own login, single sign-off, and change password pages:

  1. Edit the parameters in ORACLE_HOME/sso/conf/policy.properties. Substitute the paths to your login, logout, and password change pages for the values shown in the example:

    #Deployment login page link
    loginPageUrl = /sso/pages/login.jsp
    logoutPageUrl = /sso/pages/logout.jsp
    
    #Deployment change password page link
    chgPasswordPageUrl = /sso/pages/password.jsp
    
    
  2. 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).

To install wireless login and change password pages:

  1. Open ORACLE_HOME/sso/conf/policy.properties.

  2. Edit or add the following parameters:

    #Wireless login page link
    wirelessLoginPageUrl = wireless_login_page_url
    wirelessChgPasswordPageUrl = change_password_page_URL
    
    
  3. 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.3 Using policy.properties to Install External Application Login Pages

You can configure login pages that are presented to users when they log in to third-party applications.

To configure login pages for third-party applications:

  1. Be sure these pages accept the page parameters and page error codes discussed in "Login Page Parameters" on page 12-3 and "Page Error Codes" on page 12-7.

  2. After configuring the login pages, edit the extAppLoginPageUrl parameter in ORACLE_HOME/sso/conf/policy.properties, substituting the path to your login page for the path shown in the following example:

    extAppLoginPageUrl = /sso/pages/ealogin.jsp
    ORACLE_HOME/opmn/bin/opmnctl restartproc process-type=OC4J_SECURITY
    
    
  3. Optionally, you can configure the application page

  4. 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.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.