org.apache.shiro.realm.ldap
Class AbstractLdapRealm

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.ldap.AbstractLdapRealm
All Implemented Interfaces:
LogoutAware, Authorizer, PermissionResolverAware, RolePermissionResolverAware, CacheManagerAware, Realm, Initializable, Nameable
Direct Known Subclasses:
ActiveDirectoryRealm

public abstract class AbstractLdapRealm
extends AuthorizingRealm

A Realm that authenticates with an LDAP server to build the Subject for a user. This implementation only returns roles for a particular user, and not permissions - but it can be subclassed to build a permission list as well.

Implementations would need to implement the queryForAuthenticationInfo(org.apache.shiro.authc.AuthenticationToken ,LdapContextFactory) and queryForAuthorizationInfo(org.apache.shiro.subject.PrincipalCollection ,LdapContextFactory) abstract methods.

By default, this implementation will create an instance of DefaultLdapContextFactory to use for creating LDAP connections using the principalSuffix, searchBase, url, systemUsername, and systemPassword properties specified on the realm. The remaining settings use the defaults of DefaultLdapContextFactory, which are usually sufficient. If more customized connections are needed, you should inject a custom LdapContextFactory, which will cause these properties specified on the realm to be ignored.

Since:
0.1
See Also:
queryForAuthenticationInfo(org.apache.shiro.authc.AuthenticationToken , LdapContextFactory), queryForAuthorizationInfo(org.apache.shiro.subject.PrincipalCollection , LdapContextFactory)

Field Summary
protected  String principalSuffix
           
protected  String searchBase
           
protected  String systemPassword
           
protected  String systemUsername
           
protected  String url
           
 
Constructor Summary
AbstractLdapRealm()
           
 
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)
          Retrieves the AuthorizationInfo for the given principals from the underlying data store.
protected  void onInit()
          Initializes this realm and potentially enables a cache, depending on configuration.
protected abstract  AuthenticationInfo queryForAuthenticationInfo(AuthenticationToken token, LdapContextFactory ldapContextFactory)
          Abstract method that should be implemented by subclasses to builds an AuthenticationInfo object by querying the LDAP context for the specified username.
protected abstract  AuthorizationInfo queryForAuthorizationInfo(PrincipalCollection principal, LdapContextFactory ldapContextFactory)
          Abstract method that should be implemented by subclasses to builds an AuthorizationInfo object by querying the LDAP context for the specified principal.
 void setLdapContextFactory(LdapContextFactory ldapContextFactory)
          Configures the LdapContextFactory implementation that is used to create LDAP connections for authentication and authorization.
 void setPrincipalSuffix(String principalSuffix)
          Used when initializing the default LdapContextFactory.
 void setSearchBase(String searchBase)
          Used when initializing the default LdapContextFactory.
 void setSystemPassword(String systemPassword)
          Used when initializing the default LdapContextFactory.
 void setSystemUsername(String systemUsername)
          Used when initializing the default LdapContextFactory.
 void setUrl(String url)
          Used when initializing the default LdapContextFactory.
 
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, 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

principalSuffix

protected String principalSuffix

searchBase

protected String searchBase

url

protected String url

systemUsername

protected String systemUsername

systemPassword

protected String systemPassword
Constructor Detail

AbstractLdapRealm

public AbstractLdapRealm()
Method Detail

setPrincipalSuffix

public void setPrincipalSuffix(String principalSuffix)
Used when initializing the default LdapContextFactory. This property is ignored if a custom LdapContextFactory is specified.

Parameters:
principalSuffix - the suffix.
See Also:
DefaultLdapContextFactory.setPrincipalSuffix(String)

setSearchBase

public void setSearchBase(String searchBase)
Used when initializing the default LdapContextFactory. This property is ignored if a custom LdapContextFactory is specified.

Parameters:
searchBase - the search base.
See Also:
DefaultLdapContextFactory.setSearchBase(String)

setUrl

public void setUrl(String url)
Used when initializing the default LdapContextFactory. This property is ignored if a custom LdapContextFactory is specified.

Parameters:
url - the LDAP url.
See Also:
DefaultLdapContextFactory.setUrl(String)

setSystemUsername

public void setSystemUsername(String systemUsername)
Used when initializing the default LdapContextFactory. This property is ignored if a custom LdapContextFactory is specified.

Parameters:
systemUsername - the username to use when logging into the LDAP server for authorization.
See Also:
DefaultLdapContextFactory.setSystemUsername(String)

setSystemPassword

public void setSystemPassword(String systemPassword)
Used when initializing the default LdapContextFactory. This property is ignored if a custom LdapContextFactory is specified.

Parameters:
systemPassword - the password to use when logging into the LDAP server for authorization.
See Also:
DefaultLdapContextFactory.setSystemPassword(String)

setLdapContextFactory

public void setLdapContextFactory(LdapContextFactory ldapContextFactory)
Configures the LdapContextFactory implementation that is used to create LDAP connections for authentication and authorization. If this is set, the LdapContextFactory provided will be used. Otherwise, a DefaultLdapContextFactory instance will be created based on the properties specified in this realm.

Parameters:
ldapContextFactory - the factory to use - if not specified, a default factory will be created automatically.

onInit

protected void onInit()
Description copied from class: AuthorizingRealm
Initializes this realm and potentially enables a cache, depending on configuration.

When this method is called, the following logic is executed:

  1. If the cache property has been set, it will be used to cache the AuthorizationInfo objects returned from AuthorizingRealm.getAuthorizationInfo(org.apache.shiro.subject.PrincipalCollection) method invocations. All future calls to getAuthorizationInfo will attempt to use this cache first to alleviate any potentially unnecessary calls to an underlying data store.
  2. If the cache property has not been set, the cacheManager property will be checked. If a cacheManager has been set, it will be used to create an authorization cache, and this newly created cache which will be used as specified in #1.
  3. If neither the (org.apache.shiro.cache.Cache) cache or cacheManager properties are set, caching will be disabled and authorization look-ups will be delegated to subclass implementations for each authorization check.

Overrides:
onInit in class AuthorizingRealm

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)
Description copied from class: AuthorizingRealm
Retrieves the AuthorizationInfo for the given principals from the underlying data store. When returning an instance from this method, you might want to consider using an instance of SimpleAuthorizationInfo, as it is suitable in most cases.

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:
SimpleAuthorizationInfo

queryForAuthenticationInfo

protected abstract AuthenticationInfo queryForAuthenticationInfo(AuthenticationToken token,
                                                                 LdapContextFactory ldapContextFactory)
                                                          throws NamingException

Abstract method that should be implemented by subclasses to builds an AuthenticationInfo object by querying the LDAP context for the specified username.

Parameters:
token - the authentication token given during authentication.
ldapContextFactory - factory used to retrieve LDAP connections.
Returns:
an AuthenticationInfo instance containing information retrieved from the LDAP server.
Throws:
NamingException - if any LDAP errors occur during the search.

queryForAuthorizationInfo

protected abstract AuthorizationInfo queryForAuthorizationInfo(PrincipalCollection principal,
                                                               LdapContextFactory ldapContextFactory)
                                                        throws NamingException

Abstract method that should be implemented by subclasses to builds an AuthorizationInfo object by querying the LDAP context for the specified principal.

Parameters:
principal - the principal of the Subject whose AuthenticationInfo should be queried from the LDAP server.
ldapContextFactory - factory used to retrieve LDAP connections.
Returns:
an AuthorizationInfo instance containing information retrieved from the LDAP server.
Throws:
NamingException - if any LDAP errors occur during the search.


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