5
Customizing Single Sign-On

This section explains how to customize the Login and Change Password pages to match the look and feel of your portal or product. It also describes how to configure the Login Server for LDAP authentication.

This section contains the following topics:

Customizing the Login and Change Password Pages

The Single Sign-On login page and Change Password page can be customized to match the look and feel of your portal or product.

Any type of Web page can be customized: PL/SQL stored procedures, CGI scripts, or Java Server Pages. Although there is no restriction on the type of page, customized pages must support certain parameters and error codes in order to function properly.

This section contains the following topics:

Customizing the Single Sign-On Login Page

This section contains the following sections:

Changing the Login Page

The authentication model contains logic that calls a PL/SQL stored procedure to create the Single Sign-On login page. The Login Server recognizes the user's request to bring up the login screen and makes a PL/SQL call to create the screen. The screen submits a form to the appropriate Login Server routine, which is the same as the original calling routine, and the user's credentials are processed.

The process is as follows:

The application calls WWSSO_APP_ADMIN.LS_LOGIN to authenticate the user.
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.
DRAW_LOGIN_PAGE submits a form to WWSSO_APP_ADMIN.LS_LOGIN to process the credentials.
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 submit the login form to, such as WWSSO_APP_ADMIN.LS_LOGIN, and submit the form appropriately.

The flow of logic is as follows:

The Oracle9iAS Portal calls WWSSO_APP_ADMIN.LS_LOGIN to authenticate the user.
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.
The login page submits a form to WWSSO_APP_ADMIN.LS_LOGIN to process the credentials.
If the user is authenticated, LS_LOGIN redirects to the requested application page. The Login Server uses the LOGIN_URL column of the WWSSO_LS_CONFIGURATION_INFO$ table to store the URL for the customized login page.

Login Page Parameters

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

Table 5-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 clicks 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 5-2 to the p_submit_url routine:

Table 5-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 clicks 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 Login Server.

Login Page Error Codes

The customized login page must process the error codes listed in Table 5-3.

Table 5-3 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 login 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.

Customizing the Change Password Page

This section contains the following sections:

Changing the 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:

Oracle9iAS Portal calls the WWSSO_APP_USER_MGR.CHANGE_PASSWORD routine.
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.
CHANGE_PASSWORD processes the new password.
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:

Oracle9iAS Portal calls WWSSO_APP_USER_MGR.CHANGE_PASSWORD to display the Change Password page.
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.
The Change Password page submits a form to WWSSO_APP_USER_MGR.SAVE_NEW_PASSWORD to process and save the new password.
If there are no errors, SAVE_NEW_PASSWORD saves the new password and redirects to the appropriate Oracle9iAS Portal 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:

WWSSO_APP_ADMIN.LS_LOGIN calls WWSSO_APP_USER_MGR.CHANGE_PASSWORD to display the Change Password page.
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.
The Change Password page submits a form to WWSSO_APP_USER_MGR.SAVE_NEW_PASSWORD to process and save the new password.
If there are no errors and the user clicks OK, SAVE_NEW_PASSWORD saves the new password and returns control to WWSSO_APP_ADMIN.LS_LOGIN to perform the necessary login steps.

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

Note:

Clicking 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 clicks 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:

WWSSO_APP_ADMIN.LS_LOGIN calls WWSSO_APP_USER_MGR.CHANGE_PASSWORD to display the Change Password page.
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.
The Change Password page submits a form to WWSSO_APP_USER_MGR.SAVE_NEW_PASSWORD to process and save the new password.
If there are no errors and the user clicks OK, SAVE_NEW_PASSWORD saves the new password and returns control to WWSSO_APP_ADMIN.LS_LOGIN to perform the necessary login steps.
If there are errors, SAVE_NEW_PASSWORD calls CHANGE_PASSWORD and redisplays the Change Password page.
If the user clicks 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.

Change Password Page Parameters

The URL for the Change Password page must accept the parameters listed in Table 5-4.

Table 5-4 Change Password Page Parameters

Parameter	Description
`p_username`	Contains the username to be displayed somewhere on the page.
`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 5-5 to the p_submit_url routine.

Table 5-5 Customized Change Password Page Parameters

Parameter	Description
`p_password`	Contains the user's original password (if a password has or is about to expire).
`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.

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

p_old_password
p_new_password
p_new_password_confirm.

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.

It must also submit the following parameters, as hidden parameters, to the standard HTML login form presented to the external application from the Login Server

p_pwd_is_exp
site2pstoretoken
p_password

Change Password Page Error Codes

The customized Change Password page must process the error codes listed in Table 5-6.

Table 5-6 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 login server's password requirements.
`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.

The reset password page can encounter errors, which generates one of the following error codes, which is passed to the p_error_url page in the
p_error_code argument.

Table 5-7 Reset Password Page Error Codes

Value of p_error_code	Corresponding Error
`pwd_reset_err`	The reset password failed in local authentication mode.
`notification_failure_err`	The reset password notification failed. If using external authentication, the password is reset at this point. In local mode, the password reset is rolled back.
`ext_auth_not_supported_err`	The Login Server is configured for external authentication, and it does not support the reset password.
`ext_auth_reset_password_err`	The Login Server is configured for external authentication, and the reset password failed.
`ext_auth_setup_err`	The Login Server is configured for external authentication, but it is not set up correctly.

Installing Customized Login and Change Password Pages

The WWSSO_LS_CONFIGURATION_INFO$ table in the Login Server schema contains the LOGIN_URL column, which is used to enable customized Login and Change Password pages.

The LOGIN_URL column contains two values separated by a space. The first value specifies the URL for the Login page, and the second value specifies the URL for the Change Password page.

By default, the LOGIN_URL column contains the values UNUSED UNUSED, which specifies that the Login and Change Password pages use the standard Login Server pages.

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

On the database where the Login Server is installed, log in to the Single Sign-On schema using SQL*Plus, as in the following example:
```
sqlplus portal30_sso/portal30_sso
```
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 both pages, update both 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';
```
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';
```

Configuring the Login Server for LDAP Authentication

If the users for whom you are granting access to Oracle9iAS Portal and other Oracle9iAS Single Sign-On applications are already listed in an LDAP directory, you can use the LDAP directory to authenticate users, instead of creating each user again in the Login Server.

The Login Server provides the ssoldap.sql, ssooid.sql, and ssoldif.sql scripts to configure the Login Server for LDAP user authentication.

If you use LDAP for user authentication, you cannot create new Oracle9iAS Single Sign-On users through the Login Server. Instead, you create new users with the LDAP directory using tools such as Oracle Directory Manager.

You must be the administrator of the LDAP directory to configure the Login Server for LDAP user authentication.

To create an LDIF file using the ssoldif.sql script, the initialization parameter file must be set up to allow you to write files to a directory.

This section contains the following topics:

Configuring the Login Server for LDAP User Authentication

You can configure the Login Server for LDAP user authentication using either the DBMS_LDAP package implemented in ssoxoid.pkb, or by using the external procedure listener, implemented in ssoxldap.pkb. Oracle Corporation recommends that you use the ssoxoid.pkb package if you are using Oracle 8i Release 3 (8.1.7) or later.

Note:

In order to configure an LDAP directory for authentication, it must have a UserPassword attribute populated for each user.

To complete the configuration, you run the ssoldap.sql or ssooid.sql scripts and the ssoldif script and copy the information in the generated LDIF file to the LDAP server.

This section contains these topics:

Configuring the Login Server for LDAP Using ssoxoid.pkb

Perform the following steps to configure the Login Server for LDAP user authentication using the DBMS_LDAP package ssoxoid.pkb.

Note:

If you are using Oracle 8i Release 3 (8.1.7), the database should be in dedicated mode.

Navigate to the Oracle home of the database where the Login Server is installed.
Navigate to the rdbms/admin directory.
Log on to SQL*Plus as SYS:
```
sqlplus sys/change_on_install
```
Enter the following:
```
@catldap.sql 
```
The catldap.sql script installs the required LDAP packages.
Exit SQL*Plus.
Navigate to the Oracle9iAS Portal src/sso directory to exit.
On the database where the Login Server is installed, log on to SQL*Plus as the Login Server schema, as in the following example:
```
sqlplus portal30_sso/portal30_sso
```
Enter the following command to install ssoxoid.pkb:
```
@ssooid
```
Provide the LDAP configuration parameters as described in "Entering the LDAP Configuration Parameters".

Configuring the Login Server for LDAP Using ssoxldap.pkb

Perform the following steps to configure the Login Server for LDAP user authentication using the external listener procedure ssoxldap.pkb:

Copy the appropriate library file from the Oracle9iAS Portal src/sso directory to the appropriate directory on the Login Server:
- If the Login Server is installed on a Windows NT machine, copy the ssoxldap.dll library file from the Oracle9iAS Portal src\sso directory to the %ORACLE_HOME%\bin directory on the Login Server machine.
- If the Login Server is installed on a UNIX machine, copy the ssoxldap.so library file from the Oracle9iAS Portal src/sso to the $ORACLE_HOME/lib directory on the Login Server machine.
On the database where the Login Server is installed, log in to SQL*Plus as the Login Server schema, as in the following example:
```
sqlplus portal30_sso/portal30_sso
```
Enter the following:
```
create or replace library auth_ext as 'library_file_name'; /
commit;
```
where library_file_name is the full path and file name of the library file in Step 1.

If the Login Server is installed on a Windows NT machine, enter the following:
```
create or replace library auth_ext as
'c:\oracle\ora81\bin\ssoxldap.dll';
/
commit;
```
where oracle\ora81\bin is the path to the %oracle_home%\bin.

If the Login Server is installed on a UNIX machine, enter the following:
```
create or replace library auth_ext as
'/u01/app/oracle/product/816prod/lib/ssoxldap.so';
/
commit;
```
where u01/app/oracle/product/816prod/lib is the path to the $oracle_home/bin.
Enter the following command to install ssoxldap.pkb:
```
@ssoldap
```
Provide the LDAP configuration parameters as described in "Entering the LDAP Configuration Parameters".

Entering the LDAP Configuration Parameters

The ssooid or ssoldap script prompts you to enter configuration information. The prompts are described in Table 5-8.

Note:

If you are using a multithreaded database, you must specify TCP instead of IPC in the tnsnames.ora and listener.ora files.

Table 5-8 Required Values to Configure the Login Server for LDAP User Authentication

Prompt	Description
Enter value for Host	Enter the name of the server on which the LDAP directory is installed, as in the following example: `ldap_server.mycompany.com`
Enter value for Port	Enter the port number used to access the server on which the LDAP directory is installed, as in the following example: `389`
Enter value for Search_Base	Enter the node in the LDAP Directory Information Tree (DIT) under which all your user entries are located, as in the following example: `cn=Login Server (portal30_sso)`
Enter value for Unique_Attribute	Enter the name of the attribute that contains Single Sign-On usernames. This attribute should be able to uniquely identify user entries in the LDAP directory, as in the following example: `cn`
Enter value for Bind_DN	Enter the username of an account that has privileges to search the part of the LDAP DIT that contains your user entries, as in the following example: `cn=ldapadmin`
Enter value for Bind_Password	Enter the password for the above account, as in the following example: `welcome`

Generating and Loading the User List

To enable users to log in to Oracle9iAS Portal with default user accounts using LDAP authentication, you must migrate the Oracle9iAS Single Sign-On accounts created during Oracle9iAS Portal installation to the LDAP directory.

You should still be logged on to SQL*Plus as the Login Server schema.

Enter the following:
```
@ssoldif
```
This creates an LDIF file, users.ldif, which contains the Oracle9iAS Single Sign-On user accounts created during the installation of Oracle9iAS Portal. For an example of what the LDIF file might look like, see "LDIF File Example".
Quit SQL*Plus.

Add the information in the generated LDIF file to the LDAP directory.

For example, to add the LDIF file to the Oracle Internet Directory LDAP server, you can use the following ldapadd command provided with the Oracle database:

ldapadd -h <Host> -p <Port> -D <Bind_DN> -w <Bind_Password> -f users.ldif

Note:

Descriptions of parameters are included in the list of prompts and responses in Table 5-8.
The username you enter for the bind distinguished name should have sufficient privileges to be able to add entries to the directory.

See Also:

Oracle9iAS Internet Directory Administrator's Guide

The Login Server is now fully configured to authenticate users with the LDAP directory.

Note:

The Login Server is certified against Oracle Internet Directory and conforms to the LDAP specification. Other LDAP directories can be synchronized with Oracle Internet Directory.

When a user is added to the LDAP directory, Oracle9iAS Portal automatically creates a profile for the user when first logging in.

To delete a user, remove both the user's Oracle9iAS Portal profile and the user's LDAP entry. If the LDAP entry alone is removed, the user will not be able to login to the Oracle9iAS Portal, but the profile information will remain.

To remove LDAP integration with the Login Server, use SQL*Plus to run the ORACLE_HOME/portal30/admin/plsql/sso/ssolocal.sql script when you are logged in as the Login Server schema owner.

Note:

For more information about configuring the Login Server and Oracle9iAS Portal with LDAP, see the following on Oracle Technology Network: http://technet.oracle.com/products/iportal/pdf/conf_ldap.pdf

LDIF File Example

The following is an example of the LDIF file created by the ssoldif.sql script when configuring the Login Server for LDAP user authentication.

The example shows the LDIF file that would be created if Oracle9iAS Portal was installed in a schema named portal30.

dn: cn=Login Server (portal30_sso)
cn: Login Server (portal30_sso)
description: Central Authentication Authority
objectClass: top
objectClass: applicationProcess

dn: cn=PORTAL30_SSO, cn=Login Server (portal30_sso)
sn: PORTAL30_SSO
cn: PORTAL30_SSO
userPassword: portal30_sso
objectClass: top
objectClass: person

dn: cn=PORTAL30_SSO_ADMIN, cn=Login Server (portal30_sso)
sn: PORTAL30_SSO_ADMIN
cn: PORTAL30_SSO_ADMIN
userPassword: portal30_sso_admin
objectClass: top
objectClass: person

dn: cn=PORTAL30, cn=Login Server (portal30_sso)
sn: PORTAL30
cn: PORTAL30
userPassword: portal30
objectClass: top
objectClass: person

dn: cn=PORTAL30_ADMIN, cn=Login Server (portal30_sso)
sn: PORTAL30_ADMIN
cn: PORTAL30_ADMIN
userPassword: portal30_admin
objectClass: top
objectClass: person

dn: cn=PUBLIC, cn=Login Server (portal30_sso)
sn: PUBLIC
cn: PUBLIC
userPassword: public
objectClass: top
objectClass: person

The ssoldif.sql script produces the above code example by default. If you already have a set of user entries and a Directory Information Tree (DIT) organization defined in the LDAP directory, you can modify the script to produce the necessary format. You can also manually create entries in the LDAP directory of the appropriate object class so that users portal_schema and portal_schema_ADMIN can log in.

5 Customizing Single Sign-On

Customizing the Login and Change Password Pages

Customizing the Single Sign-On Login Page

Changing the Login Page

Login Page Parameters

Table 5-1 Login Page Parameters

Table 5-2 Customized Login Page Parameters

Login Page Error Codes

Table 5-3 Customized Login Page Error Codes

Customizing the Change Password Page

Changing the Change Password Page

Change Password Page Parameters

Table 5-4 Change Password Page Parameters

Table 5-5 Customized Change Password Page Parameters

Change Password Page Error Codes

Table 5-6 Change Password Page Error Codes

Table 5-7 Reset Password Page Error Codes

Installing Customized Login and Change Password Pages

Configuring the Login Server for LDAP Authentication

Configuring the Login Server for LDAP User Authentication

Configuring the Login Server for LDAP Using ssoxoid.pkb

Configuring the Login Server for LDAP Using ssoxldap.pkb

Entering the LDAP Configuration Parameters

Table 5-8 Required Values to Configure the Login Server for LDAP User Authentication

Generating and Loading the User List

LDIF File Example

5
Customizing Single Sign-On