WDK Authentication and Session

Management
Junaid Asifali

Date 6/19/2007
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 2

 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 :

Web Clients –
Webtop/WebPublisher/DCM/DAM

WDK Framework

Application Server Infrastructure

Documentum Foundation Classes (DFC)

DMCL

Content Server

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.

WDK Authentication and Session Management 3

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.

SSO Web Agent SSO Server

Step 1 – SSO
cookie/user
name

Step 2 – connect Step 3 - Step 4 -

call with SSO token Authenticate Authenticate
as password

Webtop Content Server SSO Plugin

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

WDK Authentication and Session Management 4

 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

App Server WDK Content Server

Application

Http request Principal Object Session created for

triggers J2EE added to http the user specified in
authentication request the 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.

WDK Authentication and Session Management 5

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:

WDK Authentication and Session Management 6

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.

WDK Authentication and Session Management 7

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>

WDK Authentication and Session Management 8

 <component id="my_login">

<!-- Description (not NLS'd) -->

<desc>
My Login Component
</desc>

<!-- Component Contract - there is none -->

<params>
</params>

<!-- Component Layout -->

<pages>
<start>/custom/component/login/my_login.jsp</start>

</pages>

<!-- Component Behavior -->

<class>com.custom.component.login.MyLogin</class>

<!-- Component specific Configuration - there is none -->

</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
{

WDK Authentication and Session Management 9

 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.

WDK Authentication and Session Management 10

 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 and Session Management 11