LDAP Configuration Properties

Use these properties in your csi_config.xml file to control the Sybase Control Center LDAP service.

Note: These characters have special meaning when they appear in a name in LDAP: , (comma), = (equals), + (plus), < (less than), > (greater than), # (number or hash sign), ; (semicolon), \ (backslash), / (forward slash), LF (line feed), CR (carriage return), " (double quotation mark), ' (single quotation mark), * (asterisk), ? (question mark), & (ampersand), and a space at the beginning or end of a string. LDAP providers do not handle these special characters in any of the names or DNs in any of the configuration properties. Additionally, some of the properties, as identified below, cannot use these special characters in common names.
Property Default Value Description
ServerType None
Optional. The type of LDAP server you are connecting to:
  • sunone5 -- SunOne 5.x OR iPlanet 5.x
  • msad2k -- Microsoft Active Directory, Windows 2000
  • nsds4 -- Netscape Directory Server 4.x
  • openldap -- OpenLDAP Directory Server 2.x
The value you choose establishes default values for these other authentication properties:
  • RoleFilter
  • UserRoleMembership
  • RoleMemberAttributes
  • AuthenticationFilter
  • DigestMD5Authentication
  • UseUserAccountControl
ProviderURL ldap://localhost:389 The URL used to connect to the LDAP server. Use the default value if the server is:
  • Located on the same machine as your product that is enabled with the common security infrastructure.
  • Configured to use the default port (389).

Otherwise, use this syntax for setting the value:

ldap://<hostname>:<port>

DefaultSearchBase None The LDAP search base that is used if no other search base is specified for authentication, roles, attribution, and self registration:
  1. dc=<domainname>,dc=<tld>

    For example, a machine in the sybase.com domain would have a search base of dc=sybase,dc=com.

  2. o=<company name>,c=<country code>

    For example, this might be o=Sybase,c=us for a machine within the Sybase organization.

Note: When you use this property to authenticate SCC:
  • Do not use special characters, as listed above, in common names or distinguished names in the value of this property.
  • Do not use Chinese or Japanese characters in user names or passwords of this property.
SecurityProtocol None The protocol to be used when connecting to the LDAP server.

To use an encrypted protocol, use ssl instead of ldaps in the URL.

AuthenticationMethod Simple The authentication method to use for all authentication requests into LDAP. Legal values are generally the same as those of the java.naming.security.authentication JNDI property. Choose one of:
  • simple — For clear-text password authentication.
  • DIGEST-MD5 — For more secure hashed password authentication. This method requires that the server use plain text password storage and only works with JRE 1.4 or later.
AuthenticationFilter For most LDAP servers: (&amp;(uid={uid})(objectclass=person))

or

For Active Directory e-mail lookups: (&amp;(userPrincipalName={uid}) (objectclass=user)) [ActiveDirectory]

For Active Directory Windows user name lookups: (&amp;(sAMAccountName={uid})(objectclass=user))

The filter to use when looking up the user.

When performing a user name based lookup, this filter is used to determine the LDAP entry that matches the supplied user name.

The string "{uid}" in the filter is replaced with the supplied user name.

Note: When you use this property to authenticate SCC:
  • Do not use special characters, as listed above, in common names or distinguished names in the value of this property.
  • Do not use Chinese or Japanese characters in user names or passwords of this property.
AuthenticationScope onelevel The authentication search scope. The supported values for this are:
  • onelevel
  • subtree

If you do not specify a value or if you specify an invalid value, the default value is used.

AuthenticationSearchBase None The search base used to authenticate users. If this property is not configured, the value for DefaultSearchBase is used.
Note: When you use this property to authenticate SCC:
  • Do not use special characters, as listed above, in common names or distinguished names in the value of this property.
  • Do not use Chinese or Japanese characters in user names or passwords of this property.
BindDN None

The user DN to bind against when building the initial LDAP connection.

In many cases, this user may need read permissions on all user records. If you do not set a value, anonymous binding is used. Anonymous binding works on most servers without additional configuration.

However, the LDAP attributer may use this DN to create users in the LDAP server. When the self-registration feature is used, this user may need permissions to create a user record. This behavior may occur if you do not set useUserCredentialsToBind to true. In this case, the LDAP attributer uses this DN to update the user attributes.

BindPassword None

The password for BindDN, which is used to authenticate any user. BindDN and BindPassword separate the LDAP connection into units.

The AuthenticationMethod property determines the bind method used for this initial connection.

Sybase recommends that you encrypt passwords, and provides a password encryption utility. If you encrypt BindPassword, include encrypted=true in the line that sets the option. For example: 
<options name="BindPassword" encrypted="true" value="1snjikfwregfqr43hu5io..."/>
If you do not encrypt BindPassword, the option might look like this: 
<options name="BindPassword" value="s3cr3T"/>
RoleSearchBase None

The search base used to retrieve lists of roles. If this property is not configured, LDAP uses the value for DefaultSearchBase.

Note: When you use this property to authenticate SCC:
  • Do not use special characters, as listed above, in common names or distinguished names in the value of this property.
  • Do not use Chinese or Japanese characters in user names or passwords of this property.
RoleFilter For SunONE/iPlanet: (&amp;(objectclass=ldapsubentry) (objectclass=nsroledefinition))

For Netscape Directory Server: (|(objectclass=groupofnames) (objectclass=groupofuniquenames))

For ActiveDirectory: (|(objectclass=groupofnames) (objectclass=group))

The role search filter. This filter should, when combined with the role search base and role scope, return a complete list of roles within the LDAP server. There are several default values, depending on the chosen server type. If the server type is not chosen and this property is not initialized, no roles are available.
Note: When you use this property to authenticate SCC:
  • Do not use special characters, as listed above, in common names or distinguished names in the value of this property.
  • Do not use Chinese or Japanese characters in user names or passwords of this property.
RoleMemberAttributes For Netscape Directory Server and OpenLDAP Server: member,uniquemember A comma-separated list of role attributes from which LDAP derives the DNs of users who have this role.

These values are cross-referenced with the active user to determine the user's role list. One example of the use of this property is when using LDAP groups as placeholders for roles. This property has a default value only when the Netscape server type is chosen.
RoleNameAttribute cn The attribute of the role entry used as the role name. This is the role name displayed in the role list or granted to the authenticated user.
RoleScope onelevel The role search scope. Supported values include:
  • onelevel
  • subtree

If you do not specify a value or if you specify an invalid value, LDAP uses the default value.

SkipRoleLookup false Set this property to true to grant the roles looked up using the attributes specified by the property UserRoleMembershipAttributes without cross-referencing them with the roles looked up using the RoleSearchBase and RoleFilter.

LDAP configuration validation succeeds even when an error is encountered when listing all the available roles. The error is logged to the server log during validation but not reported in SCC, allowing the configuration to be saved. This has an impact when listing the physical roles for role mapping as well as in SCC. To successfully authenticate the user, set the SkipRoleLookup property to true.
UserRoleMembershipAttributes For iPlanet/SunONE: nsRoleDN

For Active Directory: memberOf

For all others: none

 Defines a user attribute that contains the DNs of all of the roles a user is a member of.

These comma-delimited values are cross-referenced with the roles retrieved in the role search base and search filter to generate a list of user's roles.

If the SkipRoleSearch property is set to true, these comma-delimited values are not cross-referenced with the roles retrieved in the role search base and role search filter. See SkipRoleLookup.

Note: If you use nested groups with Active Directory, you must set this property to tokenGroups.
UserFreeformRoleMembershipAttributes None The free-form role membership attribute list. Users who have attributes in this comma-delimited list are automatically granted access to roles whose names are equal to the attribute value. For example, if the value of this property is department and the department attribute in the user's LDAP record has the values {sales, consulting}, the user is granted the roles sales and consulting.
Referral ignore The behavior when a referral is encountered. Valid values are dictated by LdapContext, but might include follow, ignore, or throw.
DigestMD5AuthenticationFormat DN

For OpenLDAP: User name

 The DIGEST-MD5 bind authentication identity format.
UseUserAccountControlAttribute

For Active Directory: true

 When this property is set to true, the UserAccountControl attribute detects disabled user accounts, account expirations, password expirations, and so on. Active Directory also uses this attribute to store the above information.
EnableLDAPConnectionTrace False Enables LDAP connection tracing. The output is logged to a file in the temp directory. The location of the file is logged to the server log.
ConnectTimeout 0 Specifies the timeout, in milliseconds, for attempts to connect to the LDAP server. The property value sets the JNDI com.sun.jndi.ldap.connect.timeout property when attempting to establish a connection to a configured LDAP server. If the LDAP provider cannot establish a connection within the configured interval, it aborts the connection attempt. An integer value less than or equal to zero results in the use of the network protocol's timeout value.
ReadTimeout 0 Controls the length of time, in milliseconds, the client waits for the server to respond to a read attempt after the initial connection to the server has been established. The property values sets the JNDI com.sun.jndi.ldap.read.timeout property when attempting to establish a connection to a configured LDAP server. If the LDAP provider does not receive an LDAP response within the configured interval, it aborts the read attempt. The read timeout applies to the LDAP response from the server after the initial connection is established with the server. An integer value less than or equal to zero indicates no read timeout is specified.
LDAPPoolMaxActive 8 Caps the number of concurrent LDAP connections to the LDAP server. A non-positive value indicates no limit. If this option is set for multiple LDAP providers, the value set by the first LDAP provider loaded takes precedence over all the others. When LDAPPoolMaxActive is reached, any further attempts by the LDAP provider classes to borrow LDAP connections from the pool are blocked indefinitely until a new or idle object becomes available in the pool. Connection pooling improves the LDAP provider's performance and resource utilization by managing the number of TCP connections established with configured LDAP servers.
controlFlag optional When you configure multiple authentication providers, use controlFlag for each provider to control how the authentication providers are used in the login sequence.

controlFlag is a generic login module option rather than an LDAP configuration property.

Parent topic: Configuring an LDAP Authentication Module