LDAP Connection Adapter

Introduction

The Spotfire Streaming Adapter for LDAP Connection allows a StreamBase application to connect to an LDAP server.

Adapter Properties

This section describes the properties you can set for this adapter, using the various tabs of the Properties view in StreamBase Studio.

General Tab

Name: Use this required field to specify or change the name of this instance of this component. The name must be unique within the current EventFlow module. The name can contain alphanumeric characters, underscores, and escaped special characters. Special characters can be escaped as described in Identifier Naming Rules. The first character must be alphabetic or an underscore.

Adapter: A read-only field that shows the formal name of the adapter.

Class name: Shows the fully qualified class name that implements the functionality of this adapter. If you need to reference this class name elsewhere in your application, you can right-click this field and select Copy from the context menu to place the full class name in the system clipboard.

Start options: This field provides a link to the Cluster Aware tab, where you configure the conditions under which this adapter starts.

Enable Error Output Port: Select this checkbox to add an Error Port to this component. In the EventFlow canvas, the Error Port shows as a red output port, always the last port for the component. See Using Error Ports to learn about Error Ports.

Description: Optionally, enter text to briefly describe the purpose and function of the component. In the EventFlow Editor canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.

Adapter Properties Tab

Property Description
Connect At Startup If enabled the adapter will attempt to connect to the LDAP server at system startup
Connection Type The type of connection to create
Security Type The type of security to use for the connection
Secure Communication Config The security communication config to use from HOCON when connecting via SSL or TLS, this value is ignored if Ignore Invalid Certificates is enabled
Ignore Invalid Certificates If enabled any SSL or TLS invalid certificate will be treated as valid. This option should only be used in a testing environment and should never be enabled in production
Hosts And Ports The hosts and ports of the LDAP servers to connect to
Log Level Controls the level of verbosity the adapter uses to send notifications to the console. This setting can be higher than the containing application's log level. If set lower, the system log level is used. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO, DEBUG, TRACE.

Auth Properties Tab

Property Description
Auth Type The auth type to use
Bind DN The bind DN to use when authenticating
Password The password to use when connecting
Auth ID Specifies the authentication ID. It may be used in conjunction with the CRAM-MD5, DIGEST-MD5, GSSAPI, and PLAIN mechanisms.
Authz ID Specifies the authorization ID. It may be used in conjunction with the DIGEST-MD5, GSSAPI, and PLAIN mechanisms.
Config File Specifies the path to the JAAS config file. It may be used in conjunction with the GSSAPI mechanism.
Debug Indicates whether debugging should be enabled. It may be used in conjunction with the GSSAPI mechanism.
KDC Address Specifies the KDC address. It may be used in conjunction with the GSSAPI mechanism.
Protocol Specifies the GSSAPI service principal protocol. It may be used in conjunction with the GSSAPI mechanism.
Quality Of Protection Specifies the quality of protection that should be used for communication that occurs after the authentication has completed.
Realm Specifies the realm name. It may be used in conjunction with the DIGEST-MD5 and GSSAPI mechanisms.
Require Cache Indicates whether to require an existing Kerberos session from the ticket cache. It may be used in conjunction with the GSSAPI mechanism.
Renew TGT Indicates whether to attempt to renew the Kerberos TGT for an existing session. It may be used in conjunction with the GSSAPI mechanism.
Ticket Cache Specifies the path to the Kerberos ticket cache to use. It may be used in conjunction with the GSSAPI mechanism.
Trace Specifies the trace string. It may be used in conjunction with the ANONYMOUS mechanism.
Use Ticket Cache Specifies whether to use a Kerberos ticket cache. It may be used in conjunction with the GSSAPI mechanism.

Advanced Properties Tab

Property Description
Initial Connections The number of initial connections to create when connecting
Max Connections The maximum number of connections to create
Initial Connect Threads The number of threads to use when creating the initial connections
Connect Timeout MS Specifies the maximum length of time in milliseconds that a connection attempt should be allowed to continue before giving up. A value of zero indicates that there should be no connect timeout.
Response Timeout MS Specifies the maximum length of time in milliseconds that an operation should be allowed to block while waiting for a response from the server. A value of zero indicates that there should be no timeout. Note that this will be set before any per operation timeout.
Search Timeout MS Specifies the maximum length of time in milliseconds that the search operation should be allowed to block while waiting for a response from the server. A value of zero indicates that there should be no timeout.
Add Timeout MS Specifies the maximum length of time in milliseconds that the add operation should be allowed to block while waiting for a response from the server. A value of zero indicates that there should be no timeout.
Compare Timeout MS Specifies the maximum length of time in milliseconds that the compare operation should be allowed to block while waiting for a response from the server. A value of zero indicates that there should be no timeout.
Delete Timeout MS Specifies the maximum length of time in milliseconds that the delete operation should be allowed to block while waiting for a response from the server. A value of zero indicates that there should be no timeout.
Modify Timeout MS Specifies the maximum length of time in milliseconds that the modify operation should be allowed to block while waiting for a response from the server. A value of zero indicates that there should be no timeout.
Modify DN Timeout MS Specifies the maximum length of time in milliseconds that the modify DN operation should be allowed to block while waiting for a response from the server. A value of zero indicates that there should be no timeout.
Bind Timeout MS Specifies the maximum length of time in milliseconds that the bind operation should be allowed to block while waiting for a response from the server. A value of zero indicates that there should be no timeout.

Cluster Aware Tab

Use the settings in this tab to enable this operator or adapter for runtime start and stop conditions in a multi-node cluster. During initial development of the fragment that contains this operator or adapter, and for maximum compatibility with releases before 10.5.0, leave the Cluster start policy control in its default setting, Start with module.

Cluster awareness is an advanced topic that requires an understanding of StreamBase Runtime architecture features, including clusters, quorums, availability zones, and partitions. See Cluster Awareness Tab Settings on the Using Cluster Awareness page for instructions on configuring this tab.

Concurrency Tab

Use the Concurrency tab to specify parallel regions for this instance of this component, or multiplicity options, or both. The Concurrency tab settings are described in Concurrency Options, and dispatch styles are described in Dispatch Styles.

Caution

Concurrency settings are not suitable for every application, and using these settings requires a thorough analysis of your application. For details, see Execution Order and Concurrency, which includes important guidelines for using the concurrency options.

Reconnect Logic

When you setup your connection you specify 1-N host/port combinations and also specify how many connections to initially connect with. If you have more than 1 host/port setup and one goes down its current connections in the connection pool will be disconnected. If those are the only current connections then the next operation that is requested will cause a new connection to be added to the pool to any server that is available (with timeouts already exposed on the connection adapter being used). If no server can respond to the action then a failure status message is reported for the operation being performed for example 'Search Error' and the info list will contains the ResultCode 91 and ResultName 'connect error', this would happen if ALL servers are unavailable. The next requested operation would try to add another connection to the connection pool again with the same timeout depending on the operation being requested. Please see the Advanced Properties Tab for all the available timeouts.

Control Input Port

The control input port is used to send commands to the adapter to perform connection operations.

The schema for the control input port is:

Field Name Field Type Description
Command String The command to send to the connection adapter, valid values are
  • Connect—The command is used to connect to the LDAP server(s) with the information contained in the input tuple. If already connected the adapter will disconnect and connect with the new information.

  • Disconnect—The command is used to disconnect from the LDAP server(s)

ConnectionType string Optional - If this field is not present or this value is null, the default value from the adapters properties will be used. The value must be one of
  • Round Robin—This will use a round-robin algorithm to select the server to which the connection should be established.

  • Fastest Connection—This will attempt to establish connections to all associated servers in parallel, keeping the one that was first to be successfully established and closing all others

  • Fewest Connections—This will establish a connection to the server with the fewest established connections previously created by the same server set instance

  • Fail Over—This will attempt to establish connections to servers in the order they are provided

SecurityType string Optional - If this field is not present or this value is null, the default value from the adapters properties will be used. The value must be one of
  • None—No security will be used to communicate with the server.

  • SSL—SSL will be used to communicated with the server

  • TLS—TLS will be used to communicated with the server

SecureCommunicationConfig string Optional - If this field is not present or this value is null, the default value from the adapters properties will be used. The security communication config to use from HOCON when connecting via SSL or TLS, this value is ignored if Ignore Invalid Certificates is enabled
IgnoreInvalidCertificates boolean Optional - If this field is not present or this value is null, the default value from the adapters properties will be used. If true any SSL or TLS invalid certificate will be treated as valid. This option should only be used in a testing environment and should never be enabled in production
Servers list(tuple(Host string, Port int)) Optional - If this field is not present or this value is null, the default value from the adapters properties will be used. The hosts and ports of the LDAP servers to connect to.
Auth tuple Optional - If this field is not present or this value is null, the default value from the adapters properties will be used. This tuple field has the schema listed in Auth Tuple Schema
Advanced tuple Optional - If this field is not present or this value is null, the default value from the adapters properties will be used. This tuple field has the schema listed in Advanced Tuple Schema

Auth Tuple Schema

If a field in this tuple is null, the default value from the adapters properties will be used.

Field Name Field Type Description
AuthType string The value must be one of
  • SIMPLE—Simple auth will be used

  • ANONYMOUS—SASL ANONYMOUS bind request as described in RFC 4505. ANONYMOUS SASL mechanism is essentially equivalent to using an anonymous simple bind (i.e., a simple bind with an empty password)

  • CRAM-MD5—SASL CRAM-MD5 bind request implementation as described in draft-ietf-sasl-crammd5

  • DIGEST-MD5—SASL DIGEST-MD5 bind request implementation as described in RFC 2831

  • EXTERNAL—SASL EXTERNAL bind request implementation as described in RFC 4422

  • GSSAPI—SASL GSSAPI bind request implementation as described in RFC 4752

  • PLAIN—SASL PLAIN bind request implementation as described in RFC 4616

BindDN string The bind DN to use when authenticating.
Password string The password to use when connecting.
Trace string Specifies the trace string. It may be used in conjunction with the ANONYMOUS mechanism.
AuthID string Specifies the authentication ID. It may be used in conjunction with the CRAM-MD5, DIGEST-MD5, GSSAPI, and PLAIN mechanisms.
AuthzID string Specifies the authorization ID. It may be used in conjunction with the DIGEST-MD5, GSSAPI, and PLAIN mechanisms.
Realm string Specifies the realm name. It may be used in conjunction with the DIGEST-MD5 and GSSAPI mechanisms.
Qop string Specifies the quality of protection that should be used for communication that occurs after the authentication has completed.
ConfigFile string Specifies the path to the JAAS config file. It may be used in conjunction with the GSSAPI mechanism.
Debug boolean Indicates whether debugging should be enabled. It may be used in conjunction with the GSSAPI mechanism.
KdcAddress string Specifies the KDC address. It may be used in conjunction with the GSSAPI mechanism.
Protocol string Specifies the GSSAPI service principal protocol. It may be used in conjunction with the GSSAPI mechanism.
RenewTGT boolean Indicates whether to attempt to renew the Kerberos TGT for an existing session. It may be used in conjunction with the GSSAPI mechanism.
RequireCache boolean Indicates whether to require an existing Kerberos session from the ticket cache. It may be used in conjunction with the GSSAPI mechanism.
TicketCache string Specifies the path to the Kerberos ticket cache to use. It may be used in conjunction with the GSSAPI mechanism.
UseTicketCache boolean Specifies whether to use a Kerberos ticket cache. It may be used in conjunction with the GSSAPI mechanism.
Controls list(tuple(OID string, Critical boolean, Value string)) Controls to use during auth

Advanced Tuple Schema

If a field in this tuple is null, the default value from the adapters properties will be used.

Field Name Field Type Description
InitialConnections int The number of initial connections to create when connecting.
MaxConnections int The maximum number of connections to create.
InitialConnectThreads int The number of threads to use when creating the initial connections.
ConnectTimeoutMS int Specifies the maximum length of time in milliseconds that a connection attempt should be allowed to continue before giving up. A value of zero indicates that there should be no connect timeout.
ResponseTimeoutMS int Specifies the maximum length of time in milliseconds that an operation should be allowed to block while waiting for a response from the server. A value of zero indicates that there should be no timeout. Note that this will be set before any per operation timeout.
SearchTimeoutMS int Specifies the maximum length of time in milliseconds that the search operation should be allowed to block while waiting for a response from the server. A value of zero indicates that there should be no timeout.
AddTimeoutMS int Specifies the maximum length of time in milliseconds that the add operation should be allowed to block while waiting for a response from the server. A value of zero indicates that there should be no timeout.
CompareTimeoutMS int Specifies the maximum length of time in milliseconds that the compare operation should be allowed to block while waiting for a response from the server. A value of zero indicates that there should be no timeout.
DeleteTimeoutMS int Specifies the maximum length of time in milliseconds that the delete operation should be allowed to block while waiting for a response from the server. A value of zero indicates that there should be no timeout.
ModifyTimeoutMS int Specifies the maximum length of time in milliseconds that the modify operation should be allowed to block while waiting for a response from the server. A value of zero indicates that there should be no timeout.
ModifyDNTimeoutMS int Specifies the maximum length of time in milliseconds that the modify DN operation should be allowed to block while waiting for a response from the server. A value of zero indicates that there should be no timeout.
BindTimeoutMS int Specifies the maximum length of time in milliseconds that the bind operation should be allowed to block while waiting for a response from the server. A value of zero indicates that there should be no timeout.

Status Output Port

The status output port will output tuples giving relevant information.

The schema for the status output port is:

Field Name Field Type Description
Status String A string describing the current status of the adapter.
Time timestamp The timestamp that the status occurred.
Info list(tuple(Name string, Value string)) A list of name value pairs of data to got more context to the status.

The following is a list of status outputs and the associated objects:

Status Description Info Elements
Invalid Command An invalid command was given to the control port
  • Command—The command given by the input tuple.

  • ValidCommands—A list of the valid commands.

  • Tuple—The input tuple that caused the status.

Connection Created A connection was created for the connection pool
  • Host—The address of the directory server to which this connection is currently established.

  • Port—The port of the directory server to which this connection is currently established.

  • Id—A value that uniquely identifies this connection within the JVM.

  • Name—The user-friendly name that has been assigned to this connection.

  • Tuple—The input tuple that caused the status.

  • ActiveConnections—The number of current active connections to the server.

Connection Pool Created The connection pool has been initialized and will start to create connections.
  • Tuple—The input tuple that caused the status.

Connection Pool Creation Failed The connection pool failed to create
  • Error—The human readable error that occurred.

  • Tuple—The input tuple the caused this status.

  • ResultCode—The LDAP result code.

  • ResultName—The name for this result code.

  • DiagnosticMessage—The diagnostic message returned by the directory server.

Disconnected A connection has been disconnected. If no connection pool exists a port value of -1 is returned.
  • Host—The address of the directory server to which this connection disconnected from.

  • Port—The port of the directory server to which this connection disconnected from. A value of -1 indicates no current connection existed.

  • Id—A value that uniquely identifies this connection within the JVM.

  • Name—The user-friendly name that has been assigned to this connection.

  • DisconnectType—Provides general information about the nature of the disconnect.

  • ResultCode—The result code most closely associated with this disconnect type.

  • Description—The description for this disconnect type.

  • Message—A message that may be associated with the disconnect.

  • Cause—If an exception occurred this will contain the exception message.

  • Tuple—The input tuple that caused the status.

  • ActiveConnections—The number of current active connections to the server.

Suspend and Resume Behavior

When suspended, the adapter disconnects from the LDAP server.

When resumed, the adapter will reconnect to the LDAP server if it was connected when suspended.