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 code that integrates OracleAS Single Sign-On with a fictional access management system.

An enterprise that has a third-party system in place can gain access to the OracleAS suite by using APIs that enable 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:

• How Third-Party Access Management Works

• Synchronizing the Third-Party Repository with Oracle Internet Directory

• Third-Party Integration Modules

• Integration Case Study: Third-Party Access Manager

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 essentially a partner application to it. 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 former 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

Text description of the illustration ssoag035.gif

The illustration captures two possible scenarios:

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

1. The unauthenticated user attempts to access a single-sign-on partner application.

2. The application redirects the user to the single sign-on server for authentication. As part of this redirection, the following occurs:
   1. The single sign-on server has the third-party user authenticate the user.

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

   3. The single sign-on server retrieves the token from the browser.

   4. The single sign-on server verifies the token with the third-party server.

   After token verification, the single sign-on server returns the user to the requested application.

3. The application provides content to the user.

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

1. The authenticated user attempts to access a single sign-on partner application.

2. The application redirects the user to the single sign-on server for authentication. As part of this redirection, the following occurs:
   1. The single sign-on server retrieves the token from the browser.

   2. The single sign-on server verifies the token with the third-party server.

   After token verification, the 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.

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 the Oracle Directory Integration Platform or bulk load tools. For details, see Oracle Internet Directory Administrator's Guide.

Third-Party Integration Modules

You use the Java tool kit oracle.security.sso.ias904 to achieve third-party integration. You must implement two interfaces, one for authentication, the other for deployment-specific cookies. The second interface is optional.

The two interfaces in the kit perform the following functions:

• Authentication Using a Token

• Set External Cookies

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 a secure cookie. Here is the interface:

/**
     * returns IPASUserInfo
     * The returned object should contain either user & subscriber
       nicknames
     * and requested URL or full user and subscriber attribute mappings
     * (including DN & GUID) and requested URL.
     * The returned object should contain either user nickname
     * and requested URL or full user attribute mapping and requested URL.
     *
     * @param request The user's HTTP request object
     *
     * @throws IPASAuthException if the authentication fails for whatever
       reasons.
     * The exception message will be propagated to the login page
       directly.
     *
     * @throws IPASInsufficientCredException if all the required
       credentials
     * (ssousername, password, subscriber name) are not
     * passed/set in the request object
     * @return IPASUserInfo authenticated user information
     */

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

Set External Cookies

The IPASCustomCookieInterface.java package 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.

/**
     * A custom cookie can be implemented using this interface.
     * SSO server sends the cookie to the user browser.
     *
     * @param user user object that contains the authenticated user
       information
     *
     * @param req  HTTP user request object
     *
     * @return array of Cookie objects
     */
public Cookie[] getCustomCookie(IPASUserInfo user, HttpServletRequest req);

After implementing the interface, configure the policy.properties file for the custom cookie provider. The file is located at $ORACLE_HOME/sso/conf.

1. Add the class name for the custom cookie provider:

   # Custom Cookie Provider Class name
   # ---------------------------------
   # Sample custom cookie tester provider class
   
   CustomCookie_ProviderPlugin = class_name
   
   

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

   See Also: Chapter 6, "Multilevel Authentication"

Integration Case Study: Third-Party Access Manager

Consider the case of Third-Party Access Manager (TPAM), a fictional product, which, like OracleAS Single Sign-On, offers single sign-on authentication to protected resources. TPAM consists of two components: the TPAM policy server and the TPAM 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 TPAM.

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

This section contains the following topics:

• Sample Integration Package

• Logging Out of the Integrated System

• Migrating the Release 9.0.2 Sample Implementation to Release 9.0.4

Sample Integration Package

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

/**
  * returns IPASUserInfo
/**

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

/*
   DESCRIPTION
     Sample class for TPAM integration with SSO Server

   PRIVATE CLASSES

   NOTES
     This class implements the SSOServerAuthInterface.
     To enable this integration, replace:
         oracle.security.sso.server.auth.SSOServerAuth
     with
         oracle.security.sso.server.auth.SSOTPAMAuth
     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 SSOTPAMAuth implements IPASAuthInterface {

    private static String CLASS_NAME = "SSOTPAMAuth";
    private static String TPAM_USER_HEADER = "TPAM_USER";

    public SSOTPAMAuth() {

    }

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

      String TPAMUserName = null;

      try
       {
         TPAMUserName = request.getHeader(TPAM_USER_HEADER);
       }
       catch (Exception e)
       {
         throw new IPASInsufficientCredException("No TPAM Header");
       }

       if (TPAMUserName == null)
           throw new IPASInsufficientCredException("No TPAM Header");

       IPASUserInfo authUser = new IPASUserInfo(TPAMUserName);

       return authUser;

    }


    public String getUserCredentialPage(HttpServletRequest request,
        String msg) {

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

    }

}

Logging Out of the Integrated System

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 TPAM system. The TPAM logout flow cleans up its own session. After cleanup, The TPAM 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 TPAM 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
  
  

• 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 TPAM system. Concurrent logout is effected by registering the Oracle logout handler (ls_logout in the URL immediately preceding) with the TPAM system. The TPAM system cleans up the TPAM session when it detects that the Oracle logout handler is being invoked.

Migrating the Release 9.0.2 Sample Implementation to Release 9.0.4

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

New Authentication Interface

Release 9.0.4:

package oracle.security.sso.server.auth;

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 SSOTPAMAuth implements IPASAuthInterface {

    private static String CLASS_NAME = "SSOTPAMAuth";
    private static String TPAM_USER_HEADER = "TPAM_USER";

public SSOTPAMAuth() {
}

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

Get User Name from HTTP Header

Release 9.0.4:

String TPAMUserName = null;

try
 {

Release 9.0.2:

l_http_header := owa_util.get_cgi_env('HTTP_TPAM_USER');
debug_print('TPAM ID : ' || l_http_header);

Error Handling if User Name Not Present

Release 9.0.4:

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

if (TPAMUserName == null)
throw new IPASInsufficientCredException("No TPAM 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

Get User Name from HTTP Header

Release 9.0.4:

IPASUserInfo authUser = new IPASUserInfo(TPAMUserName);

return authUser;

}

Release 9.0.2:

p_user := NLS_UPPER(l_ssouser);
return 0;
   END IF;
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

Return User Name to Single Sign-On Server

Release 9.0.4:

IPASUserInfo authUser = new IPASUserInfo(TPAMUserName);

return authUser;

}

Release 9.0.2:

p_user := NLS_UPPER(l_ssouser);
return 0;
END IF;