Security Data Access Objects
Getting Security Data
There are two key interfaces that fetch security data: UserDetailsService
and IUserRoleListService
. These are known as security data access objects (DAO).
UserDetailsService
The Spring Security class UserDetailsService
defines a single method: UserDetails loadUserByUsername(String username)
. Given a username, it returns a UserDetails
instance.
IUserRoleListService
The Pentaho class IUserRoleListService
defines 4 methods:
GrantedAuthority[] getAllAuthorities()
String[] getAllUsernames()
String[] getUsernamesInRole(GrantedAuthority authority)
GrantedAuthority[] getAuthoritiesForUser(String username)
For the final method above, all IUserRoleListService
implementations should delegate to the associated UserDetailsService
, if possible.
Choice of Security Back-end
An organization can keep their security data in one or more back-ends. Typical security back-ends include relational databases and directory servers accessed via LDAP. Using Spring Security, the platform offers these choices of security back-ends:
Backend |
|
|
---|---|---|
In-Memory* |
|
|
DBMS |
|
|
Directory Server |
|
|
* An in-memory security back-end is primarily provided for testing or small user populations.
Configuration Files
The platform stores its security data access object (DAO) configuration files in the pentaho-solutions/system
directory. The table below enumerates these files.
Filename |
Description |
---|---|
|
Defines a |
|
Defines an |
One might ask: Why are there so many configuration files? The Spring Security Contacts Sample Application doesn't have this many! The reason for all the files is (1) to partition the files to allow them to be swapped out in order to connect to different security backends and (2) to provide example configurations for each of the three supported security backends: memory, dbms, and ldap.
The configuration files that are enabled are specified in pentaho-solutions/system/pentaho-spring-beans.xml
.
<beans> <!-- omitted --> <import resource="applicationContext-spring-security.xml" /> <import resource="applicationContext-common-authorization.xml" /> <import resource="applicationContext-spring-security-*.xml" /> <import resource="applicationContext-pentaho-security-*.xml" /> <!-- omitted --> </beans>
To switch to an LDAP-based security backend, you simply replace the *
above with ldap
. To switch to memory-based, use memory
. And finally, to switch to db-based, use jdbc
.
Getting Password and Granted Authorities of a User
The DAO that has the responsibility of fetching a password and granted authorities, given a username, is an instance of UserDetailsService
and is defined in applicationContext-spring-security-*.xml
.
You'll notice a naming convention in the files listed in this section. Each UserDetailsService
implementation has a bean name of userDetailsService
. Why is that? It's because applicationContext-spring-security.xml
has a dependency on a bean named userDetailsService
. For this reason, do not change the names of these beans.
Note: The vast majority of the configuration contained in the
applicationContext-spring-security-*.xml
files 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.
Memory
This DAO reads usernames, passwords, and roles specified in a Spring XML file.
The InMemoryDaoImpl
class uses an instance of UserMap
. But a UserMap
restricts how the information passed into its constructor can be accessed. For example, one cannot ask the question of a UserMap
: What are all the users? Since the platform user management system needs to answer this exact question, the platform comes with a way to intercept the information passed into a UserMap
constructor. The information passed into the UserMap
constructor is intercepted as a String
and later fed into a UserMapFactoryBean
for use in the InMemoryDaoImpl
.
But InMemoryDaoImpl
doesn't take a UserMapFactoryBean
! It takes a UserMap
! The secret to this working lies in the Spring type called FactoryBean
. When Spring detects a bean of this type, instead of returning the instance, it returns instance.getObject()
.
<bean id="userDetailsService" class="org.springframework.security.userdetails.memory.InMemoryDaoImpl"> <property name="userMap"> <ref local="userMapFactoryBean" /> </property> </bean> <bean id="userMap" class="java.lang.String"> <constructor-arg type="java.lang.String"> <!-- case matters --> <value> <![CDATA[joe=password,ceo,Admin,User,Authenticated suzy=password,cto,is,User,Authenticated pat=password,dev,User,Authenticated tiffany=password,dev,devmgr,User,Authenticated]]> </value> </constructor-arg> </bean> <bean id="userMapFactoryBean" class="org.pentaho.platform.plugin.services.security.userrole.memory.UserMapFactoryBean"> <property name="userMap"> <ref local="userMap" /> </property> </bean>
DBMS
The configuration for this section does not stray from the default Spring Security distribution.
LDAP
The configuration for this section does not stray from the default Spring Security distribution. However, here are some tips.
Note: According to Spring Security Issue SEC-251, you can use {
1
} (as opposed to {0
}) in yourgroupSearchFilter
which will be replaced with a username. ({0
} will be replaced with a user DN.)
Warning: Be careful about ampersand symbols within your LDAP search filters. They must be escaped!
Getting All Usernames and Roles
The DAO that has the responsibility of fetching all usernames and authorities (plus a few other responsibilities) is an instance of IUserRoleListService
and is defined in applicationContext-pentaho-security-*.xml
.
Warning: The
UserDetailsRoleListService
class introduced in this section wraps aIUserRoleListService
instance and must be defined in the Spring XML Beans document for proper functioning of the Pentaho BI Platform.
Memory
The in-memory implementation of IUserRoleListService
is InMemoryUserRoleListService
. Notice the bean below named userRoleListEnhancedUserMapFactoryBean
? It refers to the bean defined in applicationContext-spring-security-memory.xml
. It uses the same FactoryBean
trick that is used by UserMapFactoryBean
. In an indirect fashion, the information contained in a UserMap
is passed into the InMemoryUserRoleListService
.
There's one more property to mention: allAuthorities
. This defines all authorities that are allowed to be granted to users. Why can't the platform get this information from the UserRoleListEnhancedUserMap
? That's because the UserRoleListEnhancedUserMap
might only contain a subset of all the available authorities.
<bean id="userRoleListEnhancedUserMapFactoryBean" class="org.pentaho.platform.plugin.services.security.userrole.memory.UserRoleListEnhancedUserMapFactoryBean"> <property name="userMap" ref="userMap" /> </bean> <bean id="inMemoryUserRoleListService" class="org.pentaho.platform.plugin.services.security.userrole.memory.InMemoryUserRoleListService"> <property name="userRoleListEnhancedUserMap"> <ref local="userRoleListEnhancedUserMapFactoryBean" /> </property> <property name="userDetailsService" ref="userDetailsService" /> <property name="allAuthorities"> <list> <bean class="org.springframework.security.GrantedAuthorityImpl"> <constructor-arg value="Authenticated" /> </bean> <bean class="org.springframework.security.GrantedAuthorityImpl"> <constructor-arg value="Admin" /> </bean> <!-- some authorities omitted --> </list> </property> <property name="usernameComparator"> <bean class="org.pentaho.platform.engine.security.DefaultUsernameComparator" /> </property> <property name="grantedAuthorityComparator"> <bean class="org.pentaho.platform.engine.security.DefaultGrantedAuthorityComparator" /> </property> </bean> <bean id="pentahoUserRoleListService" class="org.pentaho.platform.engine.security.userrole.UserDetailsRoleListService"> <property name="userRoleListService"> <ref local="inMemoryUserRoleListService" /> </property> </bean>
DBMS
The DBMS implementation of IUserRoleListService
is JdbcUserRoleListService
. It is analogous to JdbcDaoImpl
. It simply has three more properties defining the SQL queries that can return the information defined by the IUserRoleListService
interface.
Note: Be sure to add
as username
andas authorities
where appropriate in your queries.
<bean id="jdbcUserRoleListService" class="org.pentaho.platform.plugin.services.security.userrole.jdbc.JdbcUserRoleListService"> <constructor-arg index="0" ref="userDetailsService" /> <property name="allAuthoritiesQuery"> <value> <![CDATA[SELECT distinct(authority) as authority FROM AUTHORITIES ORDER BY authority]]> </value> </property> <property name="allUsernamesInRoleQuery"> <value> <![CDATA[SELECT distinct(username) as username FROM GRANTED_AUTHORITIES where authority = ? ORDER BY username]]> </value> </property> <property name="allUsernamesQuery"> <value> <![CDATA[SELECT distinct(username) as username FROM USERS ORDER BY username]]> </value> </property> <property name="dataSource" ref="dataSource" /> </bean> <bean id="pentahoUserRoleListService" class="org.pentaho.platform.engine.security.userrole.UserDetailsRoleListService"> <property name="userRoleListService"> <ref local="jdbcUserRoleListService" /> </property> </bean>
LDAP
Warning: Be careful about ampersand symbols within your LDAP search filters. They must be escaped!
The LDAP implementation of IUserRoleListService
is DefaultLdapUserRoleListService
.
Before continuing, it is important to be familiar with a key JNDI class: DirContext
. This class is the interface into directory services. In particular, there is a method with the following signature:
public NamingEnumeration search(String name, String filterExpr, Object[] filterArgs, SearchControls cons) throws NamingException;
Notice the parameters to this method? In the platform, these parameters are encapsulated into LdapSearchParams
.
LdapSearchParams
LdapSearchParams
bundle together the parameters that are eventually passed into a search
call on a DirContext
instance. The best description of these parameters is in the javadoc for the DirContext
class but a brief description of each is below.
Parameter Name |
Description |
---|---|
|
The DN of the node at which to begin the search. This parameter is also referred to as a search base. |
|
A query for objects in the directory. This query can contain placeholders. This is analogous to a parameterized SQL query. See LDAP Search Filter Syntax for a quick overview of the syntax. See LDAP Search Filter Syntax for a quick overview of the syntax. |
|
The values to be substituted for the placeholders in |
|
LdapSearchParams
can only be created by LdapSearchParamsFactory
instances.
LdapSearchParamsFactory
LdapSearchParamsFactory
defines a single method:
LdapSearchParams createParams(Object[] filterArgs);
The platform provides a single implementation of this interface called LdapSearchParamsFactoryImpl
. The constructor of this class requires a name
, filterExpr
, and searchControls
--all of which go into creating LdapSearchParams
instances.
LdapSearch
The LdapSearch
interface is a generalization of org.springframework.security.ldap.LdapUserSearch
. In Spring Security's LdapUserSearch
, the goal was to find a user object in the directory; in Pentaho's LdapSearch
, the goal is to find any object in the directory. In the platform, there are two implementations of this interface: GenericLdapSearch
and UnionizingLdapSearch
.
GenericLdapSearch
GenericLdapSearch
instances are created using the four parameters shown below. The diagram below shows how GenericLdapSearch
uses these parameters to execute a search.
Parameter Name |
Description |
---|---|
|
An instance of |
|
An instance of |
|
Transforms LDAP search results into custom objects. The type of this parameter is |
|
Transforms filter arguments before passing to the |
The Transformer
interface is a simple but powerful type. Transformers can be chained together, each doing a small part of a large task. There are three transformers provided with the platform.
SearchResultToAttrValueList
SearchResultToAttrValueList
extracts the value of the token tokenName
from the attribute attributeName
which is taken from the SearchResult
input.
StringToGrantedAuthority
Authorities in a directory server are simple strings. In order to each of those strings into a GrantedAuthority
, this transformer is used. It provides the option of adding a role prefix and converting the string's case.
GrantedAuthorityToString
This class does the reverse of StringToGrantedAuthority
except that it cannot control string case. This could be used in the query for what users are in particular role. The role is passed in with a role prefix, this transformer removes it, and the new role string is passed in as a filter argument.
The picture above depicts an example wiring of LDAP-related beans.
UnionizingLdapSearch
The purpose of this class is to merge the results returned by two or more LdapSearch
instances.
DefaultLdapUserRoleListService
Remember that DefaultLdapUserRoleListService
is the LDAP implementation of IUserRoleListService
. As a consequence, it must implement the methods defined in IUserRoleListService
. Recall that those methods are: getAllAuthorities()
, getAllUsernames()
, getUsernamesInRole()
, and getAuthoritiesForUser()
. DefaultLdapUserRoleListService
implements the first three methods by delegating to three separate LdapSearch
instances--stored in its allAuthoritiesSearch
, allUsernamesSearch
, and usernamesInRoleSearch
properties. (Remember GenericLdapSearch
is an implementation of LdapSearch
.) DefaultLdapUserRoleListService
implements the last method by delegating to an LdapUserDetailsService
instance--stored in its userDetailsService
property. The userDetailsService
property is not detailed below since it is covered in the section on LdapUserDetailsService.
And since DefaultLdapUserRoleListService
is configured via Spring, the task is reduced to defining three GenericLdapSearch
instances (plus an LdapUserDetailsService
) in Spring! But before the Spring config is presented, the equivalent configuration via Java code is presented. This route is chosen since Spring configuration can be very verbose and most are more familiar with the more ubiquitous Java syntax.
// create params factory with the following settings: // search base="ou=users", // filterExpr="(objectClass=person)", LdapSearchParamsFactory paramsFactory = new LdapSearchParamsFactoryImpl( "ou=users", "(objectClass=Person)"); // create a resultsTransformer that extracts the uid attribute Transformer transformer = new SearchResultToAttrValueList("uid"); // create a GenericLdapSearch with objects created above; // (don't worry about getContextSource()--just know that // it returns an ContextSource) LdapSearch allUsernamesSearch = new GenericLdapSearch( getContextSource(), paramsFactory, transformer);
Now the equivalent Spring config is presented.
<bean id="allUsernamesSearch" class="org.pentaho.platform.plugin.services.security.userrole.ldap.search.GenericLdapSearch"> <constructor-arg index="0" ref="contextSource" /> <constructor-arg index="1"> <bean class="org.pentaho.platform.plugin.services.security.userrole.ldap.search.LdapSearchParamsFactoryImpl"> <constructor-arg index="0" value="ou=users" /> <constructor-arg index="1" value="objectClass=Person" /> </bean> </constructor-arg> <constructor-arg index="2"> <bean class="org.pentaho.platform.plugin.services.security.userrole.ldap.transform.SearchResultToAttrValueList"> <constructor-arg index="0" value="uid" /> </bean> </constructor-arg> </bean>
Note: Why are
constructor-arg
elements used? Why not call property setters instead? The reason for this is that the only way to set some of the properties in the example below is to pass those properties in during object creation. This enforces the policy that these properties should be set once and never changed.
The steps to create a GenericLdapSearch
have been introduced. Follow these steps to create the three searches required by DefaultLdapUserRoleListService
. The only remaining property to set on DefaultLdapUserRoleListService
is userDetailsService
. Since that was introduced in the section on LdapUserDetailsService, it will not be covered again here.
The contents of application-pentaho-security-ldap.xml
is below. Notice that some of the bean references refer to beans defined in applicationContext-spring-security-ldap.xml
.
<!-- be sure to escape ampersands --> <bean id="allUsernamesSearch" class="org.pentaho.platform.plugin.services.security.userrole.ldap.search.GenericLdapSearch"> <constructor-arg index="0" ref="contextSource" /> <constructor-arg index="1"> <bean class="org.pentaho.platform.plugin.services.security.userrole.ldap.search.LdapSearchParamsFactoryImpl"> <constructor-arg index="0" value="ou=users" /> <constructor-arg index="1" value="objectClass=Person" /> </bean> </constructor-arg> <constructor-arg index="2"> <bean class="org.pentaho.platform.plugin.services.security.userrole.ldap.transform.SearchResultToAttrValueList"> <constructor-arg index="0" value="uid" /> </bean> </constructor-arg> </bean> <!-- be sure to escape ampersands --> <bean id="allAuthoritiesSearch" class="org.pentaho.platform.plugin.services.security.userrole.ldap.search.GenericLdapSearch"> <constructor-arg index="0" ref="contextSource" /> <constructor-arg index="1"> <bean class="org.pentaho.platform.plugin.services.security.userrole.ldap.search.LdapSearchParamsFactoryImpl"> <constructor-arg index="0" value="ou=roles" /> <constructor-arg index="1" value="objectClass=organizationalRole" /> </bean> </constructor-arg> <constructor-arg index="2"> <bean class="org.apache.commons.collections.functors.ChainedTransformer"> <constructor-arg index="0"> <list> <bean class="org.pentaho.platform.plugin.services.security.userrole.ldap.transform.SearchResultToAttrValueList"> <constructor-arg index="0" value="cn" /> </bean> <bean class="org.pentaho.platform.plugin.services.security.userrole.ldap.transform.StringToGrantedAuthority"> <property name="rolePrefix" value="" /> <property name="convertToUpperCase" value="false" /> </bean> </list> </constructor-arg> </bean> </constructor-arg> </bean> <!-- not currently used --> <bean id="usernamesInRoleSearch" class="org.pentaho.platform.plugin.services.security.userrole.ldap.search.NoOpLdapSearch"> </bean> <bean id="ldapUserRoleListService" class="org.pentaho.platform.plugin.services.security.userrole.ldap.DefaultLdapUserRoleListService"> <constructor-arg index="0" ref="contextSource" /> <property name="allAuthoritiesSearch"> <ref local="allAuthoritiesSearch" /> </property> <property name="allUsernamesSearch"> <ref local="allUsernamesSearch" /> </property> <property name="userDetailsService"> <ref bean="userDetailsService" /> </property> <property name="usernamesInRoleSearch"> <ref local="usernamesInRoleSearch" /> </property> <property name="usernameComparator"> <bean class="org.pentaho.platform.engine.security.DefaultUsernameComparator" /> </property> <property name="grantedAuthorityComparator"> <bean class="org.pentaho.platform.engine.security.DefaultGrantedAuthorityComparator" /> </property> </bean> <bean id="pentahoUserRoleListService" class="org.pentaho.platform.engine.security.userrole.UserDetailsRoleListService"> <property name="userRoleListService"> <ref local="ldapUserRoleListService" /> </property> </bean>
Just as DefaultLdapAuthoritiesPopulator
has a configurable search scope via its searchSubtree
property, LdapSearchParamsFactoryImpl
provides a way to set a search scope by passing a SearchControls
instance into the constructor. The XML below demonstrates this. If no SearchControls
is supplied via the constructor, the default search scope is ONELEVEL_SCOPE
.
<bean class="org.pentaho.platform.plugin.services.security.userrole.ldap.search.LdapSearchParamsFactoryImpl"> <constructor-arg index="0" value="ou=users" /> <constructor-arg index="1" value="objectClass=Person" /> <constructor-arg index="2"> <bean class="javax.naming.directory.SearchControls"> <!-- 2 comes from http://java.sun.com/javase/6/docs/api/javax/naming/directory/SearchControls.html#SUBTREE_SCOPE --> <property name="searchScope" value="2" /> </bean> </constructor-arg> </bean>