org.springframework.ldap.core.support

## Class AbstractTlsDirContextAuthenticationStrategy

- java.lang.Object
- - org.springframework.ldap.core.support.AbstractTlsDirContextAuthenticationStrategy

- All Implemented Interfaces:
    DirContextAuthenticationStrategy
  Direct Known Subclasses:
    DefaultTlsDirContextAuthenticationStrategy, ExternalTlsDirContextAuthenticationStrategy

      public abstract class AbstractTlsDirContextAuthenticationStrategy
      extends Object
      implements DirContextAuthenticationStrategy

  Abstract superclass for `DirContextAuthenticationStrategy` implementations that apply TLS security to the connections. The supported TLS behavior differs between servers. E.g., some servers expect the TLS connection be shut down gracefully before the actual target context is closed, whereas other servers do not support that. The `shutdownTlsGracefully` property controls this behavior; the property defaults to `false`.

  The `SSLSocketFactory` used for TLS negotiation can be customized using the `sslSocketFactory` property. This allows for example a socket factory that can load the keystore/truststore using the Spring Resource abstraction. This provides a much more Spring-like strategy for configuring PKI credentials for authentication, in addition to allowing application-specific keystores and truststores running in the same JVM.

  In some rare occasions there is a need to supply a `HostnameVerifier` to the TLS processing instructions in order to have the returned certificate properly validated. If a `HostnameVerifier` is supplied to `setHostnameVerifier(HostnameVerifier)`, that will be applied to the processing.

  For further information regarding TLS, refer to this page.

  NB: TLS negotiation is an expensive process, which is why you will most likely want to use connection pooling, to make sure new connections are not created for each individual request. It is imperative however, that the built-in LDAP connection pooling is not used in combination with the TLS AuthenticationStrategy implementations - this will not work. You should use the Spring LDAP PoolingContextSource instead.

  Author:
    Mattias Hellborg Arthursson

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractTlsDirContextAuthenticationStrategy()`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected abstract void` | `applyAuthentication(LdapContext ctx, String userDn, String password)` Apply the actual authentication to the specified `LdapContext` .
    `DirContext` | `processContextAfterCreation(DirContext ctx, String userDn, String password)` This method is responsible for post-processing the `DirContext` instance after it has been created.
    `void` | `setHostnameVerifier(HostnameVerifier hostnameVerifier)` Set the optional `HostnameVerifier` to use for verifying incoming certificates.
    `void` | `setShutdownTlsGracefully(boolean shutdownTlsGracefully)` Specify whether the TLS should be shut down gracefully before the target context is closed.
    `void` | `setSslSocketFactory(SSLSocketFactory sslSocketFactory)` Sets the optional SSL socket factory used for startTLS negotiation.
    `void` | `setupEnvironment(Hashtable<String,Object> env, String userDn, String password)` This method is responsible for preparing the environment to be used when creating the `DirContext` instance.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### AbstractTlsDirContextAuthenticationStrategy

          public AbstractTlsDirContextAuthenticationStrategy()

  - ### Method Detail

    - #### setShutdownTlsGracefully

          public void setShutdownTlsGracefully(boolean shutdownTlsGracefully)

      Specify whether the TLS should be shut down gracefully before the target context is closed. Defaults to `false`.
      Parameters:
        `shutdownTlsGracefully` - `true` to shut down the TLS connection explicitly, `false` closes the target context immediately.

    - #### setHostnameVerifier

          public void setHostnameVerifier(HostnameVerifier hostnameVerifier)

      Set the optional `HostnameVerifier` to use for verifying incoming certificates. Defaults to `null` , meaning that the default hostname verification will take place.
      Parameters:
        `hostnameVerifier` - The `HostnameVerifier` to use, if any.

    - #### setSslSocketFactory

          public void setSslSocketFactory(SSLSocketFactory sslSocketFactory)

      Sets the optional SSL socket factory used for startTLS negotiation. Defaults to `null` to indicate that the default socket factory provided by the underlying JSSE provider should be used.
      Parameters:
        `sslSocketFactory` - SSL socket factory to use, if any.

    - #### setupEnvironment

          public final void setupEnvironment(Hashtable<String,Object> env,
                                             String userDn,
                                             String password)

      Description copied from interface: `DirContextAuthenticationStrategy`
      This method is responsible for preparing the environment to be used when creating the `DirContext` instance. The base environment (including URL, `ContextFactory` etc. will already be set, and this method is called just before the actual Context is to be created.
      Specified by:
        `setupEnvironment` in interface `DirContextAuthenticationStrategy`
      Parameters:
        `env` - The `Hashtable` to be sent to the `DirContext` instance on initialization. Pre-configured with the basic settings; the implementation of this method is responsible for manipulating the environment as appropriate for the particular authentication mechanism.
        `userDn` - the user DN to authenticate, as received from the `AuthenticationSource` of the `ContextSource`.
        `password` - the password to authenticate with, as received from the `AuthenticationSource` of the `ContextSource`.

    - #### processContextAfterCreation

          public final DirContext processContextAfterCreation(DirContext ctx,
                                                              String userDn,
                                                              String password)
                                                       throws NamingException

      Description copied from interface: `DirContextAuthenticationStrategy`
      This method is responsible for post-processing the `DirContext` instance after it has been created. It will be called immediately after the instance has been created. Some authentication mechanisms, e.g. TLS, require particular stuff to happen before the actual target Context is closed. This method provides the possibility to replace or wrap the actual DirContext with a proxy so that any calls on it may be intercepted.
      Specified by:
        `processContextAfterCreation` in interface `DirContextAuthenticationStrategy`
      Parameters:
        `ctx` - the freshly created `DirContext` instance. The actual implementation class (e.g. `InitialLdapContext`) depends on the `ContextSource` implementation.
        `userDn` - the user DN to authenticate, as received from the `AuthenticationSource` of the `ContextSource`.
        `password` - the password to authenticate with, as received from the `AuthenticationSource` of the `ContextSource`.
      Returns:
        the DirContext, possibly modified, replaced or wrapped.
      Throws:
        `NamingException` - if anything goes wrong. This will cause the `DirContext` creation to be aborted and the exception to be translated and rethrown.

    - #### applyAuthentication

          protected abstract void applyAuthentication(LdapContext ctx,
                                                      String userDn,
                                                      String password)
                                               throws NamingException

      Apply the actual authentication to the specified `LdapContext` . Typically, this will involve adding stuff to the environment.
      Parameters:
        `ctx` - the `LdapContext` instance.
        `userDn` - the user dn of the user to authenticate.
        `password` - the password of the user to authenticate.
      Throws:
        `NamingException` - if any error occurs.