LDAPviewer

Connection Window

When the user clicks the Connect item on the File Menu or the Connect button (if the Button bar is enabled) the following window is displayed:

Connection Window

Four connection options are available. The first method involves selecting the Quick Connect Tab, enter the minimum necessary information and use the Connect Button.

The second method is to create a Connection Profile. This process is described in detail below.

Once one or more connection profiles have been established, the third method involves selecting the relevant Connection Profile from the list displayed and clicking the Connect button.

Note: When LDAPviewer is loaded for the first time the Profile list will be empty. Only the New button will be enabled since this is the only permissable operation involving Profiles at this stage. (Quick Connect is always available.)

Once one or more connection profiles have been established, the fourth method involves selecting the Connect Profile name from the Recent menu (File Menu).

Connection Profile

A Connection Profile allows the user to capture and save information about a specific LDAP/DSML connection. A significant number of Options are available to control the Connection and modify the display characteristics. Most options default to expected operational values and hence can be ignored but are available to allow customization of the Profile.

Creating a Connection Profile

A Profile may be created by clicking the New button. Alternatively, if a Profile exists which has at least some of the characteristics of the required new profile, then selecting that Profile and clicking the Copy button will create a profile with the original profile name, appended with -copy (the original Profile is unchanged). Selecting this new profile and Edit will allow the name and other details to be edited, the Rename button will only allow the profile name to be changed.

Profile Names may be 5 to 50 characters long and may not contain spaces, dots or commas.

Connection Profile (New or Edit Buttons)

When the new button is clicked the following window is displayed with 4 tabs. The Profile Name tab displays the Profile and allows it to be changed if required. The Connection Details tab allows entry and selection of various features defining the LDAP server, authentication method and protocol details. The Options tab allows selection of various options that control the behavior of LDAPviewer such as how it will handle Referrals and whether passwords can be saved with the profile. The More DITS tah allows the user to optionally provide concurrent access to the rootDSE and a Secondary DIT on the server such as OpenLDAP's OLC (cn=config).:

Profile Name Window

Profile Name

The Edit Window opens on the Profile Name tab which contains a default name which suggests that it be changed. In fact it is more than a suggestion, if the Save button is clicked without changing this name the user is gently reminded of the fact and invited to exhibit all their creativity by selecting any other name. Recall that names may be 5 - 50 characters long and cannot contain spaces, dots or commas.

When the new name has been entered select the Connection Details tab to display the next window:

Connection Details

Connection Details

You need only enter as much information as required to initiate the connection. A connection may be, depending on its complexity, accomplished using a small subset of the total information. This Window is organized into two sections: LDAP Details: describes the physical connection and Security Details allows selection of the security type and capture of any required credentials. The purpose and usage of each field is described below (left to right, top to bottom).

  1. Host: The host name of the server providing the target LDAP service. For example, localhost (if the LDAP server is on this machine) or ldap.example.com or fred.example.org if the server is remote. There is no need to add any protocol identifier such as ldap://, ldaps:// or http:// (for DSML). The appropriate value will be added by LDAPviewer. Note: When using any TLS/SSL service the hostname must be the same as appears on the cn= value of the subject (or subjectAltName). For example, if the LDAP server is running on the same server (normally localhost would be permissable) but has a certificate whose subject attribute has a value of cn=ldap.example.com then ldap.example.com must appear in the Host field not localhost.
  2. Port: The port number used by the LDAP service. LDAPviewer defaults to port 389 but this can be changed for all Profiles and the Quick Connect service by selecting Preferences from the Options Menu.
  3. Protocol: Select the required protocol from the drop down conbo box:
    1. LDAPv3 LDAP version 3 (default - this can be changed at Preferences). This is the current and most common protocol supported by LDAP servers including MS Active Directory.
    2. LDAPSv3 LDAP version 3 using TLS/SSL. Selecting this type will generate an LDAP URL of the form ldaps://hostame:port. By convention, LDAPSv3 is supported on port 636 but any port may be configured by the LDAP server's administration staff to support this service and the user is reminded to verify, and change as necessary, the Port: field. Selecting the LDAPSv3 option automatically adds TLS to the Access Types: below. You may want to read more about LDAPviewer's flexible TLS/SSL support.
    3. LDAPv2 LDAP version 2. An older and much less common protocol supported by certain servers.
    4. DSMLv2 Directory Services Markup Language version 2 (essentially an XML wrapper for LDAP). Selecting DSMLv2 will make visible an additional DSML Service: field.
  4. Base DN: This defines the lowest DN that LDAPviewer will attempt to read. For example, if using standard RFC 2247 style naming this may be a suffix of the form dc=example,dc=com, if using X.500 style naming it may be a suffix of the form o=corp,c=my. It is perfectly legitimate, however, to use any value as a Base DN: not just the LDAP suffix. Thus, if a user only has permission to access a part of the DIT such as that commencing ou=people,dc=example,dc=com or ou=people, ou=calgary,dc=example,dc=com then this should entered in the Base DN field. LDAPviewer will make no attempt to read entries below this DN. Conversely, if an organization uses X.500 style naming of o=corp,c=my but uses a suffix of c=my then this value (or o=corp, c=my) is a perfectly valid Base DN. Leaving the Base DN: blank will cause LDAPviewer to read the RootDSE entry (which may require authentication on some LDAP servers). (Full Profiles allow the option to permanently display the RootDSE during a connection.) The DIT for this base DN is displayed in the Primary DIT pane of the LDAPviewer window.
  5. Discover DITs: Checking this box will cause LDAPviewer to discover all the available DITs by reading the namingContexts attributes (the DIT suffixes) from the RootDSE. All the available DITs are displayed in a single tree structure.

    If authentication is required to access RootDSE (required by some servers) then the details should be entered in the Security Details section.

    If authentication is required for access to any discovered DIT then, instead, enter these details in the Security Section and select (check) Display RootDSE on the Options tab, and enter the appropriate security credentials in the RootDSE Security section of the More DITs tab.

    If more than a single DIT is discovered and more than one DIT requires authentication then the only solution is use a separate Connection Profile for each DIT.

    When Discover DITs: is checked the value of Base DN is ignored and may be left empty.

    Assuming anonymous read access to the RootDSE and the DIT(s), simply enter the Host:, click Discover DITs: followed by the Connect button.

  6. DSML Service: This field is only visible if DSMLv2 has been selected as the Protocol: and is invisible at all other times.

    DSML service

    DSMLv2 service is typically provided at a URL which consists of the Host: and suffix of the form dsml/service/at/url. Enter the full suffix in this field. LDAPviewer will open the DSMLv2 service at the URL http://hostname:port/dsml/service/at/url.

Security Details

  1. Access Type: Select the required security type to access the Host: at the defined Base DN: (if Discover DITs: was checked this security type relates to the RootDSE, Base DN: is ignored for Discover DITs:). Currently supported Access Types are shown and described below: Access Types
    1. Anonymous No credentials are required (default option - though this may be changed using Preferences: User Access). The fields User DN: and Password: will be disabled since they are not required.

    2. User+Password Credentials are required. The fields User DN: and Password: are enabled and need to be completed with the appropriate information.

      Note: If this option is selected when using Protocol:LDAPv3 credentials are always sent in clear text. If a remote LDAP server is in use then these credentials may be sniffed/intercepted at any point in the network (localhost messages never appear on the network). However, if this option is selected when using Protocol:LDAPSv3 the entire session, including authentication is encrypted and passwords cannot be sniffed or intercepted.

    3. TLS+Anonymous Credentials are not required. The fields User DN: and Password: are disabled.

      By default the connection will be verified using the TLS/SSL Root and Trusted certificates available in Java (JSEE) and appropriate error messages output if errors are detected. (The certificates available to the standard Java environment may be displayed using View All Certificates on the Certificate Menu.) Additional Root and Trusted certificates may be configured in LDAPviewer (including self-signed certificates) in which case full verification of any server certificate signed by that/those CA(s) will be provided.

      The method of TLS/SSL (X.509) certificate validation is controlled by the TLS option which is only visible when either LDAPSv3 is selected in Protocol or a TLS option is selected in the Access Type field.

    4. TLS+Client+Anonymous Credentials are not required. The fields User DN: and Password: are disabled.

      All server authentication processing when using this option is identical to TLS+Anonymous above.

      This option will send a client (X.509) certificate in a process that is sometimes referred to as Mutual Authentication. This option is only effective when a Client Keystore has been configured. (If a Client Keystore is not configured when a connection is made using a Profile containing this option then TLS+Anonymous will be assumed, that is, no Client certificate will be sent.) The LDAP server must have been configured to support this service which includes making available one or more Trusted or Root/Intermediate certificates to enable the transmitted client certificate to be validated by the LDAP server.

    5. TLS+User+Password Credentials are required. The fields User DN: and Password: are enabled and need to be completed with the appropriate information. With this option the TLS service is established before credentials are sent and hence credentials cannot be sniffed on the network.

      By default the connection will be verified using the TLS/SSL Root and Trusted certificates available in Java (JSEE) and appropriate error messages output if errors are detected. (The certificates available to the standard Java environment may be displayed using View All Certificates on the Certificate Menu.) Additional Root and Trusted certificates may be configured in LDAPviewer (including self-signed certificates) in which case full verification of any server certificate signed by that/those CA(s) will be provided.

      The method of TLS/SSL (X.509) certificate validation is controlled by the TLS option which is only visible when either LDAPSv3 is selected in Protocol or a TLS option is selected in the Access Type field.

    6. TLS+Client+User+Password Credentials are required. The fields User DN: and Password: are enabled and need to be completed with the appropriate information. With this option the TLS service is established before credentials are sent and hence credentials cannot be sniffed on the network.

      All server authentication processing when using this option is identical to TLS+User+Password above.

      This option will send a client (X.509) certificate in a process that is sometimes referred to as Mutual Authentication. This option is only effective when a Client Keystore has been configured. (If a Client Keystore is not configured when a connection is made using a Profile containing this option then TLS+User+Password will be assumed, that is, no Client certificate will be sent.) The LDAP server must have been configured to support this service which includes making available one or more Trusted or Root/Intermediate certificates to enable the transmitted client certificate to be validated by the LDAP server.

  2. Read Only: LDAPviewer provides the ability to lock the server access interface into a 'read-only' mode to prevent accidental modification of the DIT. This is in addition to (and does not replace) any permissions applied by the server. Checking the box will invoke the LDAP server access interface read-only mode and disallow all modification operations. Leaving the box unchecked means that modification permissions are determined entirely by the LDAP/DSML server.

    Note: The User DN: and Password: fields are enabled only if required. This is determined by the users selection of Access Type and Save in Profile.

  3. User DN: The DN used to authenticate the user to the defined Host: at the defined Base DN:. This may be the rootDN for the particular DIT or a DN that appears in the DIT to which particular access permissions have been assigned by server configuration.
  4. Append Base DN: Checking this box will cause LDAPviewer to append the value of the Base DN: field to the value of User DN: to save some typing. Thus, if Base DN: is dc=example,dc=com and User DN: is cn=joe,ou=people then checking the Append Base DN: box will cause LDAPviewer to authenticate using the DN cn=joe,ou=people,dc=example,dc=com.
  5. Password: Enter the password used to authenticate the User DN: for the defined Host: and Base DN:. If this entry is left empty it indicates that the user does not wish the password to be saved in the Connection Profile and the user will be prompted for one immediately prior to every connection. (All the information in a Quick Connect is discarded on termination of the connection.) See also the descriptions of the various Access Type: values for more password security information and for further information about the password saving options see Save in Profile.
  6. TLS: The TLS entry is only visible if either the Protocol: is LDAPSv3 or any Access Type using TLS is selected, at all other times it is irrelevant and therefore not displayed.

    TLS/SSL Options

    Selecting the Check button indicates that any certificate received from the LDAP Host will be verified using the standard Java Trusted KeyStore. (The contents of the Java Trusted Keystore may be inspected by using the View All Certs item from the Certificates menu.) If the root and any intermediate certificates associated with the LDAP Server's certificate are not present in the standard Java Trusted KeyStore then the connection will fail with an appropriate message. (Certificates may be imported in the standard Java Trusted KeyStore using the Import Cert button of the View or Import Certificate item of the Certificates menu.)

    Selecting the Any button indicates that LDAPviewer will accept any certificate from the LDAP Server. No attempt will be made to authenticate or validate the received certificate. The session will be secured using the public key contained in the supplied certificate. This mode may be useful where the server is using non-standard certificates (such as self-signed certificates) or where the standard Java Trusted Certificate KeyStore does not contain the relevant root and/or intermediate certificates. Caution: Using this mode where the LDAP Server is unknown may lead to security breaches and is not recomended.

    Selecting the User button indicates that the LDAP Server's certificate will be displayed to the user, where any of it attributes may be inspected, and the session will proceed only if accepted by the user, if rejected the connection will be terminated. (Example of Certificate Acceptance Window.)

    Selecting the KS button indicates that verification of the LDAP Server's certificate will use only the user's configured Trusted KeyStore. (Configuration of the Trusted KeyStore uses the Manage User's Trusted Keystore item of the Certificates menu.

    The default value is Check but this may be modified using the Preferences item on the Options menu.

Options Window

In many cases the information entered in the Connection Details Window is sufficient. Clicking Save, selecting the newly created Profile and clicking Connect will initiate the connection. Futher options are available to customize LDAPviewer behavior and selecting the Options tab will display the following window:

Connection Options

The Options Tab controls a number of features that affect the behavior of the LDAP/DSML connection. Each field is described (Left to Right, Top to Bottom).

  1. Referrals: This controls what the LDAP server will do when it encounters a referral objectClass in a read or search operation. Referrals are typically used when the DN addressing structure for any particular path (DN/RDN) is continued in another LDAP server (Referrals allow a full LDAP URI). Two options are available:
    1. Ignore Selecting Ignore (the default - which may be changed using the Options Menu, Preferences) will cause any referral objectClass encountered in a read or search path to be returned and treated as a non-referral. The server will not follow the URL/DN defined in the ref attribute of the objectClass. Selecting this option allows the referral objectClass and its associated attributes to be inspected and/or edited.
    2. Follow Selecting Follow will cause a referral objectClass, encountered in a read or search operation, to follow the URL/DN value defined in the ref attribute. The referral attribute is essentially invisible (its normal behavior in an operational DIT).
  2. Deref. Aliases: This option controls what the server will do when it encounters an alias objectClass. An Alias is typically used to change the resolution path of a DN/RDN to another location within the LDAP server (an alias only allows a DN not a full LDAP URI) by replacing (aliasing) one DN value for another. Deference Alias options only apply to search and read operations and do not apply to modify, add or delete (edit) operations. Four options are available:
    1. Always The LDAP server will always deference the alias, that is, it will substitute the DN defined in the AliasedObjectName attribute of the alias objectClass for the DN that was referenced in the search operation. This is the default option but may be changed in Preferences (Options Menu).
    2. Never The LDAP server will never deference the alias, that is, it will never substitute the DN defined in the AliasedObjectName attribute of the alias objectClass for the DN that was referenced in the search operation.
    3. Finding The LDAP server will deference any alias, that is, it will substitute the DN defined in the AliasedObjectName attribute of the alias objectClass for the DN that was referenced in the original operation but only during the name resolution of the search operation (establishing the search base DN), thereafter (on any found entry/entries) no dereferencing will be performed.
    4. Searching The LDAP server will never deference any alias, that is, it will not substitute the DN defined in the AliasedObjectName attribute of the alias objectClass for the DN that was referenced during the name resolution of the search path (establishing the search base DN). Thereafter (in the search results) all aliases will be deferenced (DN substitution will occur).
  3. Timeout: Defines the time in milliseconds before LDAPviewer will decide the LDAP operation has failed, a value of 0 (the default) indicates LDAPviewer will wait up to its normal limit of 5 seconds before determining an operation has failed.
  4. Pagesize: Defines the maximum number of entries that will be returned in any single search page. A value of zero (the default) indicates that the server will send the maximum number of search results determined by its configuration limits. In both cases LDAPViewer will continue to read from the server until all the results have been received. The only reason to not leave the field at is default value (0) is where there are limits in incoming block sizes at the LDAPviewer (or an intermediate) location.
  5. Passwords: This option determines how LDAPviewer handles passwords. If Save in Profile is unchecked (the default - this can be changed in Preferences (Options Menu)) passwords will not be saved in the Profile and all Password fields in the Connection Windows will be disabled. Whenever the user invokes a connection they will be prompted for all necessary passwords which will be discarded on Disconnect (File Menu) or when a new connection is made.

    If Save in Profile is checked all Password fields will be enabled and the passwords will be saved in the Connection Profile file in base64 format. Warning: Base64 is not an encryption method and any password saved in this format can be trivially converted to clear text. It is intended to provide what is frequently called over-the-shoulder security, that is, a casual observer will never see a clear text password. However, if there is any requirement for more than casual observer protection the password(s) should not be saved in the Connection Profile (uncheck Save in Profile).

    If the user intially opted to save passwords (Save in Profile was checked) and subsequently decides not to do so (Save in Profile is unchecked) then all previously saved passwords will be deleted from the Profile.

    If the user opts to save passwords (Save in Profile is checked) but does not enter a password then, when the profile is saved, they will be prompted to enter a valid (non-blank) password.

  6. Attribute Types: Defines the attributes to be returned on all read Entry operations and may be used to define a unique attribute set for the profile.

    Note: Attributes are generically classified as user (they contain user data and depending on ACL permissions are typically editable) or operational (they contain data created and used by the LDAP server and are never editable by the user).

    By default the drop-down menu provides three options:

    1. All-Attrs (* +) Indicates that both user and operational attributes will be returned on all Read Entry operations. This is the default but may be changed using Preferences (Options Menu). Any search requests may override this value.
    2. All-User (*) Indicates that all user attributes will be returned on all read Entry operations. Any search requests may override this value.
    3. All-Ops (+) Indicates that only operational attributes will be returned on Read Entry operations. Any search requests may override this value.

    If the user has defined one or more Return Attributes Named Lists (using the Search menu) then these are also displayed in the drop-down menu and may be selected. If the Return Attribute Named List is modified the changes will be reflected on the next connection which uses the named list.

    Note: The HTML Editor uses the user attribute objectClass to select appropriate templates. If only Operational attributes are selected or the attribute objectClass is not ncluded in the returned attributes then the default HTML template will be used to display the entry.

  7. Sort Tree: This option indicates whether sorting will occur in the DIT Tree Windows. The available choices are:
    1. None No Sorting will be done on any DIT Window. Attributes will be displayed in the order they are received from the LDAP server. This is the default option but may be changed using Preferences (Options Menu).
    2. Ascend Attributes will be displayed in ascending alphabetic order for all DIT Windows.
    3. Descend Attributes will be displayed in descending alphabetic order for all DIT Windows.
  8. LDAPviewer allows the user to optionally maintain two further concurrent connections (to the same host) to that defined in the Connection Details tab. The final More DITs tab is only relevant if either of the following options is checked.
  9. Show RootDSE Checking this box will cause LDAPviewer to permanently display the servers RootDSE object which contains information about the supported DITs, various security methods supported and additional LDAP controls provided. If access to the RootDSE requires authentication then these details may be entered in the More DITs window. The default is unchecked (this may be changed using Preferences (Options Menu).
  10. Show Secondary Checking this box will permanently display an additional DIT. While primarily designed to support On-Line Configuration DITs supported by many LDAP servers, for example, OpenLDAP's cn=config service in practice because the service definition allows the user to define the Base DN of the DIT together with any required security credentials, any secondary Base DN (a virtual DIT) within the Primary DIT, the Primary DIT but with a different set of credentials, OpenLDAP's cn=monitor service or another DIT on the same LDAP server are all examples of secondary DITs that may use this feature. The default is unchecked (this may be changed using Preferences (Options Menu).

If either of the above options is checked then the More DITs tab should be selected to display the following window:

More DITs

More DITs Tab

Note: This tab is only relevant if either Show RootDSE or Show Secondary has been checked. This example window reflects Show Secondary checked, Show RootDSE unchecked, and Save in Profile unchecked. Depending on the user selected options more or less fields may be enabled.

The fields are described in detail (left to right, top to bottom).:

  1. RootDSE Security Some LDAP servers provide anonymous access to the RootDSE object, others require authentication.
    1. Access Type:. Selecting the various options, which are identical to those described for the main DIT (though the parameters are unique to the RootDSE), will generate a RootDSE connection appropriate to the LDAP server.
    2. User DN: The DN used to authenticate the user to the RootDSE.
    3. Password: The Password field will only be enabled if the user has checked the Save in Profile option. Enter the password used to authenticate the User DN: for the RootDSE. A blank password is invalid and the user will be prompted for one when the Profile is Saved. If the user has opted not to save passwords in the Profile then they will be prompted for a password immediately prior to each connection. In this case Passwords are discarded on Disconnect. Password information is a secure as the underlying Java system and LDAP interface. See also the descriptions of the various Security Type: values for more password security information.
  2. Secondary DIT Configuration This section describes the Secondary DIT connection (any defined DIT must be present at the Host: defined in Connection Details).
    1. Secondary DN: Enter the base DN to access the Secondary DIT, such as cn=config, cn=monitor or ou=people,dc=example,dc=net.
    2. Access Type: Selecting and entering the various options and fields, which are identical to those described for the main DIT (though the parameters are unique to the Secondary DIT), will generate unique Secondary DIT connection to the LDAP server.
    3. User DN: The DN used to authenticate the user to the Secondary DIT.
    4. Password: The Password field will only be enabled if the user has checked the Save in Profile option. Enter the password used to authenticate the User DN: for the Secondary DIT. A blank password is invalid and the user will be prompted for one when the Profile is Saved. If the user has opted not to save passwords in the Profile then they will be prompted for a password immediately prior to each connection. In this case Passwords are discarded on Disconnect or on making another connection. Password information is as secure as the underlying Java system and LDAP interface. See also the descriptions of the various Security Type: values for more password security information.

Save Button

When the Save button is clicked the Connection Profile is saved in the users application directory. (For the location of Profiles.) The files are in host OS text format.

Cancel Button

Clicking the Cancel button will dismiss the current window with no action taken.

Edit Button

Clicking the Edit button will open the selected Connection Profile at the Connect Details tab to allow editing of the various connection details. However, as part of the editing sequence the user may select the Profile Name tab and change the Connection Profile name. When the Save button is clicked the old profile is deleted and the Connection Profile is saved under the new name. If the new name clashes with an existing Connection Profile name then, when the Save button is clicked, the user will be prompted to create a unique name for this profile.

Copy Button

When the Copy button is clicked the currently selected Connection Profile is copied (the existing Connection Profile is unchanged) and a new Connection Profile created using the name of the selected Connection Profile with -copy appended. Thus, if a Connection Profile with the name my-connection was selected then after the copy operation a new profile with the name my-connection-copy will be created and saved.

Delete Button

When the Delete button is clicked the currently selected Connection Profile will be deleted. The user will be prompted to confirm this operation and may choose to delete the profile or to cancel the operation.

Rename Button

When the Rename button is clicked the Connection Profile will be opened at the Profile Name tab. As well as changing the name of the Connection Profile any other edits may be make at the same time using any of the other tabs. On clicking the Save button the profile will be saved under the new Connection Profile name (any name clash will cause a user propmpt) and the old Connection Profile will be deleted.

Connect Button

When the Connect button is clicked an LDAP/DSML connection will be initiated depending on the context. If the Quick Connect tab has been selected then these connection details will be used (the Connect window will disappear). If the Profiles tab has been selected then the currently selected Connection Profile will be used to initiate the connection (the Connect window will disappear). If no profile has been selected the Connect operation will be silently ignored and the Connect window will remain open.

© LV Project 2016. Creative Commons Attribution 4.0 International License.