White Paper March 1, Integrating AR System with Single Sign-On (SSO) authentication systems

Transcription

1 White Paper March 1, 2005 Integrating AR System with Single Sign-On (SSO) authentication systems

2 Copyright 2005 BMC Software, Inc. All rights reserved. BMC, the BMC logo, all other BMC product or service names, BMC Software, the BMC Software logos, and all other BMC Software product or service names, are registered trademarks or trademarks of BMC Software, Inc. All other trademarks belong to their respective companies. BMC Software, Inc., considers information included in this documentation to be proprietary and confidential. Your use of this information is subject to the terms and conditions of the applicable end user license agreement or nondisclosure agreement for the product and the proprietary and restricted rights notices included in this documentation. For license information about the OpenSource files used in the licensed program, please read OpenSourceLicenses.pdf. This file is in the \Doc folder of the distribution CD-ROM and in the documentation download portion of the Remedy Electronic Software Distribution (ESD). Restricted Rights Legend U.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER THE COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer software by the U.S. Government is subject to restrictions, as applicable, set forth in FAR Section , DFARS , DFARS , DFARS , and DFARS , as amended from time to time. Contractor/Manufacturer is BMC Software, Inc., 2101 CityWest Blvd., Houston, TX , USA. Any contract notices should be sent to this address. Contacting Us If you need technical support for this product, contact Customer Support by at If you have comments or suggestions about this documentation, contact Information Development by at This edition applies to version 6.3 of the licensed program. BMC Software, Inc.

3 White Paper Integrating AR System with Single Sign- On authentication systems This white paper describes the architectural overview and the integration of the Action Request System 6.3 into an SSO environment. This paper contains the following sections:! Introduction to single sign-on (page 4)! SSO architecture (page 4)! Remedy mid tier implementation (page 9)! AREA plug-in implementation (page 16) Integrating AR System with Single Sign-On authentication systems! 3

4 White Paper Introduction to single sign-on SSO architecture The Remedy Mid Tier now supports integration with Single Sign-On (SSO) for web environments. This feature means that, after the mid tier is integrated with an SSO environment, the user needs only to sign in one time using a web browser and is then authenticated to access all the web applications within a configured domain, including the mid tier as one of the deployed web applications. Because each SSO environment varies greatly and there are few applicable standards for SSO, the SSO integration of the mid tier can be complicated. This document describes how to integrate the AR System with an SSO environment. For this discussion, we assume that the user is familiar with the basic AR System architecture, and for the implementation portion, we assume that the reader is familiar with the Java and C API for writing an AR System client. (For more information, see the Action Request System C API Reference Guide.) The AR System consists of a two-tiered client/server architecture with Remedy User acting as the client and the AR System Server acting as the server. Extending this to the web environment, consider the mid tier as a meta- Remedy User; that is, the mid tier is a single Remedy User with the ability to support multiple users at the same time. The mid tier behaves as described in the following sequence: 1 The mid tier presents a login page to the user if no session is established yet for this user. 2 After the user is logged on, the mid tier creates a session associated with this user containing, minimally, the user s credentials. (Other information would include locale, and so on.) 3 For each request placed by the user after a session is established, the mid tier makes a request on the user s behalf to an AR System server, supplying the request with the credentials as retrieved from the associated user session. 4 The mid tier places the request with the AR System server through the normal RPC channel. 4 "Integrating AR System with Single Sign-On authentication systems

5 Integrating AR System with Single Sign-On authentication systems The AR System does not distinguish a request made by the mid tier from that of Remedy User. Therefore, you treat the mid tier as a normal AR System client such as the Remedy User. In an SSO environment, a web application used in a configured SSO domain gives control of the authentication process to the SSO service. In other words, the deployed web application no longer performs its own user authentication; instead, the SSO service does the user authentication for it. In exchange for giving up this control, the SSO service guarantees that an SSO token is always paired with each request when the request reaches the deployed application within the configured SSO domain. The token is then retrieved and exchanged for the user s credentials by the application. You must use some type of centralized identity service running with the SSO service (1) for the SSO service to authenticate the user against the identity service and (2) for the web application at a post-authentication time to make the exchange of the SSO token for the user credentials. Request-response sequence in an SSO environment Figure 1-1 shows a typical sequence of interaction for a user request in an SSO environment. Depending on the SSO environment, a variation of the sequence shown might take place. Tip: Substitute the proxy server with a servlet filter or some type of a web agent deployed in the web-server. SSO architecture! 5

6 White Paper Figure 1-1: Request-response in an SSO environment A user request in an SSO environment carries out the following sequence of interactions: 1 The user requests a resource from a web application deployed in an SSO environment. 2 If the user has not logged in with the SSO service, the proxy server intercepts the request and routes it to the SSO service. 3 The SSO service challenges the user for his credentials by presenting a login page. 4 The user submits his credentials to the SSO service. 5 The SSO service uses the centralized identity service to authenticate the user. 6 After successful authentication, the SSO service routes the request back to the proxy server, embedding some type of SSO token (specific to the protocol used) in the request. 7 The proxy server detects the SSO token in the request (indicating that the user has been authenticated) and routes the original request (now paired with the SSO token) to the web application. 6 "Integrating AR System with Single Sign-On authentication systems

7 Integrating AR System with Single Sign-On authentication systems 8 The web application extracts the SSO token from the request and exchanges it with the identity service for the user credentials. 9 The identity service returns the user credentials to the web application. 10 The web application applies the user credentials to the request and returns the appropriate requested resource. Request-response for an AR System integrated with SSO environment Unlike a normal web application where the authentication and authorization process can be centralized to a single tier, the AR System's authentication and authorization process must start at the mid tier but is ultimately performed by the AR System server. For that reason, the mid tier, an AR System client, needs to delegate the exchange of the SSO token for the user credentials to the AR System server. Thus, the AR System client must pass this token to the AR System server in such a way that it signals the AR System server to invoke the AREA plug-in to use the token to verify that user authentication has been performed, and then exchange this token for the user credentials to perform the authorization process. The AR System server architecture isolates the authentication and authorization process to an AREA plug-in if the authentication and authorization process requires extending. The integrator of the AR System with the SSO environment must implement this AREA plug-in module to supplement the implementation of the custom authenticator (see The authenticator API on page 10) in the mid tier to provide a complete SSO solution. SSO architecture! 7

8 White Paper This sequence is illustrated in Figure 1-2. Figure 1-2: Request-response for an AR System integrated with SSO environment The AR System integrated with the SSO environment carries out the following sequence of request-response interactions: 1 The user requests a resource from the mid tier application deployed in an SSO environment. 2 If the user has not logged in with the SSO service, the proxy server intercepts the request and routes it to the SSO service. 3 The SSO service challenges the user for the credentials by presenting a login page. 4 The user submits the credentials to the SSO service. 5 The SSO service uses the identity service to authenticate the user. 6 After successful authentication, the SSO service routes the request back to the proxy server. 7 The proxy server detects the SSO token in the request (indicating that the user has been authenticated) and routes the original request to the mid tier application. 8 The mid tier constructs a request on behalf of the user and forwards it to the AR System server with the SSO token. 8 "Integrating AR System with Single Sign-On authentication systems

9 Integrating AR System with Single Sign-On authentication systems 9 The AR System server calls the AREA plug-in with the SSO token. 10 The AREA plug-in verifies that the user has been authenticated and exchanges the SSO token for the user credentials with the identity service. 11 The identity service returns the user credentials to the AREA plug-in. 12 The AREA plug-in forwards the user credentials to the AR System server. 13 The AR System server applies the user credentials to the request and returns the result to the mid tier. 14 The mid tier returns the response to the user. Note: The previous sequence is very detailed; some deployments might combine more than one service. For brevity, a caching strategy to optimize performance is not included in the diagram. Remedy mid tier implementation Integrating the 6.3 mid tier into an SSO environment requires two implementations and the proper configuration of the implemented pieces:! An implementation of the com.remedy.arsys.session.authenticator interface for the mid tier! An implementation of the AREA plug-in for the AR System server to supplement the implementation in the previous bullet! The configuration of the pieces implemented in the two previous bullets as described in Instantiation on page 11 Remedy mid tier implementation! 9

10 White Paper The authenticator API Figure 1-3 shows the class diagram for the authenticator interface. The com.remedy.arsys.sso.oracleauthenticator is packed in the midtier.jar file in a standard installation. Figure 1-3: Authenticator interface The authenticator interface is given by: public interface Authenticator { public void init(map config) public void destroy() publicusercredentials getauthenticatedcredentials (HttpServletRequest request, HttpServletResponse response) throws IOException; } where UserCredentials is a data-object class with the following constructor: public UserCredentials(String user, String password, String authenticationstr) The getauthenticatedcredentials() method throws IOException to simplify the support of the methods of the classes HttpServetRequest and HttpServletResponse. 10 "Integrating AR System with Single Sign-On authentication systems

11 Integrating AR System with Single Sign-On authentication systems Method responsibilities In the default configuration of the mid tier, an instance of the com.remedy.arsys.session.defaultauthenticator class will perform the login and authentication. If the mid tier is configured for SSO, the CustomAuthenticator extracts the user credentials from the request in a way that is specific to the SSO system in use. The mid tier sends the retrieved credentials to the AR System server using one of the following mechanisms:! Cross-reference blank password! The Authenticate Unregistered User in the AR System to invoke an AREA plug-in to validate the user s credentials with the identity management server provided by the SSO system. Both of these mechanisms are configured using Remedy Administrator. The AREA plug-in must be matched with the correct authenticator object during configuration because the plug-in and the object must be synchronized to perform the authentication/authorization as a complete SSO solution. The Java methods used with the authenticator are responsible for instantiating, initializing, and destructing the authenticator object. Instantiation Note: You can instantiate only one authenticator for the life of the mid tier execution. When the mid tier web application is initialized, it uses reflection to instantiate an instance of the authenticator. The fully qualified name of the class implementing this interface must be specified in the config.properties file under the entry arsystem.authenticator. For example: arsystem.authenticator=com.remedy.arsys.session.defaultauthenticator In a normal deployment, the config.properties file is found in the WEB_INF/ classes directory. Remedy mid tier implementation! 11

12 White Paper In the previous example, the DefaultAuthenticator is the authenticator that provides normal authentication services when the mid tier is deployed in a non-sso environment. This is the authenticator the mid tier defaults to if the configured authenticator fails. Initialization and destruction init() After the mid tier instantiates an instance of the authenticator using reflection, it builds an object of type java.util.properties using the properties specified in the file indicated by the entry arsystem.authenticator.config.file in the config.properties file. (This is a map of the name-value order pairs provided by the content of the file.) For example: arsystem.authenticator.config.file=myauthenticator.properties In a normal deployment, the property file myauthenticator.properties, used in the example, must be in the same directory as the file config.properties, for example, in WEB-INF/classes. If there is no entry for the authenticator init file in the config.properties file or if it is not possible for the mid tier to locate or open the file given by the arsystem.authenticator.config.file entry, it creates an empty properties object. This object is then passed into the init() method. In summary, any initialization of the authenticator should be done inside the init() method; if any of the parameters that can be externalized are needed during the authenticator initialization process, they should be placed in a separate file. The file name must be registered in the config.properties file under the entry arsystem.authenticator.config.file. destroy() When the mid tier is being unloaded from the application server, it calls the destroy() method of the authenticator. As a result, any clean-up of resource usage should be done here. Figure 1-4 describes the sequence for the initialization and destruction of the authenticator. 12 "Integrating AR System with Single Sign-On authentication systems

13 Integrating AR System with Single Sign-On authentication systems Figure 1-4: Init() and destroy() sequence Main authenticator implementation The main implementation of the authenticator takes place inside the getusercredentials() method. The implementation of this method is divided into two cases, depending on the SSO environment configuration.! In the case where the mid tier is deployed behind a proxy (that is, the mid tier is deployed in an SSO environment where each request that reaches the mid tier is guaranteed to have been authenticated), the method getusercredentials() is called only when the mid tier needs to retrieve the user credentials in order to establish a session for the user. Here, the method must return the UserCredentials object. The object s value is used to establish a session for the user, and then it is wrapped and passed, as is, to the AR System server when the mid tier constructs a request on behalf of the user. If the returned UserCredentials object is in an invalid format (for example, missing the user name), the mid tier will default to the DefaultAuthenticator, the normal login mechanism of the mid tier. Remedy mid tier implementation! 13

14 White Paper In summary, if the mid tier is deployed behind a proxy, guaranteeing that any request reaching the mid tier has been authenticated, then the getusercredentials() method s responsibility is to extract the user credentials that are specific to the protocol of the SSO environment from the request, construct a UserCredentials object, and return this object as the return value.! In the case where the mid tier is not deployed behind a proxy (that is, the mid tier is deployed in such a way that it must route unauthenticated requests to a configured SSO service), it has the additional responsibility of routing the pre-session establishment requests to the SSO service. This is achieved by synchronizing the mid tier with the configured authenticator. Again, the mid tier will invoke the getusercredentials() method only when it needs to establish a session for the user. In the context of pre-session establishment, when the user request arrives, the mid tier calls the getusercredentials() method, passing both the HttpServletRequest and HttpServletResponse objects. At this point, the authenticator examines the HttpServletRequest object to see whether the SSO token is embedded inside the HttpServletRequest. (The embedding protocol is specific to the SSO environment.)! If yes, the method extracts the information, constructs a UserCredentials object, and returns this object as the return value.! If no, the method embeds the routing information to the SSO service in the HttpServletResponse object and returns null. When the mid tier receives null, it routes the HttpServletResponse object to the Servlet container so that the user request is redirected to the SSO service. After the SSO service has authenticated the user, it embeds the SSO token in the HttpServletRequest object, reconstructs the original request, and routes it back to the mid tier. At this point, the behavior is the same as described in the first case. 14 "Integrating AR System with Single Sign-On authentication systems

15 Integrating AR System with Single Sign-On authentication systems Remedy Mid Tier and getusercredentials() sequence Figure 1-5 shows the calling sequence for processing a user request the first time. (The sequence is for a deployment without a proxy server, the more complex implementation.) There are two cases:! Request with token After the user has authenticated with the SSO service and an SSO token is provided with the request.! Request without token Before the user has been authenticated with the SSO service and no SSO token is provided with the request. Figure 1-5: Request processing sequence for initial user request with no proxy Remedy mid tier implementation! 15

16 White Paper AREA plug-in implementation The architecture of the AR System server allows you to isolate the authentication/authorization process so that the authentication/ authorization can be extended to work with one or more external services. The system ships with an AREA plug-in specifically for an LDAP directory service. If the Identity Service for the SSO environment can be accessed using LDAP, this plug-in can be configured to work with the authenticator without modifications. For configuration issues, see the LDAP plug-in documentation. If the SSO environment does not allow this LDAP plug-in, then a custom AREA plug-in must be implemented. Implementation objectives The two goals of the implementation of the AREA plug-in are:! Coordinate with the authenticator (implemented for the mid tier) to receive the SSO token.! Use the SSO token to verify that authentication had taken place and then exchange the SSO token for the user credentials. The AREA plug-in API The AREA plug-in API consists of three C language callback functions, five plug-in lifecycle functions to be implemented, and one data structure in which to return results. Typically, a plug-in must be implemented for each authenticator implemented, corresponding to each SSO system for which integration with the AR System is to be provided. The C API can be found in Action Request System C API Reference Guide. For the first implementation objective, make sure that the AR System server is configured to use either the cross-reference blank password or the authenticate unregistered user functions, or both, of the AR System server. This causes the AR System server to invoke an AREA plug-in that validates the user s credentials with the Identity Management server. After that, depending on the SSO environment, the AREA plug-in must do the following: 1 Establish a connection to the Identity Service. 2 Verify that the user has been authenticated using the received SSO token. 16 "Integrating AR System with Single Sign-On authentication systems

17 Integrating AR System with Single Sign-On authentication systems 3 Retrieve the user credentials using the SSO token and return this as a structure required by the C API. Authentication chaining In previous releases of the AR System, you could configure one AREA plugin to extend the authentication/authorization process. This meant all AR System clients of an AR System server were subjected to an identical process of authentication/authorization, either internally or as configured using the external AREA plug-in. In some deployments, this behavior posed a support limitation for different AR System client types. For example, you may have wanted a single AR System server to service the mid tier using an external identity service, while servicing the Remedy User clients using the internal AR System authentication process. With the 6.3 release, the AR System now supports the following three options for extending the authentication/authorization process:! Cross-reference blank passwords! Authenticate unregistered users! Authentication chaining The first two options are as in pre-6.3 release. The third option provides a flexible configuration so that one AR System server can use different authentication/authorization processes to serve varying AR System client types. Authentication chaining allows the AR System server administrator to configure the behavior using a configuration file. The behaviors and their corresponding values are described in the following table: Behavior Corresponding values Use the default behavior as in pre-6.3 release 0 Use internal authentication first, then use external 1 authentication via the AREA plug-in Use external authentication by way of the AREA plug-in first, and then use internal authentication 2 AREA plug-in implementation! 17

18 White Paper If a single external AREA plug-in is insufficient, as in the case of multiple identity services, the AR System server administrator can configure the AR System server to use the AREA plug-in hub. (For more information, see the Installing AR System Guide.) The AREA plug-in hub provides a sequential chaining of one or more external AREA plug-ins. The chain then behaves as a single AREA plug-in. That is, when the AR System server invokes the AREA plug-in hub, each AREA plug-in configured in the chain is called in sequence until a first valid response is returned. 18 "Integrating AR System with Single Sign-On authentication systems

19

20 *65700* *65700* *65700* *65700* *65708*