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 Acegi 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-acegi-security.xml is a standard Acegi Security setup and is well-documented in the Acegi Security documentation. Where the configuration strays from the Acegi 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 Acegi Security. The Acegi Security class that processes form posts is AuthenticationProcessingFilter.

Form-Based Authentication Walkthrough

What does the login process look like?

When using the PCI (without single sign-on (SSO)), the security flows look like this:

1. User requests a resource under the pentaho context (e.g. http://localhost:8080/pentaho/Home).
2. An Acegi Security filter finds no existing authentication and sends a redirect to the configured login page, but after saving the originally requested resource.
3. User submits the login page.
4. An Acegi Security filter processes the username and password (username/password combination is validated and roles are fetched).
5. Acegi Security uses the roles along with the rules in applicationContext-acegi-security.xml to grant or deny access to the requested resource.
6. If access is granted, Acegi Security sends a redirect to the user for the originally requested resource. Otherwise, Acegi Security sends an HTTP 403 code to the user.
7. If access is granted, user requests (again) the resource under the pentaho context and an Acegi Security filter finds an existing authentication and allows the request to proceed.

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. This requires a new bean definition:

<bean id="pentahoSecurityStartupFilter"
  class="org.pentaho.platform.web.http.security.SecurityStartupFilter" />

This bean is then added to 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? The login page should test for login_error=2 and print the appropriate message describing what just happened.

<bean id="httpSessionReuseDetectionFilter"
  class="org.pentaho.platform.web.http.security.HttpSessionReuseDetectionFilter">
  <property name="filterProcessesUrl" value="/j_acegi_security_check" />
  <property name="sessionReuseDetectedUrl" value="/Login?login_error=2" />
</bean>

Logout Handling

PentahoLogoutHandler

PentahoLogoutHandler executes various cleanup tasks when the user logs out.

<bean id="logoutFilter"
  class="org.acegisecurity.ui.logout.LogoutFilter">
  <constructor-arg value="/index.jsp" />
  <!-- URL redirected to after logout -->
  <constructor-arg>
    <list>
      <bean
        class="org.pentaho.platform.web.http.security.PentahoLogoutHandler" />
      <ref bean="rememberMeServices" />
      <bean
        class="org.acegisecurity.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. Acegi Security implements Basic authentication using BasicProcessingFilter and BasicProcessingFilterEntryPoint.

Basic authentication is enabled by default. 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 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:

• userid=value - the userid to authenticate
• password=value - the user's password (clear-text)

RequestParameterAuthenticationFilter

RequestParameterAuthenticationFilter provides security services for Pentaho Spreadsheet Services (PSS). If you are using PSS, add this filter, along with the associated RequestParameterFilterEntryPoint bean to your Spring config.

<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 pentahoSecurityStartupFilter needs to be preceded by the httpSessionContextIntegrationFilter. Otherwise, when the Pentaho startup filter is triggered, the java.security.Principal will not be in the session and will fail.

<bean id="filterChainProxy"
  class="org.acegisecurity.util.FilterChainProxy">
  <property name="filterInvocationDefinitionSource">
    <value>
      <![CDATA[CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
      PATTERN_TYPE_APACHE_ANT
      /**=securityContextHolderAwareRequestFilter,httpSessionContextIntegrationFilter,httpSessionReuseDetectionFilter, \
      logoutFilter,authenticationProcessingFilter,basicProcessingFilter,requestParameterProcessingFilter,rememberMeProcessingFilter, \
      anonymousProcessingFilter,pentahoSecurityStartupFilter,switchUserProcessingFilter,exceptionTranslationFilter, \
      filterInvocationInterceptor]]>
    </value>
  </property>
</bean>