LDAP Naming Service Provider for the
Java Naming and Directory InterfaceTM (JNDI)


Please send feedback to jndi@java.sun.com

Table of Contents

  1. Introduction
  2. Conformance
  3. Environment Properties
  4. Names
  5. Attributes
  6. URLs
  7. Java Objects
  8. Schema
  9. Exceptions
  10. API Mapping
  11. Federation
  12. Event Notification
  13. SSL
  14. Security Considerations



1. Introduction

The Lightweight Directory Access Protocol (LDAP) is an Internet standard for accessing directory services. The JNDI/LDAP service provider provides access to servers implementing the LDAP protocols.

This document describes the features of the LDAP service provider. A major portion of the description is couched in terms of how the LDAP service provider behaves with respect to the descriptions in Guidelines for LDAP Service Providers. For examples and descriptions of how to use this provider, please see the JNDI Tutorial.

The LDAP service provider implements the basic features for LDAP access. Additional functionality, such as support for a number of popular LDAP controls, for SASL authentication, and for storing and reading RMI and CORBA objects, can be added to the basic provider by installing a booster pack, available for download at the JNDI Web site.


2. Conformance

The LDAP service provider conforms to the following standards:
 
Standard Supported Comments
LDAPv3 (RFC-2251) Yes  
LDAPv3 Attributes (RFC-2252) Yes  
LDAPv3 Distinguished Names (RFC-2253) Yes  
LDAP Search Filters (RFC-2254) Yes  
LDAP  URL Format (RFC-2255) Yes  
LDAPv3 Schema (RFC-2256) Yes  
LDAPv2 (RFC-1777) Yes  


3. Environment Properties

Descriptions of JNDI and LDAP-specific properties are found in Guidelines for LDAP Service Providers.

3.1 JNDI Properties

The LDAP service provider supports the following JNDI environment properties:
 
Property Supported Comments
java.naming.batchsize Yes Default value is 1.
java.naming.factory.control Yes  
java.naming.factory.initial Yes Specify com.sun.jndi.ldap.LdapCtxFactory to use the LDAP service provider as the initial context.
java.naming.factory.object Yes  
java.naming.factory.state Yes  
java.naming.language No Ignored by the provider.
java.naming.provider.url Yes  
java.naming.referral Yes  
java.naming.security.authentication Yes simple, none
java.naming.security.credentials Yes  
java.naming.security.principal Yes  
java.naming.security.protocol Yes  

3.2 LDAP-specific Properties

The provider supports the following LDAP-specific environment properties:
 
Property Supported Comments
java.naming.ldap.attributes.binary Yes  
java.naming.ldap.control.connect Yes  
java.naming.ldap.deleteRDN Yes  
java.naming.ldap.derefAliases Yes  
java.naming.ldap.factory.socket Yes Default value is javax.net.ssl.SSLSocketFactory when the java.naming.security.protocol  property is set to ssl. See the SSL Section for details.
java.naming.ldap.ref.separator Yes  
java.naming.ldap.referral.limit Yes  
java.naming.ldap.typesOnly Yes  
java.naming.ldap.version Yes  

3.4 Provider-specific Properties

The LDAP service provider defines the following provider-specific environment properties:
 
com.sun.jndi.ldap.netscape.schemaBugs
The Netscape Directory Server 4.0 and earlier releases do not support schema entries that comply with RFC 2252. Specifically, contrary to RFC 2252, the Netscape server requires OIDs (such as those for SUP and SYNTAX) be delimited by single quotes and MUST/MAY lists be enclosed by parentheses. When you update the schema of the Netscape Directory Server 4.0, you need to use this property to get around these problems.

The following values are defined for this property:

        true
           activate the workaround.
        false
           do not activate the workaround.

If this property is not set then its default value is false.

For example,

env.put("com.sun.jndi.ldap.netscape.schemaBugs", "true");
activates the workaround.

NOTE 1: This property may only be passed to the initial context and becomes fixed for the provider. It is unaffected by the addToEnvironment or removeFromEnvironment methods.

NOTE 2: If you are using Netscape Directory Server 4.1, do not use this property. The 4.1 server has problems parsing object class definitions that contain MUST/MAY clauses without parentheses. If you are creating or modifying an object class definition that contains a single MUST/MAY item, work around the bug by adding a superfluous value (such as 'objectClass') to the MUST/MAY list.

com.sun.jndi.ldap.trace.ber
The value of this property is a java.io.OutputStream object into which a hexadecimal dump of the incoming and outgoing LDAP ASN.1 BER packets is written.

No default is defined for this property.

For example,

env.put("com.sun.jndi.ldap.trace.ber", System.out);
directs the LDAP protocol trace to the standard output stream.

NOTE: This property may only be passed to the initial context and becomes fixed for the provider. It is unaffected by the addToEnvironment or removeFromEnvironment methods.


4. Names

The LDAP service provider supports names in accordance with the description in Guidelines for LDAP Service Providers. It supports LDAP distinguished names in the following formats:
 
Distinguished Name format Comments
String Treat as composite name. Process the first component of the composite name as a distinguished name. Use rest of the components for federation.
Name If instance of CompositeName, treat as composite name, which means process the first component of the composite name as a distinguished name and use the rest for federation. Otherwise, treat as parsed LDAP name, where each component of Name is a component of the LDAP name as defined in RFC-2253.
LDAP URL String When passed to the initial context, the LDAP URL string is interpreted according to RFC-2255, and its distinguished name component interpreted according to RFC-2253.

The name parser returned by an invocation of getNameParser() returns a parser that, when given a string name, parses it into components in accordance with RFC-2253.


5. Attributes

The LDAP service provider supports attributes in accordance with the description in Guidelines for LDAP Service Providers. It supports the following formats for specifying LDAP attribute values:
 
Attribute value format Supported Comments
String values Yes  
byte[] values Yes  

Some LDAP servers support attribute subtyping, attribute name synonyms, and language codes for specifying language preferences for attribute values. In such cases, the attribute name returned by an LDAP server may be different from the one which was requested.

In LDAP, attribute names are case-insensitive. Therefore, when creating a collection of attributes to be passed as a parameter to JNDI operations, it is recommended to use a case-insensitive attributes class. For example,

        Attributes attrs = new BasicAttributes(true); // ignoreCase=true

For all attribute values, regardless of whether they are String or byte[], you need to know the syntax and format of the attribute value. You can typically find this out by reading the schema document in which the attribute and its syntax is defined.

When attributes are supplied as arguments to JNDI calls then they must satisfy whatever schema is enforced at the LDAP directory.  In particular, the objectClass attribute is normally required when creating a new LDAP entry (for example, when using Context.bind, Context.rebind or DirContext.createSubcontext).


6. URLs

The LDAP service provider supports URLs in accordance with the description in Guidelines for LDAP Service Providers. It supports the following use of URLs:
 
URL usage Supported Comments
LDAP URLs to configure the LDAP service provider. Yes  
URLs passed as names to the InitialDirContext methods. Yes The attributes, scope, filter and extensions components of LDAP URLs are ignored by the search methods.
URLs in LDAP referrals Yes The scope component of LDAP URLs is supported. The attributes, filter and extensions components are ignored.
URLs returned as names in list, listBindings, and search enumerations. Yes  
URLs linking federated namespaces. Yes  



7. Java Objects

The LDAP service provider supports storing and reading the following types of objects, as specified in Guidelines for LDAP Service Providers.
 
Storable/Readable Objects Supported Comments
Reference objects Yes  
Referenceable objects Yes  
Serializable objects Yes  
DirContext objects Yes  

See the JNDI Tutorial for examples.


8. Schema

The LDAP service provider supports the following schema bindings, as specified in Guidelines for LDAP Service Providers.
 
Schema Tree Supported Comments
AttributeDefinition Yes Attribute definitions may be added or deleted but not modified.
ClassDefinition Yes Class definitions may be added or deleted but not modified.
SyntaxDefinition Yes Syntax definitions may be added or deleted but not modified.
MatchingRule Yes Matching rules may be added or deleted but not modified.
ExtensionDefinition No  
ControlDefinition No  
SASLMechanism No  


9. Exceptions

The LDAP service provider maps LDAP error codes to JNDI exceptions according to Guidelines for LDAP Service Providers.
 


10. API Mapping

The LDAP service provider maps the following JNDI API methods to LDAP according to Guidelines for LDAP Service Providers:
 
Mapping for Context methods Supported Comments
addToEnvironment Yes  
bind Yes  
close Yes  
composeName Yes  
destroySubcontext Yes  
getEnvironment Yes  
getNameInNamespace Yes  
getNameParser Yes  
list Yes  
listBindings Yes  
lookup Yes Does not process LinkRef specially.
lookupLink Yes  
rebind Yes  
removeFromEnvironment Yes  
rename Yes  
unbind Yes  
Mapping for DirContext methods Supported Comments
bind Yes  
createSubcontext Yes  
destroySubcontext Yes  
getAttributes Yes  
getSchema Yes  
getSchemaClassDefinition Yes  
modifyAttributes Yes  
rebind Yes  
search Yes  
Mapping for LdapContext methods Supported Comments
extendedOperation Yes  
getRequestControls Yes  
getResponseControls Yes  
newInstance Yes  
reconnect Yes  
setRequestControls Yes  
Mapping for EventDirContext methods Supported Comments
addNamingListener Yes  
removeNamingListener Yes  
targetMustExist Yes  


11. Federation

The LDAP service provider supports federation in accordance with the description in Guidelines for LDAP Service Providers. It supports the following federation techniques:
 
Federation Technique Supported Comments
Junction Yes  
Implicit Next Naming System Pointer Yes  
 

The LDAP service provider treats composite names as strongly separated. That is, it processes the first component of the composite name as a distinguished name and the rest of the components as names in the next naming system(s). For example, here are examples that lists the root of the next naming system federated beyond an LDAP context and looks up a name using a multicomponent composite name:

// List the root of the nns, 
// Note use of the trailing slash to indicate traversal into the nns
NamingEnumeration enum = ctx.list("cn=objects,ou=Sales/");

// A composite name lookup
Object obj = ctx.lookup("cn=objects,ou=Sales/some/x/y/z");


12. Event Notification

The LDAP service provider supports event notification in accordance with the description in Guidelines for LDAP Service Providers. It supports the following events:
 
Event Supported Comments
Namespace change notification Yes Uses the persistent search control
Object change notification Yes Uses the persistent search control
Unsolicited notification Yes  


13. SSL

The LDAP service provider supports SSL in accordance with the description in Guidelines for LDAP Service Providers. It uses the default socket factory javax.net.ssl.SSLSocketFactory unless the java.naming.ldap.factory.socket  property has been set to the class name of some other socket factory. The use of javax.net.ssl.SSLSocketFactory requires the SSL package from Sun's Java Web Server or Hot Java Browser products. Documentation for these products describes how to initialize and configure the private keys and public key certificates necessary for authentication using SSL.

14. Security Considerations

When a security manager has been installed, you must grant to the application using JNDI and the the LDAP service provider the following permissions:

permission java.net.SocketPermission "host[:port]", "connect";
For each host/port identified in the java.naming.factory.initial property and in URL string names supplied to context methods.
permission java.net.SocketPermission "host[:port]", "connect,accept";
For each host/port named in the URL strings in References and javaCodebase attributes stored with Serializable objects.


Copyright © 1999 Sun Microsystems, Inc., All Rights Reserved.