directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From elecha...@apache.org
Subject svn commit: r1416994 - in /directory/site/trunk/content/api/user-guide: 1-introduction.mdtext 1.1-java-and-ldap.mdtext 2.1-connection-disconnection.mdtext 2.2-binding-unbinding.mdtext
Date Tue, 04 Dec 2012 15:31:36 GMT
Author: elecharny
Date: Tue Dec  4 15:31:34 2012
New Revision: 1416994

URL: http://svn.apache.org/viewvc?rev=1416994&view=rev
Log:
Added some new pages

Added:
    directory/site/trunk/content/api/user-guide/2.1-connection-disconnection.mdtext
    directory/site/trunk/content/api/user-guide/2.2-binding-unbinding.mdtext
Modified:
    directory/site/trunk/content/api/user-guide/1-introduction.mdtext
    directory/site/trunk/content/api/user-guide/1.1-java-and-ldap.mdtext

Modified: directory/site/trunk/content/api/user-guide/1-introduction.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/1-introduction.mdtext?rev=1416994&r1=1416993&r2=1416994&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/1-introduction.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/1-introduction.mdtext Tue Dec  4 15:31:34
2012
@@ -25,3 +25,11 @@ Notice: Licensed to the Apache Software 
 This User Guide goal is to provide some clue for any developer wanting to use the LDAP API.
We have mixed some description of each important features with some tested snippet of code
(all of them has been integrated as tests in the API code).
 
 We hope it will be enough for you to quickly get started, but in any case, if you feel like
improving this document, feel free to post your suggestion to the Apache Directory mailing
list : any contribution is welcomed !
+
+## Contents
+
+*  [1.1 - Java and LDAP](1.1-java-and-ldap.html)
+*  [1.2 - LDAP in a few words](1.2-ldap-in-a-few-words.html)
+*  [1.3 - The Apache LDAP API rational](1.3-apache-ldap-api-rational.html)
+*  [1.4 - Preparation to code](1.4-preparation-to-code.html)
+

Modified: directory/site/trunk/content/api/user-guide/1.1-java-and-ldap.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/1.1-java-and-ldap.mdtext?rev=1416994&r1=1416993&r2=1416994&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/1.1-java-and-ldap.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/1.1-java-and-ldap.mdtext Tue Dec  4 15:31:34
2012
@@ -23,24 +23,24 @@ Notice: Licensed to the Apache Software 
     under the License.
 
 # 1.1 - Java and LDAP
-Most developer will, at some point, face the tricky task to communicate with a LDAP server.
LDAP seems to be a very simple technology, but when you get deep into it, you realize that
many aspects are not well known, and not so easy to deal with.
+Most developer will, at some point, face the tricky task to communicate with a **LDAP** server.
**LDAP** seems to be a very simple technology, but when you get deep into it, you realize
that many aspects are not well known, and not so easy to deal with.
 
-Java is most certainly the number one language used in the enterprise, for around 10 years
now. Some even call it the new Cobol !
+Java is most certainly the number one language used in the enterprise, for around 10 years
now. Some even call it the new **Cobol** !
 
-Those two facts make it necessary to be able to communicate with a LDAP server in Java. This
is ware a convenient API is useful, and this is why we decided to provide this API.
+Those two facts make it necessary to be able to communicate with a **LDAP** server in **Java**.
This is ware a convenient **API** is useful, and this is why we decided to provide this **API**.
 
-Of course, there are alternatives, like JNDI. We truly believe that those alternative aren't
helping users to cope with the complexity of LDAP, at least they are not giving a hand to
users. For instance, JNDI semantic are far awy from *LDAP semantic. Let's see how different
it is :
+Of course, there are alternatives, like **JNDI**. We truly believe that those alternative
aren't helping users to cope with the complexity of **LDAP**, at least they are not giving
a hand to users. For instance, **JNDI** semantic are far awy from **LDAP** semantic. Let's
see how different it is :
 
-* Bind : used in LDAP to authenticate a user, and to create an entry in JNDI
-* Unbind : close the LDAP session in LDAP, delete an entry in JNDI
-* Compare : this LDAP operation is mapped to a Search in JNDI
-* Various properties have to be set in JNDI in order to connect or tweak the Search operation,
which is not convenient
-* Attributes is case sensitive by default in JNDI, and they aren't schema aware
-* Name in JNDI are not able to do a valid comparison in JNDI
-* NamingEnumeration have to be explcitly closed in JNDI, as they aren't closed when you disconnect,
leading to some resource leaks.
+* **Bind** : used in **LDAP** to authenticate a user, and to create an entry in **JNDI**
+* **Unbind** : close the **LDAP** session in **LDAP**, delete an entry in **JNDI**
+* **Compare **: this **LDAP** operation is mapped to a Search in **JNDI**
+* Various properties have to be set in **JNDI** in order to connect or tweak the **Search**
operation, which is not convenient
+* **Attributes** is case sensitive by default in **JNDI**, and they aren't schema aware
+* **Name** in **JNDI** are not able to do a valid comparison in **JNDI**
+* **NamingEnumeration** have to be explcitly closed in **JNDI**, as they aren't closed when
you disconnect, leading to some resource leaks.
 
-Some of those problems are also true for the existing LDAP API.
+Some of those problems are also true for the existing **LDAP API**.
 
-All in all, writing application including some LDAP operations in Java is just a painful
task for most of the developers.
+All in all, writing application including some **LDAP** operations in **Java** is just a
painful task for most of the developers.
 
-Our target is to provide a better API, that will help them getting efficient with their LDAP
interaction.
\ No newline at end of file
+Our target is to provide a better **API**, that will help them getting efficient with their
**LDAP** interaction.
\ No newline at end of file

Added: directory/site/trunk/content/api/user-guide/2.1-connection-disconnection.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/2.1-connection-disconnection.mdtext?rev=1416994&view=auto
==============================================================================
--- directory/site/trunk/content/api/user-guide/2.1-connection-disconnection.mdtext (added)
+++ directory/site/trunk/content/api/user-guide/2.1-connection-disconnection.mdtext Tue Dec
 4 15:31:34 2012
@@ -0,0 +1,72 @@
+Title: 2.1 - Connection and disconnection
+NavPrev: 2-basic-ldap-api-usage.html
+NavPrevText: 2 - Basic LDAP API usage
+NavUp: 2-basic-ldap-api-usage.html
+NavUpText: 2 - Basic LDAP API usage
+NavNext: 2.2-binding-unbinding.html
+NavNextText: 2.2 - Binding and unbinding
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+    .
+    http://www.apache.org/licenses/LICENSE-2.0
+    .
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+# 2.1 - Connection and disconnection
+
+**LDAP** is a protocol which requires the user to be connected - and eventually identified
- in order to be able to send requests to the server. We maintain this connection potentially
forever. What make the **LDAP** protocol different from, say, the *HTTP* protocol is that
the connection must be issued explicitly. Let's see how we do that.
+
+## Opening a connection
+
+We can open a secure or a standard connection. 
+
+### Standard connection
+
+We can first establish a standard connection, where the data are sent and received in clear
text (encoded in ASN.1 BER, but still not encrypted). This example expose the way it's done
:
+
+    :::Java
+    LdapConnection connection = new LdapNetworkConnection( "localhost", 389 );
+
+Here, we just created an unsafe connection locally, using the 389 port. Quite simple...
+
+### Secure connection
+
+Although the **LDAPS** (**LDAP** over **SSL**) is now considered as deprecated, many people
continue to use it. The big advantage of not using **LDAPS** is that you don't need to setup
two different listening ports (one for **LDAP** -389- and another one for **LDAPS** -636-
).
+
+The only difference with the previous example is that we have to tell the connection that
it has to use **SSL**, by passing **_true_** as a third parameter (incidentally, passing **_false_**
set a unsafe connection).
+
+Here is an example
+
+    :::Java
+    LdapConnection connection = new LdapNetworkConnection( "localhost", 636, true );
+
+h2. Maintaining the connection opened
+
+We keep the connection opened for a limited period of time, defaulting to 30 seconds. This
might be not long enough, so one can change this delay by calling the _setTimeOut()_ method
:
+
+    :::Java
+    LdapConnection connection = new LdapNetworkConnection( "localhost", 389 );
+    connection.setTimeOut( 0 );
+    ...
+    connection.close();
+
+>**Note:** Setting a value equal or below 0 will keep the connection opened for ever (or
a soon as the connection is not explicitly closed).
+
+## Closing the connection
+
+Once you don't need to use the connection anymore (remember that hodling a connection keeps
a session opened on the server, and a socket opened between the client and the server), then
you have to close it. This is done by calling the _close()_ method :
+
+    :::Java
+    LdapConnection connection = new LdapNetworkConnection( "localhost", 389 );
+    ...
+    connection.close();

Added: directory/site/trunk/content/api/user-guide/2.2-binding-unbinding.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/2.2-binding-unbinding.mdtext?rev=1416994&view=auto
==============================================================================
--- directory/site/trunk/content/api/user-guide/2.2-binding-unbinding.mdtext (added)
+++ directory/site/trunk/content/api/user-guide/2.2-binding-unbinding.mdtext Tue Dec  4 15:31:34
2012
@@ -0,0 +1,135 @@
+Title: 2.2 - Binding and unbinding
+NavPrev: 2.1-connection-disconnection.html
+NavPrevText: 2.1 - Connection and disconnection
+NavUp: 2-basic-ldap-api-usage.html
+NavUpText: 2 - Basic LDAP API usage
+NavNext: 2.3-searching.html
+NavNextText: 2.3 Searching
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+    .
+    http://www.apache.org/licenses/LICENSE-2.0
+    .
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+# 2.2 - Binding and unbinding (...)
+
+In **LDAP**, if one wants to access the data in the base, the common way to do it is to bind
on the server. However, it's important to understand that binding is a different beast than
connection.
+
+Creating a connection to a **LDAP** server is just about opening a socket between the client
and the server. You just need to provide the address and the port. 
+
+The **bind** operation, on the other hand, create a _Session_ which will hold some user's
information for the time being of the session. Those information are quite limited, they include
the user's credentials.
+
+But it's important to know that it's possible to bind as anonymous, providing no name and
password, and still be able to request the server (note though that the server can forbid
such anonymous bind).
+
+Once the user has finished to request the server, then he can unbind, destroying his session
on the server. That does not close the connection, because, one more time, _bind != connection_.
+
+## Binding
+
+You have two possible types of binds in *LDAP* :
+
+* **Simple**
+* **SASL**
+
+The first one is based on a user/password being send to the server, which check that they
are valid. It's also possible to proceed an Anonymous bind explicitly.
+
+The second one is more complex, and is used if you want to proceed an authentication with
some specific mechanism, like **DIGEST-MD5**, **Kerberos** or certificate based.
+
+### Simple Bind
+One can issue three kind of Simple bind :
+* _anonymous bind_
+* _name/password bind_
+* _unauthenticated authentication bind_
+
+The first one is the easiest one, but depending on the server configuration, it will be accepted
or rejected (all the servers don't allow anonymous binds)
+
+Issuing an anonymous bind is very simple, you just provide no user name nor any password
:
+
+    :::Java
+    @Test
+    public void testAnonymousBindRequest() throws Exception
+    {
+        BindResponse bindResponse = connection.bind();
+
+        assertNotNull( bindResponse );
+        assertEquals( ResultCodeEnum.SUCCESS, bindResponse.getLdapResult().getResultCode()
);
+        assertTrue( connection.isAuthenticated() );
+    }
+
+Issuing a user/password bind is just slightly more complex, you just have to provide your
user name and its password :
+
+    :::Java
+    @Test
+    public void testSimpleBindRequest() throws Exception
+    {
+        BindResponse bindResponse = connection.bind( "uid=admin,ou=system", "secret" );
+
+        assertNotNull( bindResponse );
+        assertEquals( ResultCodeEnum.SUCCESS, bindResponse.getLdapResult().getResultCode()
);
+        assertTrue( connection.isAuthenticated() );
+    }
+
+>**Note** It's important to note that the user's name is a *[Dn](6.9-dn.html)*, not a
simple name like 'John doe"
+
+Last, not least, there is a quite unknown feature in **LDAP** bind that allows you to issue
a Bind request without providing a password. It's equivalent to an anonymous bind, except
that the server can log the user's name, thus being able to trace what the user does. Servers
might forbid such bind, and this will be the case if the server disallow anonymous binds.
+
+Note that this kind of bind will be supported only if the server allows anonymous binds.
It's not supported by *ApacheDS*.
+
+    :::Java
+    @Test
+    public void testSimpleBindRequest() throws Exception
+    {
+
+        BindResponse bindResponse = connection.bind( "uid=admin,ou=system" );
+
+        assertNotNull( bindResponse );
+        assertEquals( ResultCodeEnum.SUCCESS, bindResponse.getLdapResult().getResultCode()
);
+        assertFalse( connection.isAuthenticated() );
+    }
+
+### SASL Bind
+
+TO BE COMPLETED
+
+### Unbinding
+
+This is a trivial operation : you just send an **UnbindRequest** to the server, which will
invalidate your session. 
+
+It's important to know that when you issue an **Unbind**, the connection is dropped. However,
if you immediately try another bind, the **API** will open the connection again, using the
information provided when the connection has been created. You can then do such a thing :
+
+    :::Java
+    @Test
+    public void testDoubleSimpleBindValid() throws Exception
+    {
+        BindResponse response = connection.bind( "uid=admin,ou=system", "secret" );
+        assertEquals( ResultCodeEnum.SUCCESS, response.getLdapResult().getResultCode() );
+        assertTrue( connection.isConnected() );
+        assertTrue( connection.isAuthenticated() );
+
+        // Now, unbind
+        connection.unBind();
+        assertFalse( connection.isConnected() );
+        assertFalse( connection.isAuthenticated() );
+
+        // And Bind again.
+        response = connection.bind( "uid=admin,ou=system", "secret" );
+        LdapResult ldapResult3 = response3.getLdapResult();
+        assertEquals( ResultCodeEnum.SUCCESS, response.getLdapResult.getResultCode() );
+        assertTrue( connection.isConnected() );
+        assertTrue( connection.isAuthenticated() );
+    }
+
+If you issue a _bind_ on the same connection with some different credentials, then the existing
session will be terminated on the server, and a new one will be created. All the pending requests
for the initial session will be lost.
+
+Last, not least, if you close the connection, then the session will also be terminated.
+ 



Mime
View raw message