org.openpermis.repository.basic
Class LdapSubjectRepository

java.lang.Object
  extended by org.openpermis.repository.basic.AbstractSubjectRepository
      extended by org.openpermis.repository.basic.LdapSubjectRepository
All Implemented Interfaces:
SubjectRepository

public class LdapSubjectRepository
extends AbstractSubjectRepository

Loads certificate attributes from an LDAP directory and builds up a subject repository from them. This implementation of SubjectRepository connects to an LDAP directory (either anonymously or using username and password) and looks at all nodes of the specified search context (node or subtree). For each node, it looks for attributes containing role assignment attribute certificates. The subject repository is build from all found and successfully validated role assignment attribute certificates. Note that it is not relevant in what nodes a role assignment is found. This means that a role assignment does not necessarily have to be stored in role holders node. The search scope can be limited to the specified search context or to the whole subtree it defines. An arbitrary search filter can be specified in order to limit the number of nodes or in order to get better performance in large directories. This implementation keeps the subject repository in an internal cache. It is therefore not necessary to query the directory for every call to retrieveSubject(URI). The validity period of data in the cache can be controlled using method setCacheTimeout(long) and defaults to five seconds. The cache can be disabled leading to a potentially expensive LDAP query for every call to retrieveSubject(URI).

Since:
0.1.0

Field Summary
private static String ACE_ATTRIBUTE_NAME
          The attribute name under which attribute certificates are stored in a directory
private  String bindPrincipal
           
private  String bindPrincipalPassword
           
private static int BUFFER_SIZE
          Buffer size
private  long cacheTimeout
          The number of milliseconds the data loaded from the LDAP may be cached.
private static long DEFAULT_CACHE_TIMEOUT_MILLIS
          The default cache timeout
private static String DEFAULT_LDAP_INITIAL_CONTEXT_FACTORY
          Default initial context factory
private static String DEFAULT_LDAP_SEARCH_FILTER
          LDAP search conditino that is always true
private static long DEFAULT_LDAP_SEARCH_LIMIT
          Don't limit ldap result size by default
private static boolean DEFAULT_LDAP_USE_SSL
          Default is not to use SSL
private static String DEFAULT_LDAP_VERSION
          Default LDAP version string
private static int DEFAULT_SEARCH_SCOPE
          The default search scope is subtree
private  String initialContextFactory
           
private  long latestRefresh
          Internal timestamp of latest refresh of the cache.
private  String ldapFilter
           
private  Object[] ldapFilterArgs
           
private  String ldapSearchBase
           
private  long ldapSearchLimit
          The maximum number of results an LDAP directory may return. 0 = no limit.
private  int ldapSearchScope
           
private  String ldapUrl
           
private  String ldapVersion
          The following state is used in the LDAP queries.
private  Map<URI,InternalSubject> subjectsByIdentity
          The internal data cache.
private  List<byte[]> testAcData
          Attribute certificate data user in unit tests
private  boolean unitTestMode
          Set to true in the case of a unit test without LDAP
private  boolean useSsl
           
 
Constructor Summary
LdapSubjectRepository(CertificateVerifier certificateVerifier, String... acsFileNames)
          Package private constructor used for unit testing.
LdapSubjectRepository(CertificateVerifier certificateVerifier, String ldapUrl, String bindPrincipal, String bindPrincipalPassword, String ldapSearchBase, int ldapSearchScope)
          Creates an LDAP subject repository and internally stores the specified SOA certificate.
 
Method Summary
private static List<byte[]> getAttributeCertificateData(String ldapUrl, String bindPrincipal, String bindPrincipalPassword, String ldapVersion, long ldapSearchLimit, boolean useSsl, String initialContextFactory, String ldapSearchBase, int ldapSearchLevel, String filter, Object[] filterArgs)
          Searches in on specified directory tree (context) for entries with attribute certificates and returns a list of byte arrays containing the data.
 void invalidateCache()
          Invalidates the internal data cache.
private  void refreshDataCache()
          Private method that refreshes the internal data cache by quering the LDAP.
 Subject retrieveSubject(URI identity)
          Returns a subject whose identity matches the one specified.
 LdapSubjectRepository setCacheTimeout(long milliseconds)
          Sets the cache timeout in milliseconds.
 LdapSubjectRepository setInitialLdapContextFactory(String initialLdapContextFactory)
          Allows specifying the initial LDAP context factory that is used to search attribute certificates.
 LdapSubjectRepository setLdapFilter(String filterExpression, Object[] filterArguments)
          Allows specifying an LDAP filter expression that is used to search attribute certificates.
 LdapSubjectRepository setLdapSearchLimit(long maxResults)
          Sets the maximum number of results an LDAP directory may return in a search.
 
Methods inherited from class org.openpermis.repository.basic.AbstractSubjectRepository
updateSubjectMap
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ACE_ATTRIBUTE_NAME

private static final String ACE_ATTRIBUTE_NAME
The attribute name under which attribute certificates are stored in a directory

Constant Field Value:
"attributeCertificateAttribute"

DEFAULT_CACHE_TIMEOUT_MILLIS

private static final long DEFAULT_CACHE_TIMEOUT_MILLIS
The default cache timeout

Constant Field Value:
5000L

DEFAULT_LDAP_SEARCH_LIMIT

private static final long DEFAULT_LDAP_SEARCH_LIMIT
Don't limit ldap result size by default

Constant Field Value:
0L

DEFAULT_LDAP_VERSION

private static final String DEFAULT_LDAP_VERSION
Default LDAP version string

Constant Field Value:
"3"

DEFAULT_LDAP_USE_SSL

private static final boolean DEFAULT_LDAP_USE_SSL
Default is not to use SSL

Constant Field Value:
false

DEFAULT_LDAP_INITIAL_CONTEXT_FACTORY

private static final String DEFAULT_LDAP_INITIAL_CONTEXT_FACTORY
Default initial context factory

Constant Field Value:
"com.sun.jndi.ldap.LdapCtxFactory"

DEFAULT_LDAP_SEARCH_FILTER

private static final String DEFAULT_LDAP_SEARCH_FILTER
LDAP search conditino that is always true

Constant Field Value:
"objectClass=*"

DEFAULT_SEARCH_SCOPE

private static final int DEFAULT_SEARCH_SCOPE
The default search scope is subtree

Constant Field Value:
2

BUFFER_SIZE

private static final int BUFFER_SIZE
Buffer size

Constant Field Value:
1024

ldapSearchLimit

private long ldapSearchLimit
The maximum number of results an LDAP directory may return. 0 = no limit. Note that there may be a server side limit that cannot be influenced by the client.


cacheTimeout

private long cacheTimeout
The number of milliseconds the data loaded from the LDAP may be cached.


latestRefresh

private long latestRefresh
Internal timestamp of latest refresh of the cache.


subjectsByIdentity

private final Map<URI,InternalSubject> subjectsByIdentity
The internal data cache.


ldapVersion

private String ldapVersion
The following state is used in the LDAP queries.


useSsl

private boolean useSsl

initialContextFactory

private String initialContextFactory

ldapFilter

private String ldapFilter

ldapFilterArgs

private Object[] ldapFilterArgs

ldapSearchScope

private int ldapSearchScope

ldapUrl

private String ldapUrl

bindPrincipal

private String bindPrincipal

bindPrincipalPassword

private String bindPrincipalPassword

ldapSearchBase

private String ldapSearchBase

testAcData

private List<byte[]> testAcData
Attribute certificate data user in unit tests


unitTestMode

private final boolean unitTestMode
Set to true in the case of a unit test without LDAP

Constructor Detail

LdapSubjectRepository

public LdapSubjectRepository(CertificateVerifier certificateVerifier,
                             String ldapUrl,
                             String bindPrincipal,
                             String bindPrincipalPassword,
                             String ldapSearchBase,
                             int ldapSearchScope)
                      throws SubjectRepositoryException
Creates an LDAP subject repository and internally stores the specified SOA certificate. It is used for validating the attribute certificates of a subject.

The public key of the subject in the SOA certificate is considered to be authentic. It is the callers duty to ensure that it really is authentic. Further, by specifiying the SOA certificate, its subject is trusted.

Parameters:
certificateVerifier - The certificate verifier used to verify the attribute certificates. Must not be null.
ldapUrl - The LDAP URL. Example: "ldap://foo.host.com:389"
bindPrincipal - The distinguished name of the principal used to bind at the directory to perform the search. Use null as value to anonymously bind.
bindPrincipalPassword - The password of the principal to bind at the directory to perform the search. Use null as value to anonymously bind.
ldapSearchBase - The search base.
ldapSearchScope - The search level. Must be either SearchControls.ONELEVEL_SCOPE or SearchControls.SUBTREE_SCOPE.
Throws:
SubjectRepositoryException - Thrown if an error occurs reading or interpreting the SOA certificate.
Since:
0.1.0

LdapSubjectRepository

LdapSubjectRepository(CertificateVerifier certificateVerifier,
                      String... acsFileNames)
                throws SubjectRepositoryException
Package private constructor used for unit testing. It loads the role assignments given in the specified files and uses them as input instead of querying the LDAP directory. In this mode, the verification of attribute certificates, the creation of subjects and the caching may be tested without an LDAP directory.

Parameters:
certificateVerifier - The certificate verifier user to verify the attribute certificates. Must not be null. Must not be null.
acsFileNames - One or more files names pointing to attribute certificates on the classpath.
Throws:
SubjectRepositoryException - Thrown if an error occurs reading or interpreting the SOA certificate.
Since:
0.1.0
Method Detail

refreshDataCache

private void refreshDataCache()
                       throws SubjectRepositoryException
Private method that refreshes the internal data cache by quering the LDAP.

Throws:
SubjectRepositoryException - Thrown if the subject repository cannot be built up.

setLdapFilter

public LdapSubjectRepository setLdapFilter(String filterExpression,
                                           Object[] filterArguments)
Allows specifying an LDAP filter expression that is used to search attribute certificates. Setting a filter also invalidates the cache such that data is re-read from the directory the next time retrieveSubject(URI) is called.

Parameters:
filterExpression - An LDAP filter expression (following RFC 2254).
filterArguments - A list of arguments for the filter expressions. May be null.
Returns:
Returns the object this method was called on (fluent interface).
Since:
0.1.0

setInitialLdapContextFactory

public LdapSubjectRepository setInitialLdapContextFactory(String initialLdapContextFactory)
Allows specifying the initial LDAP context factory that is used to search attribute certificates. Setting the factory also invalidates the cache such that data is re-read from the directory the next time retrieveSubject(URI) is called.

Parameters:
initialLdapContextFactory - The class name of the initial LDAP context factory.
Returns:
Returns the object this method was called on (fluent interface).
Since:
0.1.0

setLdapSearchLimit

public LdapSubjectRepository setLdapSearchLimit(long maxResults)
Sets the maximum number of results an LDAP directory may return in a search. Zero (0) means "no limit" which is the default. Note that there may be a server side limit that cannot be influenced by the client.

Parameters:
maxResults - The maximum number of results.
Returns:
Returns the object this method was called on (fluent interface).
Since:
0.1.0

setCacheTimeout

public LdapSubjectRepository setCacheTimeout(long milliseconds)
Sets the cache timeout in milliseconds. The cache timeout defines how long data loaded from the directory is considered valid before reloading it again. Use the value zero to disable caching and use Long.MAX_VALUE to cache the data for ever.

Parameters:
milliseconds - The number of milliseconds of the cache timeout.
Returns:
Returns the object this method was called on (fluent interface).
Since:
0.1.0

invalidateCache

public void invalidateCache()
Invalidates the internal data cache. Forces the data to be reload the next time retrieveSubject(URI) is called.

Since:
0.1.0

getAttributeCertificateData

private static List<byte[]> getAttributeCertificateData(String ldapUrl,
                                                        String bindPrincipal,
                                                        String bindPrincipalPassword,
                                                        String ldapVersion,
                                                        long ldapSearchLimit,
                                                        boolean useSsl,
                                                        String initialContextFactory,
                                                        String ldapSearchBase,
                                                        int ldapSearchLevel,
                                                        String filter,
                                                        Object[] filterArgs)
                                                 throws NamingException
Searches in on specified directory tree (context) for entries with attribute certificates and returns a list of byte arrays containing the data.

Parameters:
ldapUrl - The LDAP URL. Example: "ldap://foo.host.com:389"
bindPrincipal - The distinguished name of the principal used to bind at the directory to perform the search. Use null as value to anonymously bind.
bindPrincipalPassword - The password of the principal to bind at the directory to perform the search. Use null as value to anonymously bind.
ldapVersion - The LDAP version string. Normally, this is "3".
ldapSearchLimit - The maximum number of results to return in an LDAP query.
useSsl - Set to true if SSL should be used to connect to the ldap server. If set to true the SSL factory provided by the JVM is used and a corresponding trust- and keystore must be configured in the JVM.
initialContextFactory - The factory used to create initial LDAP context object. This depends on the used JVM. To use the SUN implementation use the value "com.sun.jndi.ldap.LdapCtxFactory".
ldapSearchBase - The search base.
ldapSearchLevel - The search level. Must be either SearchControls.ONELEVEL_SCOPE or SearchControls.SUBTREE_SCOPE.
filter - An LDAP filter expression (following RFC 2254).
filterArgs - The filter arguments.
Returns:
A possibly empty list of byte arrays containing attribute certificates.
Throws:
NamingException - If there is an error searching the directory or decoding the response from the directory.

retrieveSubject

public Subject retrieveSubject(URI identity)
                        throws SubjectRepositoryException
Description copied from interface: SubjectRepository
Returns a subject whose identity matches the one specified.

Parameters:
identity - a URI that identifies a subject.
Returns:
a Subject associating a person with her assigned roles. The returned subject is never null, but will have no assigned roles for unknown identities.
Throws:
SubjectRepositoryException - when the repository fails to retrieve the roles for the specified identity.
Since:
0.1.0


PERMIS Role Based Access Control 0.4.0 (Build 15)
2009/05/20 08:14:59
Copyright (c) 2002-2007 Ergon Informatik AG