ReadOnlyUsersLDAPRepository (Apache James Server 3.0-beta5-SNAPSHOT API)

java.lang.Object
- org.apache.james.user.ldap.ReadOnlyUsersLDAPRepository

All Implemented Interfaces:

Configurable, LogEnabled, UsersRepository
```
public class ReadOnlyUsersLDAPRepository
extends Object
implements UsersRepository, Configurable, LogEnabled
```
This repository implementation serves as a bridge between Apache James and LDAP. It allows James to authenticate users against an LDAP compliant server such as Apache DS or Microsoft AD. It also enables role/group based access restriction based on LDAP groups.

It is intended for organisations that already have a user-authentication and authorisation mechanism in place, and want to leverage this when deploying James. The assumption inherent here is that such organisations would not want to manage user details via James, but will do so externally using whatever mechanism provided by, or built on top off, their LDAP implementation.

Based on this assumption, this repository is strictly read-only. As a consequence, user modification, deletion and creation requests will be ignored when using this repository.

The following fragment of XML provides an example configuration to enable this repository:
```
  <users-store>
      <repository name="LDAPUsers"
      class="org.apache.james.userrepository.ReadOnlyUsersLDAPRepository"
      ldapHost="ldap://myldapserver:389"
      principal="uid=ldapUser,ou=system"
      credentials="password"
      userBase="ou=People,o=myorg.com,ou=system"
      userIdAttribute="uid"
      userObjectClass="inetOrgPerson"
      maxRetries="20"
      retryStartInterval="0"
      retryMaxInterval="30"
      retryIntervalScale="1000"
  </users-store>
 
```
Its constituent attributes are defined as follows:
- ldapHost: The URL of the LDAP server to connect to.
- principal: (optional) The name (DN) of the user with which to initially bind to the LDAP server.
- credentials: (optional) The password with which to initially bind to the LDAP server.
- userBase:The context within which to search for user entities.
- userIdAttribute:The name of the LDAP attribute which holds user ids. For example "uid" for Apache DS, or "sAMAccountName" for Microsoft Active Directory.
- userObjectClass:The objectClass value for user nodes below the userBase. For example "inetOrgPerson" for Apache DS, or "user" for Microsoft Active Directory.
- maxRetries: (optional, default = 0) The maximum number of times to retry a failed operation. -1 means retry forever.
- retryStartInterval: (optional, default = 0) The interval in milliseconds to wait before the first retry. If > 0, subsequent retries are made at double the proceeding one up to the retryMaxInterval described below. If = 0, the next retry is 1 and subsequent retries proceed as above.
- retryMaxInterval: (optional, default = 60) The maximum interval in milliseconds to wait between retries
- retryIntervalScale: (optional, default = 1000) The amount by which to multiply each retry interval. The default value of 1000 (milliseconds) is 1 second, so the default retryMaxInterval of 60 is 60 seconds, or 1 minute.
Example Schedules
- Retry after 1000 milliseconds, doubling the interval for each retry up to 30000 milliseconds, subsequent retry intervals are 30000 milliseconds until 10 retries have been attempted, after which the Exception causing the fault is thrown:
  - maxRetries = 10
  - retryStartInterval = 1000
  - retryMaxInterval = 30000
  - retryIntervalScale = 1
- Retry immediately, then retry after 1 * 1000 milliseconds, doubling the interval for each retry up to 30 * 1000 milliseconds, subsequent retry intervals are 30 * 1000 milliseconds until 20 retries have been attempted, after which the Exception causing the fault is thrown:
  - maxRetries = 20
  - retryStartInterval = 0
  - retryMaxInterval = 30
  - retryIntervalScale = 1000
- Retry after 5000 milliseconds, subsequent retry intervals are 5000 milliseconds. Retry forever:
  - maxRetries = -1
  - retryStartInterval = 5000
  - retryMaxInterval = 5000
  - retryIntervalScale = 1
In order to enable group/role based access restrictions, you can use the "<restriction>" configuration element. An example of this is shown below:
```
 <restriction
  memberAttribute="uniqueMember">
    <group>cn=PermanentStaff,ou=Groups,o=myorg.co.uk,ou=system</group>
          <group>cn=TemporaryStaff,ou=Groups,o=myorg.co.uk,ou=system</group>
 </restriction>
 
```
Its constituent attributes and elements are defined as follows:
- memberAttribute: The LDAP attribute whose values indicate the DNs of the users which belong to the group or role.
- group: A valid group or role DN. A user is only authenticated (permitted access) if they belong to at least one of the groups listed under the "<restriction>" sections.
The following parameters may be used to adjust the underlying com.sun.jndi.ldap.LdapCtxFactory. See LDAP Naming Service Provider for the Java Naming and Directory InterfaceTM (JNDI) : Provider-specific Properties for details.
- useConnectionPool: (optional, default = true) Sets property com.sun.jndi.ldap.connect.pool to the specified boolean value
- connectionTimeout: (optional) Sets property com.sun.jndi.ldap.connect.timeout to the specified integer value
- readTimeout: (optional) Sets property com.sun.jndi.ldap.read.timeout to the specified integer value. Applicable to Java 6 and above.
See Also:
ReadOnlyLDAPUser, ReadOnlyLDAPGroupRestriction

Constructor Summary

Constructors
Constructor and Description

ReadOnlyUsersLDAPRepository()
Creates a new instance of ReadOnlyUsersLDAPRepository.

Constructors
Constructor and Description
`ReadOnlyUsersLDAPRepository()` Creates a new instance of ReadOnlyUsersLDAPRepository.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addUser(String username, String password)` Adds a user to the repository with the specified password
`protected LdapContext`	`computeLdapContext()` Answers a new LDAP/JNDI context using the specified user credentials.
`void`	`configure(org.apache.commons.configuration.HierarchicalConfiguration configuration)` Extracts the parameters required by the repository instance from the James server configuration data.
`boolean`	`contains(String name)` Returns whether or not this user is in the repository
`boolean`	`containsCaseInsensitive(String name)`
`int`	`countUsers()` Returns a count of the users in the repository.
`protected Properties`	`getContextEnvironment()`
`protected LdapContext`	`getLdapContext()` Answer the LDAP context used to connect with the LDAP server.
`String`	`getRealName(String name)`
`User`	`getUserByName(String name)` Get the user object with the specified user name.
`User`	`getUserByNameCaseInsensitive(String name)`
`void`	`init()` Initialises the user-repository instance.
`Iterator<String>`	`list()` List users in repository.
`void`	`removeUser(String name)` Removes a user from the repository
`void`	`setLog(org.slf4j.Logger log)` Sets the service log.
`boolean`	`supportVirtualHosting()` VirtualHosting not supported
`boolean`	`test(String name, String password)` Test if user with name 'name' has password 'password'.
`protected void`	`updateLdapContext()`
`void`	`updateUser(User user)` Update the repository with the specified user object.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - ReadOnlyUsersLDAPRepository
```
public ReadOnlyUsersLDAPRepository()
```
    Creates a new instance of ReadOnlyUsersLDAPRepository.
- Method Detail
  - configure
```
public void configure(org.apache.commons.configuration.HierarchicalConfiguration configuration)
               throws org.apache.commons.configuration.ConfigurationException
```
    Extracts the parameters required by the repository instance from the James server configuration data. The fields extracted include ldapHost, userIdAttribute, userBase, principal, credentials and restriction.
    
    Specified by:
    
    configure in interface Configurable
    
    Parameters:
    configuration - An encapsulation of the James server configuration data.
    
    Throws:
    
    org.apache.commons.configuration.ConfigurationException
  - init
```
@PostConstruct
public void init()
          throws Exception
```
    Initialises the user-repository instance. It will create a connection to the LDAP host using the supplied configuration.
    
    Throws:
    
    Exception - If an error occurs authenticating or connecting to the specified LDAP host.
  - getLdapContext
```
protected LdapContext getLdapContext()
                              throws NamingException
```
    Answer the LDAP context used to connect with the LDAP server.
    
    Returns:
    an LdapContext
    
    Throws:
    
    NamingException
  - updateLdapContext
```
protected void updateLdapContext()
                          throws NamingException
```
    Throws:
    
    NamingException
  - computeLdapContext
```
protected LdapContext computeLdapContext()
                                  throws NamingException
```
    Answers a new LDAP/JNDI context using the specified user credentials.
    
    Returns:
    an LDAP directory context
    
    Throws:
    
    NamingException - Propagated from underlying LDAP communication API.
  - getContextEnvironment
```
protected Properties getContextEnvironment()
```
  - contains
```
public boolean contains(String name)
                 throws UsersRepositoryException
```
    Description copied from interface: UsersRepository
    
    Returns whether or not this user is in the repository
    
    Specified by:
    
    contains in interface UsersRepository
    
    Parameters:
    name - the name to check in the repository
    
    Returns:
    whether the user is in the repository
    
    Throws:
    
    UsersRepositoryException - if error
    See Also:
    UsersRepository.contains(java.lang.String)
  - containsCaseInsensitive
```
public boolean containsCaseInsensitive(String name)
                                throws UsersRepositoryException
```
    Throws:
    
    UsersRepositoryException
  - countUsers
```
public int countUsers()
               throws UsersRepositoryException
```
    Description copied from interface: UsersRepository
    
    Returns a count of the users in the repository.
    
    Specified by:
    
    countUsers in interface UsersRepository
    
    Returns:
    the number of users in the repository
    
    Throws:
    
    UsersRepositoryException - if error
    See Also:
    UsersRepository.countUsers()
  - getRealName
```
public String getRealName(String name)
                   throws UsersRepositoryException
```
    Throws:
    
    UsersRepositoryException
  - getUserByName
```
public User getUserByName(String name)
                   throws UsersRepositoryException
```
    Description copied from interface: UsersRepository
    
    Get the user object with the specified user name. Return null if no such user.
    
    Specified by:
    
    getUserByName in interface UsersRepository
    
    Parameters:
    name - the name of the user to retrieve
    
    Returns:
    the user being retrieved, null if the user doesn't exist
    
    Throws:
    
    UsersRepositoryException - if error
    See Also:
    UsersRepository.getUserByName(java.lang.String)
  - getUserByNameCaseInsensitive
```
public User getUserByNameCaseInsensitive(String name)
                                  throws UsersRepositoryException
```
    Throws:
    
    UsersRepositoryException
  - list
```
public Iterator<String> list()
                      throws UsersRepositoryException
```
    Description copied from interface: UsersRepository
    
    List users in repository.
    
    Specified by:
    
    list in interface UsersRepository
    
    Returns:
    Iterator over a collection of Strings, each being one user in the repository.
    
    Throws:
    
    UsersRepositoryException - if error
    See Also:
    UsersRepository.list()
  - removeUser
```
public void removeUser(String name)
                throws UsersRepositoryException
```
    Description copied from interface: UsersRepository
    
    Removes a user from the repository
    
    Specified by:
    
    removeUser in interface UsersRepository
    
    Parameters:
    name - the user to remove from the repository
    
    Throws:
    
    UsersRepositoryException - if error
    See Also:
    UsersRepository.removeUser(java.lang.String)
  - test
```
public boolean test(String name,
           String password)
             throws UsersRepositoryException
```
    Description copied from interface: UsersRepository
    
    Test if user with name 'name' has password 'password'.
    
    Specified by:
    
    test in interface UsersRepository
    
    Parameters:
    name - the name of the user to be tested
    password - the password to be tested
    
    Returns:
    true if the test is successful, false if the user doesn't exist or if the password is incorrect
    
    Throws:
    
    UsersRepositoryException - if error
    See Also:
    UsersRepository.test(java.lang.String, java.lang.String)
  - addUser
```
public void addUser(String username,
           String password)
             throws UsersRepositoryException
```
    Description copied from interface: UsersRepository
    
    Adds a user to the repository with the specified password
    
    Specified by:
    
    addUser in interface UsersRepository
    
    Parameters:
    username - the username of the user to be added
    password - the password of the user to add
    
    Throws:
    
    UsersRepositoryException - if error
    See Also:
    UsersRepository.addUser(java.lang.String, java.lang.String)
  - updateUser
```
public void updateUser(User user)
                throws UsersRepositoryException
```
    Description copied from interface: UsersRepository
    
    Update the repository with the specified user object. A user object with this username must already exist.
    
    Specified by:
    
    updateUser in interface UsersRepository
    
    Throws:
    
    UsersRepositoryException - if error
    See Also:
    UsersRepository#updateUser(org.apache.james.api.user.User)
  - setLog
```
public void setLog(org.slf4j.Logger log)
```
    Description copied from interface: LogEnabled
    
    Sets the service log.
    
    Specified by:
    
    setLog in interface LogEnabled
    
    Parameters:
    log - not null
    See Also:
    LogEnabled.setLog(org.slf4j.Logger)
  - supportVirtualHosting
```
public boolean supportVirtualHosting()
                              throws UsersRepositoryException
```
    VirtualHosting not supported
    
    Specified by:
    
    supportVirtualHosting in interface UsersRepository
    
    Returns:
    true or false
    
    Throws:
    
    UsersRepositoryException

Class ReadOnlyUsersLDAPRepository

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

ReadOnlyUsersLDAPRepository

Method Detail

configure

init

getLdapContext

updateLdapContext

computeLdapContext

getContextEnvironment

contains

containsCaseInsensitive

countUsers

getRealName

getUserByName

getUserByNameCaseInsensitive

list

removeUser

test

addUser

updateUser

setLog

supportVirtualHosting