B
Using the PL/SQL and Java APIs

This appendix provides sample programs that illustrate how to enable partner applications for single sign-on.

The appendix contains the following topics:

• Before Using the APIs

• Writing Partner Applications Using PL/SQL APIs

• Writing Partner Applications Using Java APIs

Before Using the APIs

Before you begin writing partner applications with the single sign-on SDK, make sure that you have correctly installed and configured it. Follow the instructions included with it. The SDK is available at $ORACLE_HOME/sso/lib/ssosdk902.zip.

Writing Partner Applications Using PL/SQL APIs

The example that follows shows how to develop a partner application using PL/SQL APIs. If you need help creating a database access descriptor, see Oracle Application Server 10G mod_plsql User's Guide. If you need help writing PL/SQL applications, see Oracle Application Server 10G PL/SQL Web Toolkit Reference. The example incorporates three procedures: SAMPLE_SSO_PAPP.SSOAPP, SAMPLE_SSO_PAPP.SIGN_ON, and SAMPLE_SSO_PAPP.LOGOUT.

SAMPLE_SSO_PAPP.SSOAPP

This procedure constructs the application URL. The procedure checks to see if the application cookie exists and user information can be retrieved; otherwise it redirects the user to the single sign-on server by generating a redirect URL.

SAMPLE_SSO_PAPP.SIGN_ON

This procedure gets the URLC token from the single sign-on server, decrypts it, and retrieves user information and the requested URL. The procedure sets the application cookie and redirects the browser to the partner application URL.

SAMPLE_SSO_PAPP.LOGOUT

This procedure implements the logout URL for the application.

The sample code for the package papp.pks and papp.pkb is in the file ssosdk902.zip, which is located in demo/plsql.

Note: The request URL and the cancel URL must be URL encoded if these URLs contain a URL parameter. For example: http://host:port/dad/schema.procedure?itemid=1234&type=purchase In PL/SQL, the wwutl_htf.encode procedure can be used to encode the URL.

Writing Partner Applications Using Java APIs

Initially, the partner application redirects you to the single sign-on server for authentication and, after successful authentication, sets its own application session cookie. Any subsequent request first attempts to validate the application session cookie. If the application session cookie is not found, the partner application redirects the user to the single sign-on server. To spare the server from having to verify every user request, all partner applications should maintain their own application session.

This section shows how to implement a generic bean that can be used in servlets and JavaServer pages (JSPs). The section contains the following topics

• Servlet Partner Application

• JSP Partner Application

  Note: The request URL and the cancel URL must be URL encoded if these URLs contain a URL parameter. For example: http://host:port/jsp/order.jsp?itemid=1234&type=purchase In Java, the java.net.URLEncoder class can be used to encode the URL.

Servlet Partner Application

The example Java servlet provided consists of files that are located in ssosdk902.zip. These are the files:

• Bean classes

  The files SSOEnablerBean.java and SSOEnablerServletBean.java are located in demo/java/beans. Edit these files to suit your deployment.

• Servlet classes

  The files SSOPartnerServlet.java, SSOSignOnServlet.java and SSOPartnerLogoutServlet.java are in demo/java/servlet.

You must compile the bean and servlet files and deploy them in OC4J before you can access your application.

The authentication flow for this application is as follows:

1. The user goes to the SSOPartnerServlet application URL. This servlet retrieves user information with the help of SSOEnablerServletBean. If the user information is found, it is used inside the application; otherwise, the browser redirects the user to the single sign-on server.

2. After authentication, the single sign-on server does the following:
   • Redirects the user to the SSOSignOnServlet URL to set the application cookie

   • Redirects the user to the requested application URL using SSOEnablerServletBean. The servlet uses the application cookie to shows user information.

JSP Partner Application

The example JSP partner application also consists of files that are located in ssosdk902.zip. These are the files:

• Bean classes

  The files SSOEnablerJspBean.java and SSOEnablerServletBean.java are located in demo/java/beans. Edit these files to suit your deployment.

• JSP files

  The files ssoinclude.jsp, ssosignon.jsp, papp.jsp, and papplogoff.jsp are located in demo/java/jsp.

You must compile bean java files and then deploy them with JSP files in OC4J before you can access your application. For detailed information about compilation, see ssosdk902.zip.

The authentication flow for this application is as follows:

1. The user goes to the papp.jsp page.

2. papp.jsp retrieves user information with the help of the ssoinclude.jsp page. If the user information can be found, then it is used by the application; otherwise, the browser redirects the user to the single sign-on server using SSOEnablerJspBean.

3. After authentication, the single sign-on server redirects the user to the ssosignon.jsp page. This page sets the application cookie and redirects the user to the requested application URL using SSOEnablerJspBean.