Requirements:

• A CAS server accessible through https.  It may be possible to get phpCAS to work without it, but it is safer and probably easier just to set up the https.
• A webserver such as Apache, but any that will be capable of running PHP will do.
• PHP5 with cURL installed on the machine.

Directions:

1. The easiest way to install is through PEAR with the command “pear install  http://downloads.jasig.org/cas-clients/php/current.tgz”.  If PEAR is not already installed, it will tell you the command needed to install it.  If on Windows or a flavor of linux that does not provide a command to install PEAR, a manual install would probably be easier.  Just download from the link in the command above and extract somewhere logical (if you’re on Windows, you’ll need something like 7zip to open the .tgz) and add the include_path to your php.ini file.
2. Go to the directory web pages are served from for that server (/var/www/) and copy config.php and example_simple.php from the examples directory provided with phpCAS’s documentation (/usr/share/php/doc/CAS/docs/examples).  Other examples can be copied if desired, but this is all that is necessary to test the connection.
3. Modify Config.php to reflect the setup of the machine it is install on.  This file is included in all of the example files, so you should only need to change this once.  For a typical machine, the following changes were made:
• $phpcas_path = ‘/usr/share/php’;
• $cas_host = ‘localhost’;
• $cas_context = ‘/cas-server-webapp-3.4.8’;
• $cas_port = 8443;
4. In a web browser, go to http://localhost/example_simple.php to test the server. It should redirect you to the CAS login page and then return you once logged in.  If you were already logged in through another app, it will automatically take you to the requested page.

While it may not seem like much as it is, the examples included with phpCAS will give you a good basis for using this client with your own PHP applications.  Do keep in mind that Single Sign On with CAS does not mean Single Sign Off, so always log out of your applications separately.  Also remember that Authentication and Authorization are separate concepts and CAS will only decide if a valid username and password were provided.  It is up to your application to determine if that username should have access.

Version compatibility

Many people seemed to have trouble with the directions using more recent versions of the software than this was made on.  I have successfully connected Pentaho 4.1 to CAS 3.4.11 following these directions, so they will most likely remain valid until Pentaho implements a more recent version of Spring Security (which would probably be Pentaho 5 at the earliest).  The only part of the install that is absolutely version specific is the spring-security-cas-client-2.0.5.RELEASE.jar file.  A later version of this jar will not work.

The difficulty connecting that many people seem to have most likely comes from applicationContext-spring-security.xml file.  Since the directions were made with a specific version of CAS, all of the URL references in it are made to the “http://localhost:8080/cas-server-webapp-3.4.8/” version of the webapp.  Since you can technically name the webapp anything, these URL references need to be changed to match, such as “http://localhost:8080/cas-server-webapp-3.4.11/” for the current version.

Security

While CAS will complain on its login page about not using SSL, I am as of yet to find a version that will actually not allow pentaho login. This does not mean that certain setups will not run into this problem, and many other CAS clients require SSL connections  Either way, setting up your server to use SSL is always a good idea.  The instructions apache provides (http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html for the version of tomcat pentaho uses) should be sufficient for setting this up, and remains mostly consistent between later versions of tomcat.

Again changes need to be made to the applicationContext-spring-security.xml file’s URLs, this time make sure to change the “http://localhost:8080” to the equivalent secure URL such as “https://localhost:8443” to make sure it actually uses the SSL.

XML Encoding

This is something that I’m sure some people have run into before, namely that when copying the XML over it sometimes cannot be read by the server.  The primary cause of this is due to the XML file requiring UTF-8 encoding, and many text editing programs (especially in Windows land) tend to automatically save to more modern text encodings.  So When editing these files, make sure to force UTF-8 encoding when you save.

Authentication vs Authorization

CAS like its spelled out name implies is designed to handle authentication, i.e. verifying a valid username and password combination.  This does not include authorization, i.e. checking if a user is actually allowed to access something.  Authorization is handled on the client end, in this case Pentaho.  Any time a user successfully logs in to CAS but does not have any authorization in pentaho, they will be redirected to the default public/casFailed page which does not exist by default.  As usual, this can be changed in the applicationContext-spring-security.xml file.

Normally both are handled in Pentaho, with authentication handled in the applicationContext-spring-security.xml that is modified as part of the CAS integration, and also in another file that is imported through the pentaho-spring-beans.xml file, the default being called applicationContext-spring-security-hibernate.xml. After CAS is integrated, this imported file is mostly ignored, as CAS is bypassing all of the beans in it.

Authorization is handled primarily by another file imported through the pentaho-spring-beans.xml file called applicationContext-pentaho-security-hibernate.xml by default.  Like the similarly named file mentioned previously, there are a number of alternate versions that can be used instead of the default hibernate version, such as -jdbc (checks against a database query), -ldap (checks against an ldap server), -memory (checks against data written directly in the XML file).

I haven’t fully explored all of the possibilities those different authorization options may provide, so it is very possible that there is an elegant solution available in modifying those files.  If the user base for a pentaho deployment is not especially large and/or does not change often, updating user permissions by hand may be a more cost effective solution than spending hours coming up with a custom solution.  When confronted with this same problem with a client who had potentially thousands of users, I went to the Pentaho developer’s multipurpose tool:  PDI.

This ETL is designed to check the USERS table found in the hibernate database that Pentaho CE comes with against an LDAP server and make comparisons for any new users, which it then adds to the Hibernate database with the basic Authenticated role.  The main advantage of this technique is that it is not difficult to implement against any size, and can be scheduled to run regularly to keep the records up to date.  It also allows the Admin Console to still be used to add additional roles to the users.  The main disadvantage is the fact that there will always be a time delay until its next scheduled run or the next time someone manually does so.  It also lacks flexibility, as it grants the same permission to every user it adds, so still requires human intervention to make users an admin or some other role. This could probably be overcome with further development and more precise deployment specifications from a client, and in its current form is still very effective at authorizing large groups of users at once.

If there are any other solutions out there, or other comments about these or any other issues, let me know.

Special Thanks to Nilesh Patil, whose blog gave me a good basis to start from: http://pentahointegra.blogspot.com/2011/04/cas-with-pentaho-community-edition.html

Some security things to note before getting started.  Single Sign On does not mean Single Sign Off, due to the different ways web-based applications can retain session data.  Also note that this does not require an https connection, and thus is not ideal for things outside of a LAN or VPN connection.  It is possible to do this set up using https, but it requires more steps.  Addressing these sorts of issues will probably be the topic of a later post.

This guide is accurate for Pentaho CE 3.8 and CAS Server 3.4.8.

Installing CAS Server

1. Download the most recent CAS Server from http://www.jasig.org/cas/download and unzip it.
2. In the newly created directory, navigate to the modules directory, which will contain various jar and war files.
3. Move the war file for the CAS server webapp (e.g. cas-server-webapp-3.4.8.war) to tomcat’s webapp directory.  If using the standard one that is part of Pentaho, this directory would be biserver-ce/tomcat/webapps.  Since war files automatically create a directory that shares the name of the war file, it might be a good idea to rename it to something more convenient before placing it in the webapps directory.
4. If the tomcat server is not already running, start it.  The war file will be automatically inflated into its own directory.
5. In a web browser, navigate to the subdirectory on the tomcat server, such as http://localhost:8080/cas-server-webapp-3.4.8/ which will bring you to the CAS main login screen if working correctly.  The default authentication that CAS uses merely requires the username and password entered to match for a successful authentication.

Connecting Pentaho to CAS

1. Download spring-security-cas-client-2.0.5.RELEASE.jar from a site such as http://www.jarvana.com/jarvana/browse/org/springframework/security/spring-security-cas-client/2.0.5.RELEASE/.  Note that it needs to be this version of the jar file, as later versions do not contain the necessary classes.
2. Download cas-client-core-3.1.10.jar from a site such as http://www.jarvana.com/jarvana/archive-details/org/jasig/cas/cas-client-core/3.1.10/cas-client-core-3.1.10.jar.  A later version should also be sufficient for this.
3. Move both of these jar files to biserver-ce\tomcat\webapps\pentaho\WEB-INF\lib.
4. Edit the file applicationContext-spring-security.xml in the directory biserver-ce\pentaho-solutions\system\.  Because of the widespread number of changes, the whole document will be reproduced here:

<?xml version=”1.0″ encoding=”UTF-8″?>
<!DOCTYPE beans PUBLIC “-//SPRING//DTD BEAN//EN” “http://www.springsource.org/dtd/spring-beans.dtd”>

<!–+
| Application context containing FilterChainProxy.
+–>
<beans default-autowire=”no” default-dependency-check=”none” default-lazy-init=”false”>

<!– ======================== FILTER CHAIN ======================= –>
<!– overridden from applicationContext-spring-security.xml to enable CAS –>
<bean id=”filterChainProxy” class=”org.springframework.security.util.FilterChainProxy” autowire=”default” dependency-check=”default” lazy-init=”default”>
<property name=”filterInvocationDefinitionSource”>
<value>
<![CDATA[CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
PATTERN_TYPE_APACHE_ANT
/**=securityContextHolderAwareRequestFilter,httpSessionContextIntegrationFilter,logoutFilter,casProcessingFilter,basicProcessingFilter,requestParameterProcessingFilter,anonymousProcessingFilter,pentahoSecurityStartupFilter,exceptionTranslationFilter,filterInvocationInterceptor,casSingleSignOutFilter]]>
</value>
</property>
</bean>
<!– ===================== HTTP REQUEST SECURITY ==================== –>
<bean id=”serviceProperties” class=”org.springframework.security.ui.cas.ServiceProperties” autowire=”default” dependency-check=”default” lazy-init=”default”>
<property name=”service” value=”http://localhost:8080/pentaho/j_spring_cas_security_check”/>
<property name=”sendRenew” value=”false”/>

</bean>
<!– replaces authenticationProcessingFilter in filterChainProxy above –>
<bean id=”casProcessingFilter” class=”org.springframework.security.ui.cas.CasProcessingFilter” autowire=”default” dependency-check=”default” lazy-init=”default”>
<property name=”authenticationManager”>
<ref bean=”authenticationManager”/>
</property>
<property name=”authenticationFailureUrl” value=”/public/casFailed”/>
<property name=”defaultTargetUrl” value=”/”/>
<property name=”filterProcessesUrl” value=”/j_spring_cas_security_check”/>
</bean>

<bean id=”casSingleSignOutFilter” class=”org.jasig.cas.client.session.SingleSignOutFilter”>
</bean>
<bean id=”casSingleSignOutHttpSessionListener” class=”org.jasig.cas.client.session.SingleSignOutHttpSessionListener”>
</bean>
<!– overridden from applicationContext-spring-security.xml –>

<bean id=”exceptionTranslationFilter”  class=”org.springframework.security.ui.ExceptionTranslationFilter” autowire=”default” dependency-check=”default” lazy-init=”default”>
<property name=”authenticationEntryPoint”>
<ref local=”casProcessingFilterEntryPoint”/>
</property>
<property name=”accessDeniedHandler”>
<bean class=”org.springframework.security.ui.AccessDeniedHandlerImpl” />
</property>
</bean>

<bean id=”casProcessingFilterEntryPoint” class=”org.springframework.security.ui.cas.CasProcessingFilterEntryPoint” autowire=”default” dependency-check=”default” lazy-init=”default”>
<property name=”loginUrl” value=”http://localhost:8080/cas-server-webapp-3.4.8/login”/>
<property name=”serviceProperties”>
<ref local=”serviceProperties”/>
</property>
</bean>

<!– overridden from applicationContext-spring-security.xml –>
<bean id=”authenticationManager” class=”org.springframework.security.providers.ProviderManager” autowire=”default” dependency-check=”default” lazy-init=”default”>
<property name=”providers”>
<list>
<!–ref bean=”daoAuthenticationProvider” /–>
<ref bean=”anonymousAuthenticationProvider”/>
<ref bean=”casAuthenticationProvider”/>
</list>
</property>
</bean>

<bean id=”casAuthenticationProvider” class=”org.springframework.security.providers.cas.CasAuthenticationProvider”>
<property name=”userDetailsService”>
<ref bean=”userDetailsService”/>
</property>
<property name=”serviceProperties”>
<ref local=”serviceProperties”/>
</property>
<property name=”ticketValidator”>
<ref local=”ticketValidator”/>
</property>
<property name=”key” value=”my_password_for_this_auth_provider_only”/>
</bean>

<bean id=”ticketValidator” class=”org.jasig.cas.client.validation.Cas20ServiceTicketValidator” autowire=”default” dependency-check=”default” lazy-init=”default”>
<constructor-arg index=”0″ value=”http://localhost:8080/cas-server-webapp-3.4.8″/>
</bean>
<!– overridden from applicationContext-spring-security.xml to specify logoutSuccessUrl as CAS logout page –>

<bean id=”logoutFilter” class=”org.springframework.security.ui.logout.LogoutFilter” autowire=”default” dependency-check=”default” lazy-init=”default”>
<constructor-arg value=”http://localhost:8080/cas-server-webapp-3.4.8/logout”/>
<constructor-arg>
<list>
<bean class=”org.pentaho.platform.web.http.security.PentahoLogoutHandler”/>
<bean class=”org.springframework.security.ui.logout.SecurityContextLogoutHandler”/>
</list>
</constructor-arg>
<property name=”filterProcessesUrl” value=”/Logout”/>
</bean>

<!– ======================== AUTHENTICATION ======================= –>
<!–    <bean id=”authenticationManager” class=”org.springframework.security.providers.ProviderManager”>
<property name=”providers”>
<list>
<ref bean=”daoAuthenticationProvider” />
<ref local=”anonymousAuthenticationProvider” />
</list>
</property>
</bean>
–>
<!– Automatically receives AuthenticationEvent messages –>
<bean id=”loggerListener”
class=”org.springframework.security.event.authentication.LoggerListener” />
<bean id=”basicProcessingFilter”
class=”org.springframework.security.ui.basicauth.BasicProcessingFilter”>
<property name=”authenticationManager”>
<ref local=”authenticationManager” />
</property>
<property name=”authenticationEntryPoint”>
<ref local=”basicProcessingFilterEntryPoint” />
</property>
</bean>
<bean id=”basicProcessingFilterEntryPoint”
class=”org.springframework.security.ui.basicauth.BasicProcessingFilterEntryPoint”>
<property name=”realmName” value=”Pentaho Realm” />
</bean>

<!– custom Pentaho begin –>
<bean id=”requestParameterProcessingFilter”
class=”org.pentaho.platform.web.http.security.RequestParameterAuthenticationFilter”>
<property name=”authenticationManager”>
<ref local=”authenticationManager” />
</property>
<property name=”authenticationEntryPoint”>
<ref local=”requestParameterProcessingFilterEntryPoint” />
</property>
</bean>
<bean id=”requestParameterProcessingFilterEntryPoint”
class=”org.pentaho.platform.web.http.security.RequestParameterFilterEntryPoint” />
<bean id=”pentahoSecurityStartupFilter”
class=”org.pentaho.platform.web.http.security.SecurityStartupFilter”>
<property name=”injectAnonymous” value=”true” />
</bean>
<!– custom Pentaho end –>
<bean id=”anonymousProcessingFilter”
class=”org.springframework.security.providers.anonymous.AnonymousProcessingFilter”>
<property name=”key” value=”foobar” />
<property name=”userAttribute” value=”anonymousUser,Anonymous” />
</bean>
<bean id=”anonymousAuthenticationProvider”
class=”org.springframework.security.providers.anonymous.AnonymousAuthenticationProvider”>
<property name=”key” value=”foobar” />
</bean>
<bean id=”httpSessionContextIntegrationFilter”
class=”org.springframework.security.context.HttpSessionContextIntegrationFilter” />
<!–
<bean id=”logoutFilter” class=”org.springframework.security.ui.logout.LogoutFilter”>
<constructor-arg value=”/index.jsp” />
<constructor-arg>
<list>
<bean class=”org.pentaho.platform.web.http.security.PentahoLogoutHandler” />
<bean
class=”org.springframework.security.ui.logout.SecurityContextLogoutHandler” />
</list>
</constructor-arg>
<property name=”filterProcessesUrl” value=”/Logout” />
</bean>
–>
<bean id=”securityContextHolderAwareRequestFilter”
class=”org.springframework.security.wrapper.SecurityContextHolderAwareRequestFilter” />
<bean id=”httpSessionReuseDetectionFilter”
class=”org.pentaho.platform.web.http.security.HttpSessionReuseDetectionFilter”>
<property name=”filterProcessesUrl” value=”/j_spring_security_check” />
<property name=”sessionReuseDetectedUrl” value=”/Login?login_error=2″ />
</bean>

<bean id=”httpRequestAccessDecisionManager” class=”org.springframework.security.vote.AffirmativeBased”>
<property name=”allowIfAllAbstainDecisions” value=”false” />
<property name=”decisionVoters”>
<list>
<ref bean=”roleVoter” />
</list>
</property>
</bean>
<!–
Note the order that entries are placed against the
objectDefinitionSource is critical. The FilterSecurityInterceptor will
work from the top of the list down to the FIRST pattern that matches
the request URL. Accordingly, you should place MOST SPECIFIC (ie
a/b/c/d.*) expressions first, with LEAST SPECIFIC (ie a/.*)
expressions last
–>
<bean id=”filterInvocationInterceptor”
class=”org.springframework.security.intercept.web.FilterSecurityInterceptor”>
<property name=”authenticationManager”>
<ref local=”authenticationManager” />
</property>
<property name=”accessDecisionManager”>
<ref local=”httpRequestAccessDecisionManager” />
</property>
<property name=”objectDefinitionSource”>
<value>
<!–
Note – the “=Nobody” below is saying that resource URLs with those
patterns not be available through a web call.
–>
<![CDATA[
CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
\A/docs/.*\Z=Anonymous,Authenticated,ea_admin
\A/mantlelogin/.*\Z=Anonymous,Authenticated,ea_admin
\A/mantle/mantleloginservice/*\Z=Anonymous,Authenticated,ea_admin
\A/mantle/.*\Z=Authenticated,ea_admin
\A/welcome/.*\Z=Anonymous,Authenticated,ea_admin
\A/public/.*\Z=Anonymous,Authenticated,ea_admin
\A/login.*\Z=Anonymous,Authenticated,ea_admin
\A/ping/alive.gif.*\Z=Anonymous,Authenticated,ea_admin
\A/j_spring_security_check.*\Z=Anonymous,Authenticated,ea_admin
\A/getimage.*\Z=Anonymous,Authenticated,ea_admin
\A/getresource.*\Z=Anonymous,Authenticated,ea_admin
\A/admin.*\Z=Admin,uidai_admin
\A/auditreport.*\Z=Admin,uidai_admin
\A/auditreportlist.*\Z=Admin,uidai_admin
\A/versioncontrol.*\Z=Admin,uidai_admin
\A/propertieseditor.*\Z=Admin,uidai_admin
\A/propertiespanel.*\Z=Admin,uidai_admin
\A/subscriptionadmin.*\Z=Admin,uidai_admin
\A/resetrepository.*\Z=Admin,uidai_admin
\A/viewaction.*solution.admin.*\Z=Admin,uidai_admin
\A/scheduleradmin.*\Z=Admin,uidai_admin
\A/publish.*\Z=Admin,uidai_admin
\A/logout.*\Z=Anonymous
\A/solutionrepositoryservice.*component=delete.*solution=system.*\Z=Nobody
\A/solutionrepositoryservice.*solution=system.*component=delete.*\Z=Nobody
.*system.*pentaho.xml.*=Nobody
.*system.*applicationcontext.*.xml.*=Nobody
.*system.*pentahoobjects.spring.xml.*=Nobody
.*system.*pentahosystemconfig.xml.*=Nobody
.*system.*adminplugins.xml.*=Nobody
.*system.*plugin.properties.*=Nobody
.*system.*publisher_config.xml.*=Nobody
.*system.*sessionstartupactions.xml.*=Nobody
.*system.*systemlisteners.xml.*=Nobody
.*system.*hibernate.*=Nobody
.*system.*birt/.*=Nobody
.*system.*dialects/.*=Nobody
.*system.*google/.*=Nobody
.*system.*jasperreports/.*=Nobody
.*system.*jfree/.*=Nobody
.*system.*kettle/.*=Nobody
.*system.*logs/.*=Nobody
.*system.*metadata/.*=Nobody
.*system.*mondrian/.*=Nobody
.*system.*olap/.*=Nobody
.*system.*quartz/.*=Nobody
.*system.*simple-jndi/.*=Nobody
.*system.*smtp-email/.*=Nobody
.*system.*ui/.*=Nobody
.*system.*analysistemplate.tpl.*=Nobody
.*system.*\.\./.*=Nobody
\A/.*\Z=Authenticated,ea_admin
]]>
</value>
</property>
</bean>
</beans>

1. Restart the server and navigate to the Pentaho home page in a web browser (http://localhost:8080/pentaho). If successful, it will redirect you to the CAS login page, and once authenticated redirect back to the main body of pentaho.

Connecting CAS to LDAP

1. Download Spring-ldap-1.3.1.jar from a site such as http://www.jarvana.com/jarvana/archive-details/org/springframework/ldap/spring-ldap/1.3.1.RELEASE/spring-ldap-1.3.1.RELEASE-all.jar or similar version.
2. Download cas-server-ldap-3.0.5.jar or similar from a site such as http://developer.jasig.org/repo/content/repositories/m1/cas/jars/
3. Download LdapTemplate-1.0.2.jar or similar version from a site such as http://mvnrepository.com/artifact/net.sf.ldaptemplate/ldaptemplate/1.0.2
4. Place all of these jar files in the CAS Server’s WEB-INF/lib directory (In this case, biserver-ce/tomcat/webapps/cas-server-webapp-3.4.8/WEB-INF/lib).
5. Edit the deployerConfigContext.xml file in CAS Server’s WEB-INF directory (biserver-ce/tomcat/webapps/cas-server-webapp-3.4.8/WEB-INF/) and add to the end before the final </beans>  tag:

<bean id=”contextSource” class=”org.jasig.cas.adaptors.ldap.util.AuthenticatedLdapContextSource”>
<property name=”pooled” value=”false”/>
<property name=”urls”>
<list>
<value>ldap://localhost:389</value>
</list>
</property>
<property name=”password” value=”secret”/>
<property name=”baseEnvironmentProperties”>
<map>
<entry key=”java.naming.security.authentication” value=”simple” />
</map>
</property>
</bean>

1. In the same file, replace the Bean named SimpleTestUsernamePasswordAuthenticationHandler with this:
2. <bean class=”org.jasig.cas.adaptors.ldap.BindLdapAuthenticationHandler”>
   <property name=”filter” value=”uid=%u” />
   <property name=”searchBase” value=”ou=people,dc=datamensional-Virtualbox” />
   <property name=”contextSource” ref=”contextSource” />
   </bean>
3. In a web browser, navigate to the CAS login page or any app integrated with it.  You should be able to log in using the credentials provided on the connected ldap server.