ReadOnlyUsersLDAPRepository (Apache James Server LDAP Data Implementation 3.0-beta4 API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.apache.james.user.ldap
Class ReadOnlyUsersLDAPRepository

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

All Implemented Interfaces:: Configurable, LogEnabled, UsersRepository

public class ReadOnlyUsersLDAPRepository
extends Object
implements UsersRepository, Configurable, LogEnabled
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
`ReadOnlyUsersLDAPRepository()` Creates a new instance of ReadOnlyUsersLDAPRepository.

Method Summary
`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)`
`User`	`getUserByName(String name)`
`User`	`getUserByNameCaseInsensitive(String name)`
`void`	`init()` Initialises the user-repository instance.
`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(User user)`

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

Constructor Detail