forked from aptivate/openldap-jldap
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
409 lines (312 loc) · 17.4 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
LDAP Classes for Java
June 2005
Table of Contents
1.0 LDAP Classes for Java
2.0 Known Issues and Solutions
3.0 Dependencies
4.0 Installation
5.0 LDAPv2 and LDAPv3 Support
6.0 Java LDAP Documentation
7.0 Building JLDAP
8.0 Building DSML Services
8.1 dsmlstream.war
8.2 dsmldom.war
9.0 Building DSMLv2 & SPML Connection Support
10.0 Using DSMLv2 Connection Support
11.0 Using SPML Connection Support
1.0 LDAP Classes for Java
LDAP (Lightweight Directory Access Protocol) is
an emerging Internet standard for accessing directory
information, allowing LDAP-enabled applications to
access multiple directories. LDAP v3 supports such
features as secure connections (through SSL and SASL),
entry management, schema management, and LDAP controls
and extensions for expanding LDAP's functionality.
The LDAP Classes for Java enables you to
write applications to access, manage, update, and
search for information stored in LDAP-aware directories.
This API is a work-in-progress implementing the IETF draft 18
of the Java LDAP API (draft-ietf-ldapext-ldap-java-api-18.txt),
and as such, most but not all features in the IETF draft are
currently implemented. For details, see section 2.0.
2.0 Known Issues and Solutions
- The Java LDAP API IETF 18 draft Features not yet implemented.
Classes do not yet extend Serializable
The API does not return the exception LDAPLocalException in all
cases where the exception does not originate from the server.
The class LDAPExtendedResponse does not yet implement the register
method.
- An incompatibility with previous versions exists for applicatons
using LDAPSchema.getAtribute() and LDAPSchemaElement.getName().
Both methods were deprecated in the May 2002 NDK. These methods
have been removed in this release of the API to comply with IETF
draft version 18 (draft-ietf-ldapext-ldap-java-api-18.txt).
The reason for this change is described in the following text.
LDAPSchema now extends LDAPEntry. This means that LDAPSchema
inherits the getAttribute method from LDAPEntry which has the same
signature as the getAttribute method of LDAPSchema, but the two
methods differ in functionality. Thus, the getAttribute method of
LDAPSchema has been removed from the IETF draft and from the API
in this release.
To fix your application, use the getAttributeSchema method of
LDAPSchema instead of getAttribute.
The following error will occur when trying to compile code
using this deprecated method:
incompatible types;
found: com.novell.ldap.LDAPAttribute,
required: com.novell.ldap.LDAPSchemaElement
The following error will occur when trying to run code using this
deprecated method:
java.lang.NoSuchMethodError
LDAPSchemaElement now extends LDAPAttribute. This means that
LDAPSchemaElement inherits the getName method from LDAPAttribute
which has the same signature as the getName method of
LDAPSchemaElement, but the two methods differ in functionality.
Thus, the getName method of LDAPSchemaElement has been removed
from the IETF draft and from the API in this release.
To fix your application, use the getNames method of
LDAPSchemaElement instead of getName.
Note: You will not get a compile or runtime error if your code
uses this deprecated method. You may, however, get errors trying
to intrepret the data returned.
3.0 Dependencies
Building the Java LDAP API is dependent upon the following:
- JDK 1.4 or higher, required for building classes that
use the new DSML functionality. Optionally, you can use JDK 1.2
or higher by installing the JAXP package and XML parser and
by and placing the associated jar files the external directory
external/jaxp as follows:
external/jaxp/jaxp.jar
external/jaxp/xerces.jar
- JDK 1.4 or higher, required for building classes that reference
TLS(SSL) connections. Optionally, you can download a Sun-compliant
JSSE implementation to compile with JDK 1.2 or higher and place
the associated jar files in the external/jsse directory as follows:
external/jsse/lib/jcert.jar
external/jsse/lib/jnet.jar
external/jsse/lib/jsse.jar
- The Ant build tool for Java, required for building the product.
Ant was developed by the jakarta.apache.org project and can be
obtained from their web site. We have built this system using
Ant version 1.5.1 compiled on October 2 2002.
The ant tool is placed in the following directory structure
under the root of the source.
external/ant/LICENSE
external/ant/LICENSE.dom
external/ant/LICENSE.sax
external/ant/LICENSE.xerces
external/ant/welcome.html
external/ant/bin/ant
external/ant/bin/ant.bat
external/ant/bin/antRun
external/ant/bin/antRun.bat
external/ant/bin/lcp.bat
external/ant/etc/changelog.xsl
external/ant/etc/checkstyle-frames.xsl
external/ant/etc/coverage-frames.xsl
external/ant/etc/jdepend-frames.xsl
external/ant/etc/jdepend.xsl
external/ant/etc/junit-frames.xsl
external/ant/etc/junit-noframes.xsl
external/ant/etc/log.xsl
external/ant/etc/maudit-frames.xsl
external/ant/etc/mmetrics-frames.xsl
external/ant/etc/tagdiff.xsl
external/ant/lib/ant.jar
external/ant/lib/optional.jar
external/ant/lib/xercesImpl.jar
external/ant/lib/xml-apis.jar
Running an application that uses the LDAP Classes for
Java is dependent upon the following:
- JRE 1.2 or higher, required to run an application.
- JDK/JRE 1.4 or higher, required for running appplications that use
the new DSML functionality. Optionally, you can use JDK/JRE 1.2 or
higher by installing the JAXP package and setting the associated
jar files in your classpath.
- JDK/JRE 1.4 or higher, required for running applications that create
TLS(SSL) connections. Optionally, you can download a Sun-compliant
JSSE implementation to run with JDK/JRE 1.2 or higher.
- A directory that supports TLS(SSL), required if you wish to
run applications that create TLS(SSL) connections.
- Novell eDirectory 8.5 or higher, required if you wish to run
applications that use the LDAP extensions for partition and
replica management.
- Applications that use com.novell.ldap.util.DSMLReader require
an XML parser (like xerces.jar) in order to run. This jar file needs
to be in classpath of the Application.
4.0 Installation
To install the libraries do the following:
1. Run the build process outlined below.
2. Copy the ldap.jar file (either debug or release) to a directory
of your choice on your platform.
3. Add the complete path, including the file name, of the
ldap.jar file to your CLASSPATH.
5.0 LDAPv2 and LDAPv3 Support
This version of the LDAP Classes for Java supports LDAPv3.
Since the consensus in the LDAP community is to encourage
everyone to update to LDAPv3, there is no attempt to ensure
that these libraries support LDAPv2 servers.
6.0 Java LDAP Documentation
Building JLDAP generates javadoc for the Java LDAP Classes.
There are three directories containing javadoc. The index.html
file is the starting point for the javadoc in each of the directories.
The directories are:
pkg/ietfdoc - contains javadoc for the public classes of the IETF LDAP
Java API. These classes are used by applications needing
binary compatibility with Java LDAP implementations from
other vendors.
pkg/doc - contains javadoc for the public classes of the Novell LDAP
Java API. These classes provide a richer set of
functionality than the IETF classes, and are used by
applications needing a full featured API.
doc - contains javadoc for all classes in the LDAP Java API,
and includes package and private methods and variables.
This javadoc is typically used by developers developing
or modifying the API.
7.0 Building JLDAP
JLDAP is built using a system developed by jakarta.apache.org called ANT.
The build files are named "build.xml" and "javac.xml" and are found in the
root directory of the Java LDAP source.
To set up your environment for ANT, do the following:
For Win32
Assuming this source directory on win32 is d:\jldap, and java is installed
in d:\j2sdk1.4.1_1 then you set in your environment:
set JAVA_HOME=d:\j2sdk1.4.1_1
set ANT_HOME=d:\jldap\external\ant
PATH %ANT_HOME%\bin;%JAVA_HOME%\bin;%PATH%
For Linux / Unix
Assuming the following:
1) A Linux system running bourne shell
2) The source directory is located in /work/jldap
3) The Java jdk is installed in /usr/local/j2sdk1.4.1_1
then export in your environment:
ANT_HOME=/work/jldap/external/ant
JAVA_HOME=/usr/local/j2sdk1.4.1_1
PATH="$ANT_HOME/bin:$JAVA_HOME/bin:$PATH"
export ANT_HOME JAVA_HOME PATH
To build everything except the DSML services, invoke ant as follows from the
top of the source tree:
ant all
Targets available at the top of the source tree are:
clean - Cleans all generated files and directories in this and
subbordinate directories
cleanpkg - Cleans pkg directory
cleanwars - Cleans services/dsml directory
doc - Builds javadoc files
debug - Builds debug classes and jar files
release - Builds release classes and jar files
lib - Builds debug & release classes and jar files
jar - Synonym for lib
all - Builds everything possible except the DSML services.
This builds in all directories - debug and release jar files,
java doc, samples, test programs, and creates an installation
directory called pkg.
install - Copies build results from all directories and creates the
pkg directory
pkg - Synonym for install
war_stream- Builds dsmlstream.war (see 8.0 Building DSML Services)
war_dom - Builds dsmldom.war (see 8.0 Building DSML Services)
wars - Builds dsmlstream.war and dsmldom.war
The following directories are created when "ant all" is run:
Contents of directories in the ldap directory
jldap/ldap/classes # Classes used to build lib/ldap.jar
jldap/ldap/classes_debug # Classes used to build lib_debug/ldap.jar
jldap/ldap/doc # Developer Javadoc for classes in ldap.jar
jldap/ldap/lib # Jar file for ldap - optimized, debug off
jldap/ldap/lib_debug # Jar file for ldap - not optimized, debug on
Contents of directories in the jldap/pkg directory
jldap/pkg # Distribution directories and files
jldap/pkg/doc # Javadoc for the Java LDAP API
jldap/pkg/ietfdoc # Javadoc for the IETF Java LDAP API
jldap/pkg/lib # Jar file for ldap - optimized, debug off
jldap/pkg/lib_debug # Jar file for ldap - not optimized, debug on
8.0 Building DSML Services
The LDAP Classes for Java include functionality that enables an LDAP server to
run as a DSML service. Currently there are two DSML service implementations
(.war files) that can be generated using the ant build process: dsmlstream.war
and dsmldom.war. See README.dsml for additional information.
8.1 dsmldom.war
In addition to the dependencies listed in section 3.0, building
dsmldom.war is dependent upon the following:
- Novell eXtend JBroker Web. During the JBroker Web installation,
specify the following install location:
<javasource_home>/external/JBroker. JBroker Web can be obtained
at https://developer.novell.com/ndk/jbroker.htm.
To build dsmldom.war, invoke ant as follows from the
top of the source tree:
ant war_dom
8.2 dsmlstream.war
In addition to the dependencies listed in section 3.0, building
dsmlstream.war is dependent upon the following:
- servlet.jar. If you have installed JBroker Web, as outlined
in 8.1, servlet.jar is already installed. If not, place the
servlet.jar from your application server (JBroker, tomcat, etc.)
in the directory <javasource_home>/external/servlet/.
NOTE: dsmlstream.war requires an XML parser (like xerces.jar) in order
to run. This jar file needs to be in the classpath of the Web
Application Server or Servlet engine running dsmlstream.war.
To build dsmlstream.war, invoke ant as follows from the
top of the source tree:
ant war_stream
You can build both of the above war files by invoking ant as follows:
ant wars
9.0 Building DSMLv2 & SPML Connection Support
The JLDAP libraries provide optional support for using DSMLv2 and SPML in
a similar fashion as you would use an LDAP connection. In order to build
support for this functionality into JLDAP you need to add the following
libraries to the "ext" directory of your JLDAP source directory:
commons-httpclient-*.jar - https://jakarta.apache.org/site/news/news-2005-q2.html#20050410.1
openspml.jar & soap.jar - https://www.openspml.org/
10. Using DSMLv2 Connection Support
The JLDAP libraries provide optional support for interacting with DSMLv2 based directories
like you would an LDAP directory. In order to use this functionality, you first create your
DSML connection:
DsmlConnection dsmlCon = new DsmlConnection();
//Some DSMLv2 implementations do not support SOAP
dsmlCon.setUseSOAP(true);
//The port is in the URL
dsmlCon.connect("https://my.ldap.domain.com:port/path/to/dsmlv2",0);
LDAPConnection con = dsmlCon;
con.bin("CN=User","secret");
.
.
.
Once case to an LDAPConnection, you can perform any synchronouse operation. Operations that
involve queue's are not supported. The bind operation includes the bind dn and password in
an HTTP BASIC authentication header.
In addtion you may create an implementation of the com.novell.ldap.util.HttpRequestCallback
interface to add HTTP Header variables.
The DSMLv2 connection library has been tested with Novell DSMLv2 web services, Octet String
VDE 3.0+ and IBM Tivoli Directory Integrator.
11. Using SPML Connection Support
The JLDAP libraries provide optional support for the Service Provisioning Markup Language.
SPML is a standard for integrating and interacting with provisioning servers. SPML support
is provided by the OpenSPML project. In order to use SPML using JLDAP:
//Create the connection using a "no auth" implementation.
SPMLConnection spmlCon = new SPMLConnection("com.novell.ldap.spml.NoAuthImpl");
spmlCon.connect("https://my.spml.domain.com/path/to/spml",0);
LDAPConnection con = spmlCon;
.
.
.
Like the DSMLv2 connection libraries, the SPML libraries only support synchronous operations.
As in DSMLv2, there is no BIND operation. Each SPML implementation has it's own standard. JLDAP
contains support for Sun Identity Manager and OpenSPML implementations. New authentication
schemes can be implemented by implementing the com.novell.ldap.spml.SPMLImpl interface.
When manipluating users, the DN takes the follwing form:
IdentityType=name
For instance, using the GenericString identifier the DN may be
GenericString=myUserName
$OpenLDAP$
******************************************************************************
* Copyright (C) 1999 - 2003 Novell, Inc. All Rights Reserved.
*
* THIS WORK IS SUBJECT TO U.S. AND INTERNATIONAL COPYRIGHT LAWS AND
* TREATIES. USE, MODIFICATION, AND REDISTRIBUTION OF THIS WORK IS SUBJECT
* TO VERSION 2.0.1 OF THE OPENLDAP PUBLIC LICENSE, A COPY OF WHICH IS
* AVAILABLE AT HTTP:https://WWW.OPENLDAP.ORG/LICENSE.HTML OR IN THE FILE "LICENSE"
* IN THE TOP-LEVEL DIRECTORY OF THE DISTRIBUTION. ANY USE OR EXPLOITATION
* OF THIS WORK OTHER THAN AS AUTHORIZED IN VERSION 2.0.1 OF THE OPENLDAP
* PUBLIC LICENSE, OR OTHER PRIOR WRITTEN CONSENT FROM NOVELL, COULD SUBJECT
* THE PERPETRATOR TO CRIMINAL AND CIVIL LIABILITY.
******************************************************************************