SASL Authentication

The LDAP v3 protocol uses the SASL to support pluggable authentication. That is, the LDAP client and server can be configured to negotiate and use possibly nonstandard and/or customized mechanisms for authentication depending on the level of protection desired by the client and the server. The LDAP v2 protocol does not support the SASL.
There are several SASL mechanisms currently defined:

Anonymous (RFC 2245)
CRAM-MD5 (RFC 2195)
Digest-MD5 (draft-leach-digest-sasl-05.txt)
External (RFC 2222)
GSSAPI mechanisms (draft-ietf-cat-sasl-gssapi-00.txt)
Kerberos V4 (RFC 2222)
Kerberos V5 (draft-ietf-cat-sasl-gssapi-00.txt)
SecurID (draft-nystrom-securid-sasl-01.txt
Secure Remote Password (draft-burdis-cat-srp-sasl-01.txt)
S/Key (RFC 2222)
X.509 (draft-ietf-ldapext-x509-sasl-02.txt)

SASL Mechanisms Supported by LDAP Servers
Of the mechanisms on this list, popular LDAP servers (such as those from Netscape and Innosoft) currently support CRAM-MD5 and External. draft-ietf-ldapext-authmeth-04.txt proposes the use of DIGEST-MD5 as the mandatory default mechanisms for LDAP v3 servers.
Here is a simple program for finding out the list of SASL mechanisms that an LDAP server supports:
// Create initial context
DirContext ctx = new InitialDirContext();

// Read supportedSASLMechanisms from root DSE
Attributes attrs = ctx.getAttributes(
    "ldap://localhost:389", new String[]{"supportedSASLMechanisms"});
Here is the output produced by running this program against a server that supports the External SASL mechanism:
{supportedsaslmechanisms=supportedSASLMechanisms: EXTERNAL}
Specifying the Authentication Mechanism

To use a particular SASL mechanism, you specify its IANA-registered mechanism name in the Context.SECURITY_AUTHENTICATION("java.naming.security.authentication") environment property. You can also specify a list of mechanisms, by specifying an ordered list of space-separated mechanism names, for the LDAP provider to try. The LDAP provider will use the first mechanism for which it finds an implementation.
Here's an example that asks the LDAP provider to try to get the implementation for DIGEST-MD5 mechanism, and if that's not available, use the one for CRAM-MD5.
env.put(Context.SECURITY_AUTHENTICATION, "DIGEST-MD5 CRAM-MD5");
You might get this list of authentication mechanisms from the user of your application. Or you might get this list of mechanisms by asking the LDAP server, by using a call similar that shown above. The LDAP provider itself does not consult the server for this information. It simply attempts to locate and use the implementation of the specified mechanisms.
Sun's LDAP provider has builtin support for the following SASL mechanisms: CRAM-MD5, External. You can add support for additional mechanisms. See the Using Arbitrary SASL Mechanisms section.
Specifying the Bind Distinguished Name
SASL authentication consists of the client and the server exchanging SASL messages embedded inside LDAP "bind" requests and responses. The "bind" request contains a name field, which is the distinguished name of the directory object that the client wishes to bind as. The field's value may be null (that is, not specified), depending on the SASL mechanism (which may embed the DN within the credentials that it exchanges with the server).
The value of the Context.SECURITY_AUTHENTICATION("java.naming.security.authentication") environment property is used as the bind DN.
Specifying Input for the Authentication Mechanism
Some mechanisms, such as External, require no additional input--only the mechanism name is sufficient for the authentication to proceed. The External example shows how to use the External SASL mechanism.
Most other mechanisms require some additional input. Depending on the mechanism, the type of input might vary. Some common input required by mechanisms are:

The authentication id. This is the identity of the entity performing the authentication.
The authorization id. This is the identity of the entity for which access control checks should be made if the authentication succeeds.
The authentication credentials such as a password or a key.
The authentication and authorization ids might be different if the program (such as a proxy server) is authenticating on behalf of another entity.
The authentication id is specified by using the Context.SECURITY_PRINCIPAL("java.naming.security.principal") environment property. It is of type java.lang.String.
The password/key of the authentication entity is specified by using the Context.SECURITY_CREDENTIALS("java.naming.security.credentials") environment property. It is of type java.lang.String, char array (char[]), or byte array (byte[]). If the password is a byte array, it is transformed into a char array assuming an UTF-8 encoding.
By default, in addition to being the authentication id, the value of the Context.SECURITY_PRINCIPAL environment property is also used as the authorization id. If you need to specify an authorization id distinct from the authentication id, use the java.naming.security.sasl.authorizationId environment property. Its value must be of type java.lang.String.
The CRAM-MD5 example shows how to use the Context.SECURITY_PRINCIPAL and Context.SECURITY_CREDENTIALS properties for CRAM-MD5 authentication.
If a mechanism requires input other than those already described, you need to define a callback object for the mechanism to use. See the Callback section for an example of how to do this.

Security