LDAP Connection Adapter

Contents

Introduction
Adapter Properties
Control Input Port
Status Output Port
Configuration Example
Suspend and Resume Behavior
Related Topics

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.

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 configuration to use when connecting via SSL or TLS. This value is ignored when Ignore Invalid Certificates is enabled. The configuration must be of SecureCommunicationClientProfile type. See this section for a configuration example.
Ignore Invalid Certificates When enabled, any SSL or TLS invalid certificate is treated as valid. Use this option in testing environments only; use in production environments is not recommended.
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.

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 with application: If this field is set to Yes (default) or to a module parameter that evaluates to true, this instance of this adapter starts as part of the JVM engine that runs this EventFlow fragment. If this field is set to No or to a module parameter that evaluates to false, the adapter instance is loaded with the engine, but does not start until you send an epadmin container resume command (or its sbadmin equivalent), or until you start the component with StreamBase Manager.

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 canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.

Auth Tab

Property Description
Auth Type The authentication 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, which you can use in conjunction with the CRAM-MD5, DIGEST-MD5, GSSAPI, and PLAIN mechanisms.
Authz ID Specifies the authorization ID, which you can use in conjunction with the DIGEST-MD5, GSSAPI, and PLAIN mechanisms.
Config File Specifies the path to the JAAS config file, which you can use in conjunction with the GSSAPI mechanism.
Debug Enables debugging, which you can use in conjunction with the GSSAPI mechanism.
KDC Address Specifies the KDC address, which you can use in conjunction with the GSSAPI mechanism.
Protocol Specifies the GSSAPI service principal protocol, which you can use 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, which you can use in conjunction with the DIGEST-MD5 and GSSAPI mechanisms.
Require Cache Indicates whether to require an existing Kerberos session from the ticket cache, which you can use in conjunction with the GSSAPI mechanism.
Renew TGT Indicates whether to attempt to renew the Kerberos TGT for an existing session, which you can use in conjunction with the GSSAPI mechanism.
Ticket Cache Specifies the path to the Kerberos ticket cache to use, which you can use in conjunction with the GSSAPI mechanism.
Trace Specifies the trace string, which you can use in conjunction with the ANONYMOUS mechanism.
Use Ticket Cache Specifies whether to use a Kerberos ticket cache, which you can use 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.

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.

Control Input Port

Use the control input port 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 disconnects and connects 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 is used. The value must be one of:

  • Round Robin — The adapter will use a round-robin algorithm to select the server to which the connection should be established.

  • Fastest Connection — This attempts 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 — Establishes a connection to the server with the fewest established connections previously created by the same server set instance.

  • Fail Over — This attempts 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 is used. The value must be one of:

  • None — No security will be used to communicate with the server.

  • SSL — SSL will be used to communicate with the server.

  • TLS — TLS will be used to communicate with the server.

SecureCommunicationConfig string Optional — The security communication configuration to use when connecting via SSL or TLS. This value is ignored when Ignore Invalid Certificates is enabled. The configuration must be of SecureCommunicationClientProfile type. See this section for a configuration example.
IgnoreInvalidCertificates boolean Optional — When enabled, any SSL or TLS invalid certificate is treated as valid. Use this option in testing environments only; using in production environments is not recommended.
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 is 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 is 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 is 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 is used.

Field Name Field Type Description
AuthType string The value must be one of:

  • SIMPLE — Simple authentication is used.

  • ANONYMOUS — SASL ANONYMOUS bind request as described in RFC 4505. ANONYMOUS SASL mechanism is essentially equivalent to using an anonymous simple bind (that is, 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, which you can use in conjunction with the CRAM-MD5, DIGEST-MD5, GSSAPI, and PLAIN mechanisms.
AuthzID string Specifies the authorization ID, which you can use in conjunction with the DIGEST-MD5, GSSAPI, and PLAIN mechanisms.
Realm string Specifies the realm name, which you can use in conjunction with the DIGEST-MD5 and GSSAPI mechanisms.
Qop string Specifies the quality of protection that you should use for communication that occurs after the authentication completes.
ConfigFile string Specifies the path to the JAAS config file, which you can use in conjunction with the GSSAPI mechanism.
Debug boolean Indicates whether debugging should be enabled, which you can use in conjunction with the GSSAPI mechanism.
KdcAddress string Specifies the KDC address, which you can use in conjunction with the GSSAPI mechanism.
Protocol string Specifies the GSSAPI service principal protocol, which you can use in conjunction with the GSSAPI mechanism.
RenewTGT boolean Indicates whether to attempt to renew the Kerberos TGT for an existing session. It can be used in conjunction with the GSSAPI mechanism.
RequireCache boolean Indicates whether to require an existing Kerberos session from the ticket cache. It can be used in conjunction with the GSSAPI mechanism.
TicketCache string Specifies the path to the Kerberos ticket cache to use, which you can use in conjunction with the GSSAPI mechanism.
UseTicketCache boolean Specifies whether to use a Kerberos ticket cache, which you can use in conjunction with the GSSAPI mechanism.
Controls list(tuple(OID string, Critical boolean, Value string)) Controls to use during authentication.

Advanced Tuple Schema

If a field in this tuple is null, the default value from the adapters properties is 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.

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 adapter status.
Time timestamp The timestamp for when the status occurred.
Info list(tuple(Name string, Value string)) A list of name-value pairs of data to get more status context.

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

Status Info Elements
Invalid Command

  • Command — The command given by the input tuple.

  • ValidCommands — A list of the valid commands.

Connection Created

  • Host — The address of the directory server to which this connection is currently established.

  • Post — 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 assigned to this connection.

Connection Pool Created None
Connection Pool Creation Failed

  • Error — The error that occurred.

Disconnected

  • Host — The address of the directory server from which this connection disconnected.

  • Post — The port of the directory server from which this connection disconnected.

  • 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 relates to the disconnect.

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

Configuration Example

When setting the Secure Communication Config field, specify a configuration with the same name as the file itself. The file (my-profile in this example) must be located in your project's src/main/configurations folder: 

// This is a sample of the com.tibco.ep.dtm.configuration.security.SecureCommunicationClientProfile 
// configuration containing only required properties. The contents as presented are not valid; uncomment 
// and replace sample values with valid values as needed.

name = "sample-SecureCommunicationClientProfile-document"
type = "com.tibco.ep.dtm.configuration.security"
version = "1.0.0"
configuration = {

// A secure communication client profile configuration object contains settings used 
// to secure client-side transport connections, for example to external services such 
// as LDAP. Profiles are named, and then referenced as needed by other configurations 
// needing secure communication.

SecureCommunicationClientProfile = {

// The name of this profile, unique across all secure communication profiles. This 
// property is required.
   name = "my-profile"

// Enable or disable required client authentication. Enabling requires presence of a 
// key store to sign the client side of the secure communication handshake. This property 
// is optional, and its default value is false. If its value is true, both a key store
// and key store password are required.
// requireClientAuthentication = true

// Trust store containing CAs by which client certificates must be signed to be trusted. 
// If specified, this must be a file. The path is required to be absolute, therefore 
// the file must exist on the target node's file system. This property is optional. 
// If you do not specify a trust store, the default JRE default CA cert store is used 
// instead (for example, in $STREAMBASE_HOME/jdk/jre/).
   trustStore = "C:/absolute/path/myTrustStore.jks"

// The password to access the trust store. This optional property is encryptable as part of 
// the node-level secrecy system described in Encrypting Sensitive Configuration Data.
   trustStorePassword = "password"

// Trust store type. This key is optional and its default value is 'jks'.
   trustStoreType = "jks"
  }
}

Suspend and Resume Behavior

When suspended, the adapter disconnects from the LDAP server.

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

Related Topics

Back to Top ^