LDAP Connection Adapter

< Previous		Next >

Introduction

The TIBCO StreamBase® 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, which must be unique in the current EventFlow module. The name must contain only alphabetic characters, numbers, and underscores, and no hyphens or other special characters. 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 check box 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 component's purpose and function. 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.

Cluster Aware Tab

Use the settings in this tab to allow this operator or adapter to start and stop based on conditions that occur at runtime in a cluster with more than one node. During initial development of the fragment that contains this operator or adapter, and for maximum compatibility with TIBCO Streaming 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.

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

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.