Purpose
To enable single sign-on into some legacy application it may be necessary to provide them with the actual cleartext password. While such approach inevitably increases security risk, a number of institutions found it to be a "necessary evil". This page describes a solution by Unicon for Sacramento State.
Architecture
A service may obtain cleartext credentials for an authenticated user by presenting a valid proxy ticket obtained specifically for the CAS cleartext extension service end-point (ClearPass). The specific sequence of calls is shown in a diagram below:
Until the last two steps, only standard CAS protocols are involved. The two steps involve request/response interaction between uPortal and a newly introduced CAS ClearPass service to obtain the cleartext credentials. The request follows the same syntax as standard CAS proxy ticket validation request (typically configured under /proxyValidate path), except that the service endpoint is different (/clearPass in default configuration). Upon receiving the request, ClearPassController ensures that the following validation criteria are met:
- The proxy ticket was obtained for the URL specifying location of the ClearPass service
- The proxy is valid according to standard CAS spec
- The proxy ticket is indeed a proxy ticket, not a service ticket
- Each member of the proxy chain has been given explicit permission to receive cleartext credentials
Upon successful validation the ClearPass service provides credentials in the following response:
<cas:clearPassResponse xmlns:cas='http://www.yale.edu/tp/cas'> <cas:clearPassSuccess> <cas:credentials>actual_password</cas:credentials> </cas:clearPassSuccess> </cas:clearPassResponse>
If any of the validation steps fail, the error response is returned:
<cas:clearPassResponse xmlns:cas='http://www.yale.edu/tp/cas'> <cas:clearPassFailure>description of the problem</cas:clearPassFailure> </cas:clearPassResponse>
Implementation
The code is available in the JA-SIG SVN repository. The reference implementation also includes modifications to uPortal CAS client necessary to take advantage of the new feature.
CAS extensions
_(note: all classes described in this subsection are in the edu.csus.cas.clearpass package)_The CAS login workflow is modified to capture the cleartext password using CacheCredentialsAction. The passwords are stored in an cache implementing CredentialsCache interface. The default cache implementation (CredentialsCacheImpl) uses EhCache.
The ClearPass service endpoint (configured by default under /clearPass) is implemented by ClearPassController class. This service relies on a instance of ClearPassServiceValidator to check if a particular service is allowed to receive cleartext credentials. The default implementation (ClearPassServiceValidatorImpl) simply accepts an explicit list of approvied services (listed by their ProxyReceptor endpoints).
uPortal client extensions
uPortal extensions are implemented by providing an alternative SecurityContext implementation: org.jasig.portal.security.provider.cas.PasswordCachingCasFilteredSecurityContext.
Accessing clear-text credentials within uPortal
Within uPortal, the cleartext password can be accessed in exactly the same way as opaque credentials.
The modified security context will make cleartext passwords accessible to the IPrivileged channels via ISecurityContext.getOpaqueCredentialsInstance()
Portlets that need to access cleartext credentials can instruct portal to place the password among the other user attributes by including the following declaration within portlet.xml:
<user-attribute> <description>User Password</description> <name>password</name> </user-attribute>
For illustration and testing purposes, a modified version of FunctionalTestsPortlet has been configured in this way, and extended to show the obtained password. The portlet is distributed in /uportal/FunctionalTestsPortlet, can be built using "mvn package", and the resulting war file can be deployed using standard procedure.
Installation and required configuration changes
CAS extensions
CAS extensions are packaged as a maven2 patch on top of CAS 3.2.1.
- Edit src/main/webapp/WEB-INF/cas-servlet.xml
- Change clearPassControllerUrl property (last one) on the clearPassController bean to specify the URL at which the clearPass service will be accessible
- Edit enabledServices property of the clearPassServiceValidator bean to list all of the services that will be allowed to retrieve cleartext credentials. Note that the services must be listed by their ProxyReceptor (CasProxyServlet) URLs.
- Add any additional required CAS configuration changes (e.g. LDAP config, skin customizations)
- Run "mvn package" command to create a war file in the target directory, deploy war file into the servlet container
- Make sure that the SSL certificates used by the CAS-enabled applications (e.g. uPortal instances) are registered with the JVM that is being used to run CAS.
uPortal extensions
- Make sure that appropriate uPortal.jar is present in your Maven repository
- Build uportal.clearpass jar by running "mvn package" in the uportal-clearpass folder
- Copy the uportal.clearpass jar to your uPortal lib folder
- Edit properties/security.properties (these instructions assume you have already configured uPortal to use CAS)
- see doc/security.properties.example for details
- replace this line "root.cas=org.jasig.portal.security.provider.cas.CasFilteredSecurityContextFactory", with this line "org.jasig.portal.security.provider.cas.PasswordCachingCasFilteredSecurityContextFactory"
- add the CAS clearpass URL to the security.properties file: org.jasig.portal.security.provider.cas.PasswordCachingCasFilteredSecurityContextFactory.clearPassCasUrl=https://\{cas.location}/clearPass
- Make sure that uPortal is properly configured to utilize proxy tickets. (i.e. CasProxyServlet is configured in WEB-INF/web.xml. If using clustered uPortal instances, configure ProxyEchoFilter to list all uPortal instances running in the cluster)