|
Oracle® Application Server Single Sign-On Administrator's Guide
10g Release 2 (10.1.2) B14078-02 |
|
 Previous |
 Next |
|
Oracle® Application Server Single Sign-On Administrator's Guide
10g Release 2 (10.1.2) B14078-02 |
|
|
Previous |
Next |
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:
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. |
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:
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 |
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 |
|---|---|
|
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 |
v |
Contains the page version. Recommended but optional. If the parameter is passed, its value must be |
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.
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.
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 |
p_pwd_is_exp |
Contains the flag value indicating whether the password has expired or is about to expire. The value can be either |
locale |
User's language preference (optional). Must be in ISO format. For example, French is |
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 |
site2pstoretoken |
Contains the redirect URL information for login processing. |
p_action |
Commits changes. The values must be either |
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 |
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.
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
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.
The login page must process the error codes listed in Table 12-6.
Table 12-6 Login 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. |
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.
This section explains how to use either the HTTP Accept-Language header or deployment page logic to choose a language to display.
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.
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 thelocale 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.
|
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
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.
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.
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
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
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 beUNUSED.
|
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.
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. |
