Authentication

Unknown macro: {scrollbar}

The act of processing a submitted username and password is called authentication. Note that authentication is a prerequisite to authorization. The Pentaho BI Platform uses Spring Security to process authentication requests. Out-of-the-box authentication mechanisms provided by the platform are form, basic, and request parameter.

The vast majority of the configuration contained in the applicationContext-spring-security.xml is a standard Spring Security setup and is well-documented in the Spring Security documentation. Where the configuration strays from the Spring Security documentation, it is documented below.

Form-Based Authentication

Form-based authentication lets developers customize the authentication user interface. While the J2EE specifications provide a standard way to specify the login page URL as well as URL authorization rules, there is still container-specific configuration to specify how to read usernames and passwords from a security datastore. This is one reason that the platform uses Spring Security. The Spring Security class that processes form posts is AuthenticationProcessingFilter.

Form-Based Authentication Walkthrough

What does the login process look like?

  1. User requests a resource from the Pentaho BI Platform.
  2. A Spring Security filter finds no existing authentication (user is anonymous) and sends a redirect to the configured login page, but after saving the originally requested resource.
  3. User submits the login page.
  4. A Spring Security filter processes the username and password (username/password combination is validated and roles are fetched).
  5. Spring Security uses the roles along with the rules in applicationContext-spring-security.xml to grant or deny access to the requested resource.
  6. Spring Security sends a redirect to the user for the originally requested resource.
  7. If access to the requested resource is granted, Spring Security allows the processing of that resource. Otherwise, Spring Security sends an HTTP 403 code to the user.

Login Handling

SecurityStartupFilter

SecurityStartupFilter allows the Pentaho BI Platform to obtain a user's credentials (java.security.Principal) and inject it into the Pentaho user session.

SecurityStartupFilter Bean Definition (applicationContext-spring-security.xml)
<bean id="pentahoSecurityStartupFilter"
  class="org.pentaho.platform.web.http.security.SecurityStartupFilter" />

This bean is referenced in the filterChainProxy bean (shown later).

HttpSessionReuseDetectionFilter

HttpSessionReuseDetectionFilter detects when an HTTP session which contains a authenticated user is attempting to authenticate again without logging out. Upon detecting this condition, the session is invalidated, the security context is cleared, and the user is redirected to sessionReuseDetectedUrl. This prevents reuse of an HTTP session which contains potentially sensitive, user-specific data. The filterProcessesUrl value should match the value of the same property in AuthenticationProcessingFilter.

Notice the login_error=2 parameter on the filterProcessesUrl? If customizing the login page, the login page should test for login_error=2 and print an appropriate message. Here is the bean definition:

HttpSessionReuseDetectionFilter Bean Definition (applicationContext-spring-security.xml)
<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>

Logout Handling

PentahoLogoutHandler

PentahoLogoutHandler executes various cleanup tasks when the user logs out.

PentahoLogoutHandler Bean Definition (applicationContext-spring-security.xml)
<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>

Logout Page

There is no logout page. The page to which a user is redirected after a logout is specified in the first constructor argument in the logoutFilter bean above.

Basic Authentication

Basic authentication is part of the HTTP specification. It is simple but relatively inflexible. Spring Security implements Basic authentication using BasicProcessingFilter and BasicProcessingFilterEntryPoint.

Basic authentication is enabled by default since various Pentaho client tools use Basic authentication to publish to the platform. There is a property of BasicProcessingFilter called ignoreFailure which affects what happens during a failed authentication attempt. By default, it is false.

Note: On a Linux system, you can run

wget --header='Authorization: Basic am9lOnBhc3N3b3Jk' --output-document='out.html' http://localhost:8080/pentaho/Navigate

to test that basic authentication is working properly. (This logs in with username=joe and password=password.)

Request Parameter Authentication

RequestParameterAuthenticationFilter provides security services for Pentaho Spreadsheet Services (PSS). It is enabled by default. It allows the user requesting access to provide his or her username and password on the query string of the URL. The credentials are unencrypted.

The parameters to pass on the query string are:

Parameter Name

Parameter Description

userid

username with which to authenticate

password

password (clear-text) for username

RequestParameterAuthenticationFilter and RequestParameterFilterEntryPoint Bean Definitions (applicationContext-spring-security.xml)
<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" />

FilterChainProxy

The FilterChainProxy with the Pentaho BI Platform filters is shown below.

Warning: Note that the end-of-line backslashes that occur in the excerpt below are present for formatting purposes only and should not be present in the actual file.

Warning: The order of the filters is critical.

FilterChainProxy Bean Definition (applicationContext-spring-security.xml)
<bean id="filterChainProxy" class="org.springframework.security.util.FilterChainProxy">
  <property name="filterInvocationDefinitionSource">
    <value>
    <![CDATA[CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
    PATTERN_TYPE_APACHE_ANT
    /**=securityContextHolderAwareRequestFilter,httpSessionContextIntegrationFilter,httpSessionReuseDetectionFilter, \
    logoutFilter,authenticationProcessingFilter,basicProcessingFilter,requestParameterProcessingFilter, \
    anonymousProcessingFilter,pentahoSecurityStartupFilter,exceptionTranslationFilter,filterInvocationInterceptor]]>
    </value>
  </property>
</bean>