Sun Java System Directory Server Enterprise Edition 6.1 Developer's Guide

Extending the Bind Operation

This section shows how to develop functions called by Directory Server before client bind operations.

Note –

Pre-bind plug-in functions are often used to handle extensions to authentication. Yet, you might have to account for special cases such as binds by the directory superuser and anonymous users. Sometimes, you have to account for multiple calls to the same preoperation or postoperation plug-in function.

To Set Up an Example Suffix

If you have not done so already, set up a directory instance with a suffix, dc=example,dc=com, containing data loaded from a sample LDIF file, install-path/ds6/ldif/Example.ldif.

Create a new Directory Server instance.

For example:

$ dsadm create /local/ds
Choose the Directory Manager password:
Confirm the Directory Manager password:
$

Start the new Directory Server instance.

For example:

$ dsadm start /local/ds
Server started: pid=4705
$

Create a suffix called dc=example,dc=com.

For example, with long lines folded for the printed page:

$ dsconf create-suffix -h localhost -p 1389 dc=example,dc=com
Enter "cn=directory manager" password: 
Certificate "CN=defaultCert, CN=hostname:1636" presented by the
 server is not trusted.
Type "Y" to accept, "y" to accept just once,
 "n" to refuse, "d" for more details: Y
$

Load the sample LDIF.

For example, with long lines folded for the printed page:

$ dsconf import -h localhost -p 1389 \
 /opt/SUNWdsee/ds6/ldif/Example.ldif dc=example,dc=com
Enter "cn=directory manager" password:  
New data will override existing data of the suffix
 "dc=example,dc=com".
Initialization will have to be performed on replicated suffixes. 
Do you want to continue [y/n] ? y

## Index buffering enabled with bucket size 16
## Beginning import job...
## Processing file "/opt/SUNWdsee/ds6/ldif/Example.ldif"
## Finished scanning file "/opt/SUNWdsee/ds6/ldif/Example.ldif" (160 entries)
## Workers finished; cleaning up...
## Workers cleaned up.
## Cleaning up producer thread...
## Indexing complete.
## Starting numsubordinates attribute generation.
 This may take a while, please wait for further activity reports.
## Numsubordinates attribute generation complete. Flushing caches...
## Closing files...
## Import complete. Processed 160 entries in 5 seconds.
 (32.00 entries/sec)

Task completed (slapd exit code: 0).
$

Logging the Authentication Method

The following example logs the bind authentication method. Refer to install-path/examples/testpreop.c for complete example code.

Example 6–2 Logging the Authentication Method (`testpreop.c`)

#include "slapi-plugin.h"

int
testpreop_bind(Slapi_PBlock * pb)
{
    char * auth;                       /* Authentication type     */
    char * dn;                         /* Target DN               */
    int    method;                     /* Authentication method   */
    int    connId, opId, rc = 0;
    long   msgId;

    /* Get target DN for bind and authentication method used.     */
    rc |= slapi_pblock_get(pb, SLAPI_BIND_TARGET,     &dn);
    rc |= slapi_pblock_get(pb, SLAPI_BIND_METHOD,     &method);
    rc |= slapi_pblock_get(pb, SLAPI_OPERATION_MSGID, &msgId);
    rc |= slapi_pblock_get(pb, SLAPI_CONN_ID,         &connId);
    rc |= slapi_pblock_get(pb, SLAPI_OPERATION_ID,    &opId);
    if (rc == 0) {
        switch (method) {
            case LDAP_AUTH_NONE:   auth = "No authentication";
                break;
            case LDAP_AUTH_SIMPLE: auth = "Simple authentication";
                break;
            case LDAP_AUTH_SASL:   auth = "SASL authentication";
                break;
            default: auth = "Unknown authentication method";
                break;
        }
    } else {
        return (rc);
    }

    /* Log target DN and authentication method info.              */
    slapi_log_info_ex(
        SLAPI_LOG_INFO_AREA_PLUGIN,
        SLAPI_LOG_INFO_LEVEL_DEFAULT,
        msgId,
        connId,
        opId,
        "testpreop_bind in test-preop plug-in",
        "Target DN: %s\tAuthentication method: %s\n", dn, auth
    );
    return (rc);
}

This plug-in function sets the auth message based on the authentication method. The function does nothing to affect the way Directory Server processes the bind.

To Register the Plug-In

If you have not already done so, build the example plug-in library and activate both plug-in informational logging and the example plug-in.

Build the plug-in.

Hint Use install-path/examples/Makefile or install-path/examples/Makefile64.

Configure Directory Server to log plug-in informational messages and load the plug-in.

Hint Use the commands specified in the comments at the outset of the plug-in source file.

Restart Directory Server.
$ dsadm restart instance-path

To Generate a Bind Log Message

Bind as Kirsten Vaughan (for example).

$ ldapsearch -h localhost -p 1389 -b "dc=example,dc=com" \
 -D "uid=kvaughan,ou=people,dc=example,dc=com" -w bribery "(uid=*)"

Search instance-path/logs/errors for the resulting message from the testpreop_bind() function.

If you ignore housekeeping information for the entry, output similar to this appears:
Target DN: uid=kvaughan,ou=people,dc=example,dc=com Authentication method: Simple authentication
For a discussion of less trivial pre-bind plug-in functions, refer to Chapter 7, Handling Authentication Using Plug-Ins.

Bypassing Bind Processing in Directory Server

When the plug-in returns 0, Directory Server continues to process the bind. To bypass Directory Server bind processing, set SLAPI_CONN_DN in the parameter block, and return a positive value, such as 1.

Normal Directory Server Bind Behavior

Directory Server follows the LDAP bind model. At minimum, the server authenticates the client. The server also sends a bind response to indicate the status of authentication. Refer to RFC 1777, Lightweight Directory Access Protocol, and RFC 45111, Lightweight Directory Access Protocol (v3), for details.