org.opends.server.tools
Class LDAPAuthenticationHandler

java.lang.Object
  org.opends.server.tools.LDAPAuthenticationHandler

All Implemented Interfaces:

java.security.PrivilegedExceptionAction<java.lang.Object>, javax.security.auth.callback.CallbackHandler

public class LDAPAuthenticationHandler
extends java.lang.Object
implements java.security.PrivilegedExceptionAction<java.lang.Object>, javax.security.auth.callback.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 threadsafe, so if the same AuthenticationHandler object is to be used concurrently by multiple threads, it must be externally synchronized.

Constructor Summary

LDAPAuthenticationHandler(LDAPReader reader, LDAPWriter writer, java.lang.String hostName, java.util.concurrent.atomic.AtomicInteger nextMessageID)
Creates a new instance of this authentication handler.

Method Summary

java.lang.String	doSASLAnonymous(ASN1OctetString bindDN, java.util.Map<java.lang.String,java.util.List<java.lang.String>> saslProperties, java.util.ArrayList<LDAPControl> requestControls, java.util.ArrayList<LDAPControl> responseControls) Processes a SASL ANONYMOUS bind with the provided information.
java.lang.String	doSASLBind(ASN1OctetString bindDN, ASN1OctetString bindPassword, java.lang.String mechanism, java.util.Map<java.lang.String,java.util.List<java.lang.String>> saslProperties, java.util.ArrayList<LDAPControl> requestControls, java.util.ArrayList<LDAPControl> responseControls) Processes a SASL bind using the provided information.
java.lang.String	doSASLCRAMMD5(ASN1OctetString bindDN, ASN1OctetString bindPassword, java.util.Map<java.lang.String,java.util.List<java.lang.String>> saslProperties, java.util.ArrayList<LDAPControl> requestControls, java.util.ArrayList<LDAPControl> responseControls) Processes a SASL CRAM-MD5 bind with the provided information.
java.lang.String	doSASLDigestMD5(ASN1OctetString bindDN, ASN1OctetString bindPassword, java.util.Map<java.lang.String,java.util.List<java.lang.String>> saslProperties, java.util.ArrayList<LDAPControl> requestControls, java.util.ArrayList<LDAPControl> responseControls) Processes a SASL DIGEST-MD5 bind with the provided information.
java.lang.String	doSASLExternal(ASN1OctetString bindDN, java.util.Map<java.lang.String,java.util.List<java.lang.String>> saslProperties, java.util.ArrayList<LDAPControl> requestControls, java.util.ArrayList<LDAPControl> responseControls) Processes a SASL EXTERNAL bind with the provided information.
java.lang.String	doSASLGSSAPI(ASN1OctetString bindDN, ASN1OctetString bindPassword, java.util.Map<java.lang.String,java.util.List<java.lang.String>> saslProperties, java.util.ArrayList<LDAPControl> requestControls, java.util.ArrayList<LDAPControl> responseControls) Processes a SASL GSSAPI bind with the provided information.
java.lang.String	doSASLPlain(ASN1OctetString bindDN, ASN1OctetString bindPassword, java.util.Map<java.lang.String,java.util.List<java.lang.String>> saslProperties, java.util.ArrayList<LDAPControl> requestControls, java.util.ArrayList<LDAPControl> responseControls) Processes a SASL PLAIN bind with the provided information.
java.lang.String	doSimpleBind(int ldapVersion, ASN1OctetString bindDN, ASN1OctetString bindPassword, java.util.ArrayList<LDAPControl> requestControls, java.util.ArrayList<LDAPControl> responseControls) Processes a bind using simple authentication with the provided information.
byte[]	generateDigestMD5RspAuth(java.lang.String authID, java.lang.String authzID, byte[] password, java.lang.String realm, java.lang.String nonce, java.lang.String cnonce, java.lang.String nonceCount, java.lang.String digestURI, java.lang.String qop, java.lang.String charset) Generates the appropriate DIGEST-MD5 rspauth digest using the provided information.
static java.util.LinkedHashMap<java.lang.String,Message>	getSASLAnonymousProperties() Retrieves the set of properties that a client may provide when performing a SASL ANONYMOUS bind, mapped from the property names to their corresponding descriptions.
static java.util.LinkedHashMap<java.lang.String,Message>	getSASLCRAMMD5Properties() Retrieves the set of properties that a client may provide when performing a SASL CRAM-MD5 bind, mapped from the property names to their corresponding descriptions.
static java.util.LinkedHashMap<java.lang.String,Message>	getSASLDigestMD5Properties() Retrieves the set of properties that a client may provide when performing a SASL DIGEST-MD5 bind, mapped from the property names to their corresponding descriptions.
static java.util.LinkedHashMap<java.lang.String,Message>	getSASLExternalProperties() Retrieves the set of properties that a client may provide when performing a SASL EXTERNAL bind, mapped from the property names to their corresponding descriptions.
static java.util.LinkedHashMap<java.lang.String,Message>	getSASLGSSAPIProperties() Retrieves the set of properties that a client may provide when performing a SASL EXTERNAL bind, mapped from the property names to their corresponding descriptions.
static java.util.LinkedHashMap<java.lang.String,Message>	getSASLPlainProperties() Retrieves the set of properties that a client may provide when performing a SASL PLAIN bind, mapped from the property names to their corresponding descriptions.
static java.util.LinkedHashMap<java.lang.String,Message>	getSASLProperties(java.lang.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 java.lang.String[]	getSupportedSASLMechanisms() Retrieves a list of the SASL mechanisms that are supported by this client library.
void	handle(javax.security.auth.callback.Callback[] callbacks) Handles the authentication callbacks to provide information needed by the JAAS login process.
ASN1OctetString	requestAuthorizationIdentity() Uses the "Who Am I?" extended operation to request that the server provide the client with the authorization identity for this connection.
java.lang.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,
                                 java.lang.String hostName,
                                 java.util.concurrent.atomic.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 java.lang.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 java.util.LinkedHashMap<java.lang.String,Message> getSASLProperties(java.lang.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 java.lang.String doSimpleBind(int ldapVersion,
                                     ASN1OctetString bindDN,
                                     ASN1OctetString bindPassword,
                                     java.util.ArrayList<LDAPControl> requestControls,
                                     java.util.ArrayList<LDAPControl> 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 java.lang.String doSASLBind(ASN1OctetString bindDN,
                                   ASN1OctetString bindPassword,
                                   java.lang.String mechanism,
                                   java.util.Map<java.lang.String,java.util.List<java.lang.String>> saslProperties,
                                   java.util.ArrayList<LDAPControl> requestControls,
                                   java.util.ArrayList<LDAPControl> 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.

doSASLAnonymous

public java.lang.String doSASLAnonymous(ASN1OctetString bindDN,
                                        java.util.Map<java.lang.String,java.util.List<java.lang.String>> saslProperties,
                                        java.util.ArrayList<LDAPControl> requestControls,
                                        java.util.ArrayList<LDAPControl> responseControls)
                                 throws ClientException,
                                        LDAPException

Processes a SASL ANONYMOUS 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.

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.

getSASLAnonymousProperties

public static java.util.LinkedHashMap<java.lang.String,Message> getSASLAnonymousProperties()

Retrieves the set of properties that a client may provide when performing a SASL ANONYMOUS bind, mapped from the property names to their corresponding descriptions.

Returns:

The set of properties that a client may provide when performing a SASL ANONYMOUS bind, mapped from the property names to their corresponding descriptions.

doSASLCRAMMD5

public java.lang.String doSASLCRAMMD5(ASN1OctetString bindDN,
                                      ASN1OctetString bindPassword,
                                      java.util.Map<java.lang.String,java.util.List<java.lang.String>> saslProperties,
                                      java.util.ArrayList<LDAPControl> requestControls,
                                      java.util.ArrayList<LDAPControl> responseControls)
                               throws ClientException,
                                      LDAPException

Processes a SASL CRAM-MD5 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.

getSASLCRAMMD5Properties

public static java.util.LinkedHashMap<java.lang.String,Message> getSASLCRAMMD5Properties()

Retrieves the set of properties that a client may provide when performing a SASL CRAM-MD5 bind, mapped from the property names to their corresponding descriptions.

Returns:

The set of properties that a client may provide when performing a SASL CRAM-MD5 bind, mapped from the property names to their corresponding descriptions.

doSASLDigestMD5

public java.lang.String doSASLDigestMD5(ASN1OctetString bindDN,
                                        ASN1OctetString bindPassword,
                                        java.util.Map<java.lang.String,java.util.List<java.lang.String>> saslProperties,
                                        java.util.ArrayList<LDAPControl> requestControls,
                                        java.util.ArrayList<LDAPControl> responseControls)
                                 throws ClientException,
                                        LDAPException

Processes a SASL DIGEST-MD5 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.

generateDigestMD5RspAuth

public byte[] generateDigestMD5RspAuth(java.lang.String authID,
                                       java.lang.String authzID,
                                       byte[] password,
                                       java.lang.String realm,
                                       java.lang.String nonce,
                                       java.lang.String cnonce,
                                       java.lang.String nonceCount,
                                       java.lang.String digestURI,
                                       java.lang.String qop,
                                       java.lang.String charset)
                                throws java.io.UnsupportedEncodingException

Generates the appropriate DIGEST-MD5 rspauth digest using the provided information.

Parameters:

authID - The username from the authentication request.

authzID - The authorization ID from the request, or null if there is none.

password - The clear-text password for the user.

realm - The realm for which the authentication is to be performed.

nonce - The random data generated by the server for use in the digest.

cnonce - The random data generated by the client for use in the digest.

nonceCount - The 8-digit hex string indicating the number of times the provided nonce has been used by the client.

digestURI - The digest URI that specifies the service and host for which the authentication is being performed.

qop - The quality of protection string for the authentication.

charset - The character set used to encode the information.

Returns:

The DIGEST-MD5 response for the provided set of information.

Throws:

java.io.UnsupportedEncodingException - If the specified character set is invalid for some reason.

getSASLDigestMD5Properties

public static java.util.LinkedHashMap<java.lang.String,Message> getSASLDigestMD5Properties()

Retrieves the set of properties that a client may provide when performing a SASL DIGEST-MD5 bind, mapped from the property names to their corresponding descriptions.

Returns:

The set of properties that a client may provide when performing a SASL DIGEST-MD5 bind, mapped from the property names to their corresponding descriptions.

doSASLExternal

public java.lang.String doSASLExternal(ASN1OctetString bindDN,
                                       java.util.Map<java.lang.String,java.util.List<java.lang.String>> saslProperties,
                                       java.util.ArrayList<LDAPControl> requestControls,
                                       java.util.ArrayList<LDAPControl> 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.

getSASLExternalProperties

public static java.util.LinkedHashMap<java.lang.String,Message> getSASLExternalProperties()

Retrieves the set of properties that a client may provide when performing a SASL EXTERNAL bind, mapped from the property names to their corresponding descriptions.

Returns:

The set of properties that a client may provide when performing a SASL EXTERNAL bind, mapped from the property names to their corresponding descriptions.

doSASLGSSAPI

public java.lang.String doSASLGSSAPI(ASN1OctetString bindDN,
                                     ASN1OctetString bindPassword,
                                     java.util.Map<java.lang.String,java.util.List<java.lang.String>> saslProperties,
                                     java.util.ArrayList<LDAPControl> requestControls,
                                     java.util.ArrayList<LDAPControl> responseControls)
                              throws ClientException,
                                     LDAPException

Processes a SASL GSSAPI 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. 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.

getSASLGSSAPIProperties

public static java.util.LinkedHashMap<java.lang.String,Message> getSASLGSSAPIProperties()

Retrieves the set of properties that a client may provide when performing a SASL EXTERNAL bind, mapped from the property names to their corresponding descriptions.

Returns:

The set of properties that a client may provide when performing a SASL EXTERNAL bind, mapped from the property names to their corresponding descriptions.

doSASLPlain

public java.lang.String doSASLPlain(ASN1OctetString bindDN,
                                    ASN1OctetString bindPassword,
                                    java.util.Map<java.lang.String,java.util.List<java.lang.String>> saslProperties,
                                    java.util.ArrayList<LDAPControl> requestControls,
                                    java.util.ArrayList<LDAPControl> 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.

getSASLPlainProperties

public static java.util.LinkedHashMap<java.lang.String,Message> getSASLPlainProperties()

Retrieves the set of properties that a client may provide when performing a SASL PLAIN bind, mapped from the property names to their corresponding descriptions.

Returns:

The set of properties that a client may provide when performing a SASL PLAIN bind, mapped from the property names to their corresponding descriptions.

run

public java.lang.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 java.security.PrivilegedExceptionAction<java.lang.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(javax.security.auth.callback.Callback[] callbacks)
            throws javax.security.auth.callback.UnsupportedCallbackException

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

Specified by:

handle in interface javax.security.auth.callback.CallbackHandler

Parameters:

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

Throws:

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

requestAuthorizationIdentity

public ASN1OctetString 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.