13 Integrating with Third-Party Access Management Systems

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.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:

• Guidelines for Using the Interfaces

• The Classes and Interfaces

• Configuration Steps

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);
}
 

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);
}

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);
}

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);
   }
}
 

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);
   }
}
 

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.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.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.

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 {

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

String AcmeUserName = null;

try
 {
  AcmeUserName = request.getHeader(ACME_USER_HEADER)

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

}
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");

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

IPASUserInfo authUser = new IPASUserInfo(AcmeUserName);

return authUser;

}

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