|
Oracle® Application Server Single Sign-On Administrator's Guide
10g (9.0.4) Part No. B13791-01 |
|
|
|
|
Oracle® Application Server Single Sign-On Administrator's Guide
10g (9.0.4) Part No. B13791-01 |
|
|
|
|
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 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:
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 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
The illustration captures two possible scenarios:
The unauthenticated user attempts to access an application protected by OracleAS Single Sign-On.
The application redirects the user to the OracleAS Single Sign-On server for authentication. As part of this redirection, the following occurs:
The OracleAS Single Sign-On server has the third-party server authenticate the user.
The third-party server sets a token in the user's browser.
The OracleAS Single Sign-On server retrieves the token from the browser.
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 to the requested application.
The application provides content to the user.
The authenticated user attempts to access an application protected by OracleAS Single Sign-On.
The application redirects the user to the OracleAS Single Sign-On server for authentication. As part of this redirection, the following occurs:
The OracleAS Single Sign-On server retrieves the token from the browser (step 2c in scenario 1).
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.
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. |
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.
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.
You can use the Java tool kit oracle.security.sso.ias904, provided later in this chapter, to build your own third-party integration adapter. The tool kit consists of two interfaces, one for performing authentication, the other for setting deployment-specific cookies. The OracleAS single sign-on server invokes the first during authentication. It invokes the second, the cookie adapter, after it has successfully determined the user's identity.
This section contains the following topics:
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.
The two interfaces in the kit perform the following functions:
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:
/**
* returns IPASUserInfo
* The returned object should contain user information
nicknames
*
* @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
* @return IPASUserInfo authenticated user information
*/
public IPASUserInfo authenticate(HttpServletRequest request)
throws IPASAuthException, IPASInsufficientCredException;
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);
To create your own third-party integration adapter using the interfaces, follow these steps:
In the third-party access management system, create rules that protect these URIs:
/pls/orasso/ORASSO.wwsso_app_admin.ls_login /sso/auth/*
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. |
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;
Compile the file, including $ORACLE_HOME/sso/lib/ipastoolkit.jar in the class path. The sample file SSOAcmeAuth.java is compiled this way:
javac -classpath /usr1/ias/infra/sso/lib/ipastoolkit.jar:/usr1/ias/infra/j2ee/ home/lib/servlet.jar SSOAcmeAuth.java
In the directory $ORACLE_HOME/sso/plugin, create a directory structure that corresponds with the package hierarchy that you specified in step 3. The path to the sample plugin looks like this:
$ORACLE_HOME/sso/plugin/acme/security/ssoplugin
Put the class that you generated in step 4 into the ssoplugin directory.
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. |
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
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
Restart the single sign-on middle tier. See "Stopping and Starting the Single Sign-On Middle Tier" for instructions.
Test the integrated system.
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:
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;
}
}
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 SSOAcme system. The SSOAcme logout flow cleans up its own session. After cleanup, The SSOAcme 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 SSOAcme 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
where 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 SSOAcme system. Concurrent logout is effected by registering the Oracle logout handler (ls_logout in the URL immediately preceding) with the SSOAcme system. The SSOAcme system cleans up the SSOAcme session when it detects that the Oracle logout handler is being invoked.
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 9.0.4 package is written in Java. In the lines that follow, the pertinent sections of the two packages appear together.
Release 9.0.4:
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
Release 9.0.4:
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);
Release 9.0.4:
}
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
