Package org.opends.server.tools

Class LDAPAuthenticationHandler

java.lang.Object

org.opends.server.tools.LDAPAuthenticationHandler

All Implemented Interfaces:

PrivilegedExceptionAction<Object>, CallbackHandler

public class LDAPAuthenticationHandler
extends Object
implements PrivilegedExceptionAction<Object>, CallbackHandler

This class provides a generic interface that LDAP clients can use to perform various kinds of authentication to the Directory Server. This handles both simple authentication as well as several SASL mechanisms including:

• ANONYMOUS
• CRAM-MD5
• DIGEST-MD5
• EXTERNAL
• GSSAPI
• PLAIN

Note that this implementation is not thread safe, so if the same AuthenticationHandler object is to be used concurrently by multiple threads, it must be externally synchronized.

Constructor Summary

Constructors

Constructor	Description
LDAPAuthenticationHandler(LDAPReader reader, LDAPWriter writer, String hostName, AtomicInteger nextMessageID)	Creates a new instance of this authentication handler.

Method Summary

Modifier and Type	Method	Description
String	doSASLBind(ByteSequence bindDN, ByteSequence bindPassword, String mechanism, Map<String,List<String>> saslProperties, List<Control> requestControls, List<Control> responseControls)	Processes a SASL bind using the provided information.
String	doSASLExternal(ByteSequence bindDN, Map<String,List<String>> saslProperties, List<Control> requestControls, List<Control> responseControls)	Processes a SASL EXTERNAL bind with the provided information.
String	doSASLPlain(ByteSequence bindDN, ByteSequence bindPassword, Map<String,List<String>> saslProperties, List<Control> requestControls, List<Control> responseControls)	Processes a SASL PLAIN bind with the provided information.
String	doSimpleBind(int ldapVersion, ByteSequence bindDN, ByteSequence bindPassword, List<Control> requestControls, List<Control> responseControls)	Processes a bind using simple authentication with the provided information.
static Map<String,org.forgerock.i18n.LocalizableMessage>	getSASLProperties(String mechanism)	Retrieves a list of the SASL properties that may be provided for the specified SASL mechanism, mapped from the property names to their corresponding descriptions.
static String[]	getSupportedSASLMechanisms()	Retrieves a list of the SASL mechanisms that are supported by this client library.
void	handle(Callback[] callbacks)	Handles the authentication callbacks to provide information needed by the JAAS login process.
ByteString	requestAuthorizationIdentity()	Uses the "Who Am I?"
Object	run()	Performs a privileged operation under JAAS so that the local authentication information can be available for the SASL bind to the Directory Server.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LDAPAuthenticationHandler

public LDAPAuthenticationHandler(LDAPReader reader,
                                 LDAPWriter writer,
                                 String hostName,
                                 AtomicInteger nextMessageID)

Creates a new instance of this authentication handler. All initialization will be done lazily to avoid unnecessary performance hits, particularly for cases in which simple authentication will be used as it does not require any particularly expensive processing.

Parameters:

reader - The LDAP reader that will be used to read data from the server.

writer - The LDAP writer that will be used to send data to the server.

hostName - The host name used to connect to the remote system (fully-qualified if possible).

nextMessageID - The atomic integer that will be used to obtain message IDs for request messages.

Method Detail

getSupportedSASLMechanisms

public static String[] getSupportedSASLMechanisms()

Retrieves a list of the SASL mechanisms that are supported by this client library.

Returns:

A list of the SASL mechanisms that are supported by this client library.

getSASLProperties

public static Map<String,org.forgerock.i18n.LocalizableMessage> getSASLProperties(String mechanism)

Retrieves a list of the SASL properties that may be provided for the specified SASL mechanism, mapped from the property names to their corresponding descriptions.

Parameters:

mechanism - The name of the SASL mechanism for which to obtain the list of supported properties.

Returns:

A list of the SASL properties that may be provided for the specified SASL mechanism, mapped from the property names to their corresponding descriptions.

doSimpleBind

public String doSimpleBind(int ldapVersion,
                           ByteSequence bindDN,
                           ByteSequence bindPassword,
                           List<Control> requestControls,
                           List<Control> responseControls)
                    throws ClientException,
                           LDAPException

Processes a bind using simple authentication with the provided information. If the bind fails, then an exception will be thrown with information about the reason for the failure. If the bind is successful but there may be some special information that the client should be given, then it will be returned as a String.

Parameters:

ldapVersion - The LDAP protocol version to use for the bind request.

bindDN - The DN to use to bind to the Directory Server, or null if it is to be an anonymous bind.

bindPassword - The password to use to bind to the Directory Server, or null if it is to be an anonymous bind.

requestControls - The set of controls to include the request to the server.

responseControls - A list to hold the set of controls included in the response from the server.

Returns:

A message providing additional information about the bind if appropriate, or null if there is no special information available.

Throws:

ClientException - If a client-side problem prevents the bind attempt from succeeding.

LDAPException - If the bind fails or some other server-side problem occurs during processing.

doSASLBind

public String doSASLBind(ByteSequence bindDN,
                         ByteSequence bindPassword,
                         String mechanism,
                         Map<String,List<String>> saslProperties,
                         List<Control> requestControls,
                         List<Control> responseControls)
                  throws ClientException,
                         LDAPException

Processes a SASL bind using the provided information. If the bind fails, then an exception will be thrown with information about the reason for the failure. If the bind is successful but there may be some special information that the client should be given, then it will be returned as a String.

Parameters:

bindDN - The DN to use to bind to the Directory Server, or null if the authentication identity is to be set through some other means.

bindPassword - The password to use to bind to the Directory Server, or null if this is not a password-based SASL mechanism.

mechanism - The name of the SASL mechanism to use to authenticate to the Directory Server.

saslProperties - A set of additional properties that may be needed to process the SASL bind.

requestControls - The set of controls to include the request to the server.

responseControls - A list to hold the set of controls included in the response from the server.

Returns:

A message providing additional information about the bind if appropriate, or null if there is no special information available.

Throws:

ClientException - If a client-side problem prevents the bind attempt from succeeding.

LDAPException - If the bind fails or some other server-side problem occurs during processing.

doSASLExternal

public String doSASLExternal(ByteSequence bindDN,
                             Map<String,List<String>> saslProperties,
                             List<Control> requestControls,
                             List<Control> responseControls)
                      throws ClientException,
                             LDAPException

Processes a SASL EXTERNAL bind with the provided information.

Parameters:

bindDN - The DN to use to bind to the Directory Server, or null if the authentication identity is to be set through some other means.

saslProperties - A set of additional properties that may be needed to process the SASL bind. SASL EXTERNAL does not take any properties, so this should be empty or null.

requestControls - The set of controls to include the request to the server.

responseControls - A list to hold the set of controls included in the response from the server.

Returns:

A message providing additional information about the bind if appropriate, or null if there is no special information available.

Throws:

ClientException - If a client-side problem prevents the bind attempt from succeeding.

LDAPException - If the bind fails or some other server-side problem occurs during processing.

doSASLPlain

public String doSASLPlain(ByteSequence bindDN,
                          ByteSequence bindPassword,
                          Map<String,List<String>> saslProperties,
                          List<Control> requestControls,
                          List<Control> responseControls)
                   throws ClientException,
                          LDAPException

Processes a SASL PLAIN bind with the provided information.

Parameters:

bindDN - The DN to use to bind to the Directory Server, or null if the authentication identity is to be set through some other means.

bindPassword - The password to use to bind to the Directory Server.

saslProperties - A set of additional properties that may be needed to process the SASL bind.

requestControls - The set of controls to include the request to the server.

responseControls - A list to hold the set of controls included in the response from the server.

Returns:

A message providing additional information about the bind if appropriate, or null if there is no special information available.

Throws:

ClientException - If a client-side problem prevents the bind attempt from succeeding.

LDAPException - If the bind fails or some other server-side problem occurs during processing.

run

public Object run()
           throws ClientException,
                  LDAPException

Performs a privileged operation under JAAS so that the local authentication information can be available for the SASL bind to the Directory Server.

Specified by:

run in interface PrivilegedExceptionAction<Object>

Returns:

A placeholder object in order to comply with the PrivilegedExceptionAction interface.

Throws:

ClientException - If a client-side problem occurs during the bind processing.

LDAPException - If a server-side problem occurs during the bind processing.

handle

public void handle(Callback[] callbacks)
            throws UnsupportedCallbackException

Handles the authentication callbacks to provide information needed by the JAAS login process.

Specified by:

handle in interface CallbackHandler

Parameters:

callbacks - The callbacks needed to provide information for the JAAS login process.

Throws:

UnsupportedCallbackException - If an unexpected callback is included in the provided set.

requestAuthorizationIdentity

public ByteString requestAuthorizationIdentity()
                                        throws ClientException,
                                               LDAPException

Uses the "Who Am I?" extended operation to request that the server provide the client with the authorization identity for this connection.

Returns:

An ASN.1 octet string containing the authorization identity, or null if the client is not authenticated or is authenticated anonymously.

Throws:

ClientException - If a client-side problem occurs during the request processing.

LDAPException - If a server-side problem occurs during the request processing.