org.apache.shiro.realm.jdbc
Class JdbcRealm

java.lang.Object
  extended by org.apache.shiro.realm.CachingRealm
      extended by org.apache.shiro.realm.AuthenticatingRealm
          extended by org.apache.shiro.realm.AuthorizingRealm
              extended by org.apache.shiro.realm.jdbc.JdbcRealm
All Implemented Interfaces:
LogoutAware, Authorizer, PermissionResolverAware, RolePermissionResolverAware, CacheManagerAware, Realm, Initializable, Nameable

public class JdbcRealm
extends AuthorizingRealm

Realm that allows authentication and authorization via JDBC calls. The default queries suggest a potential schema for retrieving the user's password for authentication, and querying for a user's roles and permissions. The default queries can be overridden by setting the query properties of the realm.

If the default implementation of authentication and authorization cannot handle your schema, this class can be subclassed and the appropriate methods overridden. (usually doGetAuthenticationInfo(org.apache.shiro.authc.AuthenticationToken), getRoleNamesForUser(java.sql.Connection,String), and/or getPermissions(java.sql.Connection,String,java.util.Collection)

This realm supports caching by extending from AuthorizingRealm.

Since:
0.2

Nested Class Summary
static class JdbcRealm.SaltStyle
          Password hash salt configuration.
 
Field Summary
protected  String authenticationQuery
           
protected  DataSource dataSource
           
protected static String DEFAULT_AUTHENTICATION_QUERY
          The default query used to retrieve account data for the user.
protected static String DEFAULT_PERMISSIONS_QUERY
          The default query used to retrieve permissions that apply to a particular role.
protected static String DEFAULT_SALTED_AUTHENTICATION_QUERY
          The default query used to retrieve account data for the user when saltStyle is COLUMN.
protected static String DEFAULT_USER_ROLES_QUERY
          The default query used to retrieve the roles that apply to a user.
protected  boolean permissionsLookupEnabled
           
protected  String permissionsQuery
           
protected  JdbcRealm.SaltStyle saltStyle
           
protected  String userRolesQuery
           
 
Constructor Summary
JdbcRealm()
           
 
Method Summary
protected  AuthenticationInfo doGetAuthenticationInfo(AuthenticationToken token)
          Retrieves authentication data from an implementation-specific datasource (RDBMS, LDAP, etc) for the given authentication token.
protected  AuthorizationInfo doGetAuthorizationInfo(PrincipalCollection principals)
          This implementation of the interface expects the principals collection to return a String username keyed off of this realm's name
protected  Set<String> getPermissions(Connection conn, String username, Collection<String> roleNames)
           
protected  Set<String> getRoleNamesForUser(Connection conn, String username)
           
protected  String getSaltForUser(String username)
           
 void setAuthenticationQuery(String authenticationQuery)
          Overrides the default query used to retrieve a user's password during authentication.
 void setDataSource(DataSource dataSource)
          Sets the datasource that should be used to retrieve connections used by this realm.
 void setPermissionsLookupEnabled(boolean permissionsLookupEnabled)
          Enables lookup of permissions during authorization.
 void setPermissionsQuery(String permissionsQuery)
          Overrides the default query used to retrieve a user's permissions during authorization.
 void setSaltStyle(JdbcRealm.SaltStyle saltStyle)
          Sets the salt style.
 void setUserRolesQuery(String userRolesQuery)
          Overrides the default query used to retrieve a user's roles during authorization.
 
Methods inherited from class org.apache.shiro.realm.AuthorizingRealm
afterCacheManagerSet, checkPermission, checkPermission, checkPermission, checkPermissions, checkPermissions, checkPermissions, checkRole, checkRole, checkRoles, checkRoles, checkRoles, clearCachedAuthorizationInfo, doClearCache, getAuthorizationCache, getAuthorizationCacheKey, getAuthorizationCacheName, getAuthorizationInfo, getPermissionResolver, getRolePermissionResolver, hasAllRoles, hasRole, hasRole, hasRoles, hasRoles, isAuthorizationCachingEnabled, isPermitted, isPermitted, isPermitted, isPermitted, isPermitted, isPermittedAll, isPermittedAll, isPermittedAll, onInit, setAuthorizationCache, setAuthorizationCacheName, setAuthorizationCachingEnabled, setName, setPermissionResolver, setRolePermissionResolver
 
Methods inherited from class org.apache.shiro.realm.AuthenticatingRealm
assertCredentialsMatch, clearCachedAuthenticationInfo, getAuthenticationCache, getAuthenticationCacheKey, getAuthenticationCacheKey, getAuthenticationCacheName, getAuthenticationInfo, getAuthenticationTokenClass, getCredentialsMatcher, init, isAuthenticationCachingEnabled, isAuthenticationCachingEnabled, setAuthenticationCache, setAuthenticationCacheName, setAuthenticationCachingEnabled, setAuthenticationTokenClass, setCredentialsMatcher, supports
 
Methods inherited from class org.apache.shiro.realm.CachingRealm
clearCache, getAvailablePrincipal, getCacheManager, getName, isCachingEnabled, onLogout, setCacheManager, setCachingEnabled
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.apache.shiro.util.Initializable
init
 

Field Detail

DEFAULT_AUTHENTICATION_QUERY

protected static final String DEFAULT_AUTHENTICATION_QUERY
The default query used to retrieve account data for the user.

See Also:
Constant Field Values

DEFAULT_SALTED_AUTHENTICATION_QUERY

protected static final String DEFAULT_SALTED_AUTHENTICATION_QUERY
The default query used to retrieve account data for the user when saltStyle is COLUMN.

See Also:
Constant Field Values

DEFAULT_USER_ROLES_QUERY

protected static final String DEFAULT_USER_ROLES_QUERY
The default query used to retrieve the roles that apply to a user.

See Also:
Constant Field Values

DEFAULT_PERMISSIONS_QUERY

protected static final String DEFAULT_PERMISSIONS_QUERY
The default query used to retrieve permissions that apply to a particular role.

See Also:
Constant Field Values

dataSource

protected DataSource dataSource

authenticationQuery

protected String authenticationQuery

userRolesQuery

protected String userRolesQuery

permissionsQuery

protected String permissionsQuery

permissionsLookupEnabled

protected boolean permissionsLookupEnabled

saltStyle

protected JdbcRealm.SaltStyle saltStyle
Constructor Detail

JdbcRealm

public JdbcRealm()
Method Detail

setDataSource

public void setDataSource(DataSource dataSource)
Sets the datasource that should be used to retrieve connections used by this realm.

Parameters:
dataSource - the SQL data source.

setAuthenticationQuery

public void setAuthenticationQuery(String authenticationQuery)
Overrides the default query used to retrieve a user's password during authentication. When using the default implementation, this query must take the user's username as a single parameter and return a single result with the user's password as the first column. If you require a solution that does not match this query structure, you can override doGetAuthenticationInfo(org.apache.shiro.authc.AuthenticationToken) or just getPasswordForUser(java.sql.Connection,String)

Parameters:
authenticationQuery - the query to use for authentication.
See Also:
DEFAULT_AUTHENTICATION_QUERY

setUserRolesQuery

public void setUserRolesQuery(String userRolesQuery)
Overrides the default query used to retrieve a user's roles during authorization. When using the default implementation, this query must take the user's username as a single parameter and return a row per role with a single column containing the role name. If you require a solution that does not match this query structure, you can override doGetAuthorizationInfo(PrincipalCollection) or just getRoleNamesForUser(java.sql.Connection,String)

Parameters:
userRolesQuery - the query to use for retrieving a user's roles.
See Also:
DEFAULT_USER_ROLES_QUERY

setPermissionsQuery

public void setPermissionsQuery(String permissionsQuery)
Overrides the default query used to retrieve a user's permissions during authorization. When using the default implementation, this query must take a role name as the single parameter and return a row per permission with three columns containing the fully qualified name of the permission class, the permission name, and the permission actions (in that order). If you require a solution that does not match this query structure, you can override doGetAuthorizationInfo(org.apache.shiro.subject.PrincipalCollection) or just getPermissions(java.sql.Connection,String,java.util.Collection)

Permissions are only retrieved if you set permissionsLookupEnabled to true. Otherwise, this query is ignored.

Parameters:
permissionsQuery - the query to use for retrieving permissions for a role.
See Also:
DEFAULT_PERMISSIONS_QUERY, setPermissionsLookupEnabled(boolean)

setPermissionsLookupEnabled

public void setPermissionsLookupEnabled(boolean permissionsLookupEnabled)
Enables lookup of permissions during authorization. The default is "false" - meaning that only roles are associated with a user. Set this to true in order to lookup roles and permissions.

Parameters:
permissionsLookupEnabled - true if permissions should be looked up during authorization, or false if only roles should be looked up.

setSaltStyle

public void setSaltStyle(JdbcRealm.SaltStyle saltStyle)
Sets the salt style. See saltStyle.

Parameters:
saltStyle - new SaltStyle to set.

doGetAuthenticationInfo

protected AuthenticationInfo doGetAuthenticationInfo(AuthenticationToken token)
                                              throws AuthenticationException
Description copied from class: AuthenticatingRealm
Retrieves authentication data from an implementation-specific datasource (RDBMS, LDAP, etc) for the given authentication token.

For most datasources, this means just 'pulling' authentication data for an associated subject/user and nothing more and letting Shiro do the rest. But in some systems, this method could actually perform EIS specific log-in logic in addition to just retrieving data - it is up to the Realm implementation.

A null return value means that no account could be associated with the specified token.

Specified by:
doGetAuthenticationInfo in class AuthenticatingRealm
Parameters:
token - the authentication token containing the user's principal and credentials.
Returns:
an AuthenticationInfo object containing account data resulting from the authentication ONLY if the lookup is successful (i.e. account exists and is valid, etc.)
Throws:
AuthenticationException - if there is an error acquiring data or performing realm-specific authentication logic for the specified token

doGetAuthorizationInfo

protected AuthorizationInfo doGetAuthorizationInfo(PrincipalCollection principals)
This implementation of the interface expects the principals collection to return a String username keyed off of this realm's name

Specified by:
doGetAuthorizationInfo in class AuthorizingRealm
Parameters:
principals - the primary identifying principals of the AuthorizationInfo that should be retrieved.
Returns:
the AuthorizationInfo associated with this principals.
See Also:
AuthorizingRealm.getAuthorizationInfo(org.apache.shiro.subject.PrincipalCollection)

getRoleNamesForUser

protected Set<String> getRoleNamesForUser(Connection conn,
                                          String username)
                                   throws SQLException
Throws:
SQLException

getPermissions

protected Set<String> getPermissions(Connection conn,
                                     String username,
                                     Collection<String> roleNames)
                              throws SQLException
Throws:
SQLException

getSaltForUser

protected String getSaltForUser(String username)


Copyright © 2004-2012 The Apache Software Foundation. All Rights Reserved.