Skip Headers
Oracle® Application Server Single Sign-On Administrator's Guide
10g Release 2 (10.1.2)
B14078-02
  Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

13 Integrating with Third-Party Access Management Systems

This chapter explains how to integrate OracleAS Single Sign-On with third-party access management products. It describes how third-party integration works; then it presents the integration APIs. Finally, it provides an example of how to integrate OracleAS Single Sign-On with a third-party access management system.

An enterprise that has a third-party system in place can gain access to the OracleAS suite by building an authentication adapter that enables the OracleAS Single Sign-On server to act as an authentication gateway between the third-party system and Oracle applications.

The chapter contains the following topics:

13.1 How Third-Party Access Management Works

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

For OracleAS Single Sign-On to issue users an authentication token under this arrangement, the third-party access management server must pass the OracleAS single sign-on server the user's identity by setting HTTP headers or by using some other mechanism. Once it obtains the user's identity, the OracleAS Single Sign-On server functions as before, authenticating and redirecting users to its partner applications. Figure 13-1 illustrates the process.

Figure 13-1 Accessing Oracle Partner Applications Using a Third-Party Server

Description of Figure 13-1  follows
Description of "Figure 13-1 Accessing Oracle Partner Applications Using a Third-Party Server"

The illustration captures two possible scenarios:

13.1.1 Scenario 1: The user has not yet authenticated to the third-party server

  1. The unauthenticated user attempts to access an application protected by OracleAS Single Sign-On.

  2. The application redirects the user to the OracleAS Single Sign-On server for authentication. As part of this redirection, the following occurs:

    1. The OracleAS Single Sign-On server has the third-party agent, typically a module on the Oracle HTTP Server, authenticate the user. You install this module when you install the third-party adapter. Note that this module resides only on the single sign-on server. It does not reside on the application server.


      Note:

      See "Integration Case Study: SSOAcme" for more about the third-party agent.

    2. The third-party server sets a token in the user's browser.

    3. The OracleAS Single Sign-On server retrieves the token from the browser.

    4. The OracleAS Single Sign-On server verifies the token with the third-party server.

    After token verification, the OracleAS Single Sign-On server returns the user—and the authenticated user information—to the requested application.

  3. The application provides content to the user.

13.1.2 Scenario 2: The user has already authenticated to the third-party server

  1. The authenticated user attempts to access an application protected by OracleAS Single Sign-On.

  2. The application redirects the user to the OracleAS Single Sign-On server for authentication. As part of this redirection, the following occurs:

    1. The OracleAS Single Sign-On server retrieves the token from the browser (step 2c in scenario 1).

    2. The OracleAS Single Sign-On server verifies the token with the third-party server (step 2d in scenario 1).

    After token verification, the OracleAS Single Sign-On server returns the user to the requested application.

  3. The application provides content to the user.


    Note:

    If the single sign-on systems involved are to be accessible to all authorized users, the user repository must be centralized in one place. This means that, before deployment, users must be synchronized between Oracle Internet Directory and the external repository if this repository is not also Oracle Internet Directory.

13.2 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 information must be synchronized with the user entry in Oracle Internet Directory. This synchronization enables the single sign-on server to retrieve the user attributes required by applications enabled for single sign-on.


Note:

Third-party access management integration 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 and Provisioning or bulk load tools. For details, see the chapters about directory synchronization in Oracle Identity Management Integration Guide.

13.3 Third-Party Integration Modules

There are two ways to achieve third-party integration: you can use existing, vendor-supplied packages, or you can build your own third-party adapter, using interfaces provided by Oracle.

13.3.1 Using Vendor-Supplied Packages

Several third-party access management vendors provide authentication adapters for the OracleAS Single Sign-On server. These products enable you to integrate a third-party system with the Oracle system without having to write your own code. The link that follows provides information about these vendors' products. All of the vendors listed certify that their products work with OracleAS Single Sign-On. See the section Single Sign-On under the heading Documentation, which appears near the bottom of the page. Note that this material cannot be found under the Services menu.

http://www.oracle.com/technology/products/id_mgmt/partners/index.html

If you decide to use a third-party adapter, be aware that the instructions for implementing the adapter are contained not in this document, but in vendor documents. If you need help implementing the adapter, you must contact the vendor directly. The link provided includes contact information.

13.3.2 Building Your Own Package

You can use the Java toolkit oracle.security.sso.ias904.toolkit to build your own third-party integration adapter. The toolkit consists of two interfaces, one for performing authentication, the other for setting deployment-specific cookies. The OracleAS Single Sign-On server invokes the first interface during authentication. It invokes the second, the cookie adapter, after it has successfully determined the user's identity.

This section contains the following topics describing the interfaces and related classes in oracle.security.sso.ias904.toolkit:

13.3.2.1 Guidelines for Using the Interfaces

The authentication interface is required only if you are building your own third-party integration adapter. The OracleAS single sign-on server uses the interface implementation to determine the user's identity during authentication. The cookie interface is provided for your convenience. Use it to set additional cookies once the user is authenticated. You may, for example, want to use this feature to set user preferences. You do not need the cookie interface to achieve third-party integration. If you choose to use it, you can include it in your own adapter or in one provided by a vendor.

13.3.2.2 The Classes and Interfaces

The classes and interfaces in the kit perform the following functions:

13.3.2.2.1 Authentication Using a Token

The IPASAuthInterface.java package is invoked by the OracleAS Single Sign-On server during authentication. If authentication using a token is to be supported, the implementer of this interface must return the user name to the OracleAS Single Sign-On server by retrieving the user identity in a secure fashion—from a securely set HTTP header, for instance, or from a secure cookie. Here is the interface:

The IPASAuthInterface.java Interface

package oracle.security.sso.ias904.toolkit;
 
/**
 * Oracle Single Sign-On server authentication interface. This package can
 * be used to integrate with custom authentication mechanism or third-party
 * access management system.
 */
public interface IPASAuthInterface
{
  /**
   * This method returns IPASUserInfo object that contains either user name,
   * subscriber name, and requested URL, or full user and subscriber
   * attribute mappings, including DN, GUID, and requested URL.
   * @param  request - HTTP request object
   * @return IPASUserInfo object that contains 
   * @authenticated user information
   * @see oracle.security.sso.ias904.toolkit.IPASUserInfo
   */
   IPASUserInfo authenticate(HttpServletRequest request)
       throws IPASAuthException, IPASInsufficientCredException;
 
  /**
   * This method returns a page URL - user will be redirected to 
   * the page to enter login credentials
   * @param request - HTTP request object
   * @param message - Message to be displayed in the page
   * @return The page URL for collecting user login credential
   */
   java.net.URL getUserCredentialPage(HttpServletRequest request,
       String message);
}
 
13.3.2.2.2 User Information Constructors

The user information class IPASUserInfo.java provides constructors for user logins.

The IPASUserInfo.java Class

package oracle.security.sso.ias904.toolkit;
/**
 * User information class
 */
public class IPASUserInfo
{
  /**
   * Constructor with user login name that belongs to default subscriber
   * @param userNickName - User login name
   */
   IPASUserInfo(String userNickName);
 
 
  /**
   * Constructor with user login name that belongs to default subscriber
   * @param userNickName - User login name
   * @param subscriberName - The user's subscriber name 
   */
   IPASUserInfo(String userNickName, String subscriberName);
 
 
  /**
   * Constructor with user login name that belongs to default subscriber
   * @param userNickName - User login name
   * @param userDN - User directory distinguished name
   * @param userGUID - User directory GUID value
   * @param subscriberName - The subscriber name for this user
   * @param subscriberDN - The subscriber's directory distinguished name 
   * for this user
   * @param subscriberGUID - The subscriber's directory GUID value 
   * for this user
   */
   IPASUserInfo(String userNickName, String userDN, String userGUID,
       String subscriberName, String subscriberDN, String subscriberGUID);

  /**
   * This method returns subscriber distinguished name
   * @return subscriber distinguished name
   */
   String getSubscriberDN();
 
  /**
   * This method sets subscriber distinguished name
   * @param subDn - subscriber distinguished name
   */
   void setSubscriberDN(String subDn);
 
  /**
   * This method returns subscriber GUID value
   * @return subscriber GUID value
   */
   String getSubscriberGUID();
 
  /**
   * This method sets subscriber GUID value
   * @param subGuid - subscriber GUID value
   */
   void setSubscriberGUID(String subGuid);
 
  /**
   * This method returns subscriber name
   * @return subscriber name
   */
   String getSubscriberName();
 
  /**
   * This method sets subscriber name
   * @param subscriber name
   */
   void setSubscriberName(String subName);
 
  /**
   * This method returns user login name
   * @return user login name
   */
   String getUserName();
 
  /**
   * This method sets user login name
   * @param user login name
   */
   void setUserName(String userName);
 
  /**
   * This method returns user distinguished name
   * @return user distinguished name
   */
   String getUserDN();
 
  /**
   * This method sets user distinguished name
   * @param user distinguished name
   */
   void setUserDN(String userDN);
 
  /**
   * This method returns user GUID value
   * @return user GUID value
   */
   String getUserGUID();
 
  /**
   * This method sets user GUID value
   * @param user GUID value
   */
   void setUserGUID(String userGUID);
}
13.3.2.2.3 Setting External Cookies

The IPASCustomCookieInterface.java interface enables you to set optional, deployment-specific cookies. These cookies are set only if authentication is successful and the cookie adapter corresponds to the appropriate authentication level.

The IPASCustomCookieInterface.java Interface

package oracle.security.sso.ias904.toolkit;
 
/**
 * Oracle Single Sign-On server invokes this method to obtain 
 * user-defined custom cookies which will be sent to the user 
 * upon successful login.
 */
public interface IPASCustomCookieInterface
{
 /**
   * Oracle Single Sign-On server invokes this method to obtain 
   * user-defined custom cookies which will be sent
   * to the user upon successful login.
   * @param user - IPASUserInfo object that contains 
   * the authenticated user information
   * @param request -  HTTP request object
   * @return Array of javax.servlet.http.Cookie objects
   * @see javax.servlet.http.Cookie
   */
   public javax.servlet.http.Cookie[] getCustomCookie(IPASUserInfo user,
       HttpServletRequest request);
}

13.3.2.2.4 Exception Handling

This section lists the exception handling classes in oracle.security.sso.ias904.toolkit.

The IPASException.java Class

package oracle.security.sso.ias904.toolkit;
 
/**
 * Generic exception class
 */
public class IPASException
   extends Exception
{
  /**
   * Default constructor with no error message
   */
   public IPASException()
   {
       super();
   }
 
  /**
   * Constructor with an error message
   */
   public IPASException(String message)
   {
       super(message);
   }
}
 

The IPASAuthException.java Class

package oracle.security.sso.ias904.toolkit;
 
/**
 * Authentication failure exception class
 */
public class IPASAuthException
   extends IPASException
{
  /**
   * Default constructor with no error message
   */
   public IPASAuthException()
   {
       super();
   }
  /**
   * Constructor with an error message
   */
   public IPASAuthException(String message)
   {
       super(message);
   }
}
 

The IPASInsufficientCredException.java Class

package oracle.security.sso.ias904.toolkit;
 
/**
 * Authentication failure exception due to insufficient user credentials
 */
public class IPASInsufficientCredException
   extends IPASException
{
  /**
   * Constructor with an error message
   */
   public IPASInsufficientCredException (String message)
   {
       super(message);
   }
}

13.3.2.3 Configuration Steps

To create your own third-party integration adapter using the interfaces, follow these steps:

  1. In the third-party access management system, create rules that protect these URIs:

    /pls/orasso/orasso.wwsso_app_admin.ls_login
    /sso/auth/*
    
    
  2. Register this logout URI with the third-party access management system:

    /pls/orasso/orasso.wwsso_app_admin.ls_logout
    

Note:

In the remaining steps and in the sample package that follows, change all instances of acme and SSOAcme to your company name.

  1. Create a Java file for your package. For help, see the sample file in "Integration Case Study: SSOAcme". The sample file is called SSOAcmeAuth.java. Before it is compiled, this package directive must be added to it:

    package acme.security.ssoplugin;
    
    
  2. Compile the file, including ORACLE_HOME/sso/lib/ipastoolkit.jar in the class path. The sample file SSOAcmeAuth.java is compiled this way:

    ORACLE_HOME/jdk/bin/javac -classpath ORACLE_HOME/sso/lib/ipastoolkit.jar:
    ORACLE_HOME/lib/servlet.jar -d ORACLE_HOME/sso/plugin SSOAcmeAuth.java
    
    

    This command creates SSOAcmeAuth.class and places it in the directory ORACLE_HOME/sso/plugin/acme/security/ssoplugin.

  3. In the policy.properties file, replace the simple authentication plugin with the plugin that you created in step 3. The simple authentication plugin looks like this:

    MediumSecurity_AuthPlugin = oracle.security.sso.server.auth.SSOServerAuth
    
    

    The sample plugin looks like this:

    MediumSecurity_AuthPlugin = acme.security.ssoplugin.SSOAcmeAuth
    

    Note:

    When editing policy.properties, take care not to insert blank space at the end of a line.

  4. If you decided to implement the custom cookie interface, add the class name of the implementation to policy.properties:

    # Custom Cookie Provider Class name
    # ---------------------------------
    # Sample custom cookie tester provider class
    
    CustomCookie_ProviderPlugin = class_name
    
    
  5. Designate the minimum authentication level at which the custom cookie is set if the user authenticates successfully:

    # Custom Cookie auth level
    # ------------------------
    CustomCookieAuthLevel = authentication_level
    
    

    If you are not using multilevel authentication and are using default settings for authentication adapter levels, you can set this value to:

    CustomCookieAuthLevel = MediumSecurity
    
    
  6. Restart the single sign-on middle tier:

    ORACLE_HOME/opmn/bin/opmnctl restartproc process-type=HTTP_Server
    
    ORACLE_HOME/opmn/bin/opmnctl restartproc process-type=OC4J_SECURITY
    
    
  7. Test the integrated system.

13.3.3 Logging Out of the Integrated System

Before proceeding with this section, make sure that you understand the concept of single sign-off and know how implement it. Read the section "Single Sign-Off" in Chapter 1.

Third-party logout takes two forms:

  • The user initiates a logout request using the third-party access management system.

    In this scenario, the user clicks a logout link that invokes a logout handler in the third-party system. The third-party logout flow cleans up its own session. After cleanup, The third-party system must invoke the OracleAS Single Sign-On logout handler. Invoking the OracleAS Single Sign-On logout handler ensures that the user is logged out of all applications protected by the OracleAS Single Sign-On server. To perform single sign-on logout, the third-party system must redirect the user to the following URL:

    http://single_sign-on_host:single_sign-on_port/pls/orasso/orasso.wwsso_app_
    admin.ls_logout?p_done_url=done_url
    
    

    or, if SSL is enabled, to this URL:

    https://single_sign-on_host:single_sign-on_ssl_port/pls/orasso/orasso.wwsso_app_admin.ls_logout?p_done_url=done_url
    
    

    done_url is the URL to which the user is redirected after logout.

  • The user initiates a logout request using the OracleAS Single Sign-On system

    In this scenario, the user clicks a logout link in an Oracle partner application. This invokes the OracleAS Single Sign-On logout handler. When logout is finished, the user should also be logged out from the third-party system. Concurrent logout is effected by registering the Oracle logout handler (ls_logout in the URL immediately preceding) with the third-party system. The third-party system cleans up the third-party session when it detects that the Oracle logout handler is being invoked.

    If you have chosen to use an adapter from a third party, see that vendor's documentation to learn how logout is actually implemented.

13.4 Integration Case Study: SSOAcme

Consider the case of SSOAcme, a product that offers single sign-on authentication to protected resources. SSOAcme consists of two components: the SSOAcme policy server and the SSOAcme 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 SSOAcme.

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


Note:

SSOAcme is a fictitious product, used for the purposes of illustration only.

This section contains the following topics:

13.4.1 Sample Integration Package

The SSOAcme.java package, presented here, can be used to integrate an existing SSOAcme implementation with OracleAS Single Sign-On.

/**
  * returns IPASUserInfo
/**

/* Copyright (c) 2002, 2003, Oracle Corporation.  All rights reserved.  */

/*
   DESCRIPTION
     Sample class for SSOAcme integration with SSO Server

   PRIVATE CLASSES

   NOTES
     This class implements the SSOServerAuthInterface.
     To enable this integration, replace:
         oracle.security.sso.server.auth.SSOServerAuth
     with
         acme.security.ssoplugin.SSOAcmeAuth
     for the desired security level in policy.properties.
 */

import java.io.PrintWriter;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import oracle.security.sso.ias904.toolkit.IPASAuthInterface;
import oracle.security.sso.ias904.toolkit.IPASAuthException;
import oracle.security.sso.ias904.toolkit.IPASUserInfo;
import oracle.security.sso.ias904.toolkit.IPASInsufficientCredException;

public class SSOAcmeAuth implements IPASAuthInterface {

    private static String CLASS_NAME = "SSOAcmeAuth";
    private static String ACME_USER_HEADER = "ACME_USER";

    public SSOAcmeAuth() {

    }

    public IPASUserInfo authenticate(HttpServletRequest request)
      throws IPASAuthException, IPASInsufficientCredException {

      String AcmeUserName = null;

      try
       {
         AcmeUserName = request.getHeader(ACME_USER_HEADER);
       }
       catch (Exception e)
       {
         throw new IPASInsufficientCredException("No Acme Header");
       }

       if (AcmeUserName == null)
           throw new IPASInsufficientCredException("No Acme Header");

       IPASUserInfo authUser = new IPASUserInfo(AcmeUserName);

       return authUser;

    }


    public String getUserCredentialPage(HttpServletRequest request,
        String msg) {

        // This function will never have been reached in the case of SSOAcme
        // because the SSOAcme Agent will intercept all requests
        return "http://error_url";

    }

}

13.4.2 Migrating the Release 9.0.2 Sample Implementation to Release 10.1.2

This section is provided for the benefit of those who used the release 9.0.2 external authentication package to perform third-party authentication. The release 9.0.2 package was written in PL/SQL. The release 10.1.2 package is written in Java. In the lines that follow, the pertinent sections of the two packages appear together.

13.4.2.1 New Authentication Interface

Release 10.1.2:

package acme.security.ssoplugin;

import java.io.PrintWriter;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import oracle.security.sso.server.util.SSODebug;
import oracle.security.sso.ias904.toolkit.IPASAuthInterface;
import oracle.security.sso.ias904.toolkit.IPASAuthException;
import oracle.security.sso.ias904.toolkit.IPASUserInfo;
import oracle.security.sso.ias904.toolkit.IPASInsufficientCredException;

public class SSOAcmeAuth implements IPASAuthInterface {

    private static String CLASS_NAME = "SSOAcmeAuth";
    private static String ACME_USER_HEADER = "ACME_USER";

public SSOAcmeAuth() {
}

public IPASUserInfo authenticate(HttpServletRequest request)
throws IPASAuthException, IPASInsufficientCredException {

Release 9.0.2:

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

13.4.2.2 Get User Name from HTTP Header

Release 10.1.2:

String AcmeUserName = null;

try
 {
  AcmeUserName = request.getHeader(ACME_USER_HEADER)

Release 9.0.2:

l_http_header := owa_util.get_cgi_env('HTTP_Acme_USER');
debug_print('Acme ID : ' || l_http_header);

13.4.2.3 Error Handling if User Name Not Present

Release 10.1.2:

}
catch (Exception e)
{  
   DebugUtil.debug(SSODebug.ERROR, "exception: " + CLASS_NAME, e);
   throw new IPASInsufficientCredException("No Acme Header");
}

if (AcmeUserName == null)
throw new IPASInsufficientCredException("No Acme Header");

Release 9.0.2:

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

13.4.2.4 Return User Name to Single Sign-On Server

Release 10.1.2:

IPASUserInfo authUser = new IPASUserInfo(AcmeUserName);

return authUser;

}

Release 9.0.2:

p_user := NLS_UPPER(l_ssouser);   -- p-user is the out parameter
return 0;                         -- SUCCESS error code
END IF;