Oracle 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 Single Sign-On product ships with sample pages that are designed for testing with the Oracle Application Server.
This chapter contains the following topics:
The process that enables single sign-on pages can be summarized as follows:
The user requests a application and is redirected to the single sign-on server.
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 A-1.
The user submits the login page, passing the parameters contained in Table A-2 to the authentication URL:
http://sso_host:sso_port/oam/server/auth_cred_submit
or
https://sso_host:sso_ssl_port/oam/server/auth_cred_submit
At least two of these parameters, ssousername and password, appear on the page as modifiable fields.
If authentication fails, the server redirects the user back to the login page and displays an error message.
To finish the single sign-on session, the user clicks Logout in the 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.
Users who try to log in when their passwords have expired or are about to expire experience the following server behavior.
Users are shown the password expiry page. User must enter the old and the new password. The new password must conform to the Access Manager password policy rules.
A warning page is displayed where the user can either change their password, or continue without changing before continuing.
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 A-1.
Table A-1 Login Page Parameters Submitted to the Page by the Single Sign-On Server
| Parameter | Description |
|---|---|
p_error_code |
Contains the error code in the form of a string. Passed when an error occurs during authentication. |
request_id |
Unique identifier that is used to track requests routed back and forth between client and server. |
OAM_REQ |
User login request context tracked at client until authentication process is completed. |
The login page must pass the parameters listed in Table A-2 to the authentication URL:
http://sso_host:sso_port/sso/auth
Table A-2 Login Page Parameters Submitted by the Page to the Single Sign-On Server
| Parameter | Description |
|---|---|
ssousername |
Contains the username. Must be UTF-8 encoded. |
password |
Contains the password entered by the user. Must be UTF-8 encoded. |
|
|
User login request context tracked at client until authentication process is completed. |
|
|
Unique identifier that is used to track requests routed back and forth between client and server. |
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.
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.
The URL for the change password page must accept the parameters listed in Table A-3.
Note:
In a GIT deployment, when a partner logout flow requires query parameters in the p_done_url, the parameters must be URL encoded such that the Access Manager logout servlet does not interpret them as being Access Manager parameters but elements of the single p_done_url.
Table A-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 A-4 to the change password URL:
http://sso_host:sso_port/sso/ChangePwdServlet
Table A-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.
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.
When OAM Server is set to OSSO10g, the login page must process the error codes listed in Table A-5.
Table A-5 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 |
Description: 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." |
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.
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 applications when it propagates the user's identity. Note that, although many 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 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 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 A-2) in the login form. A number of sites contain a full list of ISO-639 two-letter language codes. 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 A-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 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.
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. Use this command to extract the file:
ORACLE_HOME/jdk/bin/jar -xvf ORACLE_HOME/sso/lib/ipassample.jar
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 Oracle Single Sign-On or other Oracle Application Server components unusable.
From the Single Sign-On Server Administration page, clicking the Administer External Applications link, then clicking Add External Application link takes you to the Add External Applications page. This page contains the following headings and fields:
Table A-6 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 A-7 Authentication Method
| Field | Description |
|---|---|
|
Type of Authentication Use |
Use the pull-down 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:
|
| 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. |
To add an external application:
From the Administer External Applications page, select Add External Application.
The Add External Applications 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:
Login URL:
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 Applications page, described in the next section.