org.apache.shiro.realm.jdbc

Class JdbcRealm

java.lang.Object

org.apache.shiro.realm.CachingRealm

org.apache.shiro.realm.AuthenticatingRealm

org.apache.shiro.realm.AuthorizingRealm

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

Nested Classes

Modifier and Type	Class and Description
static class	JdbcRealm.SaltStyle Password hash salt configuration.

Field Summary

Fields

Modifier and Type	Field and Description
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 boolean	saltIsBase64Encoded
protected JdbcRealm.SaltStyle	saltStyle
protected String	userRolesQuery

Constructor Summary

Constructors

Constructor and Description
JdbcRealm()

Method Summary

Modifier and Type	Method and Description
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	setSaltIsBase64Encoded(boolean saltIsBase64Encoded) Makes it possible to switch off base64 encoding of password salt.
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, getPermissions, getRolePermissionResolver, hasAllRoles, hasRole, hasRole, hasRoles, hasRoles, isAuthorizationCachingEnabled, isPermitted, 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

saltIsBase64Encoded

protected boolean saltIsBase64Encoded

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 a single column, containing the permission. 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.

setSaltIsBase64Encoded

public void setSaltIsBase64Encoded(boolean saltIsBase64Encoded)

Makes it possible to switch off base64 encoding of password salt. The default value is true, ie. expect the salt from a string value in a database to be base64 encoded.

Parameters:

saltIsBase64Encoded - the saltIsBase64Encoded 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)