Skip Headers

Oracle9iAS Single Sign-On Administrator's Guide
Release 2 (9.0.2)

Part Number A96115-01
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

8
Customizing the Single Sign-On Interface

This chapter explains how to incorporate Single Sign-On Login, Change Password, and Single Sign-Off pages customized to match your portal or product. At the end of the chapter are examples of how the three pages might be reworked as JavaServer pages (JSPs).

Customized pages can be any type of Web page: a PL/SQL procedure, a CGI script, or a JSP. With each of these options, the pages must support certain parameters to function properly.

The chapter covers the following topics:

Installing Customized Login, Change Password, and Single Sign-Off Pages

The WWSSO_LS_CONFIGURATION_INFO$ table in the Single Sign-On schema contains the LOGIN_URL column, which is used to enable customized Login, Change Password, and Single Sign-Off pages.

The LOGIN_URL column contains three values separated by a space. The first value specifies the URL for the Login page, the second the URL for the Change Password page, and the third the value for the Single Sign-Off page.

By default, the LOGIN_URL column contains the values UNUSED UNUSED UNUSED, which specify that the Login, Change Password, and Single Sign-Off pages use the standard Single Sign-On pages.

Perform the following steps to install customized Login, Change Password, and Single Sign-Off pages.

  1. On the database where the Single Sign-On server is installed, log in to the Single Sign-On schema using SQL*Plus, as in the following example:

    sqlplus orasso/orasso
    
    
    
  2. Update the LOGIN_URL column.

    To replace just the Login page with the customized page, update the first value in the LOGIN_URL column, as in the following example:

    UPDATE WWSSO_LS_CONFIGURATION_INFO$
    SET LOGIN_URL='http://server.domain[:port]/login.jsp UNUSED';
    
    

    To replace just the Change Password page with a customized page, update the second value in the LOGIN_URL column, as in the following example:

    UPDATE WWSSO_LS_CONFIGURATION_INFO$
    SET LOGIN_URL='UNUSED http://server.domain[:port]/change_password.jsp';
    
    

    To replace just the Single Sign-Off page with a customized page, update the third value in the LOGIN_URL column, as in the following example:

    UPDATE WWSSO_LS_CONFIGURATION_INFO$
    

    SET LOGIN_URL='UNUSED UNUSED http://server.domain[:port]/single_sign_off.jsp';

    
    

    To replace all three pages, update all three values in the LOGIN_URL column, as in the following example:

    UPDATE WWSSO_LS_CONFIGURATION_INFO$
    SET LOGIN_URL='http://server.domain[:port]/login.jsp
    http://server.domain[:port]/change_password.jsp
    http://server.domain[:port]/single_sign_off.jsp';
    
    
  3. To revert to using the standard pages, restore the original values, as in the following example:

    UPDATE WWSSO_LS_CONFIGURATION_INFO$
    SET LOGIN_URL='UNUSED UNUSED UNUSED';
    

How Customized Single Sign-On Pages Are Enabled

This section contains the following sections:

Enabling the Customized Login Page

When a partner application redirects a user to the Single Sign-On server, the server calls a procedure that creates the Login page.

The process is as follows:

  1. The application calls WWSSO_APP_ADMIN.LS_LOGIN to authenticate the user.

  2. If the user does not yet have an Oracle9iAS Single Sign-On session, LS_LOGIN calls WWSSO_LOGIN.DRAW_LOGIN_PAGE to display the standard login page.

  3. DRAW_LOGIN_PAGE submits a form to WWSSO_APP_ADMIN.LS_LOGIN to process the credentials.

  4. If the user is authenticated, LS_LOGIN redirects to the application's success URL, which then redirects to the requested application page.

The customized solution provides the option of redirecting to a separate URL to create the login page, instead of making a PL/SQL call to WWSSO_LOGIN.DRAW_LOGIN_PAGE. The URL can point to a Java Server Page, a CGI script, or other type of page. The page should process the name of the routine to which the login form is submitted--such as WWSSO_APP_ADMIN.LS_LOGIN--and submit the form appropriately.

The flow of logic is as follows:

  1. The user selects the Login button on the Login page. Selecting this button invokes the WWSSO_APP_ADMIN.LS_LOGIN routine to authenticate the user.

  2. If a URL is specified in the LOGIN_URL column for displaying the login page, LS_LOGIN redirects to that URL.

    If a URL is not specified in the LOGIN_URL column, LS_LOGIN calls WWSSO_LOGIN.DRAW_LOGIN_PAGE to draw the standard login page.

  3. The login page submits a form to WWSSO_APP_ADMIN.LS_LOGIN to process the credentials.

  4. If the user is authenticated, LS_LOGIN redirects to the requested application page. The Single Sign-On server uses the LOGIN_URL column of the WWSSO_LS_CONFIGURATION_INFO$ table to store the URL for the customized login page.

Enabling the Customized Change Password Page

The Change Password page is created by the PL/SQL routine WWSSO_APP_USER_MGR.CHANGE_PASSWORD. This routine renders the screen and commits the form through an API to the database.

The process is as follows:

  1. The user selects the Change Password link on the SSO Server Administration page. Selecting this link invokes the WWSSO_APP_USER_MGR.CHANGE_PASSWORD routine.

  2. CHANGE_PASSWORD displays the Change Password page, which displays the username and has fields for the old password, the new password, and the password confirmation. It also has OK and Cancel buttons.

  3. CHANGE_PASSWORD processes the new password.

  4. CHANGE_PASSWORD saves the new password and redirects to the appropriate application page.

To accommodate a customized Change Password page, the logic for the Change Password page has been modified as follows:

  1. The WWSSO_APP_USER_MGR.CHANGE_PASSWORD routine is invoked to display the Change Password page.

  2. If a separate URL is to display the Change Password page, CHANGE_PASSWORD redirects to that URL.

    If no separate URL is specified, CHANGE_PASSWORD calls WWSSO_APP_USER_MGR.DRAW_CHANGE_PASSWORD_PAGE to display the standard Change Password page.

  3. The Change Password page submits a form to WWSSO_APP_USER_MGR.SAVE_NEW_PASSWORD to process and save the new password.

  4. If there are no errors, SAVE_NEW_PASSWORD saves the new password and redirects to the Single Sign-On home page.

The LOGIN_URL column of the WWSSO_LS_CONFIGURATION_INFO$ table stores the URL for the customized Change Password page. The CHANGE_PASSWORD routine queries the value of the LOGIN_URL column to determine how to proceed. This column contains URLs for the Login and Change Password pages, separated by a space.

The Change Password page is also displayed immediately following a user login if the user's password has expired or will be expiring soon. If the password has expired, the Change Password page appears with the appropriate message and the following process occurs:

  1. WWSSO_APP_ADMIN.LS_LOGIN calls WWSSO_APP_USER_MGR.CHANGE_PASSWORD to display the Change Password page.

  2. If a separate URL is to display the Change Password page, CHANGE_PASSWORD redirects to that URL.

    If a separate URL is not specified, CHANGE_PASSWORD calls WWSSO_APP_USER_MGR.DRAW_CHANGE_PASSWORD_PAGE and displays the standard Change Password page.

  3. The Change Password page submits a form to WWSSO_APP_USER_MGR.SAVE_NEW_PASSWORD to process and save the new password.

  4. If there are no errors and the user selects OK, SAVE_NEW_PASSWORD saves the new password and returns control to WWSSO_APP_ADMIN.LS_LOGIN to perform the necessary login steps.

  5. If there are errors or if the user selects Cancel, SAVE_NEW_PASSWORD calls CHANGE_PASSWORD and redisplays the Change Password page. This process repeats until the user changes the password successfully.


    Note:

    Selecting Cancel should not allow a user to continue if the password has expired. However, if the password is set to expire after a certain number of days and the user selects Cancel, the login resumes and the user's password remains unchanged.


If the user's password is about to expire, the Change Password page appears with the appropriate message and the following process occurs:

  1. WWSSO_APP_ADMIN.LS_LOGIN calls WWSSO_APP_USER_MGR.CHANGE_PASSWORD to display the Change Password page.

  2. If a separate URL is to display the Change Password page, CHANGE_PASSWORD redirects to the separate URL.

    If no separate URL is specified, CHANGE_PASSWORD calls WWSSO_APP_USER_MGR.DRAW_CHANGE_PASSWORD_PAGE to display the standard Change Password page.

  3. The Change Password page submits a form to WWSSO_APP_USER_MGR.SAVE_NEW_PASSWORD to process and save the new password.

  4. If there are no errors and the user selects OK, SAVE_NEW_PASSWORD saves the new password and returns control to WWSSO_APP_ADMIN.LS_LOGIN to perform the necessary login steps.

  5. If there are errors, SAVE_NEW_PASSWORD calls CHANGE_PASSWORD and redisplays the Change Password page.

  6. If the user selects Cancel, SAVE_NEW_PASSWORD does not save the new password but returns control to WWSSO_APP_ADMIN.LS_LOGIN to perform the login steps using the current password.

Enabling the Single Sign-Off Page

The Single Sign-Off page logs off users from all active partner applications simultaneously. When users select an application logout link, they are redirected to the Single Sign-Off URL of the Single Sign-On server. First this URL deletes the server cookies; then it calls application logout URLs in parallel, using the HTML IMG tag. The application logout URLs delete application session cookies and then stream a small image indicating a successful application logout.

The process is as follows:

  1. The User selects the application logout link.

  2. The user is redirected to the Single Sign-Off URL, WWSSSO_APP_ADMIN.LS_LOGOUT with a return URL, p_done_url parameter.

  3. The Single Sign-Off URL deletes Single Sign-On server cookies and then checks the login_url column of the wwsso_ls_configuration_info$ table to determine whether a customized page should be used.

  4. If the login_url column of the wwsso_ls_configuration_info$ table indicates that the standard page should be used, the Single Sign-On server calls the wwsso_login.draw_logout_page procedure. This procedure renders the standard Single Sign-Off page.

  5. If the login_url column indicates that a customized page should be used, the Single Sign-Off URL redirects the user to the customized page, passing the parameters required for Single Sign-Off.

  6. The Single Sign-Off page calls application logout URLs in parallel and the user is logged out from all applications.

Parameters for Login, Change Password, and Single Sign-Off 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 covers the following topics:

Login Page Parameters

The URL for the Login page must accept the parameters listed in Table 8-1.

Table 8-1 Login Page Parameters
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 VARCHAR2, if an error occurred during authentication.

p_cancel_url

Contains the URL to redirect to if the user selects Cancel, if such a button exists on the login page.

p_submit_url

Contains the URL that the login page must submit the form to, WWSSO_APP_ADMIN.LS_LOGIN.

subscribername

Reserved for future use.

Note: This field is required on the login page.

The customized login page must conform to the wwsso_app_admin.ls_login procedure in the same manner as the standard login page; passing the parameters listed in Table 8-2 to the p_submit_url routine:

Table 8-2 Customized Login Page Parameters
Parameter Description

site2pstoretoken

Contains the redirect URL information for login processing.

ssousername

Contains the username.

p_error_code

Contains the error code, in the form of a VARCHAR2, if an error occurred during authentication.

password

Contains the password entered by the user.

subscribername

Reserved for future use.

Note: This field is required on the login page.

The customized 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 p_submit_url routine. The login page must also submit the site2pstoretoken value as a hidden parameter.

In addition to submitting these parameters, the login page is responsible for displaying appropriate error messages, as specified by the p_error_code parameter, redirecting to p_cancel if the user selects Cancel and populating the ssousername text field with the given parameter value in the case of a login error.

If the customized login page requires additional fields, you can include them. Ensure that additional fields are appropriately wrapped to conform to the above convention for integration with the Single Sign-On server.

Change Password Page Parameters

The URL for the Change Password page must accept the parameters listed in Table 8-3.

Table 8-3 Change Password Page Parameters
Parameter Description

p_username

Contains the username to be displayed somewhere on the page.

p_password

Contains the user's original password (if password is or is about to expire).

p_error_code

Contains the error code, in the form of a VARCHAR2, if an error occurred in the prior attempt to change password.

p_submit_url

Contains the URL that the Change Password form must submit to.

p_done_url

Contains the URL of the appropriate Oracle9iAS Portal 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.

site2pstoretoken

Contains the site2pstoretoken that is required by the LS_LOGIN routine if the password has expired or is about to expire.

The customized Change Password page must pass the parameters listed in Table 8-4 to the p_submit_url routine.

Table 8-4 Customized Change Password Page Parameters
Parameter Description

p_username

Contains the username to be displayed somewhere on the page. Should be posted as a hidden field by the custom Change Password page.

p_old_password

Contains the user's old password.

p_new_password

Contains the user's new password.

p_new_password_confirm

Contains the confirmation of the user's new password.

p_done_url

Contains the URL of the appropriate Oracle9iAS Portal 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.

site2pstoretoken

Contains the redirect URL information for login processing.

p_password

Contains the password entered by the user.

p_action

Commits changes. The values must be either OK (commit) or CANCEL (ignore); otherwise, p_action defaults to null and does not commit changes.

The Change Password page must have at least three password fields with the following parameter names:

The Change Password page should submit these fields to the p_submit_url parameter.

The Change Password page should also submit the p_done_url parameter, as a hidden parameter, to the p_submit_url parameter, and should appropriately display any error messages according to the value of p_error_code.

For external applications, the Change Password page must submit the following parameters, as hidden parameters, to the standard HTML login form.

Single Sign-Off Page Parameters

The URL for the Single Sign-Off page must accept the parameters listed in Table 8-5.

Table 8-5 Single Sign-Off Page Parameters
Parameter Description

p_app_name

Contains the application name to be displayed on the page.

p_app_logout_url

Contains the application logout URL.

p_done_url

Contains the return URL. This URL returns users to the application from which they initiated logout.

Error Codes for Login and Change Password Pages

URLs for Login and Change Password pages must accept the parameters described in the tables that follow if these pages are to function properly.

This section covers the following topics:

Login Page Error Codes

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

Table 8-6 Customized Login Page Error Codes
Value of p_error_code Corresponding error

acct_ip_lock_err

The user has committed too many login failures from this IP address and has been locked out.

acct_lock_err

The user has committed too many login failures from any IP address and has been globally locked out.

null_uname_pwd_err

The user did not type in a username.

no_papp_err

The partner application configuration is missing or expired.

ssl_not_used_err

SSL is not being used.

ls_config_not_found_err

The Single Sign-On server configuration is missing.

cookies_disabled_err

The user's browser is not accepting cookies.

auth_fail_exception

Authentication has failed.

account_deactivated_err

The user's account has been terminated.

value_error_exception

An invalid value was specified in site2pstoretoken.

null_password_err

The user did not type in a password.

ext_auth_unknown_err

There was an unknown error in accessing the external authentication mechanism.

ext_auth_setup_err

There was an error in the setup of the external authentication mechanism.

sso_cookie_expired_err

The login cookie has expired. The user needs to log in again.

unexpected_exception

An unexpected error occurred during authentication.

Change Password Page Error Codes

The customized Change Password page must process the error codes listed in Table 8-7.

Table 8-7 Change Password Page Error Codes
Value of p_error_code Corresponding Error

null_old_pwd_err

The user did not type in an old password.

null_new_pwd_err

The user did not type in a new password.

confirm_pwd_fail_txt

The user typed in a new password confirmation that did not match the new password.

auth_fail_err

The user typed in an invalid old password.

pwd_rule_err

The user typed in a new password that does not meet the password requirements of the Single Sign-On server.

invalid_auth_mode_err

The change password operation is not supported by the current authentication mechanism.

ext_not_supported_err

The external repository is not supported.

ext_change_pwd_err

The change password operation was unsuccessful on the external repository.

pwd_expired_err

The password has expired.

pwd_needs_change_err

The password is about to expire. The user is allowed to log in.

Sample Customized Pages

This section gives examples of how standard Single Sign-On Login, Change Password, and Single Sign-Off pages might be modified as JSPs. As such, the examples provide a basis for customizing these pages to suit enterprise needs.

Three examples are provided:

Sample Login Page

<html>
<body bgcolor="white">

<%@ page buffer="5" autoFlush="true" %>
<%
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "Thu, 29 Oct 2000 17:04:19 GMT");

try
{
   String  str_token  = request.getParameterValues("site2pstoretoken")[0];
   String  str_user   = request.getParameterValues("ssousername")[0];
   String  str_err    = request.getParameterValues("p_error_code")[0];
   String  str_cancel = request.getParameterValues("p_cancel_url")[0];
   String  str_submit = request.getParameterValues("p_submit_url")[0];

   out.println("<center><h1>Single Sign-On Login</h1><p>");
   out.println("<form method='post' action='"+str_submit+"'>");
   out.println("<INPUT TYPE='hidden' NAME='site2pstoretoken'");
   out.println(" value='"+str_token+"'>");

   out.println("<table border=0>");
   if((str_err != null) && (str_err.length() > 1))
   {
       out.println("<tr>");
       out.println("<td>");
       out.println("<font color='red'>ERROR:</font>");
       out.println("</td>");
       out.println("<td>");
       out.println(str_err);
       out.println("</td>");
       out.println("</tr>");
   }

   out.println("<tr>");
   out.println("<td>");
   out.println("User Name:");
   out.println("</td>");
   out.println("<td>");
   out.println("<INPUT TYPE='text' NAME='ssousername'>");
   out.println("</td>");
   out.println("<tr>");
   out.println("<tr>");
   out.println("<td>");
   out.println("Password");
   out.println("</td>");
   out.println("<td>");
   out.println("<INPUT TYPE='password' NAME='password'>");
   out.println("</td>");
   out.println("<tr>");

   out.println("<tr>");
   out.println("<td>");
   out.println("<INPUT TYPE='submit' VALUE='Login'>");
   out.println("<INPUT TYPE='button' NAME='p_request' VALUE='Cancel' ");
   out.println("  onClick='javascript:document.location.href = '"+str_
cancel+"';'>");
   out.println("<td>");
   out.println("</tr>");
   out.println("</table>");

   out.println("</form>");
}
catch(Exception e)
{
    out.println("<h2><center><font color='red'>ERROR:</font>");
    out.println("This page can not be accessed directly!</center></h2>");
}

%>
</body>
</html>

Sample Change Password Page

<html>
<body bgcolor="white">

<%@ page buffer="5" autoFlush="true" %>

<%
    response.setHeader("Pragma", "no-cache");
    response.setHeader("Cache-Control", "no-cache");
    response.setHeader("Expires", "Thu, 29 Oct 2000 17:04:19 GMT");
%>

<script language="JavaScript">
<!--
function button1submit()
{
   document.ChangePassword.p_action.value = "OK";
   document.ChangePassword.submit();
}

function button2submit()
{
   document.ChangePassword.p_action.value = "CANCEL";
   document.ChangePassword.submit();
}
//-->"
</script>

<%
try
{
   String str_token   = request.getParameterValues("site2pstoretoken")[0];
   String str_user    = request.getParameterValues("p_username")[0];
   String str_pwd     = request.getParameterValues("p_password")[0];
   String str_err     = request.getParameterValues("p_error_code")[0];
   String str_done    = request.getParameterValues("p_done_url")[0];
   String str_submit  = request.getParameterValues("p_submit_url")[0];
   String str_pwd_exp = request.getParameterValues("p_pwd_is_exp")[0];
   out.println("<center><h1>Single Sign-On Change Password</h1><p>");

   out.println("<form method='post'  name='ChangePassword' action='"+str_
submit+"'>");

   out.println("<INPUT TYPE='hidden' NAME='p_username' value='"+ str_user
+"'>");
   out.println("<INPUT TYPE='hidden' NAME='site2pstoretoken' value='"+ str_token
+"'>");
   out.println("<INPUT TYPE='hidden' NAME='p_done_url' value='"+ str_done
+"'>");
   out.println("<INPUT TYPE='hidden' NAME='p_pwd_is_exp' value='"+ str_pwd_exp
+"'>");
   out.println("<INPUT TYPE='hidden' NAME='p_password' value='"+ str_pwd +"'>");
   out.println("<INPUT TYPE='hidden' NAME='p_request' value=''>");
   out.println("<INPUT TYPE='hidden' NAME='p_action' value=''>");

   out.println("<table border=0>");

   if((str_err != null) && (str_err.length() > 1))
   {
       out.println("<tr>");
       out.println("<td>");
       out.println("<font color='red'>ERROR:</font>");
       out.println("</td>");
       out.println("<td>");
       out.println(str_err);
       out.println("</td>");
       out.println("</tr>");
   }
   out.println("<tr>");
   out.println("<td>");
   out.println("User Name:");
   out.println("</td>");
   out.println("<td>");
   out.println(str_user);
   out.println("</td>");
   out.println("<tr>");


   out.println("<tr>");
   out.println("<td>");
   out.println("Old password:");
   out.println("</td>");
   out.println("<td>");
   out.println("<INPUT TYPE='password' NAME='p_old_password'>");
   out.println("</td>");
   out.println("<tr>");

   out.println("<tr>");
   out.println("<td>");
   out.println("New password:");
   out.println("</td>");
   out.println("<td>");
   out.println("<INPUT TYPE='password' NAME='p_new_password'>");
   out.println("</td>");
   out.println("<tr>");

   out.println("<tr>");
   out.println("<td>");
   out.println("Confirm new password:");
   out.println("</td>");
   out.println("<td>");
   out.println("<INPUT TYPE='password' NAME='p_new_password_confirm'>");
   out.println("</td>");
   out.println("<tr>");

   out.println("<tr>");
   out.println("<td>");
   out.println("<INPUT TYPE='button' NAME='p_request' VALUE='OK' "
       +" onClick='javascript:button1submit();'>");
   out.println("<INPUT TYPE='button' NAME='p_request' VALUE='Cancel' "
       +"onClick='javascript:button2submit();'>");
   out.println("</td>");
   out.println("<tr>");

   out.println("</table");

   out.println("</form>");
}
catch(Exception e)
{
    out.println("<h2><center><font color='red'>ERROR:</font>");
    out.println("This page can not be accessed directly!</center></h2>");
}

%>
</body>
</html>

Sample Single Sign-Off Page

<html>
<body bgcolor="white">

<%@ page buffer="5" autoFlush="true" %>
<%
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "Thu, 29 Oct 1970 17:04:19 GMT");

String done_url = null;
int i = 0;
try
{
   done_url =  request.getParameterValues("p_done_url")[0];

   out.println("<center><h1>Single Sign-Off</h1><p>");
   out.println("<table border=0>");
   out.println("<tr>");
   out.println("<th>Appliction Name</th>");
   out.println("<th>Logout Status</th>");
   out.println("</tr>");

   for(;;)
   {
      i++;

      String app_name = request.getParameterValues("p_app_name"+i)[0];
      String url_name = request.getParameterValues("p_app_logout_url"+i)[0];
      out.println("<tr>");
      out.println("<td>"+app_name+"</td>");
      out.println("<td><img src='" +url_name +"'></td>");
      out.println("</tr>");
   }
}
catch(Exception e)
{
    if(i>1)
    {
      out.println("</table>");
      out.println("<br>");
      out.println("<form><INPUT TYPE='button' "
          +" NAME='p_request' VALUE='Return' ");
      out.println(" onClick='javascript:document.location.href = '"
            + done_url +"';'><form></center>");
    }
    else
    {
       out.println("<h2><center><font color='red'>ERROR:</font>");
       out.println("This page can not be accessed directly!</center></h2>");
    }
}

%>
</body>
</html>


Go to previous page Go to next page
Oracle
Copyright © 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index