# This file provides information about changes that can be made to configure # an UnboundID Identity Data Store instance so that it will exhibit a behavior # that is more like that provided by an instance of the Sun/Oracle Directory # Server Enterprise Edition (hereafter referred to as DSEE). # # The default configuration for the UnboundID Identity Data Store varies in # several ways from the default configuration for DSEE, primarily for the # purpose of providing a better out-of-the-box configuration or better # standards compliance. Further, DSEE administrators are likely to make a # number of changes to their installations, and may wish to apply similar # changes when migrating to the UnboundID Identity Data Store. # # If you wish to apply any of these configuration changes, then create a copy # of this file and remove or comment out the next four uncommented lines rather # than directly editing the version of the file provided with the server. # Also, uncomment any of the changes below that you wish to have applied to the # server and apply them using a command line like the following: # # bin/dsconfig --no-prompt --bindDN "cn=Directory Manager" \ # --bindPassword "password" --batch-file /path/to/dsconfig/file ***** Create a copy of this file and remove or comment out these four lines if ***** you wish to apply any of the configuration changes described below. It ***** will also be necessary to uncomment the dsconfig examples for the changes ***** that you wish to apply. # Configuration elements addressed in this file include: # * Access Control Modifications # * Access Log Message Format # * Access to the Server Configuration # * Administrative Password Reset # * Database Cache Configuration # * Entry Cache Configuration # * Error Condition Result Codes # * Invalid Attribute Syntax Behavior # * Maximum Blocked Write Time Limit # * Maximum Concurrent Operations Per Connection # * Multiple Different Password Values # * Nested Group Support # * Number of Worker Threads # * Pre-Encoded Passwords # * Proxied Authorization # * Rejecting Non-ASCII Attribute Values # * Returning All Root DSE Attributes # * Returning All Schema Subentry Attributes # * Returning Bind Failure Messages # * Schema Modifications # * Search Size Limit # * Search Time Limit # * Single Structural Object Class Behavior # * Unindexed Searches # * Zero-Length Directory String Attribute Values # Access Control Modifications # # Overview: # ---------- # The access control mechanism supported by the UnboundID Identity Data Store is # similar to that used by DSEE, although the UnboundID implementation has a # number of features and security restrictions that DSEE does not have. For # example, in DSEE, specifying a targetattr of "*" includes not only all user # attributes, but also all operational attributes, which makes it easy to # inadvertently grant users access to things that they should not have. # # Another safety feature of the UnboundID Identity Data Store is that users are # not allowed to alter the set of access control rules unless they have the # modify-acl privilege. Root users may receive this privilege by default, but # non-root users must be explicitly granted this privilege to be allowed to # add, remove, and edit access control rules, even if they have been granted # permission to write to the aci attribute. In most environments, it is # sufficient to grant the modify-acl privilege to any non-root users that # should be allowed to manage the set of defined access control rules. # However, if this is not acceptable for some reason, then the modify-acl # privilege can be disabled so that it is not required and any user with # permission to write to the aci attribute will be allowed to alter the access # control configuration. # # # Applicable DSEE Configuration Options: # ---------- # N/A # # # Applicable UnboundID Identity Data Store Configuration Options: # ---------- # * disabled-privilege property (default value: undefined, so that all # supported privileges will be enforced). # # # Related Configuration Elements: # ---------- # The following sections also involve the use of privileges: # * Access to the Server Configuration # * Administrative Password Reset # * Proxied Authorization # * Schema Modifications # * Unindexed Searches # # # dsconfig Examples: # ---------- # * Disable the modify-acl privilege so that any user with write permission for # the aci attribute will be allowed to create, delete, and modify access # control rules: # dsconfig set-global-configuration-prop --set disabled-privilege:modify-acl # Access Log Message Format # # Overview: # ---------- # The DSEE access log format is relatively rigid and provides few options for # configuring the format. By default, it provides two messages for each # operation (one with information about the request, and one with information # about the result), and log message timestamps have only second-level # precision. # # In the UnboundID Identity Data Store, there are many more options for # configuring the way that access log messages are written. By default, it # logs a single message per operation with information about both the request # and result, which provides a more compact representation that is easier to # examine with string processing tools like grep, and it also uses timestamps # with millisecond precision. It is also important to note that the UnboundID # Identity Data Store can be configured with any number of access loggers, and # provides very flexible filtering support, so that it is possible to customize # the kinds of messages that should appear in each access log. # # Although the UnboundID Identity Data Store does not support writing an access # log file in a format that is identical to that used by DSEE, it can be # configured to provide similar behavior. However, the server does come with a # summarize-access-log tool that can be used to extract a significant amount of # useful information from UnboundID access log files, and the Commercial # Edition of the LDAP SDK for Java provides a rich API that can be used to # extract information from access log files. # # # Applicable DSEE Configuration Options: # ---------- # * nsslapd-accesslog-level attribute (default value: 256, which logs request # and response messages with processing time precision in seconds). # # # Applicable UnboundID Identity Data Store Configuration Options: # ---------- # * log-requests property (default value: false, which indicates that # log messages containing only information about requests should not be # logged). # # * include-request-details-in-result-messages property (default value: true, # which indicates that log messages for responses should also contain # information about the associated request). # # * timestamp-precision property (default value: milliseconds, which means # that timestamps for access log messages should be reported with # millisecond-precision rather than second-precision). # # # dsconfig Examples: # ---------- # * Change the logger behavior so that request and result messages are logged # separately rather than combining them into a single message: # dsconfig set-log-publisher-prop --publisher-name "File-Based Access Logger" --set log-requests:true --set include-request-details-in-result-messages:false # # * Change the logger behavior so that messages are logged with timestamp # precision of seconds rather than milliseconds: # dsconfig set-log-publisher-prop --publisher-name "File-Based Access Logger" --set timestamp-precision:seconds # Access to the Server Configuration # # Overview: # ---------- # In DSEE, access to the server configuration is based entirely on access # control, so that if a user has permission to read entries below cn=config, # then that user can see server configuration entries, and any user with the # ability to write to entries below cn=config may be allowed to modify the # server schema. In the UnboundID Identity Data Store, the same access control # requirements are in place to allow clients to interact with the server # configuration, but it is also necessary for clients to have the config-read # privilege to be able to have read access to the configuration, and the # config-write privilege to be able to modify the configuration. Without these # privileges, clients will not be allowed to access the server configuration # even if the server's access control configuration allows them to read and/or # write entries below "cn=config". # # This is a safety mechanism to ensure that poorly-crafted access control rules # do not unintentionally give a user the ability to interact with the server # configuration. By default, root users will automatically inherit both the # config-read and config-write privileges. If a non-root user should be # allowed to read the configuration, then that user should be given the # config-read privilege. Similarly, if a non-root user should be allowed to # alter the server configuration, then that user should also be given the # config-write privilege. However, if it is not acceptable for these # privileges to be granted to such users, then they can be disabled so that # access control will be the only mechanism for determining whether such users # will be allowed to interact with the server configuration. # # # Applicable DSEE Configuration Options: # ---------- # N/A # # # Applicable UnboundID Identity Data Store Configuration Options: # ---------- # * disabled-privilege property (default value: undefined, so that all # supported privileges will be enforced). # # # Related Configuration Elements: # ---------- # The following sections also involve the use of privileges: # * Access Control Modifications # * Access to the Server Configuration # * Administrative Password Reset # * Proxied Authorization # * Schema Modifications # * Unindexed Searches # # # dsconfig Examples: # ---------- # * Disable the config-read and config-write privileges so that any user with # the ability to access entries below cn=config will be allowed to interact # with the configuration # dsconfig set-global-configuration-prop --set disabled-privilege:config-read --set disabled-privilege:config-write # Additional Supported Control Values # # Overview: # ---------- # The supportedControl attribute of the root DSE is intended to contain a list # of the OIDs of controls that clients are allowed to include in requests. # According to RFC 4512, this attribute should only include request controls, # but DSEE also includes a few response control OIDs in this list, including # the Netscape password expired (2.16.840.1.113730.3.4.4), password expiring # (2.16.840.1.113730.3.4.5), and authorization identity # (2.16.840.1.113730.3.4.15) response controls. Some poorly-written # applications may expect one or more of these controls in the server's root # DSE and may fail to behave properly if they are not included. For example, # at least some versions of Solaris Native LDAP will not look for the password # expired or expiring controls in bind responses unless the OIDs of those # controls are included in the supportedControl attribute of the root DSE. # # # Applicable DSEE Configuration Options: # ---------- # N/A # # # Applicable UnboundID Identity Data Store Configuration Options: # ---------- # * additional-supported-control-oid (default value: undefined, so that only # OIDs of request controls will be listed in the root DSE). # # # dsconfig Examples: # ---------- # * Include the OIDs for the Netscape password expired and password expiring # controls in the values for the supportedControl attribute of the server's # root DSE # dsconfig set-root-dse-backend-prop --add additional-supported-control-oid:2.16.840.1.113730.3.4.4 --add additional-supported-control-oid:2.16.840.1.113730.3.4.5 # Administrative Password Reset # # Overview: # ---------- # Any user who has the ability to change the password for another user # effectively has the ability to assume the identify of that user. As such, # the ability for one user to change the password of another should be a # capability that is only carefully granted. In DSEE, any user with the # ability to write to userPassword for another user can change that user's # password. In the UnboundID Identity Data Store, it is necessary to be able to # write to the userPassword attribute for this purpose, but the server also # will require that a user have the password-reset privilege to be allowed to # change the password for another user. # # By default, root users will automatically inherit this privilege. If a # non-root user should have the ability to reset passwords for other users, # then that user should be granted the password-reset privilege. However, if # it is not feasible to assign this privilege to such users, then it is # possible to disable the password-reset privilege so that any user with the # ability to write to the userPassword attribute for another user will be # allowed to change the password for that user. # # # Applicable DSEE Configuration Options: # ---------- # N/A # # # Applicable UnboundID Identity Data Store Configuration Options: # ---------- # * disabled-privilege property (default value: undefined, so that all # supported privileges will be enforced). # # # Related Configuration Elements: # ---------- # The following sections also involve the use of privileges: # * Access Control Modifications # * Access to the Server Configuration # * Proxied Authorization # * Schema Modifications # * Unindexed Searches # # The following sections also involve configuration elements related to # password policy: # * Multiple Different Password Values # * Pre-Encoded Passwords # # # dsconfig Examples: # ---------- # * Disable the password-reset privilege so that any user with write permission # for the userPassword attribute will be allowed to reset user passwords: # dsconfig set-global-configuration-prop --set disabled-privilege:password-reset # Database Cache Configuration # # Overview: # ---------- # In order to obtain optimal performance in either DSEE or the UnboundID # Identity Data Store, it is important to configure the server to make the most # effective use of system memory. In both servers, this includes a combination # of database caching, entry caching, and filesystem caching. However, the # best way to configure the way that memory is allocated may vary significantly # between DSEE and The UnboundID Identity Data Store. The best way to configure # the UnboundID Identity Data Store for various types of deployments is beyond the # scope of this document, but in deployments in which the Identity Data Store will # be the primary application on the system, there will be a single data # backend, and all of the data will fit in the amount of memory available, then # it is recommended to use the cache settings automatically configured during # setup when choosing to optimize the memory used by the server. # # Both DSEE and the UnboundID Identity Data Store provide database caches. # While DSEE only provides a single database cache that will be shared across # all backends, the UnboundID Identity Data Store provides the ability to # configure caching differently in each backend. Another significant # difference between the two servers in this area is that the DSEE database # cache must always be specified in terms of the absolute amount of memory to # consume. While it is possible to configure the absolute amount of memory to # use for the database cache in the UnboundID Identity Data Store, it is # generally recommended that the cache be configured as a percentage of the # total memory available to the JVM. # # # Applicable DSEE Configuration Options: # ---------- # * nsslapd-dbcachesize (default value: 10MB). # # # Applicable UnboundID Identity Data Store Configuration Options: # ---------- # * db-cache-percent (default value: variable, based on the total amount of # memory available on the system and the amount allocated to the JVM). # # * db-cache-size (default value: 0 bytes, which indicates that the value of # the db-cache-percent property should be used to determine the size of the # database cache). # # # Related Configuration Elements: # ---------- # The following sections also involve the caching within the server: # * Entry Cache Configuration # * Nested Group Support # # # dsconfig Examples: # ---------- # * Configure the server to use 50% of the memory allocated to the JVM for the # database cache for the userRoot backend: # dsconfig set-backend-prop --backend-name userRoot --set db-cache-percent:50 # Entry Cache Configuration # # Overview: # ---------- # DSEE requires that at least some memory be allocated for an entry cache for # each backend defined in the server, and it is necessary to use at least a # reasonable amount of memory for entry caching in order to achieve optimal # performance. # # The UnboundID Identity Data Store does not require an entry cache, and in most # deployments it is recommended that the server be run without any kind of # entry cache. An entry cache should only be considered for use in a limited # set of scenarios (e.g., if the server contains very large entries that may # need to be frequently accessed), and in those cases that cache should be # configured so that it only holds those kinds of entries. The UnboundID # Identity Data Store provides the ability to define include and/or exclude # filters for controlling which entries are held in the cache, and these should # be used in the event that such a cache is believed necessary. It is also # strongly recommended that you contact technical support before enabling an # entry cache to determine whether the use of an entry cache may be # appropriate. # # # Applicable DSEE Configuration Options: # ---------- # * nsslapd-cachesize (default value: -1, which indicates there is no # absolute maximum on the number of entries the cache can hold). # # * nsslapd-cachememsize (default value: 10MB). # # # Applicable UnboundID Identity Data Store Configuration Options: # ---------- # * max-memory-percent (default value: 90, which indicates that if the JVM # memory reaches 90 percent full, then entries may begin to be evicted from # the entry cache). # # * max-entries (default value: 10000). # # * include-filter (default value: undefined). # # * exclude-filter (default value: undefined). # # # Related Configuration Elements: # ---------- # The following sections also involve the caching within the server: # * Database Cache Configuration # * Nested Group Support # # # dsconfig Examples: # ---------- # * Enable the entry cache in the UnboundID Identity Data Store that may be used # for caching only static group entries that contain 100 members or more: # dsconfig set-entry-cache-prop --cache-name "Static Group Entry Cache" -set enabled:true # Error Condition Result Codes # # Overview: # ---------- # In some cases, LDAP specifications are ambiguous or unclear about the # specific result code that may be returned in a particular error condition, # and as such the result codes used by DSEE and the UnboundID Identity Data Store # for a given condition may be different. Further, there are cases in which # LDAP specifications do indicate which result code should be used in a given # condition, but DSEE nevertheless uses a different, non-standard result code. # # In general, clients should not be written to expect specific result codes in # any particular error condition, even if LDAP specifications explicitly # dictate the appropriate result for that condition, in order to maintain # compatibility with the broadest range of servers. However, there are # applications in existence which do expect particular result codes in some # situations. Some cases in which DSEE and the UnboundID Identity Data Store use # different result codes for the same conditions in a manner that may impact # the behavior of such clients include: # # * A general "server error" condition. DSEE uses a result code value of "1" # (operations error) for this purpose, which is only intended for use in # cases in which a client has requested an inappropriate type of operation in # a sequence which requires multiple operations). The UnboundID Directory # Server uses the standards-based result code of 80 (other) for this purpose. # # * The case in which a client attempts to bind as a user that does not exist # in the data set. DSEE uses a result code value of "32" (no such object) in # this case, which both violates the behavior defined in LDAP specifications # and has the potential to leak information to malicious clients in a manner # that could allow them to distinguish between valid and invalid entries. # The UnboundID Identity Data Store uses the standards-based result code of 49 # (invalid credentials) for this purpose. # # * The case in which a client attempts to bind as a user whose account has # been locked as a result of too many earlier failed attempts. Although # there is no official standard which explicitly defines the result code that # should be used in this situation, the un-ratified Internet Draft # draft-behera-ldap-password-policy indicates that a result code of 49 # (invalid credentials) should be used in such conditions, and that is the # result that the UnboundID Identity Data Store uses for this purpose. DSEE # instead uses a result code of 19 (constraint violation) in this situation. # # In order to try to support clients which are hard-coded to expect certain # result codes in these conditions, the UnboundID Identity Data Store provides a # result code map configuration object type that can be used to override the # behavior that the server would otherwise use in these conditions. A result # code map can be configured for use server-wide, or may be associated with a # given client connection policy so that it will be used only for clients # associated with that policy (which provides the ability to support different # sets of clients with different expectations). # # # Applicable DSEE Configuration Options: # ---------- # N/A # # # Applicable UnboundID Identity Data Store Configuration Options: # ---------- # * result-code-map (default value: undefined, which means that the default # standards-based behavior will be used for the available result codes). # # * bind-account-locked-result-code (default value: 49). # # * bind-missing-user-result-code (default value: 49). # # * server-error-result-code (default value: 80). # # # dsconfig Examples: # ---------- # * Configure the UnboundID Identity Data Store to use a predefined result code # map that is consistent with the behavior exhibited by DSEE: # dsconfig set-global-configuration-prop --set "result-code-map:Sun DS Compatible Behavior" # Invalid Attribute Syntax Behavior # # Overview: # ---------- # Each attribute type defined in a directory server schema is associated, # either explicitly or implicitly, with an attribute syntax. Attribute # syntaxes place constraints on the kinds of data that may be stored in # attributes, and standards-compliant directory servers must reject any attempt # to store a value for an attribute which violates the syntax associated with # that attribute. The UnboundID Identity Data Store observes this requirement, # but DSEE servers do not. Some versions of DSEE do not provide any capability # for observing such requirements, while more recent versions do provide this # capability but have that setting disabled in the default configuration. # # Because DSEE does not enforce attribute syntax restrictions, data migrated # from DSEE servers may contain attribute values which violate the associated # attribute syntax, and as such would be rejected by the UnboundID Directory # Server. It is strongly recommended that all such violations be identified # and corrected in the process of migrating the data to the UnboundID Directory # Server. When running the import-ldif tool with a reject file, any entries # which in some way violate schema constraints will be written to that file so # that the problems may be corrected. # # If for some reason it is not possible to correct the data, or if there are # applications which depend on the ability to store data which violates the # associated attribute syntax, then the server may be configured to overlook # such violations. The invalid-attribute-syntax-behavior configuration # property normally has a value of "reject", which will cause it to reject any # attempt to use an attribute value which violates the associated syntax. If # the value is changed to "allow" then any such violations will be silently # overlooked. If the value is changed to "warn", then values which violate # the associated syntax will be allowed, but log messages may be generated to # warn of the violation. # # Note that if the server is configured to permit the use of attribute values # which violate the associated syntax, attempts to interact with such malformed # data may not behave as expected. This may be true particularly for cases in # which the server attempts to process an attribute value assertion (e.g., a # filter in a search operation, or the assertion value in a compare operation) # with an invalid value. # # # Applicable DSEE Configuration Options: # ---------- # N/A # # # Applicable UnboundID Identity Data Store Configuration Options: # ---------- # * invalid-attribute-syntax-behavior (default value: reject, which will cause # the server to reject any attempt to assign an attribute value that violates # the constraints of the associated attribute syntax). # # # Related Configuration Elements: # ---------- # The following sections also involve schema compliance: # * Returning All Root DSE Attributes # * Returning All Schema Subentry Attributes # * Single Structural Object Class Behavior # * Zero-Length Directory String Attribute Values # # # dsconfig Examples: # ---------- # * Configure the server to make it possible to use attribute values which # violate the associated attribute syntax, but generate a warning for every # every entry encountered with an attribute having an invalid syntax: # dsconfig set-global-configuration-prop --set invalid-attribute-syntax-behavior:warn # Maximum Blocked Write Time Limit # # Overview: # ---------- # Because of the nature of TCP, it is possible for communication between an # LDAP client and a directory server to become interrupted in a manner that the # server cannot easily detect for some period of time. The same behavior may # also occur if a client application or system becomes hung, the client system # crashes, or if the client simply stops reading data from the server. If any # of these conditions occur when the server is not actively processing any # requests for the associated client, then this may not have any adverse # effects, other than the temporary loss of a file descriptor available to the # server. However, if the server is actively processing an operation for that # client, particularly if that operation is a search that may return a large # number of entries, then the server may tie up a worker thread while trying to # send data to a client that is not consuming it. # # Both DSEE and the UnboundID Identity Data Store attempt to detect and address # this kind of problem by enforcing a maximum limit on the time that a thread # should be allowed to block while attempting to send data to the client. In # the event that a write attempt blocks for longer than this period of time, # then the associated client connection will be terminated. For DSEE, the # timeout for this condition has a default of 30 minutes, which may be # excessive. In the UnboundID Identity Data Store, the default timeout is 2 # minutes, which should be sufficiently long to avoid false positives while # short enough to quickly detect connections for clients which are no longer # available but still have active operations. # # # Applicable DSEE Configuration Options: # ---------- # * nsslapd-ioblocktimeout (default value: 1800000 milliseconds, or 30 # minutes). # # # Applicable UnboundID Identity Data Store Configuration Options: # ---------- # * max-blocked-write-time-limit (default value: 2 minutes) # # # dsconfig Examples: # ---------- # * Configure the server to use a maximum blocked write time limit of 5 minutes # for the LDAP connection handler: # dsconfig set-connection-handler-prop --handler-name "LDAP Connection Handler" --set "max-blocked-write-time-limit:5 m" # Maximum Concurrent Operations Per Connection # # Overview: # ---------- # Both DSEE and the UnboundID Identity Data Store support asynchronous operations # so that a single client may have multiple active operations at the same time. # It may be desirable to limit the number of concurrent operations for any # single client so that no client will be allowed to monopolize server # resources. # # By default, DSEE imposes a limit of five active operations per client unless # there are no other outstanding requests. Although the UnboundID Directory # Server supports limiting the number of concurrent operations for individual # client connections (as well as groups of related clients), it does not impose # any such limit in the default configuration. In environments in which there # is a significant concern about a single client connection processing many # operations concurrently at the possible expense of other clients, then it # may be desirable to impose such a limit. # # # Applicable DSEE Configuration Options: # ---------- # * nsslapd-maxthreadsperconn (default value: 5) # # # Applicable UnboundID Identity Data Store Configuration Options: # ---------- # * maximum-concurrent-operations-per-connection (default value: 0, which # indicates that there is no limit on the maximum number of concurrent # operations for a single client connection). # # * maximum-concurrent-operation-wait-time-before-rejecting (default value: # 0 milliseconds, which indicates that a request will be immediately rejected # if the server is already processing the maximum number of requests for that # client). # # # dsconfig Examples: # ---------- # * Configure the server to allow no more than 5 concurrent operations on any # client connection associated with the default client connection policy: # dsconfig set-client-connection-policy-prop --policy-name default --set maximum-concurrent-operations-per-connection:5 # Multiple Different Password Values # # Overview: # ---------- # The standards-based definition for the userPassword attribute is multivalued, # which means that it is conceivable for a single user to have multiple # passwords. DSEE allows this, and if a user has multiple passwords, then any # user with more than one password will be allowed to use any of those # passwords when attempting to authenticate. # # In the UnboundID Identity Data Store, the default configuration does not allow # a user to have multiple different passwords. There are several reasons for # this. First, it is difficult for clients to change any one individual # password without losing the remaining set of passwords. Second, allowing # multiple passwords for the same account increases the risk that one of those # passwords will be compromised. Third, if multiple passwords are allowed, # then a user may be able to take advantage of that to bypass password policy # constraints (e.g., as long as one of the passwords is replaced on a regular # basis, then other passwords may be exempted from expiration). Some of the # protection that the password policy subsystem provides cannot operate # effectively if users are allowed to have multiple different password values. # # It is very rare that environments have a legitimate need to allow users to # have multiple different passwords. However, if that is necessary, then the # UnboundID Identity Data Store may be reconfigured so that it will allow multiple # different password values for any user. This can be configured in a password # policy, and it is possible to define different password policies for # different users, so that if this capability is only necessary for a subset of # users, then it may be best to configure a custom password policy for those # users that allows multiple different passwords, while policies for remaining # users prevent this. # # # Applicable DSEE Configuration Options: # ---------- # N/A # # # Applicable UnboundID Identity Data Store Configuration Options: # ---------- # * allow-multiple-password-values (default value: false, which requires that # each user have at most one password). # # # Related Configuration Elements: # ---------- # The following sections also involve configuration elements related to # password policy: # * Administrative Password Reset # * Pre-Encoded Passwords # # # dsconfig Examples: # ---------- # * Update the default password policy so that users will be allowed to have # multiple different password values: # dsconfig set-password-policy-prop --policy-name "Default Password Policy" --set allow-multiple-password-values:true # Nested Group Support # # Overview: # ---------- # LDAP specifications do not explicitly reference nested groups, but both DSEE # and the UnboundID Identity Data Store provide support for them by making it # possible for some or all of the members of a static group to be other groups # rather than individual users. However, this can require expensive processing # when attempting to determine whether a given user is a member of a particular # group, and as such nested group support is disabled by default in the # UnboundID Identity Data Store so that more efficient processing is possible. # # The UnboundID Identity Data Store can detect attempts to use nesting and will # generate administrative alerts to indicate that it may be necessary to enable # this support, but because the use of nested groups is relatively rare, # the fact that this support is disabled by default allows for more efficient # group processing. Further, it also makes it possible to provide additional # support for maintaining a cache of mappings between the users and the DNs of # the static groups in which those users are members. This cache can # dramatically improve authentication performance in servers with a large # number of static groups, as well as the performance when attempting to # generate the appropriate set of values for the isMemberOf virtual attribute. # Note that this user-to-group cache may only be used if nesting support is # disabled, so if it is necessary to enable nesting support in the UnboundID # Identity Data Store, then it will also be necessary to disable the user-to-group # mapping capability. # # # Applicable DSEE Configuration Options: # ---------- # N/A # # # Applicable UnboundID Identity Data Store Configuration Options: # ---------- # * support-nested-groups (default value: false, which allows the server to # provide significantly improved performance in directories that do not # require this capability). # # * cache-user-to-group-mappings (default value: true) # # # Related Configuration Elements: # ---------- # The following sections also involve the caching within the server: # * Database Cache Configuration # * Entry Cache Configuration # # # dsconfig Examples: # ---------- # * Configure the server to allow nested groups to include members that are # themselves other groups, which also necessitates disabling the # user-to-group cache: # dsconfig set-group-implementation-prop --implementation-name Static --set support-nested-groups:true --set cache-user-to-group-mappings:false # Number of Worker Threads # # Overview: # ---------- # Both DSEE and the UnboundID Identity Data Store use threads to make it possible # to process multiple concurrent client requests. Choosing a value that is too # small may limit the performance that the server can achieve, but making it # too large may also degrade performance by introducing too much contention # between the worker threads. # # In DSEE, the number of worker threads to use is always explicitly specified # in the configuration. In the UnboundID Identity Data Store, the number of # worker threads may be explicitly specified, but by default it will be # automatically tuned based on the number of CPUs available on the system. In # most cases, it is recommended that the server be allowed to automatically # tune the number of worker threads. However, it may be desirable to configure # a specific value in some cases (e.g., on systems with hundreds of CPUs, or on # systems running other CPU-intensive processes). # # # Applicable DSEE Configuration Options: # ---------- # * nsslapd-threadnumber attribute (default value: 30) # # # Applicable UnboundID Identity Data Store Configuration Options: # ---------- # * num-worker-threads property (default value: 0, which will cause the server # to auto-tune the number of worker threads) # # # dsconfig Examples: # ---------- # * Set the number of worker threads to 30: # dsconfig set-work-queue-prop --set num-worker-threads:30 # Pre-Encoded Passwords # # Overview: # ---------- # Both DSEE and the UnboundID Identity Data Store will automatically encode # passwords stored in the server so that their values are obscured and (in the # case of most password storage schemes) cannot be reversed. Whenever a client # attempts to change a password, that password should generally be provided in # clear-text and encoded by the server, so that the server can ensure that it # is encoded correctly, and so that it can ensure that the provided password # meets all of the acceptability requirements defined in the password policy. # If a client is allowed to change a password by supplying a value that is # already encoded, then the server cannot determine whether that password may # be too weak, or whether it may be an alternate encoding for a password that # has already been used. # # DSEE allows clients to provide pre-encoded passwords. The UnboundID # Identity Data Store does not allow this by default so that it can ensure that # all passwords are of sufficient quality, although it can be reconfigured to # allow clients to supply pre-encoded passwords if there are existing # applications that require this and cannot be changed to supply the passwords # in clear-text. # # # Applicable DSEE Configuration Options: # ---------- # N/A # # # Applicable UnboundID Identity Data Store Configuration Options: # ---------- # * allow-pre-encoded-passwords (default value: false, which will require that # attempts to set or change user passwords have the password provided in the # clear). # # # Related Configuration Elements: # ---------- # The following sections also involve configuration elements related to # password policy: # * Administrative Password Reset # * Multiple Different Password Values # # # dsconfig Examples: # ---------- # * Update the default password policy so that clients will be allowed to # provide pre-encoded passwords to the server: # dsconfig set-password-policy-prop --policy-name "Default Password Policy" --set allow-pre-encoded-passwords:true # Proxied Authorization # # Overview: # ---------- # The proxied authorization control (which is supported by both DSEE and the # UnboundID Identity Data Store) may be used to allow one user to submit a request # that should be processed under the authority of a different user. The # intermediate client control (which is supported only in the UnboundID # Identity Data Store) may also be used to achieve this result, but also provides # a number of additional options. These controls are primarily used by # applications which maintain pools of connections which are authenticated as # a common user, but which accept requests from a number of different clients # which should result in operations performed in the directory under the # authority of the end user. # # Because these controls effectively allow one user to impersonate other users # in the server, it is essential to ensure that only users which should be # allowed to utilize this control will be allowed to request it. Both DSEE and # the UnboundID Identity Data Store provide a "proxy" access control right that is # is required for users to be allowed to use the control. In the UnboundID # Identity Data Store, it is also necessary for users to have the proxied-auth # privilege in order to be allowed to use either the proxied authorization or # intermediate client controls. As such, any user that should be allowed to # use one of these controls in the UnboundID Identity Data Store should be # granted this privilege (which is not automatically inherited by root users). # However, if this is not feasible then the proxied-auth privilege can be # disabled so that it is not required. # # # Applicable DSEE Configuration Options: # ---------- # N/A # # # Applicable UnboundID Identity Data Store Configuration Options: # ---------- # * disabled-privilege property (default value: undefined, so that all # supported privileges will be enforced). # # # Related Configuration Elements: # ---------- # The following sections also involve the use of privileges: # * Access Control Modifications # * Access to the Server Configuration # * Administrative Password Reset # * Schema Modifications # * Unindexed Searches # # # dsconfig Examples: # ---------- # * Disable the proxied-auth privilege so that it is not required and any user # with the proxy access control permission may be allowed to use the proxied # authorization or intermediate client controls: # dsconfig set-global-configuration-prop --set disabled-privilege:proxied-auth # Rejecting Non-ASCII Attribute Values # # Overview: # ---------- # Some applications may not properly be able to handle the case in which some # attribute values may contain non-ASCII characters. Both DSEE and the # UnboundID Identity Data Store offer a plugin that can be used to reject any # attempt to include any non-ASCII characters in the values of a specified set # of attribute. This plugin is enabled by default in DSEE, but it is disabled # by default in the UnboundID Identity Data Store because it is just as likely # that there may be applications which have the ability and desire to support # non-ASCII values as there are applications which cannot handle such values. # If you know of cases in which there are applications which cannot handle # non-ASCII values, then it may be necessary to enable the 7-bit check plugin # in the UnboundID Identity Data Store in order to prevent non-ASCII values from # being added to the server. # # # Applicable DSEE Configuration Options: # ---------- # The 7-bit check plugin is enabled by default and is configured to reject # non-ASCII values for the following attributes: # * uid # * mail # * userPassword # # # Applicable UnboundID Identity Data Store Configuration Options: # ---------- # The 7-bit check plugin is disabled by default, but if enabled will have a # default configuration to reject non-ASCII values for the following # attributes: # * uid # * mail # * userPassword # # # dsconfig Examples: # ---------- # * Enable the 7-bit check plugin to reject non-ASCII values for the default # set of attributes (uid, mail, and userPassword): # dsconfig set-plugin-prop --plugin-name "7-Bit Clean" --set enabled:true # Returning All Root DSE Attributes # # Overview: # ---------- # Many of the standard attributes that should be included in the root DSE are # defined with an operational usage, and therefore should not be returned to # clients unless they are explicitly requested. However, DSEE does not honor # this behavior, and a request to retrieve the root DSE entry in a DSEE server # will return a number of operational attributes as if they were user # attributes. # # The UnboundID Identity Data Store correctly treats those attributes as # operational and only returns them if they are explicitly requested. However, # some clients initially developed against DSEE may be hard-coded to expect the # incorrect behavior. In the event that such clients cannot be updated to # explicitly request the attributes that they need to use, then the UnboundID # Identity Data Store can be reconfigured to provide the same behavior as DSEE in # this regard. # # # Applicable DSEE Configuration Options: # ---------- # N/A # # # Applicable UnboundID Identity Data Store Configuration Options: # ---------- # * show-all-attributes (default value: false, which indicates that # operational attributes in the root DSE should not be returned unless they # are explicitly requested, or unless all operational attributes are # requested). # # # Related Configuration Elements: # ---------- # The following sections also involve schema compliance: # * Invalid Attribute Syntax Behavior # * Returning All Schema Subentry Attributes # * Single Structural Object Class Behavior # * Zero-Length Directory String Attribute Values # # # dsconfig Examples: # ---------- # * Change the server configuration so that all root DSE attributes will be # treated as if they were user attributes and therefore returned by default: # dsconfig set-root-dse-backend-prop --set show-all-attributes:true # Returning All Schema Subentry Attributes # # Overview: # ---------- # The standard definition for many of the attribute types which may be used in # subschema subentries (including ldapSyntaxes, matchingRules, attributeTypes, # objectClasses, nameForms, dITContentRules, dITStructureRules, and # matchingRuleUse) have those attribute types defined with an operational # usage and therefore the associated attributes should not be returned to # clients unless they are explicitly requested. However, DSEE does not honor # this behavior and always returns these attributes even if they are not # explicitly requested. # # The UnboundID Identity Data Store correctly behaves in a standards-compliant # manner in which it will not return these operational attributes unless they # are explicitly requested. However, some applications may have been developed # against DSEE and expect to be able to retrieve schema attrbutes without # explicitly requesting them. In such instances, if it is not possible to # update those applications, then it may be necessary to reconfigure the # UnboundID Identity Data Store to exhibit the same behavior as DSEE and treat # these attributes as if they were user attributes rather than operational. # # # Applicable DSEE Configuration Options: # ---------- # N/A # # # Applicable UnboundID Identity Data Store Configuration Options: # ---------- # * show-all-attributes (default value: false, which indicates that # operational attributes in the schema subentry should not be returned unless # they are explicitly requested, or unless all operational attributes are # requested). # # # Related Configuration Elements: # ---------- # The following sections also involve schema compliance: # * Invalid Attribute Syntax Behavior # * Returning All Root DSE Attributes # * Single Structural Object Class Behavior # * Zero-Length Directory String Attribute Values # # # dsconfig Examples: # ---------- # * Change the server configuration so that all attributes of "cn=schema" will # be treated as if they were user attributes and therefore returned by # default: # dsconfig set-backend-prop --backend-name schema --set show-all-attributes:true # Returning Bind Failure Messages # # Overview: # ---------- # In order to ensure that the server provides adequate protection against # unauthorized clients, it is useful to prevent the server from returning # information in error responses (and particularly error responses for bind # requests) that could aid an attacker in creating more directed attacks, or # that could leak information about information contained in the server. # # One of the ways that the UnboundID Identity Data Store attempts to provide this # protection is by omitting diagnostic messages from bind response messages in # which the authentication attempt was not successful. For most types of # operations, the Identity Data Store will attempt to return a useful error # message that can help the client better understand the nature of the problem # and how it should be addressed. However, because providing such a response # to a bind operation could aid a potential attacker, the server does not # return any diagnostic message by default, but may include an # authFailureReason element in the access log with information that can help # administrators better understand the problem. # # If an administrator determines that the benefit of useful diagnostic # messages to legitimate clients outweighs the risk of leaking data to # potential attackers, then this behavior can be changed so that bind failure # responses may include diagnostic messages with more information about the # problem. # # # Applicable DSEE Configuration Options: # ---------- # N/A # # # Applicable UnboundID Identity Data Store Configuration Options: # ---------- # * return-bind-error-messages (default value: false, which will prevent # the server from returning diagnostic messages in most responses for failed # bind operations). # # # dsconfig Examples: # ---------- # * Configure the server to allow useful diagnostic messages to be included in # responses to failed bind operations: # dsconfig set-global-configuration-prop --set return-bind-error-messages:true # Schema Modification # # Overview: # ---------- # Both DSEE and the UnboundID Identity Data Store allow clients to alter the # server schema by modifying the "cn=schema" entry to add, remove, and replace # attribute types, object classes, and other types of schema elements. In # DSEE, it is only necessary to have access control permission to modify the # cn=schema entry in order to make such changes. However, because changing the # server schema can adversely impact applications and existing data, then the # UnboundID Identity Data Store also requires that users have the update-schema # privilege to be allowed to make changes to the set of defined schema # elements. This control is automatically inherited by root users by default, # but it must be explicitly granted to non-root users that should be allowed to # make schema changes. If this is not feasible for some reason, then the # update-privilege may be disabled so that it is not required and access # control will be the only mechanism used to determine whether a user should be # allowed to modify the server schema. # # # Applicable DSEE Configuration Options: # ---------- # N/A # # # Applicable UnboundID Identity Data Store Configuration Options: # ---------- # * disabled-privilege property (default value: undefined, so that all # supported privileges will be enforced). # # # Related Configuration Elements: # ---------- # The following sections also involve the use of privileges: # * Access Control Modifications # * Access to the Server Configuration # * Administrative Password Reset # * Proxied Authorization # * Unindexed Searches # # # dsconfig Examples: # ---------- # * Disable the update-schema privilege so that it is not required and any user # with access control permission to modify cn=schema will be allowed to alter # the server schema: # dsconfig set-global-configuration-prop --set disabled-privilege:update-schema # Search Size Limit # # Overview: # ---------- # Both DSEE and the UnboundID Identity Data Store provide a global configuration # option that can be used to place a limit on the maximum number of entries # that can be returned for a single search, and both servers also make it # possible to override that limit on a per-user basis in the event that some # users (e.g., administrators) may have a legitimate need to retrieve a larger # number of entries for an operation. In addition the UnboundID Directory # Server also makes it possible to enforce additional search size limit # restrictions based on the client connection policy with which a client is # associated. # # In DSEE, the default size limit is 2000 entries, while in the UnboundID # Identity Data Store the default global size limit is 1000 entries. If clients # may routinely need to process searches that return more than 1000 entries and # it is not feasible or convenient to increase the size limit only for those # users, then it may be necessary to increase the global search size limit for # the UnboundID Identity Data Store. # # # Applicable DSEE Configuration Options: # ---------- # * nsslapd-sizelimit (default value: 2000). # # # Applicable UnboundID Identity Data Store Configuration Options: # ---------- # * size-limit (default value: 1000). # # * maximum-search-size-limit (default value: 0, which does not enforce any # further restriction on the number of entries that may be returned for # clients associated with the client connection policy). # # # dsconfig Examples: # ---------- # * Change the server to use a global size limit of 2000: # dsconfig set-global-configuration-prop --set size-limit:2000 # # * Change the default client connection policy so that associated clients # will be allowed to retrieve no more than 50 entries per search: # dsconfig set-client-connection-policy-prop --policy-name default --set maximum-search-size-limit:50 # Search Time Limit # # Overview: # ---------- # Both DSEE and the UnboundID Identity Data Store provide a global configuration # option that can be used to limit the maximum length of time that the server # may spend processing any individual search operation, and both servers # provide a way to override that limit on a per-user basis. The UnboundID # Identity Data Store also provides a mechanism for further restricting the time # limit based on the client connection policy associated with the client that # submitted the request. # # In DSEE, the default global time limit is 3600 seconds, or 1 hour. This is # an extremely long time, and it is unlikely that most clients will have a # legitimate need to process searches that take anywhere near this length of # time. In the UnboundID Identity Data Store, the default global time limit is # 60 seconds, which is a much more reasonable default value. However, if there # is a legitimate need for clients to be allowed to submit search requests that # take the server longer than 1 minute to process, and it is not feasible or # convenient to define per-user time limit values, then it may be necessary to # increase the global time limit for the UnboundID Identity Data Store. # # # Applicable DSEE Configuration Options: # ---------- # * nsslapd-timelimit (default value: 3600 seconds, or 1 hour). # # # Applicable UnboundID Identity Data Store Configuration Options: # ---------- # * time-limit (default value: 1 minute). # # * maximum-search-time-limit (default value: 0 seconds, which does not # enforce any further restriction on the length of time that the server may # spend processing a search for clients associated with the client connection # policy). # # # dsconfig Examples: # ---------- # * Change the server to use a global search time limit of 5 minutes: # dsconfig set-global-configuration-prop --set "time-limit:5 m" # # * Change the default client connection policy so that the server will not # spend more than 30 seconds processing a search from any associated clients: # dsconfig set-client-connection-policy-prop --policy-name default --set "maximum-search-time-limit:30 s" # Single Structural Object Class Behavior # # Overview: # ---------- # LDAP specifications allow entries to have any number of auxiliary classes, # but they are required to have exactly one structural object class (although # it is possible for that one structural class to inherit from other structural # classes). The UnboundID Identity Data Store correctly enforces this constraint, # but DSEE does not. DSEE allows the use of entries which do not contain any # structural object class, as well as entries which contain multiple structural # object classes. Because of this, it is common for DSEE directory # environments to contain entries that do not conform to this requirement, and # when migrating data from such environments into the UnboundID Directory # Server, then such entries may be rejected. # # The best way to address this problem is to clean up the data so that each # entry has exactly one structural object class. It may be possible to # accomplish this by altering the definitions of custom object classes so that # some classes which were previously structural will instead be classified as # auxiliary, or so that custom object classes inherit from existing structural # classes with which they are always used. However, if this is not feasible or # possible, then the UnboundID Identity Data Store does provide the ability to # relax the constraint requiring exactly one structural object class. Changing # the single-structural-objectclass-behavior configuration property from the # default value of "reject" (to reject any entry which violates this # constraint) to "allow" will cause any such entries to be silently accepted, # or to "warn" to allow such entries to be accepted but a log message generated # for every such entry encountered. # # Note that if the server is configured to allow entries which do not have any # structural object class or which have multiple structural object classes, # then some functionality which is dependent upon entries having exactly one # structural class may not work as expected. This primarily includes advanced # schema functionality like name forms, DIT content rules, and DIT structure # rules, but may impact other server functionality as well. # # # Applicable DSEE Configuration Options: # ---------- # N/A # # # Applicable UnboundID Identity Data Store Configuration Options: # ---------- # * single-structural-objectclass-behavior (default value: reject, which will # cause the server to reject any entry which does not have exactly one # structural object class). # # # Related Configuration Elements: # ---------- # The following sections also involve schema compliance: # * Invalid Attribute Syntax Behavior # * Returning All Root DSE Attributes # * Returning All Schema Subentry Attributes # * Zero-Length Directory String Attribute Values # # # dsconfig Examples: # ---------- # * Configure the server to make it possible to add entries that are missing a # structural object class or that have multiple structural object classes, # but generate a warning for every such entry encountered: # dsconfig set-global-configuration-prop --set single-structural-objectclass-behavior:warn # Unindexed Searches # # Overview: # ---------- # Unindexed searches may be very expensive because they can require iterating # across all entries in the database. With a large data set, this can take a # long time, and each active unindexed search will consume a worker thread # that cannot be used for processing any other operations. As such, clients # should be careful to submit search requests which may be processed # efficiently within the server. However, since clients cannot know what # indexes may be defined in the server, then the server should be configured to # ensure that inappropriate unindexed searches will not be allowed to consume # significant server resources. # # By default, DSEE does not prevent clients from issuing unindexed searches. # It does provide a configuration option (on a per-backend basis) that can be # used to disable unindexed searches, but if this is enabled then no users, # even the root account, will be allowed to issue unindexed search requests. # Since it may occasionally be necessary for a client to issue an unindexed # search for legitimate reasons (e.g., an administrative operation which needs # to look at every entry in the server), then it is often not feasible to # disable the ability to perform unindexed searches. # # In the UnboundID Identity Data Store, the ability to submit unindexed search # requests is controlled by the unindexed-search privilege. This makes it # possible to prevent most clients from issuing unindexed search requests while # allowing them for clients that have a legitimate need to use them. Root # users inherit this privilege by default, but if a non-root user should be # allowed to request unindexed searches, then they should be granted the # unindexed-search privilege. If this is not feasible, then the # unindexed-search privilege may be disabled in the server to allow all users # to submit such searches. Note that it is still possible (as is also the case # in DSEE) that constraints like the search size limit, time limit, and # lookthrough limit may be used to limit the impact that an unindexed search # may have, at the potential cost of preventing the search from completing # successfully. # # The UnboundID Identity Data Store can also be configured to restrict the number # of unindexed searches that may be in progress at any given time. Even if # there may be a legitimate need for some clients to request unindexed # searches, they can still require expensive processing and it may be # desirable to ensure that plenty of worker threads will remain available for # other kinds of operations (including indexed searches). # # It is further possible to restrict the ability to request unindexed searches # based on the client connection policy assigned to the client issuing the # request. This could be used, for example, to ensure that only clients # associated with a particular policy are allowed to submit such requests, and # any client associated with a client connection policy that does not allow # unindexed searches will not be allowed to request them even if they have the # unindexed-search privilege. # # # Applicable DSEE Configuration Options: # ---------- # * nsslapd-require-index (default value: off, so that unindexed searches # will be allowed) # # # Applicable UnboundID Identity Data Store Configuration Options: # ---------- # * disabled-privilege property (default value: undefined, so that all # supported privileges will be enforced). # # * maximum-concurrent-unindexed-searches (default value: 0, so that there is # no limit on the number of unindexed searches that may be in progress at any # time). # # * allow-unindexed-searches (default value: true, so that any user with the # associated client connection policy and that has been granted the # unindexed-search privilege will be allowed to submit unindexed search # requests). # # # Related Configuration Elements: # ---------- # The following sections also involve the use of privileges: # * Access Control Modifications # * Access to the Server Configuration # * Administrative Password Reset # * Proxied Authorization # * Schema Modifications # # # dsconfig Examples: # ---------- # * Disable the unindexed-search privilege so that any user will be allowed to # issue unindexed search requests in the server: # dsconfig set-global-configuration-prop --set disabled-privilege:unindexed-search # # * Configure the server to prevent a maximum of two unindexed searches to be # in progress at any time: # dsconfig set-global-configuration-prop --set maximum-concurrent-unindexed-searches:2 # # * Update the default client connection policy so that any clients using that # policy will not be allowed to issue unindexed search requests even if they # have the unindexed-search privilege: # dsconfig set-client-connection-policy-prop --policy-name default --set allow-unindexed-searches:false # Zero-Length Directory String Attribute Values # # Overview: # ---------- # The LDAP specification for the directory string attribute syntax requires # that values with this syntax be comprised of at least one character. DSEE # does not honor this constraint, and allows storing empty values for # attributes with a directory string syntax. The UnboundID Identity Data Store # properly honors the requirements of this syntax, and as a result will reject # any attempt to store a zero-length value in an attribute with a directory # string syntax. However, there may be applications which expect to be able to # store zero-length values in such attributes, and which may break when # transitioning from DSEE to the UnboundID Identity Data Store. If such # applications are to be used with the UnboundID Identity Data Store and cannot be # updated so that they do not attempt to store zero-length values, then the # Identity Data Store may be reconfigured so that it will allow empty values for # attributes with the directory string syntax. # # # Applicable DSEE Configuration Options: # ---------- # N/A # # # Applicable UnboundID Identity Data Store Configuration Options: # ---------- # * allow-zero-length-values (default value: false, which will cause the # server to reject any attempt to supply a zero-length value to an attribute # with the directory string syntax). # # # Related Configuration Elements: # ---------- # The following sections also involve schema compliance: # * Invalid Attribute Syntax Behavior # * Returning All Root DSE Attributes # * Returning All Schema Subentry Attributes # * Single Structural Object Class Behavior # # # dsconfig Examples: # ---------- # * Configure the server to allow clients to set zero-length values for # attributes with a directory string syntax: # dsconfig set-attribute-syntax-prop --syntax-name "Directory String" --set allow-zero-length-values:true