|Oracle9iAS Single Sign-On Administrator's Guide
Release 2 (9.0.2)
Part Number A96115-01
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:
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.
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.
To synchronize the third-party repository with Oracle Internet Directory, use either Oracle Directory Integration Platform (DIP) or bulk load tools.
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:
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 */
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 );
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:
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.
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:
Before concurrent logout can begin, customer applications must redirect users to the Portal logout link at
The done_url of the application might be the following:
In this example, users are redirected back to the home page of mysite.com.
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;
Perform the following steps to install and configure the Oracle Single Sign-On server with SiteMinder:
ssonete.sql. This script configures the Oracle Single Sign-On server to operate in external mode and loads the default implementation found in
map_dn_to_uid(p_user_dn IN VARCHAR2). Currently, this function has a default implementation of NULL, as indicated in
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:
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.
"Installing Customized Login, Change Password, and Single Sign-Off Pages" in Chapter 8, "Customizing the Single Sign-On Interface