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

5
Third-Party Single Sign-On

This chapter explains how to integrate Oracle Single Sign-on with third-party single sign-on products. It describes how third-party integration works; then it presents the application programming interfaces (APIs) for integration. Finally, it presents sample code that integrates Oracle9iAS Single Sign-On with SiteMinder®, a single sign-on product from Netegrity, Inc.

An enterprise that has a third-party system in place can gain access to the Oracle 9iAS suite by using APIs that enable the Oracle Single Sign-On server to act as an authentication gateway between the third-party system and Oracle applications.

The chapter covers the following topics:

How Third-Party Single Sign-On Works

In third-party single sign-on, the Oracle Single Sign-On server, the third-party single sign-on server, and the partner application form a chain of trust. The Oracle Single Sign-On server delegates authentication to the third-party single sign-on server, becoming essentially a partner application to it. Oracle applications continue to work only with the Oracle Single Sign-On server and are unaware of the third-party single sign-on server. Implicitly, however, they trust the third-party server.

For Oracle Single Sign-On to issue users an authentication token under this arrangement, the third party single sign-on server must pass the former the user's identity by setting HTTP headers. Once it obtains the user's identity, the Oracle Single Sign-On server functions as before, managing user accounts, checking account policies, auditing, generating tokens, and redirecting users to its partner applications. Figure 5-1 illustrates the process.

Figure 5-1 Authentication Flow in Third-Party Single Sign-On

Text description of ssoag008.gif follows
Text description of the illustration ssoag008.gif

  1. The user logs in to the third-party single sign-on server.

  2. If login is successful, the third-party server sets a token in the user's browser.

  3. The user attempts to access an Oracle partner application.

  4. The partner application, ignorant of the third-party server, redirects the user to the Oracle Single Sign-On server. At the same time, the user passes the third-party single sign-on token to the Oracle Single Sign-On server.

  5. The Single Sign-On server looks for its own cookie.

  6. Failing to find its cookie, the Oracle Single Sign-On server looks for a token from the third-party single sign-on server.

  7. Finding the token, the Oracle Single Sign-On server retrieves user attributes from Oracle Internet Directory.

  8. The Oracle Single Sign-On server sets its own cookie and redirects the user back to the Oracle partner application, passing a URL token that contains the user's attributes.

    Notes:

    • In the case of users who try to access a partner application before logging in to the third-party single sign-on server, the Oracle Single Sign-On server can be configured to redirect users to the third-party login page. For more information, see "Installing Customized Login, Change Password, and Single Sign-Off Pages", in Chapter 8, "Customizing the Single Sign-On Interface.

    • If the single sign-on systems are to be accessible to all authorized users, the user repository must be centralized in one place. This means that, before deployment, users may have to be migrated from the third-party single sign-on repository to the Oracle Single Sign-On repository or the reverse.

Synchronizing the Third-Party Repository with Oracle Internet Directory

The authentication scenario presented in the preceding steps assumes either that the user repository is Oracle Internet Directory or that the repository is a third-party directory or database. If the repository is the latter, the user name must be synchronized with the user entry in Oracle Internet Directory. This synchronization enables the Single Sign-On server to fetch the user attributes required by Single Sign-On-enabled applications.

Note:

Third-party single sign-on cannot proceed if the synchronization mechanism is not in place.

To synchronize the third-party repository with Oracle Internet Directory, use either Oracle Directory Integration Platform (DIP) or bulk load tools.

See Also:

Third-Party Integration Modules

To achieve third-party integration, the developer must implement the package body of wwsso_auth_external. The package specification is located in the file ssoauthx.pks. The required interfaces perform the following functions:

Authentication Using a Token

This function is called before a login screen is displayed to the user. If authentication using a token is to be supported, the implementer of this function must return the user name to the Oracle Single Sign-On server by retrieving the user identity in a secure fashion--by looking at a securely set HTTP header, for instance, or at a secure cookie. 

FUNCTION authenticate_user
(
 p_user OUT VARCHAR2
)
RETURN PLS_INTEGER;

/*The function throws the following exceptions:
EXT_AUTH_FAILURE_EXCEPTION,EXT_AUTH_UNKNOWN_EXCEPTION
EXT_AUTH_SETUP_EXCEPTION
*/

Set External Cookies

If authentication is successful, the Oracle Single Sign-On server sets all the cookies provided in the p_cookie_list parameter on behalf of the external authentication server. 

PROCEDURE set_external_cookies
(
  p_username IN VARCHAR2
 ,p_password IN VARCHAR2
 ,p_cookie_list OUT wwsso_ls_private.cookie_list
);

Integration Case Study: Netegrity SiteMinder

SiteMinder by Netegrity, Inc., is a product, which, like Oracle9iAS Single Sign-On, offers single sign-on authentication to protected resources. SiteMinder consists of two components: the SiteMinder policy server and the SiteMinder agent. The first provides users with a variety of services including user and session management, authentication, and authorization. The second is located on Web servers and Web application servers. It screens requests for resources and determines whether a resource is protected by SiteMinder.

Customers who have SiteMinder already installed may want to use it to gain access to Oracle9iAS applications. They can achieve this access by using APIs that enable SiteMinder to talk to Oracle applications by way of Oracle9iAS Single Sign-On.

This section covers the following topics:

Authentication Flow for the SiteMinder Solution

Figure 5-2 depicts the authentication flow for an integrated Single Sign-On/SiteMinder system. It shows what happens when the user tries to access a partner application--in this case, Oracle9iAS Portal--without logging in to SiteMinder first.

Figure 5-2 Authentication Flow for the SiteMinder Solution

Text description of ssoag001.gif follows
Text description of the illustration ssoag001.gif

  1. The user tries to access a protected resource within Oracle Portal.

  2. Oracle Portal redirects the user to the Oracle Single Sign-On server.

  3. The SiteMinder agent prompts the user for credentials.

  4. The user presents his or her credentials to the SiteMinder agent.

  5. The SiteMinder agent checks the user's credentials in the SiteMinder policy server. The SiteMinder policy server in turn tries to authenticate the user. If configured to do so, the policy server checks the credentials against Oracle Internet Directory.

  6. If authentication is successful, the SiteMinder agent passes the user's identity to the Oracle Single Sign-On server in the form of HTTP headers.

  7. The Oracle Single Sign-On server generates a URLC token and uses it to transfer the user's identity to Oracle Portal.

  8. If the user in this scenario is already logged in to SiteMinder, steps 3, 4, and 5 are skipped, and the SiteMinder agent sends the user's identity in the form of HTTP headers.

    Note:

    In Oracle9iAS v1.0.2.2, the Oracle Single Sign-On user repository need not be Oracle Internet Directory. In Oracle9iAS, Release 2, integration with this directory is required.

Logging Out of the Integrated System

The integrated Oracle Single Sign-On/SiteMinder system requires that, when a user logs out of the Oracle Single Sign-On server, he or she is also logged out of SiteMinder. For concurrent logout to occur, the Single Sign-On logout procedure must be registered as a URI with the SiteMinder agent. See Installing and Deploying the SiteMinder Solution for details.

When the Oracle Single Sign-On logout procedure is invoked from Oracle Portal, the SiteMinder agent intercepts the request and ends the SiteMinder session. It then transfers control to the Oracle Single Sign-On logout procedure, which ends the Oracle Single Sign-On session.

Selecting Logout in Oracle Portal initiates the following sequence:

  1. Oracle Portal ends the Portal session and redirects the user to the Single Sign-On server with the done_URL for the application home page.

  2. The SiteMinder agent intercepts the logout request, contacts the SiteMinder policy server, and ends the SiteMinder session.

  3. The SiteMinder agent transfers control to the Single Sign-On logout procedure.

  4. The Single Sign-On server ends the Single Sign-On session and redirects the user to the application home URL sent in Step 1.

Before concurrent logout can begin, customer applications must redirect users to the Portal logout link at 

http://host:port/pls/Portal_DAD/Portal_schema.wwsec_app_priv.logout?p_done_
url=url_encoded_apps_URL

The done_url of the application might be the following: 

http%3A%2F%2Fmysite.com/home

In this example, users are redirected back to the home page of mysite.com.

Sample Integration Package

The package ssoxnete.pkb, presented here, can be used to integrate an existing SiteMinder implementation with Oracle9iAS Single Sign-On. 

Rem ssoxnete.pkb
Rem
Rem  Copyright (c) Oracle Corporation 2001. All Rights Reserved.
Rem
Rem    NAME
Rem      ssoxnete.pkb - Single Sign-On Netegriry SiteMinder Integration
Rem
Rem    DESCRIPTION
Rem      This package body is used to achieve integration with Netegrity
Rem      SiteMinder. It may be customized as required. This is just a default
Rem      implementation and changes might be required based on customer's
Rem      specific deployment scenario.


CREATE OR replace PACKAGE BODY wwsso_auth_external AS

    GLOBAL_SEPARATOR CONSTANT varchar2(1)    := '~';

/* This function needs to be implemented to provide a DN
 * to UID mapping. One way to do this mapping is to lookup
 *  the UID for a given DN in the directory
 */

FUNCTION map_dn_to_uid(p_user_dn IN VARCHAR2)
  return VARCHAR2
IS
BEGIN

  -- NULL implementation by default

  raise EXT_AUTH_FAILURE_EXCEPTION;

  return p_user_dn;

END map_dn_to_uid;
FUNCTION authenticate_user
  (
   p_user OUT VARCHAR2
  )
  return PLS_INTEGER
IS
 l_http_header varchar(1000);
 l_ssouser wwsec_person.user_name%type := NULL;
BEGIN

   l_http_header := owa_util.get_cgi_env('HTTP_SM_USER');
   debug_print('SiteMinder ID : ' || l_http_header);

  /*
   if l_http_header IS NULL then user may be authenticated by PKI
   in SiteMinder so check the DN header
   */

   IF (l_http_header is NULL) THEN
   BEGIN
       debug_print('check if user authenticated using PKI');
       l_http_header := owa_util.get_cgi_env('HTTP_SM_USERDN');
       l_ssouser := map_dn_to_uid(l_http_header);
   END;
   ELSE
       l_ssouser := l_http_header;
   END IF;

   IF ( (l_ssouser IS NULL) or
       ( INSTR(l_ssouser, GLOBAL_SEPARATOR) != 0) ) THEN
       debug_print('malformed user id: '
               || l_ssouser
               || ' returned by wwsso_auth_external.authenticate_user');
       RAISE EXT_AUTH_FAILURE_EXCEPTION;
   ELSE
     p_user := NLS_UPPER(l_ssouser);
     return 0;
   END IF;


EXCEPTION
   WHEN OTHERS THEN
     debug_print('unknown exception in authenticate_user(p_user)'
                 || sqlerrm);
     RAISE EXT_AUTH_FAILURE_EXCEPTION;

END authenticate_user;


FUNCTION get_authentication_name
 RETURN VARCHAR2
AS
BEGIN
    RETURN 'Netegrity SiteMinder';
END get_authentication_name;



PROCEDURE set_external_cookies
  (
    p_username IN VARCHAR2
  , p_password IN VARCHAR2
  , p_cookie_list OUT wwsso_ls_private.cookie_list
  )
AS
BEGIN
    null;

END set_external_cookies;



END;
/
show errors;

Installing and Deploying the SiteMinder Solution

Perform the following steps to install and configure the Oracle Single Sign-On server with SiteMinder:

  1. Install the Oracle Single Sign-On server.

  2. Run ssonete.sql. This script configures the Oracle Single Sign-On server to operate in external mode and loads the default implementation found in ssoxnete.pkb.

  3. Install the SiteMinder agent in front of the Oracle Single Sign-On server. This task involves installing mod_sm, a SiteMinder module, on the same instance as the Oracle Single Sign-On server. For more details, see SiteMinder Agent Operations Guide.

  4. Configure the SiteMinder policy server to protect access to the Oracle Single Sign-On server URLs and to associate a user population with the Oracle Single Sign-On server. To accomplish this task, create policy domains and realms for the Oracle Single Sign-On server on the SiteMinder policy server. The Oracle Single Sign-On server is accessed at URLs of the form: 

    http://hostname:port/pls/Single_Sign-On_server_DAD
  5. If you are using PKI authentication, customize the function map_dn_to_uid(p_user_dn IN VARCHAR2). Currently, this function has a default implementation of NULL, as indicated in ssoxnete.pkb.

  6. Edit your modplsql DAD file, typically named wbdbsvr.app, to include the following SiteMinder headers: 

    [DAD_Single_Sign-On_server_schema]
connect_string = Single_Sign-On_server_schema_DB_connect_string


..
cgi_env_list = HTTP_SM_USER,HTTP_SM_USERDN

Register the Single Sign-Out logout procedure as a URI with the SiteMinder agent. To do this, add the following line to the WebAgent.conf file: 

logoffuri="/pls/Single_Sign-On_DAD/Single_Sign-On_schema.wwsso_app_admin.ls_
logout"

After these steps have been completed, the user can log in to a partner application. Because credentials are stored in a repository managed by SiteMinder, the Change Password page in the Oracle Single Sign-On server can be customized to point to the SiteMinder Change Password screen.

See Also:

"Installing Customized Login, Change Password, and Single Sign-Off Pages" in Chapter 8, "Customizing the Single Sign-On Interface

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