LDAP Connect User's Guide
CHAPTER 2
The steps involved in creating a Composer component using the LDAP Connect are fundamentally no different from those involved in creating any other kind of component. The steps are:
Decide on any XML Templates you may need for your component.
Create a Connection Resource to allow your component to bind to an LDAP host. (The procedure for this is explained in detail below.)
Test the action model by running the Component in animation mode.
Create a deployable Service that calls the Component. (Components cannot be deployed directly; the unit of deployment in a Composer project is the Service.)
Deploy your service to a staging area or to an app server environment (such as Novell exteNd App server, IBM WebSphere, or BEA Weblogic).
In the sections that follow, we'll look closely at Step 2: creating a Connection Resource. See the later discussion under "Creating an LDAP Component" for a detailed explanation of how to use LDAP-specific Actions.
Before you can create a working LDAP Component, you need to create a Connection Resource for it. (If you try to create an LDAP Component and there are no LDAP Connection Resources in your resource list, you will be prompted with a dialog that offers to take you to the Connection Resource wizard.)
The LDAP Connection Resource contains the information needed to allow a component to connect to an LDAP host (or directory server). You will generally create a separate resource for every different host you want to establish a connection with, or for every unique set of credentials (or timeout settings) that you want to use with a given host.
NOTE: The various parameters associated with a given connection resource can be late-binding if you specify expression-driven connection parameters in your resource, as described below.
You can specify Connection parameter values in one of two ways: as constants or as expressions.
A constant-based parameter uses the literal value you supplied in the Connection wizard every time the Connection is used. An expression-based parameter means that you set the value using a programmatic (ECMAScript) expression, which is evaluated at runtime. The "late binding" of parameters afforded by the latter method makes it possible for you to supply a different User DN or password each time the connection resource is used. That is, the connection params can be chosen programmatically, at runtime.
Suppose you want to pull login credentials from a file or database at runtime. You can set up your connection resource to use expressions that look up the necessary info from files or databases via ECMAScript File I/O extensions or via Java directly. The use of expressions allows a Connection's behavior to be flexible and vary dynamically in accordance with runtime conditions.
To switch a parameter from Constant to Expression driven:
Click the right mouse button inside the parameter field you are interested in changing.
Select Expression from the context menu that appears. A small editor button (icon) will become visible to the right of the parameter field.
Click on the button and use the Expression Builder dialog to create an ECMAScript expression that evaluates to a valid parameter value at runtime.
To create an LDAP connection, you will need to supply, at a minimum, the server IP address and the port number on which the session will occur. These two items are all that is needed to bind anonymously to a host that permits anonymous binds. (An anonymous bind in LDAP is analogous to an anonymous FTP session.) The IP address might be something like 127.0.0.1 or "localhost" at design-time (but presumably something else at runtime; perhaps switched by an expression-driven IP address parameter). The Port Number is typically 389 for a non-secure session and 636 for an SSL session, because this is how most directory servers are configured, but in fact you can supply any value here that might apply.
For non-anonymous binds, you will need to supply a User DN (user distinguished name), and a password. The User DN represents (in the words of RFC 2251) "the name of the directory object that the client wishes to bind as." It is typically the distinguished name of a person or entity in the directory, such as "cn=John Doe, ou=Mailroom,o=Rising Star Industries."
When a given server exposes more than one tree, the server needs to know which tree (more accurately, which subtree) the client wants to bind to. This information is given in the form of a Base DN.
For example, consider a directory server operated by the fictitious international conglomerate Acme, Inc. The Acme directory server might have three top-level container objects—three "trees"—representing complete directory structures for Acme Pacific, Acme U.S., and Acme Europe, as shown below.
If an LDAP client wants to bind to the Acme directory, the server will need to know which tree (Pacific., U.S., or Europe) the client wishes to bind to. In this example, if an Acme human resources manager in Spain wants to bind to the tree for Acme Europe, he would specify "o=Acme Europe" as the Base DN.
NOTE: In LDAP, the Root object is not really an entry in the tree and is not addressable directly. The Root is more formally known as the root DSE, or DSA Specific Entry. (A DSA is a directory system agent, which is an X.500 term for a directory server.) The DSE can be queried for "meta" information about the directory server (in LDAP version 3).
The LDAP Connect for Composer supports encrypted sessions (and server authentication using X.509 digital certificate technology) through the use of SSL.
To enable encryption and authentication, you must check the TLS (Transport Layer Security) checkbox on the connection setup dialog. In most cases, you will also want to set the Port Number (in the same dialog) to 636, because LDAP servers generally expect to carry out encrypted sessions on that port.
NOTE: The Port Number shown in the dialog does not automatically change to 636 when you set the TLS checkbox. You must enter the Port Number manually. (Likewise, merely entering a port value of 636 does not cause the TLS checkbox to come on.)
When the TLS box is checked, all information moving across the connection will be encrypted; no information will be sent in the clear. Also, the host (or directory server) will be presented a certificate challenge. The host will respond with its X.509 certificate info. Composer will check that certificate info against the Certificate Authority data stored in the agrootca.jar file (which is a Java archive that ships with Composer, containing Certificate Authority info for numerous industry standard certificate issuers; see the Composer User's Guide for details).
NOTE: You can find agrootca.jar in your Composer-installation \lib folder. Use WinZip to open, inspect, and/or add new certificates to this file. Be sure to consult your app server's documentation to learn how to add X.509 certificates, and any other security resources that your applications might need, to your app server's runtime environment.
The SSL3 security mechanisms supported by Composer's LDAP Connect are "all or nothing" (not dynamically switchable). In other words: the ability to begin an LDAP session in clear-text mode, then drop into "secure" mode on the fly (as part of the same session, using the same Connection Resource), is not supported in this version of the LDAP Connect.
The process of creating an LDAP Connection Resource is straightforward.
To create a LDAP connection resource:
From Composer's main menubar, select File > New > xObject, then open the Resource tab and select Connection.
Type a Name for the connection object. (This is the name that will show up later in the Navigator pane of Composer's main window when you are browsing resources in the Connection category.)
(Optional) Enter text in the Description area of the dialog.
Select LDAP Connection from the Connection Type pulldown menu.
Next to Host or IP Address, enter the name or IP address of the directory server with which you intend to connect. (For testing, this might be localhost.)
NOTE: This parameter, and all subsequent text fields in this dialog, can be set dynamically using ECMAScript expressions. See "About Expression-Driven Connection Parameters" earlier in this chapter.
If your connection will be using a port other than the default of 389, enter the appropriate value next to Port Number. (If the connection will be a TLS connection using SSL, and you are not sure what value to enter here, enter 636, which is the standard port for LDAP-over-SSL.)
TIP: You can specify a port as part of the IP address (previous step) using
colon notation, such as localhost:389. If you do decide to use the all-in-
one IP-address:port notation, enter 0 (zero) in the Port Number field.
Enter a valid Base DN (tree name), if applicable. This value might look something like t=DEVNET-TREE.
Enter a valid User DN (user distinguished name). See earlier discussion for information about distinguished names.
NOTE: If you are attempting an anonymous (no-password) bind, you can enter any value here.
No password is required for an anonymous bind. In all other cases, enter a valid Password for the given User DN.
CAUTION: This password will be sent in the clear if the connection is not TLS-enabled.
Unless your LDAP host requires a different value, accept the default Version value (LDAP version) of 3.
Check the TLS checkbox if this is to be a secure connection (SSL3). Note that for X.509 certificate-based authentication to work, you must have the appropriate Certificate Authority entries in your agrootca.jar file (in Composer's \lib directory). Also, the appropriate certificate setups must exist on the server. Consult your app server documentation for details.
Optionally enter a Time Limit value representing the maximum number of milliseconds your component is willing to wait for establishment of a connection with the server. The default is no limit.
Optionally enter an integer value in Size Limit, representing the maximum number of tree entries (nodes) you are willing to accept for purposes of rendering tree-views of the directory at design time. The default value is 1000, which means that Composer can display a maximum of 1000 child nodes under any given parent node (entry) in the tree browser.
Two things could happen if you enter a very large number here:
Performance could suffer as Composer tries to pull down and render all the requested entries
The remote host might reach a preset limit on how many entries it can serve, and return an error (in which case Composer will not be able to display entries under the node in question)
It is recommended that you accept the default value of 1000, unless you know for sure that you will need to browse a tree node that contains a particularly large number of child nodes.
NOTE: This is a design-time consideration only. At runtime, on the server, this setting does nothing.
Click Test to see if the connection defined in your resource really works. A success or failure alert dialog will appear after a few seconds. (The test can take 30 seconds or more to "time out" if no connection can be made. To lessen the wait, enter a Time Limit value as described in the previous step.)
NOTE: You can continue editing the resource if your connection fails. You can also Save the resource and edit it later.
Optionally check the Default checkbox (underneath the Test button) if you want this connection to be used as the default connection each time you create a new LDAP Component. (You can override this behavior at any time.)
Click Finish. The newly-created resource connection object appears in the Composer Connection Resource detail pane.
If you see an error dialog (instead of an alert with the message "Connected Successfully") when you press the Test button, click the Details button of the dialog to see a full stack trace for the exception. See illustration below.
The stack trace message often provides useful clues for isolating the cause of the problem. In the example shown above, the connection was refused. On closer examination, it can be seen that the IP address specifies (at the end, after a colon) a port number of 390. The correct port number for the server was 389. Hence, no connection could be obtained and an LDAPException was thrown.
Here are some issues to bear in mind if you encounter trouble:
Anonymous binds: If you can't establish an anonymous bind, remember that the host server might not be set up to allow anonymous binds—the same way that an FTP server may not be set up to allow "anonymous FTP" sessions. If the server doesn't allow anonymous binding, you must authenticate to the server in some fashion (whether by simple password and User DN over port 389, or full SSL on port 636, or some other way).
ECMAScript expressions: When expression-driven parameters are used (see "About Expression-Driven Connection Parameters" further above), literal string values must be wrapped in quotation marks. Conversely, if you are not using expression-driven parameters, do not wrap param values in quotation marks.
TLS: Be sure to uncheck this checkbox when a secure connection is not needed; and when it is checked, verify that you've specified a "secure port" (such as 636). Also verify, when using a secure connection, that your Certificate Authority .jar file contains the correct entries and is installed properly. (Look for a file called agrootca.jar in your Composer installation. The fully qualified path to this file must be specified in the <XCCERTFILE> element of your xconfig.xml file, not only in the design-time installation but also the runtime, or server, installation. Also, you may have to take additional steps to be sure this file can be found by your app server at runtime. See your app server documentation for details on how to set up X.509 certificates and certificate authority files.)
It is possible to see a "Connected Successfully" alert, followed by an error dialog, when testing a connection. The success message means the host IP address and port number that you supplied were valid and a connection was established with the host. The subsequent exception message means a problem was encountered after connecting (such as a timeout, or an unknown Base DN).
NOTE: LDAP makes a subtle distinction between connecting and binding. Establishing a connection merely means that a the host and client were able to begin an LDAP session over TCP/IP, without reference to any particular target objects in a directory. A bind occurs when the host sees fit to associate a given combination of User DN and credentials with a given object in the server, in the context of session access.
By way of analogy: Suppose 10-year-old Danny knocks on the door of the next-door-neighbor's house. An adult opens the door. The child asks the adult: "Can Tommy come out and play?" In this example, Danny is analogous to an LDAP client and the adult is the LDAP host. When the door opens, a connection is established. The adult (server) then has to decide whether the child (client) should have access to Tommy (the target object). If the adult knows Danny (i.e., Danny can be authenticated in some way), and Danny has access rights to Tommy (i.e., it's the right time of day, Tommy is done with his homework, etc.), then the two children might be allowed to play (to "bind"). But if the adult has never seen Danny before or doesn't trust him, or if access rules preclude Tommy's availability, then Danny will be turned away, even though the front door did open and a conversation took place.
Directories quite often form the heart of mission-critical systems, and as a result, things like system outages (no matter how brief) and normal maintenance-related takedowns tend to be extremely disruptive. For that reason, directory trees are often replicated across servers, so that if a client tries to connect with Server A, but Server A is down, it can try Server B.
If you know the IP address of one or more backup servers that can be used if the primary server you're interested in is either physically down or simply bogged down due to high demand, you can construct your LDAP Connection Resource in such a way as to provide silent failover capability.
Suppose your primary server is at server1.acme.com, but there are replicas of the directory also on server2.acme.com and server3.acme.com. When you create your connection resource, enter all three addresses (separating each with a space character) in the "Host or IP Address" field:
In the example shown, you'll see that not only have three addresses been entered in "Host or IP Address," but a value of 200 milliseconds has been specified under Time Limit (at the bottom of the dialog). When a component uses this resource, it will first try to connect to server1.acme.com (on the specified port of 389). If that server is down, or takes longer than 200 milliseconds to respond, a new connection attempt will be tried on the next address: server2.acme.com. If that server doesn't respond within 200 milliseconds, server3.acme.com will be tried. Finally, if none of the servers can be connected to, an exception is thrown.
NOTE: All three servers, in this example, will be tried on port 389, because that's the value that was entered in the Port Number field of the dialog. If the servers are not all using the same port, it is still possible to build a failover connection by using colon notation in the IP addresses: server1.acme.com:389, server2.acme.com:636, etc. If you do this, however, you should enter 0 (zero) in the Port Number field of the dialog.
You can go back and change a connection resource at any time. Simply locate the resource by name in the Navigator pane (at the Composer window's left edge) and doubleclick it to bring up a tabbed dialog containing the information you typed into the wizard when you created the resource originally. (See previous illustration.) Choose the tab of interest and type new information into the appropriate fields. Click OK to keep your changes, or Cancel to revert back to the resource's original settings.
Copyright © 2003 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved. more ...
