CAS SSO FOR EMC DOCUMENTUM REST SERVICES
Contents
1. sas E savas usa to state oe Users po oer SES spre so mt o And from Firebug you can find that the browser is using the DOCUMENTUM CLIENT TOKEN to authenticate the user bae enasna ender m p These snapshots demonstrate an intuitive way to trouble the CAS SSO on the client side Conclusion This paper explains the architecture of CAS and how CAS SSO can be enabled in Documentum REST Sewices For further information on CAS protocol and configuration please refer to the jasig CAS project site For feature requests and successful stores on the Documentum REST Services please contract EMC product manager for Documentum REST Services for further information on the CAS SSO integration for Documentum REST Services please contact support References EMC Support hto support eme com Documentum Platform REST Services 7 1 Development Guide Documentum Platform REST Services 7 1 Release Notes Documentum Content Server 7 1 Administration and Configuration Guide c DOCUMENTUM CONTENT SERVER CENTRAL AUTHENTICATION SERVICE CAS 550 A Detailed Review CAS project site http w jasig ong cas CAS User Manual Wiki hitps viki jasig org display CASUM Home CAS RESTful API htips wiki jasig org display CASUM RESTfulsAPI CAS LDAP https wiki jasig org display CASU2. 6 in browser SSO flow and for the same Step 7 in non browser SSO flow As mentioned in the CAS SSO the authentication from the REST server to Content Server is using CAS proxy The CAS proxy requires callback to complete the PGT negotiation The diagram below illustrates how a PGT is obtained during the ST validation This happens between the REST server and CAS server and is totally opaque to the user client Figure 5 Proxy Negotiation between REST Server and CAS Server Step 1 The REST server calls the CAS server to validate the ST sent by the user client and it asks to callback the PGT for instance Step 2 Prior to responding the validation request the CAS server makes a callback to passing PGTIOU and PGT in the URI parameters AUTHENTI FOR EMC DOCUME The callback service responds to the CAS server with OK status Typically the callback service is implemented within the REST server and it saves the PGTIOU and PGT mapping a local storage Step 4 The CAS server responds to the initial ST validation request and additionally sends back a PGTIOU token in the response Step 5 The REST server looks for the exact PGT from callback service storage using the PGTIOU as the key Step 6 The REST server calls the CAS server to get a PT for Content Server access by passing the PGT Step 7 The CAS server responds with a PT With the PT the REST server is able to logi
3. Here we show samples about how to import the LT keys between two repositories By default client tokens are encrypted by the RSA SafelCE provider To support flexible security options Documentum REST Services allows the use of different cryptography algorithms to encrypt and decrypt CTs All options are available in the restapi runtime properties file Currently we support two crypto providers dsafelCE RSA provider the default provider BC Bouncy Castle provider the altemate provides The default crypto algorithm is AES128 It DESede RCS etc ould be changed to other algorithms like Note The default cryptography algorithms used for the client token encryption and decryption are strong enough in most cases Therefore we recommend keeping the original settings unless special security requirements are required for your organization It s strongly recommended to consult your security department and EMC Support to make crypto changes for the CT token The crypto key size and block size can be changed too but please make sure it meets the requirement of specific crypto algorithm Also please note that the default version of Java Cryptography Extension ICE policy files bundled in the environment limits the key size of cryptography algorithms to 128 bits To remove this restriction download Unlimited Strength Jurisdiction Policy Files from the Oracle web site The default security provider w
4. INF Classes rest api runtime properties Open the file edit it and repackage the war rest security auth mode The authentication mode should be ct cas which stands for CAS SSO With this mode the basic authentication for inline users is disabled There is another option that enables both HTTP Basic and CAS modes which will be introduced in section Multiple Authentication Schemes The CAS server related URLs point tothe host of the CAS server These include restsecuriy cas serverurl restsecuriy cas serverioginnt restsecuniy cas serverlogout ur restsecuy cas serventcketsun rest secuiy cas prony service The proxy service is ContentServer which has been registered in CAS service registry It can be changed but we do not recommend doing that unless separate proxy services need to be configured for multiple Content Server instances rest security server The server URL is the REST server s host and port mapping which is used by the CAS client agent to construct the redirecting back resource URLS rest security cas caliback service url The CAS callback service URL points to the REST server s CAS proxy callback service Documentum REST Services has default implementation of the callback service so it s painted to the REST server s root context URL If the customers are familiar with CCAS Java client and Spring MVC they can build their custom CAS callback service and PGTIOU PGT mapping storage rest securlty auth cas cli
5. SSO again Login Ticket A ticket produced by Content Server to act as temporary password for an authenticated user Secure Sockets Layer 55 SSL is a cryptographic protocol which is designed to provide communication security over the Internet Jasig A consortium of educational institutions and commercial affiliates sponsoring open source software projects for higher education including the CAS implementation The website is http www Jasig org Ehcache An open source standards based cache for boosting performance offloading your database and simplifying scalability The website is http ehcache org CENTRAL AUTHENTICATI FOR EMC DOCUME Part I CAS Feature Overview CAS Architecture CAS is a single sign on protocol for the web purpose is to permit a user to access multiple applications while providing their credentials such as userid and password only ance The CAS protocol involves at least three parties t web browser the web application requesting authentication called CAS Service the CAS server It may also involve a back end service called CAS Target such as a database server that does not have its own HTTP interface but communicates with a web application There are several open source CAS server implementations for the CAS protocol The Jasig CAS server is the most widely adopted by the industry In Documentum REST Services the CAS serv
6. an optimized approach which enables the users to follow the CAS authentication workflow only for once and then use an authenticated token to access resource subsequently Please refer to CAS Integration with Documentum REST Services for details CAS Extensions and Support The CAS 550 provides an authentication framework and it can be integrated with other authentication schemes like LDAP authentication Kerberos SSO SAML SSO and on Therefore once CAS has been integrated to a web application it can do more than simple centralized authentication In Documentum REST Services we provide the basic capability af CAS SSO for the REST Services Moreover customers also have the option to integrate the CAS SSO with other authentication Schemes Please refer to Jasig community for extending the authentication schemes for your system In the CAS deployment required by Documentum REST Services several CAS server extensions are required to be installed CAS server integration with Ehcache CAS server integration with Restlet CAS server suppor far generic CAS server support for LDAP All these extensions are open source software and can be downloaded from the open Maven repository The details will be illustrated in the section Obtaining CAS ServerBinary There are a number of ways to find support for CAS authentication please refer to http wweijasig org jasig support for help CAS Integration with Documentum REST Services Architec
7. for proxy callback mandatory in HTTPS so go to the REST server and import it to the REST servers JRE trust store Obtaining CAS Server Binary The CAS server is an open source project it can be download from Jasig source repository However jasi doesn t publish the CAS server binary directly instead it allows downloading the java source code for CAS server and lets the users to build it by themselves Step 2 Go to download center of Jasig CAS project htip Jwww jasig org cas download and download CAS Server 3 5 2 Release Step 2 Prior to building please install Java 6 and Maven 2 in your local machine Go to their websites to download and install them CENTRAL AUTHENTI FOR EMC DOCUME Maven After installation set both Java and Maven bin path into the system environment variable Step 3 The CAS deployment for Documentum REST Services requires some additional extensions to be installed in the CAS server So before building the CAS WAR file unzip the downloaded CAS in local file system and add the following elements within he dependencies element of the root pom xml peas server support idape arfactid Step 4 After building the WAR file the next step is to configure and build the CAS server The precedence can be changed In this sample we will configure the CAS server after building The CAS server can also be configured firstly prior to the build using the technology of MAV
8. AS 550 for Documentum REST Services es Step 1 An non browser client visits a Documentum REST resource for instance http restserver 8080 dctm rest repositories acme01 Step 2 The REST server sends back a response based on the client redirecting preference If the client request has set an header DOCUMENTUM NO CAS REDIRECT trve REST server returns 401 with the CAS RESTful login URL AUTHENTICATI FOR EMC DOCUME Otherwise REST server just retums 302 for redirecting same to the browser client fly Step 3 The non browser client gets the login URI for CAS RESTful API from the response Location header and posts to CAS server to get TGT for instance Step 4 The CAS server validates the user against the directory service or other identity provider Step 5 The CAS server returns back a TGT resource location for instance With this location the non browser client posts to CAS server to get ST for the specific resource URI for instance Note that URL encoding is required for the service URL in the request body CAS server tums the ST directly in its response Step 6 The non browser client posts to the REST server to consume the resource with ST appended as query parameter for instance M The rest of the flow is exactly the same as browser client flow seeing browser client flow from Steps 6 to Step 13 CAS Proxy Negotiation This section describes Step
9. Content Server to validate the user distinguished name Step 10 Content Server creates a session for user halbert and generates a ticket the client will be able to use for subsequent call Step 11 The REST server sends actual operations to Content Server using the established Step 12 Content Server retums operation results to the REST server Step 13 The REST server returns results to the browser client including a DOCUMENTUM CLIENT TOKEN cookie for future resource access for instance The REST server calls Content Server passing the taken credentials then retums the result as resource response for instance The redirecting mechanism does not make much sense in many scenarios For instance non browser clients may not have the built in ability to actually handle URL redirects the redirected CAS login URL is pointed to an HTML form page which is aimed for human being interaction and some browser clients i e widgets in mash ups may never reach the intended caller with 302 HTTP code For all above scenarios the altemative approach that authenticating clients to CAS with pure RESTful API is more promising We leverage the CAS RESTful API to achieve the CAS mon browser client The introduction for CAS RESTful API can be found on ki t requires the CAS deployment to include extension cas seerintegrationrestler Here is ihe authentication flow for non browser CAS 550 Figure 4 Non browser Client C
10. DAP server immediately Step 7 It s better to start a job to synchronize the LDAP periodically UTHENTICATION SERI FOR EMC DOCU Enabling CAS SSO Plugin Step 1 Navigate to the Content Server installation directory and find the CAS plugin DLL file cas auth dl Typically it s located at Documentum product 7 1 nstalllexternal appslauthpluginsiCentralAuthentication Service Step 2 Copy it to the target directory Documentumldbalauth Step 3 Create an empty dm cas auth following entries i file under the same directory and fil in the MOM sete Phe dona or hast whieh Js used in connecting to CAs server sar nte for cas servar r s aoe tn gp remet sem to cas server to ved ma eich Service name for which the ticket was generated RUE acier specify rep canmaccton be done over heras cd The server hostand server portare forthe CAS server deployment The url path is defined by CAS servlet mapping Typically It s not required to change the path The service param specifies the proxy service name for Content Server It has to be registered in CAS service registry Use this value consistently across the CAS server REST server and Content Server The value is not necessary to be changed unless separate proxies have been configured for multiple Content Server instances Step 4 Restart the repository Validating Content Server Configuration Check the
11. EN2 WAR overlay For the latter please refer Step 5 Run the command myn clean install DskipTests true And the cas serverwebapp 3 5 2 warfile is generated under the following directory Icasssener 5 2lcas serverwebappVMarget Configuring CAS RESTful The CAS RESTful API is used by non browser clients Update the file cas server webapp 3 5 2 war WEB INF web xm by adding the following elements Configuring CAS Properties The cas properties file is located in cas server webapp 3 5 2 war WEB INFY This file contains the basic settings for the CAS server Update server name and hast name according to the corresponding instructions CENTRAL AUTHENTICATI FOR EMC DOCUMENTI The CAS LDAP mapping is configured at cas serverwebapp 3 5 2 war INF deployerConfigContextxml Add the following element in the bean of credentia sToPrincipalResalvers This bean resolves CAS credentials to LDAP user attributes during login attempts other rsohes beans here Please note that the values highlighted in red are specific to Microsoft Active Directory For other LDAP servers the values could be different The same assumption applies to other samples in this section Add the following element in the bean of authenticationHandlers This bean resolves the LDAP user binding for CAS authenticating users Add the following element in the root This bean configures the connection from the CAS serve
12. M LDAP CAS Services Management hiips wiki jasig org display CASUM Services Management CAS Cluster https wiki jasig org display CASUM Clustering CAS Ehcache Replicatior http ehcache org documentation replication
13. Policy NeverExpiresExpirati onPolicy Sr os CASSewer MuliTimeUseOrfime NeverExpiresExpi Sever REST Sever outExpirationPolicy rationPolicy REST Client 10 seconds PGT CAS je CASSever Sameto TGT Same to TET Server REST sever Pr CAS CASSever SameTo ST Same to ST Sever J REST Sewer Content Server CT REST REST Sewer HardTimeoutExpirati TouchedTimeout cookie Sever REST Client onPolicy ExpirationPolicy TouchedTimeouttxpi 3600 seconds rationPolicy TolerantTimeoutExpi rationPolicy Tr Content e Content Tntemally controlled nterally Server Server GT controlled by CT REST Sever REST Client Upon the CAS authentication flow ST and PT tokens are used for only once It is assumed that the user client or the REST server regarding to PT sends the ST token for validation immediately after obtaining the token As a result the ST token has very short lifetime The TGT token is held by the user client for a relatively long period to request multiple STs upon on demand requests so it has much longer living time The PGT token is used internally by the REST server to request PTs so it does not affect the end user interactions The CT cookie is held by the user client to access on demand REST resources so it has a relatively longer living time too The LT token s validness is controlled by the CT token so it has no impact to the end user For the robust security configuration the
14. White Paper CENTRAL AUTHENTICATION SERVICE CAS SSO FOR EMC DOCUMENTUM REST SERVICES Abstract This white paper provides a detailed review of Central Authentication Service CAS SSO integration with EMC Documentum REST Services by exploring the architecture and consumption workflow the deployment recommendations and altematives and the troubleshooting for this integration January 2014 Copyright 2014 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 fora particular purpose Use copying and distribution of any EMC software described in this publication requires an applicable software license For the most up to date listing of EMC product names see EMC Corporation Trademarks on EMC com Part Number 12766 Table of Contents Executive summary Audience Terminology Parti CAS Feature Overview CAS Architecture Basic Authentication Flow Proxy Authentication CAS Extensions and Support CAS integration with Documentum REST Services Architecture Overvie Browser CAS SSO Walkthrough Non browse
15. allcas lt cookie called CASTGC is set back to the user client which is essentially a Ter The ST is used only once but the TGT can be reused to represent one authenticated user When the user client attempts to access another web resource the CASTGC cookie is reused to request a new ST without needing to provide the user credential again as long as the CASTGC is not expired The TGT is held by the user client and remains private between the user client and CAS server It will nat be sent to the web application Step 6 The web application validates the request Specifically it obtains the ticker parameter from the request URI and validates it to the CAS server Same to Step 2 this is usually done by a CAS client agent in the web application Step 7 The CAS Server returns the validation success response The CAS server may additionally retum some user attributes after the validation so that the web CENTRAL AUTHENTICATI FOR EMC DOCUMENTU application can make access control for the web resources based on the user attributes Step 8 Web application retums the web resource to the user client Proxy Authentication As Documentum REST Services is a multilayer system it uses CAS proxy authentication to achieve Single Sign on multi tier CAS installation an agent acting on behalf of a user but without direct access to the user s cookie cache may need to convince a third party that it represents the u
16. ce for which the CAS has been enabled Enter the URL in the address bar of your web browser Attp rest server 8443 dctm rest repositories acme01 Now the browser client will be redirected to the CAS server login UNICI UE TIE Enter your Username and Password mote Please note the redirected URL that the original Repository resource URL is appended service parameter to the CAS login URL Now please enter the user name and password The browser will be redirected back to the original Repository resource after a successful CAS login Fee doer nat the ns formats xane wih pee eno Please note the redirected URL that a ST is appended to it in parameter ticket which was sent by CAS Please note that an ST which is sent from the CAS server appended to the redirected URL in the ticket parameter With these steps the CAS 550 for Documentum REST Services has been working UTHENTIC FOR EMC DOCU Advanced CAS Integration Options This chapter introduces some advanced deployment options for the Documentum REST Services with CAS SSO Multiple Authentication Schemes Documentum REST Services allows for multiple authentication schemes in your production environments Various combinations of authentication schemes are configured by modifying rest securty auth mode in the restapi untime pro
17. ent pg storage The CAS PGT storage supports two modes inmemory and ehcache in memory is the default mode and is used for single REST server deployment If customers deploy cluster environment for REST services the mode needs to be changed to Ehcache Section REST Server Clustering for CAS will discuss more details about it Validating REST Deployment After the WAR file has been configured and deployed restart the web container By default if the logging level is INFO the following entry is visible in the startup logs Then try to access the Documentum REST service via a web browser Step 1 Verify home document resource CENTRAL AUTHENTICATION FOR EMC DOCUMENTU Enter the URL in the address bar or your web browser http rest server8443 detm rest EMC Documentum REST Services MC Dosa MEST Soetens ots os a pare one hee meren te rman Sonat This step confirms the REST services is running Step 2 Verify Repositories resource Enter the URL in the address bar or your web browser ht rest server 8443 dctm rest repositories Bins eom reticere p mb UTHENTIC FOR EMC DOCU This step confirms the DFC docbroker is working Step 3 Verify Repository resource The two resources above are for anonymous access and do not meet any CAS login challenge Now try with the Repository resour
18. eplace the existing SSO with CAS for the usage of Documentum REST Services instead CAS can be integrated into the existing security infrastructure to achieve the enterprise SSO CAS can be even integrated into federation security to meet the requirement of cloud enablement We will explore the possibilities of the CAS extensions for Documentum REST Services in separate documentation CENTRAL AUTHENTI FOR EMC DOCUME Part Il CAS Configuration and Troubleshooting CAS Server Configuration Preliminaries Documentum REST Services 7 1 supports CAS Server version 3 5 2 The CAS server is deployed in a Java web container as a WAR file it must be installed within a web container such as Tomcat JBoss etc The ticket validation of CAS requires HTTPS so iis required to enable SSL for the web container as well For the formal product implementation you need to register the SSL certificate to an authority For the quick startup create a certificate for your web container with any of the following tools For instance use Java keytool http does oracle com javase 6 dacs technotes taals solaris keytool htm Openssl iip waw openssiorg any other certificate tool ike Portecle hiip portecle saurceforge net to produce a certificate for the web container After the certificate generation import it to the IRE keystore of the CAS server with following command addition to that a s certificate must be truste REST server
19. er we talk about is referring to the Jasig CAS Sever implementation The lasig CAS is designed as a standalone Java web application tips www jasig org cas There are also a number of CAS clients developed to facilitate web applications to complete the CAS authentication Basic Authentication Flow this section we go through the basic authentication flow of the CAS SSO From the flow we will get the basic idea of the CAS SSO Figure 1 Basic CAS Authentication Flow lease Teds ec returne Step 1 The end user client requests the URI of a web application The web application leverages CAS server io provide the authentication service Under these assumptions the client comes to access a specific web resource on the web server eg http web app about me Step 2 1f the web application checks the request and finds no CAS tickets along with the request it will redirect the request to a CAS login URI The request URI is typically validated by a CAS client agent e g a Spring Security filte which is deployed in the same context as the web application The CAS client agent redirects the end user request to the CAS server login This redirection also occurs when CAS ticket for the request is not valid Please see Step 5 to know what a valid request URI looks like The redirecting URI must contain service parameter whose value is the original web resource URI This is impo
20. erver sends a PGTIOU PGT mapping to the callback URI which is specified by the web application The web application needs to have storage to save the PGTIOU PGT mapping Step 8 After the callback succeeds the CAS server then responds to the validation request by Step 6 In the validation response the CAS server tells the web application a PGTIOU token The web application is responsible to go to the PGTIOU PGT mapping storage to lookup the PGT based on the input af the PGTIOU Step 9 The web application requests a PT for the Back end Server access using the obtained PGT Step 10 The CAS server validates the PGT and returns a PT to the web application Similarly as the web application the back end server must be registered as a CAS service to enable the proxied authentication Step 11 The web application visits the back end sever with the PT Step 12 The back end server validates the PT to the CAS server Step 13 The CAS server retums the proxy validation responses to the back end Step 14 The back end server returns the user session to the web application Step 15 UTHENTICATION OR EMC DOCUMENTU The web application then uses the session to operate the abject and returns the web resource to the user client The CAS proxy authentication is adopted by Documentum REST Services far its CAS 3550 There are many requited steps to complete the CAS SSO thus in Documentum REST Services we have introduced
21. ing and Troubleshooting The CAS S50 for Documentum REST Services involves multiple parties so it s necessary to collect logs from all paries to get a thorough analysis Basically logs need to be collected from these servers Content Server REST server CAS server Cluster f any LDAP server optional Content Server Logging The authentication related logs can be found in the repository log files typically located Documentum dba log repository namelog and Documentumldba iog Am itor To get the full tracing logs please enable Content Server tracings by adding otrace authentication in the repository service script When the CAS authe the following will be generated in dm cas repository name log as And more log information for the successful authentication will be obtained from repository names logas The REST sewer logging is configured in both detmrrest warlWEB IWF classes ogdjproperties and dctmvrest warlWEB INFlclasses rest api runtime properties In log jproperties file please enable tracing level logging for the following Java packages The log file will be found at the location as specified by ag4 appenderR File in ogaj properties CAS server logging is configured by the cas war WEB INF classes ogaj properties file Please enable debugging level logging for the following Java packages param name Jon Pattern values 3a pe It is also he
22. lpful to capture the HTTP access logs for the web container For instance for Tomcat server it can be configured in ctomcap canflserv Then HTTP access logs can be found in ctomcabllags Vocalhost access log txt the CAS server it is strongly recommended dumping all the CAS configuration files for thorough analyze including casar WEB NF cas properties cas war WEB INF web xml cas wat WEB INF deployerConfigContext xml cas wat WEB INF viewisp protocol 2 0 casServiceValidaitonSuccess isp cas wat WEB INF spring configuration ticketRegisty xml cas mar WEB INF classes ehcache replicated xml REST Server Troubleshooting Here are general steps to verify the deployment of REST server Review all settings in the rest api untime properties file SSLis required to be setup for the Web Container Please refer to container documentation for the SSL setting up If the error message contains PAIX path building failed it is usually caused by invalid SSL setting Enable INFO DEBUG TRACE logging level Check the server startup log The following log will be seen for the successful CAS SSO start Authentication mode is set to c cas for the Documentum Core REST Services AUTHENTICATI FOR EMC DOCUME Verify home document resource For instance https rest 8443 dctm rest services should return the resource representation of home dacument anonymous access Please make sure the Content Server c
23. modifications In cas warlWEB INFlspring configuration ticketRegisty xml set shared of the The default Ehcache configuration recommends setting TGT PGT replication in async mode However in RESTful Services an ST PT ticket request may happen immediately after the TGT PGT generation in milliseconds Therefore it is strongly recommended using sync mode for both ST and TGT replications To make the CAS ticket replication work enable the cache replication engine from IWEB INFlclasseslehcache replicated aml Here is the example of RMI Ehcache site provides options for cache replication n and http RMI Multicast Peer Discovery Here is a sample configuration in the ehcache replicated file to set automatic peer discovery using the same RMI protocol apdsteChec taise JGroup Peer Discovery Here is a sample of JGroup cache replication To use Group please update configurations in both ticketRegistry xmland ehcache replicated xml In ticketfegistry xm Performance Consideration The CAS clustering and CAS ticket replication is outofbox functionality which is provided by 3rd party libraries In REST deployment customers have the choice to use CAS ticket replication implementation However the replicate method of RMI manual discovery is found not performing well when some REST servers were down EMC engineering test shows that Group and RMI multicast has better performance Logg
24. mple of RMI manual peer discovery It can be changed to other replication methods like JMS or Group To get more options please refer to http ehcache org dacumentation replication Performance Consideration The replication of PGT IOU PGT mappings across the whole cluster may degrade performance especially when the number of REST server is large In this case create child cluster behind a reverse proxy server and limit the replication of PGT IOU PGT mappings within the child cluster Next designate the child cluster to handle PGT callbacks This method reduces the amount of replication and thus improves performance The following diagram illustrates the network topology of this method Figure Setup Sub Group for PGT Storage This method requires the following configurations For all REST servers in the parent cluster the callback URL must be set to the address of the reverse proxy server that is placed in front of the child cluster the diagram Reverse Proxy Server 2 Peer discovery for all REST servers must be configured in the child cluster in which all these REST servers must be set as peers The CAS authentication can be deployed in a clustered environment to achieve high availability HA Please the instructions on Jasig wiki to configure CAS clustering AS if CAS clustering utilizes Ehcache to make all nodes in the cluster recognize and validate each other s tickets make the following
25. n IE poop Phe cns Sates aque ear m T TS Miam Set tases Mech 0 6 1 WDA c 22 0 Secto ZO1E9I01 Firatox 22 0 UTHENTICATION OR EMC DOCUMENTUM R hen enter the LDAP user name and password Finally the repository resource is returned aepo po deep ACMED CORD pe rari embspce pear 1000 008 Wit SC rti prd nk ep denis ec Meets 0 s And at the back end further activities from Firebug are tracked Ta Guns ors sa nor E If we look at the details the first request posts the user credentials to the CAS server and the CAS server redirects the web browser to the REST repository resource in its response In addition a CASTGC cookie is sent back UTHENTICATION OR EMC DOCUMENTUM R Tae ICT SAU ee RCE our The next request reaches the REST server In the resource response new DOCUMENTUN CLIENT TOKEN cookie is set back to the web browser hast ages and mel 28 Me Hoe Mm ed um madera eee If another resource is accessed immediately after that in the same browser the resource is accessible without entering credentials again For instance access hitps rest server detm test repositories acmed1 users t 8
26. n to Content Serv The purpose of producing a CT is to provide an authenticated REST client with temporary and expirable token to access the REST server without a need to negotiate new session ticket The CT cookie has no session state stored the REST serve Therefore it works in cluster environment as well It contains an encrypted Documentum login ticket LT and additional metadata used for further pass through authentication A CT cookie is encrypted and validated by the REST server The REST client is not expected in any means to persist or decrypt the token A validation failure of the CT cookie leads to CAS authentication failure The CT is expirable and we expose two options in rest api untime properties to set the timeout fora CT cookie restsecurity clienttoken timeout It s the expiration forthe CT n seconds The default is 3600 rest security client token expiration policy The use ofthe policy is explained in below table Table 2 Expiration Policy of Client Token Policy Description com eme documentum r The client token expires after a specified duration est security ticket impLH ardTimeoutExpirationPol If the REST client sends a request before the duration y the REST server accepts the client token If the REST client sends a request after the duration the REST server rejects the client token and the client has to authenticate again com emc documentum r The client token ex
27. nectivity Please use a web browser to verify that the REST server can be reached from the CAS Server For instance enter this URL in a browser Attps rest 8443 dctm rest cas proxy receptorand a blank page will be returned not an error page Client Side Troubleshooting On the client side it s useful to use a web browser to test the CAS 550 Almost all latest versions of web browsers have the inspector plugins or development mode It s easy to use such kind of plugins to test the CAS 550 workflow on the client side Here is the snapshot for Firefox 22 0 test using the Firebug addon http getfirebug com Step 1 Redirect from resource URL to CAS login URL Enter https rest server dctm rest rep ies acme01 in the browser address bar and your browser is redirected to the URL of Attps cas server cas login senice https 3A 2F 2Frestserver 2Fdcim rest 2frepositories 2Facme01 m gt Bee _JASIG Enter your Username and Password temi betore E EI At the backend the activities from Firebug show the detail of the HTTP layer interactions And for each HTTP access there is detailed information Get the repository resource URL umm TENEO serene etm mpm Navigate to the CAS login page ege MN Tes 92180848 Params Heaters Response Cache HIM Coles tes Tne 07 a
28. onnectivity is good Review all settings in the dc properties file Verify repositories resource is available For instance https rest 8443 dctm rest repositories should retum the repository feed anonymous access Please also make sure the CAS server connectivity is good Verify the CAS server can be reached from the REST server For instance ty _https cas 8443 cas serviceValidaterticket Faked Aservice http localhost Jt is expected to get an error XML page Content Server Troubleshooting First of all it s necessary to verify that the CAS SSO plugin for Content Server has been enabled and loaded successfully For any failure related to the plugin please review all settings in dm cas auth iniand tracing logs in DOCUMENTUM dba log Then please verify that the LDAP server configuration for each repository has been setup correctly For any user authentication failure please review the LDAP configuration using Documentum Administrator and check whether LDAP users are synchronized to the repository with the right user source and the right distinguished name attribute Thirdly please verify that the CAS server can be reached using web browser For instance enter https cas 8443 cas proxyValidate ticket Faked amp service ContentServer and it is expected to get the error XML page For more information abaut Content Server troubleshooting please refer to the white paper Documentum Content Server Central Authen
29. orks RPS140 MODE http Jesrcistgov groups STM emvp standards hm To support security compatibility for specific environment the provider may have to be run in NON_FIPS140_MODDE Note One known issue about FIPS140 is for IBM WebSphere Server that it can be run only in NON 5140 MODE So make sure to change the mode to NON FIPS140 for the REST server deployment in WebSphere to support CAS 550 REST Server Clustering for CAS REST servers can be deplayed in a clustered environment where there usually has reverse proxy server deployed in front To deploy REST server clustering perform the following steps Step 1 Update the key salt to a non empty value in all restapi runtime properties files AUTHENTICATI FOR EMC DOCUME Step 2 Update the PGT storage type to ehcachein all restapi runtime properties make a callback to the REST server rt REST servers are deployed cluster the callback may nat find the REST server requesting the PGT Therefore REST servers must maintain the same PGT IDU PGT mappings To do this REST servers utilizes Ehcache to perform the replication of PGT IOU PGT mappings across the cluster When using ehcache storage configure the dctm rest warlWEB INFlclasses ehcache casxmlfile _stnoNamespaceSch sd updatecheck alse gt The host names and ports for this REST server and other REST servers in this XML file must be updated Please note that this sample gives an exa
30. perties flle The following CAS related combinations of authentication schemes are supported HTTP Basic and CAS with client tokens rest security auth mode basicctcas CAS with client tokens rest securi auth mode ct cas The following diagram illustrates the workflow of authentication when a request comes to access a resource where both HTTP Basic and CAS are working Figure 7 Basic and CAS Authentication Work Together Here we show samples of REST messages for multi authentication schemes Example 1 No Authorization header CENTRAL AUTHENTICATI FOR EMC DOCUMENTI code t GENERAL AUTHENTICATION ERROR GET resource urticket ST 29 HelcS6dMorTrZnLBPZe badcredentia DOCUMENUM AC CAS REDIRECT false ponse CAS plugin is enabled per repository To enable CAS SSO for tiple repositories perform following actions Configure the LDAP server for each repository Enable the CAS SSO plugin for each repository Configure repository trust The trust relationship setup for Content Sever repositories can be found in Content Server Administration Guide The reason to require trust across repositories is because the CT cookie is depending on the Documentum Login Ticket LT and the LT is by default private to one repository To make the CT cookie usable for all repositories please setup trust across these repositories The trust acrass multiple repositories can be setup using DFC API
31. pires after two times of the specified est security ticket impl T duration The REST server issues new client tokens olerantTimeoutExpiration under certain conditions For details see the following Policy default Ifthe REST client sends a request before the duration the REST server accepts the client token Ifthe REST client sends a request after the duration and before two times of the duration the REST server accepts the client token and issues another client token with the same duration to the client for subsequent requests Ifthe REST client sends a request after two times of the duration comes to an end the REST server rejects the client token and the client has to authenticate again com emc documentum r The client token expires after a specified duration The est security ticketimpLT REST server issues new client tokens under certain auchedTimeoutExpiratio_ conditions Far details see the following CENTRAL AUTHENTICATION FOR EMC DOCUMENTU Policy Ifthe REST client sends a request before the duration the REST server accepts the client token and issues another client token with the same duration to the client for subsequent requests Ifthe REST client sends a request after the duration the REST server rejects the client token and the client has to authenticate again The CT cookie is encrypted with cryptography algorithms Users can choose different c
32. r CAS SSO Walkthrough CAS Proxy Negotiation Using Client Token Managing Timeout fr Toke Producer anita Timeout Policy Default Single Sign out Future Possibilities Obtaining CAS Server Binary Configuring CAS RESTIuL Configuring CAS Properties Configuring LDAP mapping Configuring Service Registry Customizing CAS Proxy Response Validating CAS Deployment Content Server Configuration Preliminaries Enabling CAS SSO Plugin Validating Content Server Configuration REST Server Configuration Preliminaries gt Enabling CAS Authentication Scheme Validating REST Deployment Advanced CAS Integration Options Multiple Authentication Schemes CAS 550 across Content Server Repositories Security Configuration for Client Token Logging and Troubleshooting Content Server Logging REST Server Logging CAS Server Logging REST Server Troubleshooting Content Server Troubleshooting CAS Server Troubleshooting Client Side Troubleshooting ii eee References Table 1 Terminology Table 2 Expiration Policy of Client Token Table 3 Full View of Token Timeout Figure 2 CAS Proxy Authentication 10 Figure 3 Browser Client CAS SSO for Documentum REST Services E Figure 4 Non browser Client CAS 550 for Documentum REST Services 18 Fig
33. r to the LDAP server Add the following element in the root This bean resolves user attributes for authenticated users The CAS LDAP mapping is configured at cas sewerwebapp 3 5 2 war WEB INF deployerConfigContext xml The service registry holds the services that CAS server grants access permission We need to register services for both Documentum REST Services and Content Server There are basically three ways to configure the service registry By beans set service registry in Java beans in deployerConfigContext xml By Service Management set service registry in CAS service management Ul database persist service registry to a database We will show the sample of bean configuration Open deployercOnfigContext xml and add the following element in the root The CAS proxy response file is at casemerwebapp 3 5 2war WEB INF view isp protocol 2 0 CasServiceValidationSuccess jsp Add following element to the cas authenticationSuccess between casiusen and cf test S not empty After you complete these the configurations above deploy the CAS WAR file renamed to casa to the web container and start the web server The CAS login can be tested by accessing the page Atips cas server cas login CAS login page should be Enter the user id and password The login successful page appears ne Please check the pag which carries TGT token The client reuses
34. repository log under lDocumentumldbalogs The following log information will be desplayed HR td ven seb pecomentuy thai cation plugin Trace ile ATI rs reserved znitializing dm ces plugin Following are the such Init params server host Vr sth lt a5 proxyeaidate aras 2 Concentserver 12 19 13 18 Far more information about Content Server configuration please refer to the whitepaper Documentum Content Server Central Authentication Service CAS 550 AUTHENTIC OR EMC DOCUME CAS 550 is available for Documentum REST Services since version 7 1 To make CAS SSO work for the REST server the web container which hosts the REST services must enable SSL For formal product implementation you need to register the SSL certificate to an authority For quick startup create a certificate for your web Container with any of the following tools For instance Java keytool Openssl or any other certificate tool like Portecle orge net After the certificate generation import it to the JRE keystore of the REST server with following command path the addition to that this certificate must be trusted by the CAS server for ticket validation mandatory in HTTPS so go to CAS server and import it to the CAS server s JRE trust store CAS is not the default authentication scheme for Documentum REST Services To enable CAS open dctm restwar and navigate to WEB
35. rios Browser CAS 550 Walkthrough The following diagram illustrates the workflow of CAS authentication for a browser client The browser CAS SSO is following the standard CAS proxy authentication Figure 3 Browser Client CAS SSO for Documentum REST Services m m peu pm B Step 1 browser client visits a Documentum Core REST Service resource for instance http restserver BOBO dctmrest repositories acme01 Step 2 The REST server sends back a 302 redirecting response asking the user to authenticate to the CAS server for instance Step 3 The client inputs usemame password and submits the request to the CAS Server Step 4 The CAS server connects to the directory service to verify the user credential Step 5 The CAS server retums back 302 redirecting response providing the ST and TGT for user to visit the resource for instance CENTRAL AUTHENTICATI FOR EMC DOCUMENTU Step The REST server negotiates a PT from the CAS server Please refer to section CAS Proxy Negotiation for details Step 7 The REST server calls Content Server by passing the PT Step 8 t s new CAS Plugin calls the CAS server to validate PT for instance Step 9 Note that there is a custom attribute dmCSLdapUserDN retumed in the validation response This is a customized behavior of CAS deployment required by Documentum REST Services This attribute is used by
36. rompted to log in again at each of them Central Authentication An open SSO protocol for web access In most cases Service CAS it also refers to the open source Java server that provides enterprise Single Sign On solution for web services CAS Service A CAS 550 enabled web application that clients try to CAS Proxy CAS service that accesses other CAS services on behalf ofa particular user CAS Target A service that accepts proxied credentials from at least one particular proxy Ticket Granting Ticket en A ticket produced by CAS and held by the user client as an authenticated identity CAS Ticket Granting Ticket Cookie CASTGC ATT carried in the format of a cookie Service Ticket SD A ticket produced by CAS Clients send STs to services Each ST is used only once for access to one specific service Proxy Granting Ticket ect A ticket produced by CAS and held by a proxy to confer the ability to produce proxy tickets Proxy Granting Ticket 100 PGToU A ticket sent by CAS alone in a service validation response and with a PGT to the callback URL Proxy Ticket PT A ticket usable by a proxy to access a target by impersonating a single user Client Token Atoken produced by Documentum REST Server and carried a cookie for an authenticated CAS identity The user client can use the CT to access REST resources without going through the CAS
37. rtant for below two reasons The CAS server next will produce a ST for the resource access Since each ST is specific to a unique resource and one time use the CAS server must know which service URI the user is attempting to access The CAS server needs to know the original service URI to redirect the user back after a successful authentication CENTRAL AUTHENTICATI OR EMC DOCUMENTU A redirecting URI follows this pattem Atfp cas senver login service htip web app about me step 3 The CAS server retums an HTML page which contains a login form Stepa The user client posts the userid and password to the CAS server Step 5 Next the CAS server must validate the user credential against a back end user directory sever which is usually an identity provider or LDAP server The CAS sever must also check whether the service URI within service parameter e g htp web app about m has been registered as a CAS Service If not the authentication fails even if the user credential is correct After validation the CAS server redirects the user client back to the original service URL In addition to that CAS appends the information below in the redirecting response An ST is appended to the original service URI which represents the authorized access to the web resource and will be later validated by the web application So the redirecting back URI is like Atfo web app about mevticket STibdgbwHiReBonmaudv
38. rypto options for the CT cookie during the REST service deployment For instance the secutity provider other than RSA the crypto algorithm other than AES the key size other than 128 etc Please refer to section Security Configuration for Client Token for details The CT cookie is by default used for a single REST server Therefore the CT cookie produced from one REST server cannot be used by another REST server To make the CT work across multiple REST servers please refer to section REST Server Clustering for CAS for details The CT cookie is by default used by single repository access Therefore the CT cookie produced based on one repository login cannot be used to access REST resources in the other repository To make the CT work across repositories please referto section CAS 550 across Content Server Repositories Managing Timeout for Tokens the full CAS authentication flow there are multiple tokens and cookies produced by the authorities Here is the table showing the tokens and their timeout policies in the CAS authentication Table 3 Full View of Token Timeout N P Involved Parties Timeout Policy Default a r m e d u e fas e CASSener e TimeoutExpirationPa TimeoutExpiratio cookie Sever REST Client liey nPolicy HardTimeoutExpirati 7200 seconds onPolicy CENTRAL AUTHENTICATION OR EMC DOCUMENTU ThroitledUseAndTim eoutExpiration
39. sends a request to the REST server for logout by providing a CT 2 The REST server validates the CT and resets it and then redirects the REST client to the CAS serverfor logout The REST client resets the client side CASTGC cookie and access the CAS server for logout CENTRAL AUTHENTICATI FOR EMC DOCUMENTU 3 The CAS server destroys the TGT from its memory entry and sends back HTTP 200 with an empty CASTGC cooki 5 The REST client resets its client side cookie and the single sign out finishes Both TGT and CT are invalidated Please note that the actual Documentum CT token cannot be invalidated by the server side It is just be cleared up on the client side The actual invalidation of the CT token depends on its own expiry For strict security requirement itis recommended to set a short default time out for the CT token Future Possibilities CAS 850 not only provides the basic authentication for LDAP integration but also allows extending its authentication protocol to work with other authentication protocols The Jasig CAS space httns wiki jasig org display CASUM Home has a list of possible authentication mechanisms that can be integrated with CAS For example CAS server can work as a delegation party for Kerberos protocol that it negotiates the Kerberos SPNEGO ticket between the end user and the Kerberos KDC What it means is that if an IT system has already adopted some SSO security it isn t necessary to r
40. ser legitimately So in CAS 20 authentication is introduced to support the authentication delegation in a malilayer system authentication flow is presented in the diagram below Figure 2 CAS Proxy Authentication Flow User Cent Web Application 2 User is a web resource 2 Webapgrtdiettheresust is CAS bogin ps om mmt Webel OS Sl server ena validation rego CAS Server ELE TIT Step 1 to Step 5 are the same as basic authentication fow Starting with Step 6 the flow is follows Step 6 The requested resource is on the backend server instead of the web application Therefore the web application must to request a PT to access the back end server to get the resource In this step the web application sends the ST validation request to the CAS server and it appends PGT callback URL to the request asking for proxy authentication after the ST validation To perform proxy authentication the web application first needs to get a PGT just like TGT then use the PGT to request a PT fora specific resource from the back end server During the ST validation the CAS Server sends a PGT to the web application Step 7 After the ST validation the CAS server will further enable proxying for the web application The PGT is sent to the web application in two steps In Step 7 the CAS s
41. this cookie to achieve 550 Cocks set by ths page owed cakes re set ane dep cokes Nere pos Cheated Thursday Decaer Is 2013 9428 sakes When fhe sasson ende CENTRAL AUTHENTICATION FOR EMC DOCUMENTU Content Server Configuration Preliminaries CAS SSO for Content Server is available since Documentum 7 1 Please refer to Content Server Administration Guide for the detailed configuration In this chapter we just reference the key steps for Content Server CAS setup Prior to the CAS plugin configuration create an LDAP configuration to synchronize the LDAP users to the Content Server repository if not yet Content Server Administration Guide has details on the setup of LDAP configuration Just for your quick reference we take the snapshots forthe setup Step 1 Login to Documentum Administrator and create an LDAP Server Configuration Step2 Enter the LDAP name directory type host port and admin credentials The LDAP configuration name should be the domain name i en nA center Step 3 Select users and or groups to synchronize Step 4 Map the user class and search base If necessary set filters to synchronize a Subset of LDAP users to the repository UTHENTICATION SERI FOR EMC DOCU Step 5 Configure Failover settings and complete the configuration Step 6 Synchronize the L
42. tication Service CAS 550 CENTRAL AUTHENTICATI FOR EMC DOCUMENTU CAS Server Troubleshooting Here is a checkli to verify the CAS server deployment Verify CAS deployment As CAS server requires extensions to support the SSO the following CAS plugin jars are required to be in lt cas 3 5 2 WEB INF lib casseverintegration ehcache 3 5 2 jar cassenerintegration restlet 3 5 jar casseversupport generic 3 5 2 jar casseversupportldap 3 jar SSL is required to be setup forthe Web Container Please referto container documentation forthe SSL setting up Please check server logs after the CAS startup completes Try CAS home login page by visiting https eas 8443 cas login Verify service registry for REST and CS c Attribute dmCSLdapUserDN must be mapped from LDAP distinguished name in the bean of attributeRepository c Attribute dmCStdapUserDW must be allowed for releasing in Content Server service registry Content Sewer service must be registered to support proxy Verify LDAP connectivity c Below beans are required to be set correctly in lt cas 3 5 21WEB INFideployContext xm bindidaphuthenticationHandler eredentissToLDAPAtrbutePricipal Resolver IdapContextSource attributeRepository c Ty login to CAS with the LDAP usemame and password eg tips cas 8443 cas login Forany failure please check CAS server logs Verify REST server con
43. timeout for all these tokens and cookies must be managed carefully Typically the timeout of ST should be less than 30 seconds the timeout of TGT should be more than 15 minutes which prevents the web application from returning the session timed out error to the end user frequently the timeout for the CT should be between the ST and the TGT usually fram 10 minutes to hour The timeout of CT needs to be shorter than the time of TGT because when the end user gets the timed out error using an expired CT cookie to access some resources he she still has the chance to use the valid TGT to negotiate new CT cookies without needing to send the private credentials over the wire again For a browser client this is usually done silently with the cookie handling and URL redirecting mechanisms supported by the web browser CENTRAL AUTHENTICATI FOR EMC DOCUMENTU Single Sign out CAS authentication utilizes CT cookies to simplify the communication between an authenticated REST client and the REST server Moreover CAS authentication supports Single Sign out that invalidates both the CT cookie and the CAS TGT cookie When client explicitly logs out the session is terminated and the client has to negotiate a new session ticket The following diagram shows the flow for CAS Single Sigh out Figure 6 CAS Single Sign out Flow The following workflow explains the single sign out process in more detail 1 A client
44. ture Overview Documentum REST Services supports CAS authentication to achieve a robust authentication and SSO infrastructure for both browser and non browser clients There are at least four parties taking part in the CAS SSO Auser agent e g web browser generic HTTP client etc a CAS server 3 5 2 UTHENTICATION FOR EMC DOCUMENTU Documentum REST Services server 7 1 Content Server7 1 Documentum REST Services acts as a CAS proxy in the CAS 550 in that it needs to access another CAS service Content Server on behalf of the end user Therefore Content Server in the CAS SSO acts as a CAS target which accepts the proxied credentials Optionally there could be other components involved in the 550 such as an LDAP server a load balancer and a reverse proxy server for business specific deployment consideration To achieve the practical CAS SSO performance Documentum REST Services introduces an authentication token called Client Token to provide the pass through access for CAS authenticated clients This token is sent by the REST server to the client after initial CAS 550 authentication flow has completed successfully either after initial login or after token was renegotiated due to an expiry time It is carried in the form of a DOCUMENTUM CLIENT TOKEN cookie The CAS authentication supports browser and non browser clients The next sections elaborate on the authentication workflows for both scena
45. ure 5 Proxy Negotiation between REST Server and CAS Serve 20 Figure 7 Basic and CAS Authentication Work Together 45 Figure Setup Sub Group for PGT Storage 52 UTHENTICATI OR EMC DOCUME Executive summary Central Authentication Service CAS is an enterprise Single Sign On SSO solution for web services SSO means a better user experience when running multitude of web services each with its own means of authentication With SSO solution different web services may authenticate to one authorized source of trust that the user needs to log in to instead of requiring the end user to log in into each separate service This white paper provides a complete overview of CAS SSO for the Documentum REST Services 7 1 release which includes the following Architecture and the authentication flow Deployment details including both basic and advanced environment setup Troubleshooting recommendations Samples Audience This white paper is intended for architects engineers support professianals and customers t provides the information needed for enabling CAS SSO for Documentum REST Services Terminology Special terms abbreviations and acronyms that may appear in this guide are defined below Table 1 Terminology Tem Description Single Sign on 550 property of access control of multiple related but independent software systems that a user logs in once and gains access to all systems without being p
Download Pdf Manuals
Related Search