Spring Security Framework

org.springframework.security.userdetails.jdbc
Class JdbcDaoImpl

java.lang.Object
  extended by org.springframework.dao.support.DaoSupport
      extended by org.springframework.jdbc.core.support.JdbcDaoSupport
          extended by org.springframework.security.userdetails.jdbc.JdbcDaoImpl
All Implemented Interfaces:
InitializingBean, UserDetailsService
Direct Known Subclasses:
JdbcUserDetailsManager

public class JdbcDaoImpl
extends JdbcDaoSupport
implements UserDetailsService

UserDetailsServiceRetrieves implementation which retrieves the user details (username, password, enabled flag, and authorities) from a database using JDBC queries.

Default Schema

A default database schema is assumed, with two tables "users" and "authorities".

The Users table

This table contains the login name, password and enabled status of the user.
Column
username
password
enabled

The Authorities Table

Column
username
authority
If you are using an existing schema you will have to set the queries usersByUsernameQuery and authoritiesByUsernameQuery to match your database setup (see DEF_USERS_BY_USERNAME_QUERY and DEF_AUTHORITIES_BY_USERNAME_QUERY).

In order to minimise backward compatibility issues, this implementation doesn't recognise the expiration of user accounts or the expiration of user credentials. However, it does recognise and honour the user enabled/disabled column. This should map to a boolean type in the result set (the SQL type will depend on the database you are using). All the other columns map to Strings.

Group Support

Support for group-based authorities can be enabled by setting the enableGroups property to true (you may also then wish to set enableAuthorities to false to disable loading of authorities directly). With this approach, authorities are allocated to groups and a user's authorities are determined based on the groups they are a member of. The net result is the same (a UserDetails containing a set of GrantedAuthoritys is loaded), but the different persistence strategy may be more suitable for the administration of some applications.

When groups are being used, the tables "groups", "group_members" and "group_authorities" are used. See DEF_GROUP_AUTHORITIES_BY_USERNAME_QUERY for the default query which is used to load the group authorities. Again you can customize this by setting the groupAuthoritiesByUsernameQuery property, but the format of the rows returned should match the default.

Version:
$Id$
Author:
Ben Alex, colin sampaleanu, Luke Taylor

Field Summary
static String DEF_AUTHORITIES_BY_USERNAME_QUERY
           
static String DEF_GROUP_AUTHORITIES_BY_USERNAME_QUERY
           
static String DEF_USERS_BY_USERNAME_QUERY
           
protected  MessageSourceAccessor messages
           
 
Fields inherited from class org.springframework.dao.support.DaoSupport
logger
 
Constructor Summary
JdbcDaoImpl()
           
 
Method Summary
protected  void addCustomAuthorities(String username, List authorities)
          Allows subclasses to add their own granted authorities to the list to be returned in the User.
protected  UserDetails createUserDetails(String username, UserDetails userFromUserQuery, GrantedAuthority[] combinedAuthorities)
          Can be overridden to customize the creation of the final UserDetailsObject returnd from loadUserByUsername.
protected  String getAuthoritiesByUsernameQuery()
           
protected  boolean getEnableAuthorities()
           
protected  boolean getEnableGroups()
           
protected  String getRolePrefix()
           
 String getUsersByUsernameQuery()
           
protected  void initDao()
           
protected  boolean isUsernameBasedPrimaryKey()
           
protected  List loadGroupAuthorities(String username)
           
protected  List loadUserAuthorities(String username)
          Loads authorities by executing the authoritiesByUsernameQuery.
 UserDetails loadUserByUsername(String username)
          Locates the user based on the username.
protected  List loadUsersByUsername(String username)
          Executes the usersByUsernameQuery and returns a list of UserDetails objects (there should normally only be one matching user).
 void setAuthoritiesByUsernameQuery(String queryString)
          Allows the default query string used to retrieve authorities based on username to be overriden, if default table or column names need to be changed.
 void setEnableAuthorities(boolean enableAuthorities)
          Enables loading of authorities (roles) from the authorities table.
 void setEnableGroups(boolean enableGroups)
          Enables support for group authorities.
 void setGroupAuthoritiesByUsernameQuery(String queryString)
          Allows the default query string used to retrieve group authorities based on username to be overriden, if default table or column names need to be changed.
 void setRolePrefix(String rolePrefix)
          Allows a default role prefix to be specified.
 void setUsernameBasedPrimaryKey(boolean usernameBasedPrimaryKey)
          If true (the default), indicates the getUsersByUsernameQuery() returns a username in response to a query.
 void setUsersByUsernameQuery(String usersByUsernameQueryString)
          Allows the default query string used to retrieve users based on username to be overriden, if default table or column names need to be changed.
 
Methods inherited from class org.springframework.jdbc.core.support.JdbcDaoSupport
checkDaoConfig, createJdbcTemplate, getConnection, getDataSource, getExceptionTranslator, getJdbcTemplate, initTemplateConfig, releaseConnection, setDataSource, setJdbcTemplate
 
Methods inherited from class org.springframework.dao.support.DaoSupport
afterPropertiesSet
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEF_USERS_BY_USERNAME_QUERY

public static final String DEF_USERS_BY_USERNAME_QUERY
See Also:
Constant Field Values

DEF_AUTHORITIES_BY_USERNAME_QUERY

public static final String DEF_AUTHORITIES_BY_USERNAME_QUERY
See Also:
Constant Field Values

DEF_GROUP_AUTHORITIES_BY_USERNAME_QUERY

public static final String DEF_GROUP_AUTHORITIES_BY_USERNAME_QUERY
See Also:
Constant Field Values

messages

protected MessageSourceAccessor messages
Constructor Detail

JdbcDaoImpl

public JdbcDaoImpl()
Method Detail

addCustomAuthorities

protected void addCustomAuthorities(String username,
                                    List authorities)
Allows subclasses to add their own granted authorities to the list to be returned in the User.

Parameters:
username - the username, for use by finder methods
authorities - the current granted authorities, as populated from the authoritiesByUsername mapping

getUsersByUsernameQuery

public String getUsersByUsernameQuery()

initDao

protected void initDao()
                throws ApplicationContextException
Overrides:
initDao in class DaoSupport
Throws:
ApplicationContextException

loadUserByUsername

public UserDetails loadUserByUsername(String username)
                               throws UsernameNotFoundException,
                                      DataAccessException
Description copied from interface: UserDetailsService
Locates the user based on the username. In the actual implementation, the search may possibly be case insensitive, or case insensitive depending on how the implementaion instance is configured. In this case, the UserDetails object that comes back may have a username that is of a different case than what was actually requested..

Specified by:
loadUserByUsername in interface UserDetailsService
Parameters:
username - the username presented to the DaoAuthenticationProvider
Returns:
a fully populated user record (never null)
Throws:
UsernameNotFoundException - if the user could not be found or the user has no GrantedAuthority
DataAccessException - if user could not be found for a repository-specific reason

loadUsersByUsername

protected List loadUsersByUsername(String username)
Executes the usersByUsernameQuery and returns a list of UserDetails objects (there should normally only be one matching user).


loadUserAuthorities

protected List loadUserAuthorities(String username)
Loads authorities by executing the authoritiesByUsernameQuery.

Returns:
a list of GrantedAuthority objects for the user

loadGroupAuthorities

protected List loadGroupAuthorities(String username)

createUserDetails

protected UserDetails createUserDetails(String username,
                                        UserDetails userFromUserQuery,
                                        GrantedAuthority[] combinedAuthorities)
Can be overridden to customize the creation of the final UserDetailsObject returnd from loadUserByUsername.

Parameters:
username - the name originally passed to loadUserByUsername
userFromUserQuery - the object returned from the execution of the
combinedAuthorities - the combined array of authorities from all the authority loading queries.
Returns:
the final UserDetails which should be used in the system.

setAuthoritiesByUsernameQuery

public void setAuthoritiesByUsernameQuery(String queryString)
Allows the default query string used to retrieve authorities based on username to be overriden, if default table or column names need to be changed. The default query is DEF_AUTHORITIES_BY_USERNAME_QUERY; when modifying this query, ensure that all returned columns are mapped back to the same column names as in the default query.

Parameters:
queryString - The query string to set

getAuthoritiesByUsernameQuery

protected String getAuthoritiesByUsernameQuery()

setGroupAuthoritiesByUsernameQuery

public void setGroupAuthoritiesByUsernameQuery(String queryString)
Allows the default query string used to retrieve group authorities based on username to be overriden, if default table or column names need to be changed. The default query is DEF_GROUP_AUTHORITIES_BY_USERNAME_QUERY; when modifying this query, ensure that all returned columns are mapped back to the same column names as in the default query.

Parameters:
queryString - The query string to set

setRolePrefix

public void setRolePrefix(String rolePrefix)
Allows a default role prefix to be specified. If this is set to a non-empty value, then it is automatically prepended to any roles read in from the db. This may for example be used to add the ROLE_ prefix expected to exist in role names (by default) by some other Spring Security classes, in the case that the prefix is not already present in the db.

Parameters:
rolePrefix - the new prefix

getRolePrefix

protected String getRolePrefix()

setUsernameBasedPrimaryKey

public void setUsernameBasedPrimaryKey(boolean usernameBasedPrimaryKey)
If true (the default), indicates the getUsersByUsernameQuery() returns a username in response to a query. If false, indicates that a primary key is used instead. If set to true, the class will use the database-derived username in the returned UserDetails. If false, the class will use the loadUserByUsername(String) derived username in the returned UserDetails.

Parameters:
usernameBasedPrimaryKey - true if the mapping queries return the username String, or false if the mapping returns a database primary key.

isUsernameBasedPrimaryKey

protected boolean isUsernameBasedPrimaryKey()

setUsersByUsernameQuery

public void setUsersByUsernameQuery(String usersByUsernameQueryString)
Allows the default query string used to retrieve users based on username to be overriden, if default table or column names need to be changed. The default query is DEF_USERS_BY_USERNAME_QUERY; when modifying this query, ensure that all returned columns are mapped back to the same column names as in the default query. If the 'enabled' column does not exist in the source db, a permanent true value for this column may be returned by using a query similar to
 "SELECT username,password,'true' as enabled FROM users WHERE username = ?"

Parameters:
usersByUsernameQueryString - The query string to set

getEnableAuthorities

protected boolean getEnableAuthorities()

setEnableAuthorities

public void setEnableAuthorities(boolean enableAuthorities)
Enables loading of authorities (roles) from the authorities table. Defaults to true


getEnableGroups

protected boolean getEnableGroups()

setEnableGroups

public void setEnableGroups(boolean enableGroups)
Enables support for group authorities. Defaults to false

Parameters:
enableGroups -

Spring Security Framework

Copyright © 2004-2010 SpringSource, Inc. All Rights Reserved.