Interceptors are used to handle specific steps before storing an object in the backend. W e will use them to authenticate a user, normalize a DN, log some information, etc...

They are like filters in servlet.

Each operation is associated with a method in each interceptors, even if it does nothing else than calling the next interceptor.

The base idea is to allow pre and post actions to be executed before and after the call of the next interceptors :

Each interceptor process the pre action, call the next interceptor, wait for the response, execute the post action, and returns. We have to implement this chain of interceptors in a way which allows us to add new interceptors, or new pre or post actions, without having to modify the existing code or mechanism. 

Bind Operation

The Bind  operation call the interceptor chain in the PartitionNexusProxy class, where we can found a bind method :

public void bind( LdapDN bindDn, byte[] credentials, List mechanisms, String saslAuthId, Collection bypass ) throws NamingException
    {    ...
            this.configuration.getInterceptorChain().bind( bindDn, credentials, mechanisms, saslAuthId );    ...

this will call the first configured interceptor from a chain which is declared in the configuration file server.xml. The first interceptor is the NormalizationService.

The information which are passed are :

• The DN used to bind
• The password (credentials)
• The list of supported mechanisms 
• The SASL authent
  We will often use only the two first elements.

Normalization interceptor

This interceptor will just normalize the DN used to bind. If the DN is invalid, an exception will be thrown.

It is the first interceptor in the chain because as we will manupulate the DN through all interceptors, it is important that we normalize it as soon as possible.

The normalized DN will be stored in an special form, usefull for internal comparizons. This operation can be costly, but as the DN has already been parsed, this is quite efficient.

We can call the next interceptor :

Authentication interceptor

We must check that this bind request is valid, that is the DN and the associated password are known by the server. We have two cases :

1. The user have already been authenticated
2. This is the first time this user try to bind

 What we call user is the DN of a known entry stored in the server.

In the first case, we will have to search the password in the backend, and this will be a lookup operation, which will be applied through another chain of interceptors.

Let's assume we are in the second case, because if we are in the first case, we will have to ask the backend about the entry which DN is equal to the one we received, to get its associated password, thus callaing a specific chain of interceptors (FINAL_INTERCEPTOR).

The password is compared using the given mechanism (which should be simple on a new server), and if it matches, we create a principal object which will be stored in the connection context for future usage.

We are done with the bind operation.

 Add operation

An add operation is more complex. What we need to do is to check if the current user has enough right to add an entry, and that the entry can be added.

A new entry is a composition of three elements :

• A partition name
• A path from this partition
• An entry name

For instance, when adding an entry which DN is cn=acme, ou=users, ou=system , we will have :

• Partition = "ou=system"
• Path = "ou=users, ou=system"
• Entry name = "cn=acme"
  The two first elements must exist in the base. We can't add an entry in an not existing partition, and we can't add an entry which path is not existing.