mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-11-07 12:15:51 +00:00
542 lines
22 KiB
HTML
542 lines
22 KiB
HTML
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<meta name="Author" content="Miodrag Kekic">
|
|
<meta name="GENERATOR" content="Mozilla/4.5 [en]C-NSCP (WinNT; U) [Netscape]">
|
|
<title>Netscape LDAP Service Provider - Readme</title>
|
|
</head>
|
|
<body>
|
|
|
|
<h2>
|
|
|
|
Netscape LDAP Service Provider for JNDI (08-02-99)</h2>
|
|
The Netscape LDAP service provider for JNDI implements the JNDI DirContext
|
|
interface. It is implemented as a layer on top of the Netscape Directory
|
|
SDK for Java (ldapjdk.jar). While the ldapjdk uses the LDAP connection
|
|
as the primary abstraction enabling the access to the directory services,
|
|
the JNDI provider uses the concept of a Directory Context (the
|
|
DirContext interface) to achieve the same functionality. A DirContext as
|
|
an equivalent of a directory entry in the ldapjdk.
|
|
<p>The following sections are available in this document:
|
|
<p><a href="#Using">Using Netscape Ldap Service Provider</a>
|
|
<br><a href="#Env Props">Environment Properties</a>
|
|
<br><a href="#Controls">Working With Controls</a>
|
|
<br><a href="#Not Impl">What's Not Implemented</a>
|
|
<br>
|
|
<h3>
|
|
<a NAME="Using"></a>Using Netscape LDAP Service Provider</h3>
|
|
The current implementation is based on the JNDI 1.2 FCS. In addition
|
|
to the DirContext interface implementation, the Netscape LDAP provider
|
|
implements the new JNDI event service (<i>javax.naming.event</i> package)
|
|
and support for controls (<i>javax.naming.ldap</i> package) which were
|
|
introduced with the JNDI 1.2.
|
|
<p>To use the service provider, you'll need to:
|
|
<p>(1) Add the provider and the jars it depends on in the classpath. For
|
|
example, on Windows NT the classpath should be set as follows:
|
|
<p><tt>set classpath=%classpath%;ldapsp.jar;ldapjdk.jar;jndi.jar;</tt>
|
|
<p>Assuming that all the jars are available in the current directory. The
|
|
listed jar files are:
|
|
<br>
|
|
<table CELLSPACING=0 COLS=2 WIDTH="477" >
|
|
<tr>
|
|
<td WIDTH="100">ldapsp.jar </td>
|
|
|
|
<td WIDTH="400">Netscape LDAP Service Provider for JNDI</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>ldapjdk.jar</td>
|
|
|
|
<td>Netscape Directory SDK for Java 4.0 Beta</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>jndi.jar</td>
|
|
|
|
<td>JNDI 1.2 FCS</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>(2) Specify the Netscape LDAP provider as the provider in the context
|
|
environment created for the initial context;
|
|
<br> <tt>Hashtable env = new Hashtable();</tt>
|
|
<br><tt> env.put(Context.INITIAL_CONTEXT_FACTORY,</tt>
|
|
<br><tt> "com.netscape.jndi.ldap.LdapContextFactory");</tt>
|
|
<br><tt> env.put(...</tt>
|
|
<br><tt> ...</tt>
|
|
<br><tt> DirContext ctx = new InitialDirContext(env);</tt>
|
|
<p>(3) For storing of Java objects in a LDAP Directory, the JNDI
|
|
java object schema must be added to the directory. To enable the JNDI schema
|
|
copy the file <i>jndi-object-schema.conf</i> to your <i><server-root>/slapd-<id>/config</i>
|
|
directory, and include the file into your <i><server-root>/slapd-<id>/config/ns-schema.conf</i>
|
|
schema configuration file.
|
|
<p>For examples of using JNDI please go to the official JNDI site.
|
|
<h3>
|
|
<a NAME="Env Props"></a>Environment Properties</h3>
|
|
The environment properties can be passed directly to the initial context
|
|
as a hash table, or specified as system properties. For compatibility reasons,
|
|
for those environment properties that are relevant to LDAP protocol but
|
|
are not defined in the JNDI, the Netscape LDAP provider is using the same
|
|
property names as the SUN LDAP service provided, if a property with the
|
|
same semantics is defined by the SUN provider.
|
|
<p>Note: If a new property is added to the context environment, or an existing
|
|
property is changed after the initial context is created, the change will
|
|
be immediately visible unless the changed property pertains to the connection.
|
|
For changes related to connection, in order to take effect you'll need
|
|
to invoke <i>LdapContext.reconnect().</i>
|
|
<p>The following table contains JNDI environment properties are relevant
|
|
for the Netscape LDAP service provider. Properties not found in this table
|
|
are silently ignored.
|
|
<br>
|
|
<table BORDER CELLSPACING=0 COLS=2 WIDTH="100%" >
|
|
<tr>
|
|
<th WIDTH="20%" BGCOLOR="#000000"><font color="#FFFFFF">Environment Property</font></th>
|
|
|
|
<th BGCOLOR="#000000"><font color="#FFFFFF">Description</font></th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>java.naming.factory.initial</td>
|
|
|
|
<td>
|
|
<br>This environment property is used to select the LDAP provider. To select
|
|
the Netscape LDAP provider "<b>com.netscape.jndi.ldap.LdapContextFactory</b>"
|
|
should be specified.
|
|
<p><tt> env.put(Context.INITIAL_CONTEXT_FACTORY, "com.netscape.jndi.ldap.LdapContextFactory");</tt></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>java.naming.provider.url</td>
|
|
|
|
<td>
|
|
<br>Specifies LDAP server information. For example:
|
|
<p><tt>env.put(Context.PROVIDER_URL, "ldap://dilly.mcom.com:389");</tt>
|
|
<p>If it has not been set then the provider will attempt to access an LDAP
|
|
server at port 389 on the local host.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>java.naming.ldap.version</td>
|
|
|
|
<td>
|
|
<br>Specifies the protocol version for the provider. Two values are
|
|
<br>possible:
|
|
<ul>
|
|
<li>
|
|
2 - selects LDAP Version 2 (LDAPv2)</li>
|
|
|
|
<li>
|
|
3 - selects LDAP Version 3 (LDAPv3)</li>
|
|
</ul>
|
|
For example, <tt>env.put("java.naming.ldap.version", "3");</tt>
|
|
<p>If this environment property has not been set then the provider will
|
|
<br>attempt to use LDAPv3.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>java.naming.security.authentication</td>
|
|
|
|
<td>
|
|
<br>Specifies the authentication mechanism for the provider to use.
|
|
<br>The following values are permitted for this property:
|
|
<ul>
|
|
<li>
|
|
<b>none</b> - use no authentication
|
|
(anonymous)</li>
|
|
|
|
<li>
|
|
<b>simple</b> - use weak authentication (clear
|
|
text password)</li>
|
|
</ul>
|
|
If this environment property has not been set but the
|
|
java.naming.security.principal environment property has been
|
|
<br>set then the provider will use 'simple'. If neither have been set then
|
|
the provider will use anonymous bind.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td WIDTH="20%">java.naming.security.principal</td>
|
|
|
|
<td>
|
|
<br>Specifies the DN of the principal to be authenticated. For example:
|
|
<p><tt>env.put(Context.SECURITY_PRINCIPAL, "cn=Directory manager");</tt>
|
|
<p>If this environment property has not been set then the provider
|
|
<br>will use anonymous bind.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>java.naming.security.credentials</td>
|
|
|
|
<td>
|
|
<br>Specifies the password of the principal to be authenticated. For example:
|
|
<p><tt>env.put(Context.SECURITY_CREDENTIALS, "secret");</tt></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>java.naming.security.protocol</td>
|
|
|
|
<td>
|
|
<br> Specifies the security protocol for the provider to use. One
|
|
possible value is defined: <b>ssl</b> - use Secure Socket Layer
|
|
<p><tt> env.put(Context.SECURITY_PROTOCOL, "ssl");</tt>
|
|
<p>When this environment property has been set and the
|
|
<br> <i>java.naming.ldap.factory.socket</i> property has not been
|
|
set, then
|
|
<br>the ldapjdk default socket factory <i>netscape.net.SSLSocket</i>
|
|
is used. This class is provided with Netscape Communicator 4.05 and higher.
|
|
If java.naming.ldap.factory.socket property has been set, the
|
|
<br>socket factory specified therein is used.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>java.naming.ldap.factory.socket</td>
|
|
|
|
<td>Specifies the class name of a socket factory. This environment
|
|
<br>property is used to override the default socket factory. For example:
|
|
<p><tt>env.put("java.naming.ldap.factory.socket", "crysec.SSL.SSLSocket");</tt>
|
|
<p>If the security protocol environment property has been set but
|
|
this property has not been set, then this property's value is set to <i>netscape.net.SSLSocket</i>.
|
|
See ldapjdk documentation for more information for connecting over SSL.
|
|
<br> </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>java.naming.ldap.ssl.ciphers</td>
|
|
|
|
<td>Specifies the suite of ciphers used for SSL connections made through
|
|
sockets created by the factory specified with <i>java.naming.ldap.factory.socket</i>.
|
|
The value of this property is of type <i>java.lang.Object</i>. For example:
|
|
<p><tt><font size=-1>try {</font></tt>
|
|
<br><tt><font size=-1> Class c = Class.forName("crysec.SSL.SSLParams");</font></tt>
|
|
<br><tt><font size=-1> java.lang.reflect.Method m = </font></tt>
|
|
<br><tt><font size=-1>
|
|
getMethod("getCipherSuite",new Class[0]);</font></tt>
|
|
<br><tt><font size=-1> Object cipherSuite = m.invoke(null,null);</font></tt>
|
|
<br><tt><font size=-1> if (cipherSuite != null) {</font></tt>
|
|
<br><tt><font size=-1> env.put("java.naming.ldap.ssl.ciphers",
|
|
cipherSuite);</font></tt>
|
|
<br><tt><font size=-1> }</font></tt>
|
|
<br><tt><font size=-1>}</font></tt>
|
|
<br><tt><font size=-1>catch (Exception e) {}</font></tt>
|
|
<br> </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>java.naming.batchsize</td>
|
|
|
|
<td>Specifies that search results are to be returned in batches. A setting
|
|
of zero indicates that the provider should block until all results have
|
|
been received. If this environment property has not been set then search
|
|
results are returned in batches of one.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>java.naming.ldap.maxresults</td>
|
|
|
|
<td>
|
|
<br>The default maximum number of search results to be returned for
|
|
a search request. 0 means no limit. If not specified, the ldapjdk default
|
|
is 1000. This value can be overridden per request with the parameter <i>SearchConstraints</i>
|
|
in the <i>DirContex.search()</i> method.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>java.naming.ldap.timelimit</td>
|
|
|
|
<td>The default maximum number of milliseconds to wait for a search operation
|
|
to complete. If 0, which is the ldapjdk default, there is no maximum time
|
|
limit for a search operation. This value can be overridden per request
|
|
with the parameter <i>SearchConstraints</i> in the <i>DirContex.search()</i>
|
|
method.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>java.naming.referral</td>
|
|
|
|
<td>
|
|
<br> Specifies how referrals shall be handled by the provider. Three
|
|
possible values are defined:
|
|
<ul>
|
|
<li>
|
|
<b> follow</b> - automatically follow any referrals</li>
|
|
|
|
<li>
|
|
<b>throw</b> - throw a ReferralException for each referral</li>
|
|
|
|
<li>
|
|
<b>ignore</b> - ignore referrals if they appear in results and treat
|
|
them like ordinary attributes if they appear in entries.</li>
|
|
</ul>
|
|
If this environment property has not been set then the LDAP provider by
|
|
default follows referrals.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>java.naming.ldap.referral.limit</td>
|
|
|
|
<td>
|
|
<br>Specifies the maximum number of referrals to follow in a chain of
|
|
<br>referrals. A setting of zero indicates that there is no limit. The
|
|
default limit is 10.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>java.naming.ldap.deleteRDN</td>
|
|
|
|
<td> Specifies whether the old RDN is removed during rename().
|
|
<br> If the value is "true", the old RDN is removed; otherwise,
|
|
<br> the RDN is not removed. The default value is true.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>java.naming.ldap.derefAliases</td>
|
|
|
|
<td>
|
|
<br> Specifies how aliases are dereferenced during search operations.
|
|
<br> The possible values are:
|
|
<ul>
|
|
<li>
|
|
<b>always</b> always dereference
|
|
aliases</li>
|
|
|
|
<li>
|
|
<b>never</b> never dereference
|
|
aliases</li>
|
|
|
|
<li>
|
|
<b>finding</b> dereference aliases
|
|
only during name resolution</li>
|
|
|
|
<li>
|
|
<b>searching</b> dereference aliases only after name resolution</li>
|
|
</ul>
|
|
NOTE: Netscape LDAP Server 3.x and 4.x do not support aliases</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>java.naming.ldap.typesOnly</td>
|
|
|
|
<td>
|
|
<br> Specifies whether only attribute types are to be returned during
|
|
<br> searches and getAttributes(). Its possible values are "true"
|
|
or "false". The default is false.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>java.naming.ldap.conntrol.connect</td>
|
|
|
|
<td>An array of <i>Control</i>s to be set on the LDAPConnection before
|
|
a connection attempt is made to the server. </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>java.naming.ldap.attributes.binary</td>
|
|
|
|
<td>Specifies attributes that have binary syntax. It extends the provider's
|
|
list of known binary attributes. Its value is a space separated list of
|
|
attribute names.
|
|
<p><tt>env.put("java.naming.ldap.attributes.binary", "mpegVideo");</tt>
|
|
<p>In contrast to ldapjdk, JNDI does not provide for reading of attribute
|
|
values as either Strings or byte arrays. All attributes are returned as
|
|
Strings unless recognized as having binary syntax. The values of attributes
|
|
that have binary syntax are returned as byte arrays instead of Strings.
|
|
<p>If this environment property has not been set then, by default, only
|
|
the following attributes are considered to have binary syntax:
|
|
<ul>
|
|
<li>
|
|
attribute names containing '<b>;binary'</b></li>
|
|
|
|
<li>
|
|
photo
|
|
(0.9.2342.19200300.100.1.7)</li>
|
|
|
|
<li>
|
|
personalSignature (0.9.2342.19200300.100.1.53)</li>
|
|
|
|
<li>
|
|
audio
|
|
(0.9.2342.19200300.100.1.55)</li>
|
|
|
|
<li>
|
|
jpegPhoto
|
|
(0.9.2342.19200300.100.1.60)</li>
|
|
|
|
<li>
|
|
javaSerializedData (1.3.6.1.4.1.42.2.27.4.1.7)</li>
|
|
|
|
<li>
|
|
thumbnailPhoto (1.3.6.1.4.1.1466.101.120.35)</li>
|
|
|
|
<li>
|
|
thumbnailLogo (1.3.6.1.4.1.1466.101.120.36)</li>
|
|
|
|
<li>
|
|
userPassword
|
|
(2.5.4.35)</li>
|
|
|
|
<li>
|
|
userCertificate (2.5.4.36)</li>
|
|
|
|
<li>
|
|
cACertificate
|
|
(2.5.4.37)</li>
|
|
|
|
<li>
|
|
authorityRevocationList (2.5.4.38)</li>
|
|
|
|
<li>
|
|
certificateRevocationList (2.5.4.39)</li>
|
|
|
|
<li>
|
|
crossCertificatePair
|
|
(2.5.4.40)</li>
|
|
|
|
<li>
|
|
x500UniqueIdentifier (2.5.4.45)</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>java.naming.ldap.ref.separator</td>
|
|
|
|
<td>Specifies the character to use when encoding a RefAddr object in
|
|
<br>the javaReferenceAddress attribute. This environment property should
|
|
be used to avoid a conflict in the case where the default separator
|
|
character appears in the components of a RefAddr object.
|
|
<p> If unspecified, the default separator is the hash character '#'.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h3>
|
|
<a NAME="Controls"></a>Working with Controls</h3>
|
|
JNDI 1.2 adds support for Controls which are fully implemented with the
|
|
Netscape LDAP provider. However, JNDI 1.2 does not define interfaces for
|
|
any of the standard controls, like for example the sort control. Instead,
|
|
the task of defining particular controls and their interfaces is left to
|
|
service providers. Therefore, if using controls, you will also need to
|
|
import the <i>com.netscape.jndi.ldap.controls</i> package in your
|
|
souce in addition to the JNDI packages.
|
|
<p>Being implemented on the top of ldapjdk, the Netscape LDAP provider
|
|
simply exposes all of the ldapjdk controls as JNDI controls. Thus, the
|
|
control APIs are exactly the same as in ldapjdk. The only difference is
|
|
that for the LDAP provider controls class names start with "Ldap"
|
|
while in ldapjdk the class names start with "LDAP". For instance, the ldapjdk
|
|
control LDAPSortControl is LdapSortControl in the Netscape LDAP provider.
|
|
<p>Here is an example of how to use the LdapSortControl. Notice that you'll
|
|
need to obtain a LdapContext object as an initial context, because controls
|
|
are not part of the directory context (DirContext). That means that instead
|
|
of calling <i>getInitialDirContext()</i> you 'll need to call <i>getInitialLdapContext()</i>.
|
|
<p><tt>import java.util.Hashtable;</tt>
|
|
<br><tt>import javax.naming.*;</tt>
|
|
<br><tt>import javax.naming.directory.*;</tt>
|
|
<br><b><tt>import javax.naming.ldap.*;</tt></b>
|
|
<br><b><tt>import com.netscape.jndi.ldap.controls.*;</tt></b>
|
|
<p><tt>public class SortReverseOrder {</tt>
|
|
<p><tt>public static void main(String[] args) {</tt>
|
|
<p><tt> Hashtable env = new Hashtable(5, 0.75f);</tt>
|
|
<br><tt> /*</tt>
|
|
<br><tt> * Specify the initial context implementation
|
|
to use.</tt>
|
|
<br><tt> */</tt>
|
|
<br><tt> env.put(Context.INITIAL_CONTEXT_FACTORY,</tt>
|
|
<br><tt> "com.netscape.jndi.ldap.LdapContextFactory");</tt>
|
|
<p><tt> /* Specify host and port to use for directory
|
|
service */</tt>
|
|
<br><tt> //env.put(Context.PROVIDER_URL, "ldap://localhost:389");</tt>
|
|
<p><tt> LdapContext ctx = null;</tt>
|
|
<br><tt> try {</tt>
|
|
<br><tt> /* get a handle to an
|
|
Initial DirContext */</tt>
|
|
<br><tt> <b>ctx = new InitialLdapContext(env,
|
|
null);</b></tt>
|
|
<p><tt> /* specify search constraints
|
|
to search subtree */</tt>
|
|
<br><tt> SearchControls cons
|
|
= new SearchControls();</tt>
|
|
<br><tt> cons.setSearchScope(SearchControls.SUBTREE_SCOPE);</tt>
|
|
<br><tt> cons.setReturningAttributes(new
|
|
String[] { "sn" });</tt>
|
|
<p><tt> // specify sort control</tt>
|
|
<br><tt> <b>ctx.setRequestControls(</b></tt>
|
|
<br><tt>
|
|
<b>new Control[] {new LdapSortControl(</b></tt>
|
|
<br><tt>
|
|
<b>new LdapSortKey[]{</b></tt>
|
|
<br><tt>
|
|
<b>new LdapSortKey("sn", true,null)},Control.CRITICAL)});</b></tt>
|
|
<p><tt> /* search for all entries
|
|
with surname of Jensen */</tt>
|
|
<br><tt> NamingEnumeration results</tt>
|
|
<br><tt>
|
|
= ctx.search("o=mcom.com", "(objectclass=person)", cons);</tt>
|
|
<p><tt> /* for each entry print
|
|
out name + all attrs and values */</tt>
|
|
<br><tt> while (results != null
|
|
&& results.hasMore()) {</tt>
|
|
<br><tt>
|
|
SearchResult si = (SearchResult)results.next();</tt>
|
|
<p><tt>
|
|
Attributes attrs = si.getAttributes();</tt>
|
|
<br><tt>
|
|
/* print each attribute */</tt>
|
|
<br><tt>
|
|
for (NamingEnumeration ae = attrs.getAll(); ae.hasMoreElements();) {</tt>
|
|
<br><tt>
|
|
Attribute attr = (Attribute)ae.next();</tt>
|
|
<br><tt>
|
|
String attrId = attr.getID();</tt>
|
|
<p><tt>
|
|
/* print each value */</tt>
|
|
<br><tt>
|
|
for (NamingEnumeration vals = attr.getAll(); vals.hasMore();</tt>
|
|
<br><tt>
|
|
System.out.println(attrId + ": " + vals.next()));</tt>
|
|
<br><tt>
|
|
}</tt>
|
|
<br><tt>
|
|
System.out.println();</tt>
|
|
<br><tt> }</tt>
|
|
<br><tt> }</tt>
|
|
<br><tt> catch (NamingException e) {</tt>
|
|
<br><tt> System.err.println("Search
|
|
example failed.");</tt>
|
|
<br><tt> e.printStackTrace();</tt>
|
|
<br><tt> }</tt>
|
|
<br><tt> finally {</tt>
|
|
<br><tt> // cleanup</tt>
|
|
<br><tt> if (ctx != null) {</tt>
|
|
<br><tt> try
|
|
{ ctx.close(); } catch (Exception e) {}</tt>
|
|
<br><tt> }</tt>
|
|
<br><tt> }</tt>
|
|
<br><tt>}</tt>
|
|
<br><tt>}</tt>
|
|
<p>For full documenation on available controls and their interfaces, please
|
|
check the ldapjdk documentation.
|
|
<h3>
|
|
<a NAME="Not Impl"></a>What's Not Implemented</h3>
|
|
Currently, the following JNDI features are not implemented by the Netscape
|
|
JNDI provider:
|
|
<ul>
|
|
<li>
|
|
Support for federated names</li>
|
|
|
|
<li>
|
|
Support for the code base attribute for objects stored in LDAP directory.
|
|
Therefore, the class name specified with the <i>javaClassName</i> attribute
|
|
must be available in the local <i>CLASSPATH</i>.</li>
|
|
|
|
<li>
|
|
<i>search()</i> and <i>modifyAttribute()</i> methods for schema directory
|
|
contexts. Instead of <i>DirContext.search()</i>, the <i>Context.lookup()</i>
|
|
request should be used for a schema directory context. Instead of <i>DirContext.modifyAttribute()</i>,
|
|
<i>DirContext.deleteSubcontext()</i>
|
|
followed the <i>DirContext.craeteSubcontext()
|
|
</i>should be used.</li>
|
|
</ul>
|
|
|
|
</body>
|
|
</html>
|