org.apache.james.user.ldap

Class ReadOnlyUsersLDAPRepository

java.lang.Object

org.apache.james.user.ldap.ReadOnlyUsersLDAPRepository

All Implemented Interfaces:

org.apache.james.lifecycle.api.Configurable, org.apache.james.lifecycle.api.LogEnabled, org.apache.james.user.api.UsersRepository

public class ReadOnlyUsersLDAPRepository
extends Object
implements org.apache.james.user.api.UsersRepository, org.apache.james.lifecycle.api.Configurable, org.apache.james.lifecycle.api.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"
      administratorId="ldapAdmin"
  </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.
• administratorId: (optional) User identifier of the administrator user. The administrator user is allowed to authenticate as other users.

The supportsVirtualHosting tag allows you to define this repository as supporing virtual hosting. For this LDAP repository, it means users will be looked for by their email address instead of their unique identifier. Generally to make it work, you need to configure userIdAttribute attribute to map to a mail attribute such as mail instead of an unique id identifier.

See Also:

ReadOnlyLDAPUser, ReadOnlyLDAPGroupRestriction

Field Summary

Fields

Modifier and Type	Field and Description
static String	SUPPORTS_VIRTUAL_HOSTING

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
void	addUser(String username, String 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)
boolean	containsCaseInsensitive(String name)
int	countUsers()
protected Properties	getContextEnvironment()
protected LdapContext	getLdapContext() Answer the LDAP context used to connect with the LDAP server.
String	getRealName(String name)
String	getUser(org.apache.mailet.MailAddress mailAddress)
org.apache.james.user.api.model.User	getUserByName(String name)
org.apache.james.user.api.model.User	getUserByNameCaseInsensitive(String name)
void	init() Initialises the user-repository instance.
boolean	isAdministrator(String username)
Iterator<String>	list()
void	removeUser(String name)
void	setLog(org.slf4j.Logger log)
boolean	supportVirtualHosting() VirtualHosting not supported
boolean	test(String name, String password)
protected void	updateLdapContext()
void	updateUser(org.apache.james.user.api.model.User user)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SUPPORTS_VIRTUAL_HOSTING

public static final String SUPPORTS_VIRTUAL_HOSTING

See Also:

Constant Field Values

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 org.apache.james.lifecycle.api.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 org.apache.james.user.api.UsersRepositoryException

Specified by:

contains in interface org.apache.james.user.api.UsersRepository

Throws:

org.apache.james.user.api.UsersRepositoryException

See Also:

UsersRepository.contains(java.lang.String)

containsCaseInsensitive

public boolean containsCaseInsensitive(String name)
                                throws org.apache.james.user.api.UsersRepositoryException

Throws:

org.apache.james.user.api.UsersRepositoryException

countUsers

public int countUsers()
               throws org.apache.james.user.api.UsersRepositoryException

Specified by:

countUsers in interface org.apache.james.user.api.UsersRepository

Throws:

org.apache.james.user.api.UsersRepositoryException

See Also:

UsersRepository.countUsers()

getRealName

public String getRealName(String name)
                   throws org.apache.james.user.api.UsersRepositoryException

Throws:

org.apache.james.user.api.UsersRepositoryException

getUserByName

public org.apache.james.user.api.model.User getUserByName(String name)
                                                   throws org.apache.james.user.api.UsersRepositoryException

Specified by:

getUserByName in interface org.apache.james.user.api.UsersRepository

Throws:

org.apache.james.user.api.UsersRepositoryException

See Also:

UsersRepository.getUserByName(java.lang.String)

getUserByNameCaseInsensitive

public org.apache.james.user.api.model.User getUserByNameCaseInsensitive(String name)
                                                                  throws org.apache.james.user.api.UsersRepositoryException

Throws:

org.apache.james.user.api.UsersRepositoryException

list

public Iterator<String> list()
                      throws org.apache.james.user.api.UsersRepositoryException

Specified by:

list in interface org.apache.james.user.api.UsersRepository

Throws:

org.apache.james.user.api.UsersRepositoryException

See Also:

UsersRepository.list()

removeUser

public void removeUser(String name)
                throws org.apache.james.user.api.UsersRepositoryException

Specified by:

removeUser in interface org.apache.james.user.api.UsersRepository

Throws:

org.apache.james.user.api.UsersRepositoryException

See Also:

UsersRepository.removeUser(java.lang.String)

test

public boolean test(String name,
                    String password)
             throws org.apache.james.user.api.UsersRepositoryException

Specified by:

test in interface org.apache.james.user.api.UsersRepository

Throws:

org.apache.james.user.api.UsersRepositoryException

See Also:

UsersRepository.test(java.lang.String, java.lang.String)

addUser

public void addUser(String username,
                    String password)
             throws org.apache.james.user.api.UsersRepositoryException

Specified by:

addUser in interface org.apache.james.user.api.UsersRepository

Throws:

org.apache.james.user.api.UsersRepositoryException

See Also:

UsersRepository.addUser(java.lang.String, java.lang.String)

updateUser

public void updateUser(org.apache.james.user.api.model.User user)
                throws org.apache.james.user.api.UsersRepositoryException

Specified by:

updateUser in interface org.apache.james.user.api.UsersRepository

Throws:

org.apache.james.user.api.UsersRepositoryException

setLog

public void setLog(org.slf4j.Logger log)

Specified by:

setLog in interface org.apache.james.lifecycle.api.LogEnabled

See Also:

LogEnabled.setLog(org.slf4j.Logger)

supportVirtualHosting

public boolean supportVirtualHosting()

VirtualHosting not supported

Specified by:

supportVirtualHosting in interface org.apache.james.user.api.UsersRepository

getUser

public String getUser(org.apache.mailet.MailAddress mailAddress)
               throws org.apache.james.user.api.UsersRepositoryException

Specified by:

getUser in interface org.apache.james.user.api.UsersRepository

Throws:

org.apache.james.user.api.UsersRepositoryException

isAdministrator

public boolean isAdministrator(String username)
                        throws org.apache.james.user.api.UsersRepositoryException

Specified by:

isAdministrator in interface org.apache.james.user.api.UsersRepository

Throws:

org.apache.james.user.api.UsersRepositoryException