SPNEGO based Single sign-on (SSO) setup for Webtop

[update Aug 2, 2010] I just finished SSO solution to resolve the security issue with authentication plug-in. You may check it out.

[update June 13, 2010] I posted Security Consideration to resolve the security flaw due to the shortcut implemenation of authentication plug-in. Further details will come soon.

[update April 08, 2010] As Deniel pointed out in his comment, the setup has serious flaw, which would compromise the security of the repository. I will work on a solution to address it, hopefully soon.

Webtop has default setup that can be configured to support SSO using either RSA Access Manager(formerly known as ClearTrust) or using CA SiteMinder Policy Server. The Documentum download site for EMC RAS plug-in from Powerlink lists documents for how to setup SSO for Webtop. The following link presented a document about the setup using SiteMinder.
https://community.emc.com/servlet/JiveServlet/previewBody/3809-102-1-12177/Netegrity%20Configuration%20for%20Webtop.pdf.

While searching for Webtop SSO solutions, I also found out that IBM presented a solution using Tivoli Access Manager (http://www-01.ibm.com/support/docview.wss?uid=swg24007434).

Needless to say, all these SSO solutions need additional proprietary components (either RSA Access Manager, or CA SiteMinder Policy Server, or IBM Tivoli Access Manager) to make it happen. Here I will present a way to set up SSO for Webtop where no extra component is necessary. The approach is to rely on SPNEGO support from Internet Explorer or Firefox. The underlying authentication protocol is Kerberos. 

Environment

Even the solution presented here should be working with broader environments, the following is the system configuration I have been working with:

– Webtop 6.5 SP1 on Tomcat 6.0.18 under Windows 2003 SR2.
– Windows 2003 Server with Active Directory 2003
– JDK 1.6 used for Tomcat
– JRE 1.6+ used for IE or Firefox

Prerequisite

The only thing I can think of is that the users in Documentum repositories should have their login name set the same as their AD login name. How the users in Documentum were created was irrelevant here, and as long as they are not using inline password.

Preparation for the setup

As for understanding the basics about the approach, please implement the setup from the following two links (where each link has detailed explanation and references to other resources):

http://webmoli.com/2009/08/29/single-sign-on-in-java-platform/
http://spnego.sourceforge.net/spnego_tomcat.html

Please note when testing, the browser instance has to be on a different host other than the web server. That’s the requirement of Kerberos support from IE and Firefox. Configuration is also needed for the browser to support SPNEGO(see here).

After you have successfully run the above two samples, you may follow the following the steps to set up SSO for Webtop (actually the solution is an application of SpnegoHttpFilter, many setup already done will be re-used here):

Service Account

Make sure to get a service account from AD, say myssoaccount. Actually I was using the LDAP binding account that already exists for my Documentum setup. The account and its password will be used later. 

Service Principal Name 

The following commands are run to against the AD, which created the service principal names for the above service account (probably you need to ask your AD admin to do that for you):

setspn -a HTTP/mytomcatserver.mydomain.com myssoaccount 
setspn -a HTTP/mytomcatserver myssoaccount

SpnegoHttpFilter 

– Gets the source from SPNEGO SourceForge project

– Modify the implementation for SpnegoHttpFilter as following:

public void doFilter(ServletRequest request, ServletResponse response,
FilterChain chain) throws IOException, ServletException 
{
    HttpServletRequest httpRequest = (HttpServletRequest)request;
    // go through the negotiation process.
    SpnegoHttpServletResponse spnegoResponse =
         new SpnegoHttpServletResponse((HttpServletResponse)response);
    SpnegoPrincipal principal;
    try {
        principal = authenticator.authenticate(httpRequest, spnegoResponse);
    } catch(GSSException gsse) {
        LOGGER.severe((new StringBuilder("HTTP Authorization Header=")).append(
                   httpRequest.getHeader("Authorization")).toString());
        throw new ServletException(gsse);
    }
    if(spnegoResponse.isStatusSet()) {
        return;
    }
    if(principal == null) {
        LOGGER.severe("Principal was null.");
        spnegoResponse.setStatus(500, true);
        return;
    } else {
        LOGGER.fine((new StringBuilder("principal=")).append(principal).toString());
        // chain.doFilter(new SpnegoHttpServletRequest(httpRequest, principal), response); 
        HttpSession hs = httpRequest.getSession(); 
        if (hs != null) { 
            String principalAttr = "spnego_principal_"; 
            hs.setAttribute(principalAttr, principal); 
        } 
        chain.doFilter(request, response); 

        return;
    }

The reason to just modify the original source was for the purpose of simplicity. We could make a sub-class if class SpnegoHttpFilter were not defined as final class. Please note the hard-coded attribute name for SpnegoPrincipal spnego_principal_, which will be used later in the authentication scheme and could be a point to improve by using configuration parameter.

The compiled classes should be put under Webtop’s class path.

kbr5.conf

Create file kbr5.conf as the following:

[libdefaults]        
     default_realm = mydomain.com 
     default_tkt_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc  
     default_tgs_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc  
     permitted_enctypes   = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc
[realms]   = {
     kdc =  myactivedirectoryserverhost 
     default_domain = mydomain.com
}
[domain_realm]  
     .mydomain.com = mydomain.com

And put the file under Tomcat boot folder.

login.conf

create a file, login.conf with the following content:

spnego-client {  
     com.sun.security.auth.module.Krb5LoginModule required;
}; 

spnego-server {  
    com.sun.security.auth.module.Krb5LoginModule required  
    storeKey=true  
    isInitiator=false;
};

and put the file under Tomcat root folder.

web.xml for Webtop

Add the following section

   <filter>
       <filter-name>SpnegoHttpFilter</filter-name>
       <filter-class>net.sourceforge.spnego.SpnegoHttpFilter</filter-class>

       <init-param>
           <param-name>spnego.allow.basic</param-name>
           <param-value>true</param-value>
       </init-param>

       <init-param>
           <param-name>spnego.allow.localhost</param-name>
           <param-value>false</param-value>
       </init-param>

       <init-param>
           <param-name>spnego.allow.unsecure.basic</param-name>
           <param-value>true</param-value>
       </init-param>

       <init-param>
           <param-name>spnego.login.client.module</param-name>
           <param-value>spnego-client</param-value>
       </init-param>

       <init-param>
           <param-name>spnego.krb5.conf</param-name>
           <param-value>krb5.conf</param-value>
       </init-param>

       <init-param>
           <param-name>spnego.login.conf</param-name>
           <param-value>login.conf</param-value>
       </init-param>

       <init-param>
           <param-name>spnego.preauth.username</param-name>
           <param-value>your service account</param-value>
       </init-param>

       <init-param>
           <param-name>spnego.preauth.password</param-name>
           <param-value>password for your service account</param-value>
       </init-param>

       <init-param>
           <param-name>spnego.login.server.module</param-name>
           <param-value>spnego-server</param-value>
       </init-param>

       <init-param>
           <param-name>spnego.prompt.ntlm</param-name>
           <param-value>true</param-value>
       </init-param>

       <init-param>
           <param-name>spnego.logger.level</param-name>
           <param-value>1</param-value>
       </init-param>
   </filter>

before the following section in web.xml file

   <filter>
      <filter-name>WDKController</filter-name>
      <filter-class>com.documentum.web.env.WDKController</filter-class>
   </filter>

which would result in the SpnegoHttpFilter being called before the WDKController. The placeholders for account name and password should be replaced by the service account, myssoaccount and its password.

Also add the filter mapping to web.xml before the filter mapping for WDKController.

   <filter-mapping>
      <filter-name>SpnegoHttpFilter</filter-name>
      <url-pattern>/index.jsp</url-pattern>
      <dispatcher>REQUEST</dispatcher>
   </filter-mapping>

The  above initial parameter definition for SpnegoHttpFilter showed that NTLM and basic authentication are actually supported as well as Kerberos. When Kerberos support is not available (usually due to the browser configuration), it will fall back to NTLM, or then Basic authentication.  

MySSOAuthenticationSchema

Create a java class as the following and compile it. The class file needs to put under Webtop WEB-INF/classes folder. The package definition for the class can be anything you like. 

public class MySSOAuthenticationScheme implements IAuthenticationScheme 
{
    public SpnegoSSOAuthenticationScheme() {
        if(Trace.SESSION) {
             System.out.println(getClass().getName() + " starting ...");
         }
    }
    public String authenticate(HttpServletRequest httpservletrequest,
          HttpServletResponse httpservletresponse, String docbase) throws DfException 
    {
        String principalAttr = "spnego_principal_";
        HttpSession hs = httpservletrequest.getSession();
        SpnegoPrincipal spnego_principal = (SpnegoPrincipal)hs.getAttribute(principalAttr);
        String domain = null;
       String strUser = null;
       String s3 = "noop";
       if (spnego_principal == null) {
           return null;
       } else {
           String username[] = spnego_principal.getName().split("@", 2);
           strUser = username[0];
       } if (Trace.SESSION) {
           System.out.println("Trying to log in: " + strUser + " into " + docbase);
       }
       HttpSession httpsession = httpservletrequest.getSession();
       IAuthenticationService authservice = AuthenticationService.getService();
       String sTempDocbase = docbase;
       docbase = null;
       try {
           authservice.login(httpsession, sTempDocbase, strUser, getServiceLogin(s3), domain);
           docbase = sTempDocbase;
           if (Trace.SESSION) {
               System.out.println(getClass().getName() + " - Authentication succeed.");
           }
       } catch (DfException dfe) {
           docbase = null;
       }
       return docbase;
    }
    public String getLoginComponent(HttpServletRequest httpservletrequest,
       HttpServletResponse httpservletresponse, String s, ArgumentList argumentlist)
    {
       String principalAttr = CookieStringFinder.cookieString(httpservletrequest);
       HttpSession hs = httpservletrequest.getSession();
       SpnegoPrincipal spnego_principal = (SpnegoPrincipal)hs.getAttribute(principalAttr);
       if (spnego_principal == null) {
           if (Trace.SESSION) {
              System.out.println(getClass().getName() + " - null.");
           }
           return null;
       } else {
       if (Trace.SESSION) {
           System.out.println(getClass().getName() + " - sso_login .");
       }
       return "sso_login";
       }
    }
    private String getServiceLogin(String s)
    {
       StringBuffer stringbuffer = new StringBuffer(128);
       stringbuffer.append("DM_PLUGIN");
       stringbuffer.append("=");
       stringbuffer.append("myspnegossoauth");
       stringbuffer.append("/");
       stringbuffer.append(s);
       return stringbuffer.toString();
    }
    private static final String DM_PLUGIN = "DM_PLUGIN";
}

Please note the plug-in id was named as ‘myspnegossoauth’, which will be matched in the authentication plug-in definition for Content Server later. The hard-coded attribute name, spnego_principal_ was used to retrieve the SpnegoPrincipal in the scheme.

AuthenticationSchemes.properties

Update the properties file from Webtop installation under /WEB-INF/classes/com/documentum/web/formext/session/ as following:

scheme_class.1=com.documentum.web.formext.session.TicketedAuthenticationScheme
scheme_class.2=<the package name>.MySSOAuthenticationScheme
scheme_class.3=com.documentum.web.formext.session.RSASSOAuthenticationScheme
scheme_class.4=com.documentum.web.formext.session.SSOAuthenticationScheme
scheme_class.5=com.documentum.web.formext.session.UserPrincipalAuthenticationScheme
scheme_class.6=com.documentum.web.formext.session.SavedCredentialsAuthenticationScheme
scheme_class.7=com.documentum.web.formext.session.DocbaseLoginAuthenticationScheme

app.xml for Webtop

So far I have found out no changes to app.xml are necessary for the SSO setup to work. However, if you only have one repository, or want to use a different authentication service class, definitely you can do so by customizing the authentication section from the file.

Authentication plug-in

From your Content Server, make a backup of several files under $DM_HOME/install/external_apps/authplugins/sampleauth, such as sampleauth.cpp, sampleauth.so (sampleauth.dll if the CS is on Windows), and sampleauth.o.

Open file sampleauth.cpp and locate the line,

static const char pluginId[] = "sampleauth";

and change it to:

static const char pluginId[] = "myspnegossoauth";

The matching plug-in id to that from the authentication scheme would ensure that users would be validated by this plug-in.

In the same file, locate method dm_authenticate_user and make changes as the following:

  // Add the following two lines
dmTrace(traceEnabled, isTraceInitialized, traceFilePath, "Authentication-%s: ALWAYS Success.", userOsName);
return true;
// dmTrace(traceEnabled, isTraceInitialized, traceFilePath,
// "Authentication-%s: Failure. Unknown user or password", userOsName);
// dmSetProperty(outPropBag, DM_ERROR_MSG, "Sorry, I couldn't authenticate this user!");
// return false;

Yes, the changes would result in all the users who reach to this plug-in will be accepted by the plug-in. I will explain this later. Then compile the plug-in with available C++ compiler on your CS platform and set it up for the repository you want to run SSO. The CS administration guide provides details about how to implement authentication plug-in and how to set it up.

Internet Explorer and Firefox setup

The link SPNEGO SSO Browser configuration shows how to set up IE or Firefox to support SPNEGO.

For now, you should be able to make your Webtop SSO enabled. congratulations!

Further explanation

You may have noticed the authentication plug-in would accept any users. Is it a security concern? I would say No.
The SPNEGO protocol would make sure the users are trustworthy between Webtop server and the client (IE or Firefox). Only users who passed the security checking by SPNEGO with Kerberos (via KDC from the setup) will reach the authentication plug-in. The following is an exception for an user login from docbase log (the timestamp for each line was removed for clarity. Space lines were added as well):

.. AT 61102: Start-AuthenticateUser: ClientHost(), LogonName(myuserloginname),
   LogonOSName(SYSTEM), LogonOSDomain(), UserExtraDomain(), ServerDomain()

.. AT 61102: Start-AuthenticateUserName:
.. AT 61102: dmResolveNamesForCredentials: auth_protocol()
.. AT 61102: End-AuthenticateUserName: dm_user.user_login_domain(myldapconfigname)
.. AT 61102: success
.. AT 61102: Found dm_user.user_login_name(myuserloginname),
    dm_user.user_login_domain(myldapconfigname)

.. AT 61102: Start-AuthenticateDomain:LogonName(myuserloginname),
    UserExtraDomain(), auth_protocol()
.. AT 61102: AuthenticateDomain - no domain required:domainOverride(False),
    user_login_domain(myldapconfigname), serverAuthTarget(), userAuthTarget()
.. AT 61102: End-AuthenticateDomain:
.. AT 61102: success

.. AT 61102: Start-AuthenticateUserState:UserLoginName(myuserloginname), UserExtraDomain()

.. AT 61102: Start-AuthenticateUserState:
.. AT 61102: dmStateForUser: auth_protocol()
.. AT 61102: End-AuthenticateUserState:
.. AT 61102: success

.. AT 61102: Start-AuthenticateByTrust:OSLogonName(SYSTEM),
    UserLoginName(myuserloginname), OSLogonDomain(), UserExtraDomain()
.. AT 61102: End-AuthenticateByTrust:
.. AT 61102: failure

.. AT 61102: Start-AuthenticateByPassword:UserLoginName(myuserloginname), UserExtraDomain()

.. AT 61102: Start-authenticateByPlugin: UserLogonName(myuserloginname), PluginId(myspnegossoauth)
.. AT 61102: End-authenticateByPlugin:
.. AT 61102: success

.. AT 61102: End-AuthenticateByPassword:
.. AT 61102: success

.. AT 61102: Final Auth Result=T, LOGON_NAME=myuserloginname, AUTHENTICATION_LEVEL=8,
OS_LOGON_NAME=SYSTEM, OS_LOGON_DOMAIN=,CLIENT_HOST_NAME=,
CLIENT_HOST_ADDR=xx.xxx.x.x, USER_LOGON_NAME_RESOLVED=1, AUTHENTICATION_ONLY=0,
userID=xxxx xxxx xxxx xxxx, USER_NAME=My User Name, USER_OS_NAME=myuserloginname,
USER_LOGIN_NAME=myuserloginname, USER_LOGIN_DOMAIN=myldapconfigname,
USER_EXTRA_CREDENTIAL[0]=, USER_EXTRA_CREDENTIAL[1]=, USER_EXTRA_CREDENTIAL[2]=F,
USER_EXTRA_CREDENTIAL[3]=, USER_EXTRA_CREDENTIAL[4]=, USER_EXTRA_CREDENTIAL[5]=T

The user authentication log shows there are several steps for an user to be authenticated to a repository:

– First of all, the user has to be existing in the repository.

– Secondly the user domain is checked (I guess this step would branch into different path based on user’s setup method, i.e. inline password, LDAP authentication, or authentication plug-in, and so on).

– Then the user state is checked.

– And then the trusted login is tried with the user. Usually it would fail unless the user is the installation owner.

– Lastly, the user is checked with his/her login credential.

From the log, only the last step would involve the authentication plug-in when necessary. Apparently the Content Server employes other means to make sure the user has to pass the previous several steps to reach the last checking.

During my testing, only a valid user would be able to reach the last step where the plug-in is being called to verify the user. Since the SPNEGO protocol has made sure the user is from our trusted domain, it will be safe for our authentication plug-in to accept anyone who has ‘entitled’ with the ‘myspngossoauth’ identifier and come this far.

Hopefully I have clearly stated the necessary steps to implement the SSO solution. Please leave your questions or comments if you run into any issues.

Disclaimer:
This document and the information contained herein are provided on an “AS IS” basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY) DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Tags: Administrator, Documentum, Kerberos, SSO, Webtop