wdk authentication session management

WDK Authentication and Session Management

Junaid Asifali

Date 6/19/2007

WDK Authentication and Session Management 2

Copyright © 2006-2007 EMC Corporation. All rights reserved.

EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice.

THE INFORMATION IN THIS PUBLICATION IS PROVIDED “AS IS.” EMC CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Use, copying, and distribution of any EMC software described in this publication requires an applicable software license.

EMC2, EMC, and EMC Documentum product names are trademarks of EMC Corporation. All other trademarks used herein are the property of their respective owners. All other brand names are trademarks or registered trademarks of their respective owners.


WDK Authentication and Session Management Introduction: EMC Documentum web applications are based on the WDK framework. These act as web clients to the Content Server and provide a way of leveraging content server functionality through the web. The web clients are J2EE based and run on an application server. The following is a very simple diagram of this setup :

As it is clear from the stack above, we need to have an understanding of how authentication and sessions are managed and related in the above layers – WDK/Application Server, DFC, DMCL and the Content Server. In the course of debugging/troubleshooting, we deal with both Http Sessions and Documentum Sessions. Http Session Management capabilities are provided by the application server. WDK and DFC provide Documentum Session Management capabilities. WDK is also responsible for binding a user’s Http session to Documentum sessions. By default, application server authentication is not used (except for principal authentication). WDK and DFC are responsible for generating the appropriate authentication call to the content server.

Web Clients – Webtop/WebPublisher/DCM/DAM

WDK Framework

Application Server Infrastructure

Documentum Foundation Classes (DFC)

DMCL

Content Server


Authentication: WDK framework gathers user information via different schemes and sends it over to the content server through DFC for the actual authentication. The end result of any type of authentication is the generation of a connect api call to the content server having the user name, password, docbase and any additional parameters. The following authentication schemes can be used with WDK. The next section will have details on how these schemes can be setup. Ticketed Authentication Scheme: In this scheme, a content server ticket is used instead of the user password for authentication. Typically, this is used when a user has logged into a different non-documentum application and now needs to access a Documentum app (say Webtop) without having to login in again. The first app generates a ticket and passes it as part of URL arguments including an option ‘startupAction’ parameter that specified the action to be run after login. The following is an example of the ticketed login URL: http://localhost:8080/webtop/component/main?ticket=DM_TICKET%3d0000001a3dd7626e.viper@denga0008&username=testuser&docbase=viper Please note the ticket parameter above. Content server generated tickets usually start with a DM_TICKET qualifier. One way to test ticketed authentication is to use IAPI to get the ticket from the content server and manually construct the url above and invoke it. SSO Authentication Scheme: Single sign-on lets a user log on once and access multiple applications in a corporate intranet without having to go through a login process for each application. For example, if a single sign on is implemented in EMC/Documentum intranet, we would be able to access the support website, dm_notes webtop, powerlink etc. after logging in only once through the web agent. A login token and a user name is added to the http request by the Web Agent. Each application (say Webtop) examines the request and extracts the token and user name. The token is then used as a password for the user. Http requests to all applications are routed through the SSO Web Agent.

The following are the detailed steps for logging into webtop using SSO. Please refer to the diagram above.

SSO Web Agent

Webtop Content Server SSO Plugin

SSO Server

Step 1 – SSO cookie/user name

Step 2 – connectcall with SSO token as password

Step 3 -Authenticate

Step 4 - Authenticate


1. User accesses Webtop using the standard URL. The user request is redirected to the SSO Web

agent that checks if the user is logged in to the SSO policy server. If yes, the user is redirected to the webtop url. If not, an SSO login screen is presented. Once the user logs in, the request is redirected to Webtop.

2. Webtop extracts the user name and token from the request and generates a connect call to the server using the sso token as the password. The string DM_PLUGIN=<plugin_name>/ is appended to the password.

3. Content server examines the password and sends over the authentication request to the plugin indicated by the string in step 2.

4. The authentication plugin (that resides on the content server) finally authenticates the user against the policy server.

Please note that the user_source attribute of the dm_user object can be modified to indicate plugin authentication. This eliminates the need to append the string in step 2 to the password. Principal Authentication Scheme: Principal Authentication enables a single login to the application server as well as the content server. J2EE Principal Authentication leverages the authentication support provided by the application server. Each application server has its own way of authenticating users. Once the user is authenticated, the application server adds a principal object

The following steps take place during principal authentication:

1. User accesses a WDK application URL and a standard windows login dialog is shown. 2. Authentication succeeds and the user is redirected to the WDK application. The application server

adds a principal object to the http request that contains the user/principal name that has been successfully authenticated.

3. WDK grabs the principal/user name and uses super user credentials to create a ticket for this user. 4. Finally, a super user session is created and the session is ‘assumed’ to the principal user using the

ticket created in step 3. Please note that principal authentication requires super user credentials to be setup in one of the property files on the application server machine.

App Server WDK Application

Content Server

Http request triggers J2EE authentication

Principal Object added to http request

Session created for the user specified in the principal object.


Docbase Authentication Scheme: This is the standard authentication where the user has to manually enter the user/password and select a docbase to login. Authentication Schemes Configuration: Authentication schemes are configured in WEB-INF/com/documentum/web/formext/session/ AuthenticationSchemes.properties file. In a default configuration, it has the following entries: scheme_class.1=com.documentum.web.formext.session.TicketedAuthenticationScheme scheme_class.2=com.documentum.web.formext.session.SSOAuthenticationScheme scheme_class.3=com.documentum.web.formext.session.UserPrincipalAuthenticationScheme scheme_class.4=com.documentum.web.formext.session.SavedCredentialsAuthenticationScheme scheme_class.5=com.documentum.web.formext.session.DocbaseLoginAuthenticationScheme The WDK framework invokes all the schemes in the order they are specified. If one of the schemes succeeds, the user is redirected to the WDK component requested. Custom schemes can also be configured in this file. Please note that the last scheme is the Docbase Authentication. If all the other schemes fail, the default login component that is part of this scheme is displayed. Authentication Service: Authentication service is responsible for managing the authentication process in WDK. The component dispatcher (which serves requests for components) calls the authentication service when a component requires authentication. Please refer to the sequence diagram below for the authentication flow:


As the diagram above indicates, Authenticate service invokes ‘authenticate’ on the Authentication Scheme class. If the authentication is successful, the scheme returns the docbase name. If that returns a ‘null’, Authentication Service invokes ‘getLoginComponent’. If that returns ‘null’ as well, the Authentication Service moves over to the next scheme and follows the same sequence. After gathering the user name, password and docbase, Authentication Schemes invoke AuthenticationService.login method that sets up the credentials in the http session and also authenticates the credentials with the content server. Session Management: Http Session Binding: WDK framework does not maintain a docbase session once the user logs on to a docbase. Docbase sessions are requested and released by components and actions as needed. Thus, there can be multiple docbase sessions requested/released in a single http session depending on the number of components that a user navigates. Each http session has a singleton instance of a DFC session manager (not a DFC session). Once the authentication is complete, the authentication service creates an IDfLoginInfo object containing the user name and password and sets it as an identity in the session manager. Any component or action requiring a docbase session can request a session from this session manager by simply passing in the docbase name. More than one identity can be set on the session manager. Thus, through the same http session we can access multiple docbases. The SessionManagerHttpBinding class provides an interface for getting access to a session manager associated with the http session. It has static methods for getting the session manager, current user, current docbase etc. Custom components can also use the SessionManagerHttpBinding class to get access to the session manager. Session Pooling: Components usually get a docbase session from the session manager associated with the http session. Once the docbase work is done, the session is released using the IDfSessionManager.release call. The released docbase session may be internally pooled by DFC and DMCL. In a default configuration, once a session is released, DFC keeps it in its pool for 5 seconds before releasing it to dmcl. If another getSession call is made during this 5 second interval, DFC returns the same session instead of requesting it from DMCL. This improves performance as session are rapidly requested and released in a WDK application. Please refer to the white paper on ‘DMCL and Session Management’ for understanding session pooling in dmcl. Timeouts: In a WDK application, we need to be aware of three different session timeouts:

1. HTTP Session timeout – Specified in the the web.xml file. 2. HTTP Session Control timeout – Specified in the the wdk/app.xml file. 3. DMCL sessions timeout – Controlled by the client_session_timeout key in the server.ini.


HTTP Session timeout is controlled by the J2EE Application server. If there are no requests for a web application for a particular time period (30 min by default in most application servers) , the application server kills the http session and the web application forces the user to re-login. Http Session Control Timeout is specific to WDK applications. This is triggered if the main frame of the WDK application unloads. The main frame could unload if the user closes the browser window or navigates to a different website (without logging off from WDK first). Once this event happens, the http session for the user is invalidated after the time specified in the app.xml file which is set to 3 minutes by default. How do I: Create and create and deploy a new Authentication Scheme in Webtop?

1. Create an AuthenticationScheme class that implements IAuthenticationScheme public class MyAuthenticationScheme implements IAuthenticationScheme { /* * This method gets the user name and password that is set by the login component * and authenticates the credentials. * */ public String authenticate(HttpServletRequest request, HttpServletResponse response, String docbase) throws com.documentum.fc.common.DfException { String user = (String) SessionState.getAttribute(USER); String password = (String) SessionState.getAttribute(PASS); String domain = null; //If the user name and passsword is not set return null. This means that the login //component has not been invoked as yet. if(user == null || password== null) return null; //Authenticate the user using AuthenticationService AuthenticationService.getService().login(request.getSession(),docbase,user,password,domain); return docbase; } public String getLoginComponent(HttpServletRequest request, HttpServletResponse response, String docbase,ArgumentList argumentList) { return LOGIN_COMPONENT; } private static final String LOGIN_COMPONENT = "my_login"; private static final String USER = "my_user"; private static final String PASS = "my_password"; }

2. Create a new login component. This is not always required and depends on the need. Please refer to the authentication steps to understand when the login component is invoked.

XML config file: <?xml version="1.0" encoding="UTF-8" standalone="no"?> <config version='1.0'> <scope>

<component id="my_login">  <desc> My Login Component </desc>  <params> </params>  <pages> <start>/custom/component/login/my_login.jsp</start> </pages>  <class>com.custom.component.login.MyLogin</class>  </component> </scope> </config>

JSP Page: <%@ page contentType="text/html; charset=UTF-8" %> <%@ page errorPage="/wdk/errorhandler.jsp" %> <%@ taglib uri="/WEB-INF/tlds/dmform_1_0.tld" prefix="dmf" %> <%@ taglib uri="/WEB-INF/tlds/dmformext_1_0.tld" prefix="dmfx" %> <html> <head> <dmf:webform/> </head> <body class='contentBackground' marginheight='0' marginwidth='0' topmargin='0' bottommargin='0' leftmargin='0' rightmargin='0'> <dmf:form> <table align="center"> <tr><td><h2> My Login Component</td></tr> <tr><td><BR><BR><BR><BR></td></tr> <tr> <td> <b> <dmf:label label="Repository "/></b><dmf:dropdownlist name="drDocbase"/> </td> </tr> <tr> <td align="center"> <dmf:button onclick="onButtonClick" name="btnLogin" label="Login"/> </td> </tr> </table> </dmf:form> </body> </html> Java File public class MyLogin extends Component { //**************Standard Lifecycle Methods *******************// public void onInit(ArgumentList args) { try {


buildDocbaseList(); } catch(DfException e) { e.printStackTrace(); } } public void onRender() { super.onRender(); } public void onRenderEnd() { super.onRenderEnd(); } public void onExiit() { super.onExit(); } //********************Helper Methods *************************// private void buildDocbaseList() throws DfException { DropDownList docbaseList = (DropDownList) getControl("drDocbase", DropDownList.class); IDfClient client = DfClient.getLocalClient(); int docbaseCount = client.getDocbaseMap().getDocbaseCount(); for(int i = 0; i < docbaseCount; i++) { String docbase = client.getDocbaseMap().getDocbaseName(i); Option op = new Option(); op.setLabel(docbase); op.setValue(docbase); docbaseList.addOption(op); } } //*****************Server Side Event Handlers ****************// /* * This event handler updates the label on the UI with a number * stamp */ public void onButtonClick(Control ctrl,ArgumentList args) { //Get the label control to update DropDownList docbaseList = (DropDownList) getControl("drDocbase", DropDownList.class); String docbase = docbaseList.getValue(); SessionManagerHttpBinding.setCurrentDocbase(docbase); //User name and password hardcoded for simplicity // We can get this from the request object or from any external source. SessionState.setAttribute(USER,"dmadmin"); SessionState.setAttribute(PASS, "r1ng3r"); //Navigate to the main component super.setComponentJump("main",getContext()); } private static final String USER = "my_user"; private static final String PASS = "my_password"; }

3. Change the Authentication Schemes property file to add the new authentication scheme. This file is located in WEB-INF/classes/com/documentum/web/formext/session.


scheme_class.1=com.custom.authentication.MyAuthenticationScheme scheme_class.2=com.documentum.web.formext.session.TicketedAuthenticationScheme scheme_class.3=com.documentum.web.formext.session.SSOAuthenticationScheme scheme_class.4=com.documentum.web.formext.session.UserPrincipalAuthenticationScheme scheme_class.5=com.documentum.web.formext.session.SavedCredentialsAuthenticationScheme scheme_class.6=com.documentum.web.formext.session.DocbaseLoginAuthenticationScheme

Questionnaire:

1. How can you use the WDK Http Session Binding interface to create a docbase session? Write a few lines of code.

2. List the steps necessary to create, deploy and test a new Authentication Scheme in WDK Apps? 3. If Netegrity SSO authentication is not working for a customer, what debugging steps would you

follow based on the authentication flow diagram for SSO given earlier in this white paper?

wdk authentication session management

Documents