UnboundID LDAP SDK for Java

Overview of Additional UnboundID-Specific Functionality

The UnboundID LDAP SDK for Java provides a significant amount of additional functionality that is available for use when the SDK is used to communicate with an instance of the Ping Identity, UnboundID, or Nokia/Alcatel-Lucent 8661 Directory Server. This page describes that additional functionality.

Additional Controls

The following additional controls are available when communicating with a Ping Identity, UnboundID, or Nokia/Alcatel-Lucent 8661 Directory Server instance:

• Account Usability Control -- Provides information about whether a specified user account is available for use, and if not information about why it may be unavailable.
  
  
• Administrative Operation Control -- Indicates that the associated request is intended for some administrative purpose rather than a general application request. Operations with this control may be treated specially by the server, including placing additional information in access log messages and excluding them from inclusion in response time histogram tracking.
  
  
• Assured Replication Control -- May be used to indicate that the server should delay the response to the associated write operation until it receives confirmation that the change has been replicated to other local or remote servers in the topology, in accordance with the desired asurance criteria.
  
  
• Batched Transaction Specification Control -- Indicates that the associated operation is part of a batched transaction. This must be used in conjunction with the start batched transaction and end batched transaction extended operations.
  
  
• Exclude Branch Control -- Provides the ability to exclude entries in a specified set of branches from search results.
  
  
• Extended Schema Information Control -- Provides the ability to request that the server return extended information (including information about the files in which schema elements are defined and whether those definitions are considered read-only) as part of the server schema.
  
  
• Generate Password Control -- May be included in an add request to indicate that the server should generate a password for the new entry and return it to the client in a corresponding response control.
  
  
• Get Authorization Entry Control -- Provides the ability to retrieve the entries for the authentication and/or authorization entries for the user in the bind response received from the server.
  
  
• Get Backend Set ID Control -- Provides a way for the client to request information from a Directory Proxy Server about the entry balancing backend sets in which an operation was processed. It may be used in conjunction with the route to backend set request control to request that subsequent operations be processed within specified backend sets.
  
  
• Get Effective Rights Control -- Provides access to information about what rights a specified user has when interacting with a given entry.
  
  
• Get Password Policy State Issues Control -- May be included in a bind request (that meets additional security criteria) to request that the server return extended information about password policy-related issues that may affect the user's ability to authenticate, either now or in the near future.
  
  
• Get Server ID Control -- Provides a way for the client to request information about which server was actually used to process a request (including the ability to make that determination through a Directory Proxy Server). It may be used in conjunction with the route to server request control to request that an operation be processed by a specific server.
  
  
• Get User Resource Limits Control -- May be included in a bind request to indicate that the server should return information about resource limits that will be enforced for the authenticated user, including size limit, time limit, lookthrough limit, and idle time limit. Other information returned may include the name of the selected client connection policy, the DNs of the groups in which the user is a member, and the names of any privileges assigned to that user.
  
  
• Hard Delete Control -- May be included in a delete request to indicate that the target entry should be completely removed from the server, even if it would have otherwise been soft-deleted.
  
  
• Ignore NO-USER-MODIFICATION Control -- Provides the ability to add an entry to a Directory Server that already contains attributes which may be marked NO-USER-MODIFICATION in the server schema.
  
  
• Interactive Transaction Specification Control -- Indicates that the specified operation is part of an interactive transaction. This must be used in conjunction with the start interactive transaction and end interactive transaction extended operations.
  
  
• Intermediate Client Control -- May be used to help track requests and responses through a directory environment (e.g., between a client, a directory proxy server, and a directory server).
  
  
• Join Control -- Can be used to correlate search result entries with other entries related based on a given set of criteria.
  
  
• Matching Entry Count Control -- May be included in a search request to indicate that the server should merely return an estimate of the number of entries that match the search criteria rather than actually returning the matching entries themselves.
  
  
• Name With entryUUID Control -- May be included in an add request to indicate that the resulting entry should use the server-generated entryUUID attribute as its naming (RDN) attribute, rather than using the RDN that was provided in the add request.
  
  
• No Operation Control -- Provides the ability to request that the server validate that a write operation would likely succeed, but without making any changes to data in the server.
  
  
• Operation Purpose Control -- Provides the ability for a client to identify itself to the server and provide information about the reason for the associated operation.
  
  
• Override Search Limits Control -- May be included in a search request to indicate that the server should use client-specified values for certain resource limits rather than the limits that would normally be imposed.
  
  
• Password Policy Control -- Provides password policy-related information for a user account.
  
  
• Password Update Behavior Control -- May be included in an add, modify, or password modify request to provide additional control over the way the server will handle any passwords included in the request.
  
  
• Password Validation Details Control -- May be included in an add, modify, or password modify request to obtain information about the requirements that a user's password will be required to satisfy, and which of those requirements were actually satisfied by the provided password.
  
  
• Permit Unindexed Search Control -- May be included in a search request to indicate that the server should attempt to process the request even if it would have otherwise been rejected because it could not be efficiently processed using the defined set of indexes.
  
  
• Purge Password Control -- May be included in a modify or password modify request to indicate that the user's former password should be purged from the server, even if it would have otherwise been converted to a retired password.
  
  
• Real Attributes Only Control -- Indicates that search entries returned should not include any virtual attributes.
  
  
• Reject Unindexed Search Control -- May be included in a search request to indicate that the server should reject the requested operation if it cannot be efficiently processed using the defined set of indexes, even if the server would have otherwise permitted the search for the requester.
  
  
• Replication Repair Control -- Provides the ability to make a change in the server which will not be replicated to other servers, primarily intended for fixing problems due to replication conflicts.
  
  
• Retain Identity Control -- May be used with a bind request to indicate that the server should process the bind but not actually change the identity associated with the client connection.
  
  
• Retire Password Control -- May be included in a modify or password modify request to indicate that the user's former password should be retired, allowing it to be used as an alternative to the new password for a limited period of time.
  
  
• Return Conflict Entries Control -- May be included in a search request to indicate that the server should include replication conflict entries in the set of search results.
  
  
• Route to Backend Set Control -- May be used to request that the operation be routed to a particular set of entry balancing backend sets. This is only intended for use when the request is to be sent through a Directory Proxy Server.
  
  
• Route to Server Control -- May be used to request that the operation be routed to a particular backend server. This is primarily intended for use when the request is to be sent through a Directory Proxy Server.
  
  
• Soft-Delete Control -- May be included in a delete request to indicate that the server should process the operation as a soft delete, in which the entry will be hidden rather than immediately removed from the server.
  
  
• Soft-Deleted Entry Access Control -- May be included in a search request to indicate that the server should include soft-deleted entries in the set of search results.
  
  
• Suppress Operational Attribute Update Control -- May be used to indicate that the server should not alter one or more operational attributes (e.g., modifiers name, modify timestamp, last access time, last login time, or last login IP address) that would otherwise be updated by the request.
  
  
• Suppress Referential Integrity Updates Control -- May be included in a delete or modify DN request to indicate that the server should not make any referential integrity updates that would normally be performed as part of the operation.
  
  
• Transaction Settings Control -- May be used to override a number of settings that would otherwise be used for transaction-related processing involving the operation.
  
  
• Undelete Control -- May be included in an add request to indicate that the specified soft-deleted entry should be un-deleted.
  
  
• Unsolicited Cancel Control -- Indicates that the associated operation was canceled by the Directory Server for a reason other than being canceled by the client (e.g., because the client connection is being closed or the server is shutting down and all outstanding requests are being canceled).
  
  
• Virtual Attributes Only Control -- Indicates that search entries returned should only include virtual attributes.
  
  

Additional Extended Operations

The following additional extended operations are available when communicating with a Ping Identity, UnboundID, or Nokia/Alcatel-Lucent 8661 Directory Server instance:

• Clear Missed Notification Changes Alarm -- Clears a server alarm condition about missed notification changes.
  
  
• Collect Support Data -- Invokes the collect-support-data utility on the server and streams the output and support data archive back to the client.
  
  
• Consume Single-Use Token -- Indicates that a single-use token has been received and consumed by the client.
  
  
• Delete Notification Destination -- Removes a notification destination from the server.
  
  
• Delete Notification Subscription -- Removes a notification subscription from the server.
  
  
• Deliver One-Time Password -- Generates and sends a one-time password to a user for use in conjunction with the UNBOUNDID-DELIVERED-OTP SASL mechanism.
  
  
• Deliver Password Reset Token -- Generates and sends a password reset token to a user for use in conjunction with the password modify extended operation.
  
  
• Deliver Single-Use Token -- Generates and sends a single-use token to a user for use in conjunction with the consume single-use token extended operation.
  
  
• Deregister YubiKey OTP Device -- Deregisters a YubiKey OTP device from the server so it may no longer be used to authenticate via the UNBOUNDID-YUBIKEY-OTP SASL mechanism.
  
  
• End Administrative Session -- Indicates that the server should end an active administrative session for the connection.
  
  
• End Batched Transaction -- Indicates that the server should either commit or abort a batched transaction.
  
  
• End Interactive Transaction -- Indicates that the server should either commit or abort an interactive transaction.
  
  
• Generate Password -- Generates one or more passwords to suggest to a user (e.g., when they are choosing a new password).
  
  
• Generate TOTP Shared Secret -- Generates a TOTP shared secret and stores it in a user's entry to allow that user to authenticate using the UNBOUNDID-TOTP SASL mechanism.
  
  
• Get Backup Compatibility Descriptor -- Requests that the server provide a backup compatibility descriptor, which may be used in conjunction with the identify backup compatibility problems operation operation to determine if a backup from one server instance may be restored in another.
  
  
• Get Changelog Batch -- Allows the client to request a batch of changelog entries from the server. This may be used to retrieve information about changes in a manner that works across multiple servers (and through a Directory Proxy Server) and can resume where the last batch ended.
  
  
• Get Configuration -- Retrieves a version of a server's configuration, which may be the currently active configuration, a baseline configuration for the installed version, or any of the archived former configurations.
  
  
• Get Connection ID -- Allows the client to request the connection ID associated with the client connection used to issue the request.
  
  
• Get Password Quality Requirements -- Retrieves the requirements that a proposed password must satisfy for a user.
  
  
• Get Subtree Accessibility -- Retrieves information about any subtree accessibility restrictions currently set in the server.
  
  
• Get Supported OTP Delivery Mechanisms -- Retrieves a list of the one-time password delivery mechanisms that are supported by the server and available for a specified user.
  
  
• Identify Backup Compatibility Problems -- Identifies any potential problems that may prevent a backup taken on one server instance from being properly restored in another server instance.
  
  
• List Configurations -- Retrieves a list of the configurations that may be retrieved using the get configuration extended operation.
  
  
• List Notification Subscriptions -- Retrieves a list of the notification subscriptions configured in the server.
  
  
• Multi-Update -- Sends multiple update requests to the server in a single request so that they may be processed in sequence without requiring multiple network round trips for each request. The operations may be processed individually or as a single atomic unit.
  
  
• Password Policy State -- Allows the client to get and set a number of properties related to a user's password policy state.
  
  
• Register YubiKey OTP Device -- Registers a YubiKey OTP device with the server for a specified user so that it may be used to authenticate via the UNBOUNDID-YUBIKEY-OTP SASL mechanism.
  
  
• Revoke TOTP Shared Secret -- Revokes a TOTP shared secret that has been generated for a user so that it may no longer be used to authenticate.
  
  
• Set Notification Destination -- Creates or updates a notification destination in the server.
  
  
• Set Notification Subscription -- Creates or updates a notification subscription in the server.
  
  
• Set Subtree Accessibility -- Creates or removes an accessibility restriction for a specified subtree within the server.
  
  
• Start Administrative Session -- Creates an administrative session that can be used to request that operations be processed using a dedicated pool of worker threads.
  
  
• Start Batched Transaction -- Indicates that the client wishes to perform multiple updates as part of a single atomic transaction.
  
  
• Start Interactive Transaction -- Indicates that the client wishes to process multiple operations as a single atomic unit using a transaction.
  
  
• Stream Directory Values -- Provides the ability to obtain a list of entry DNs and/or the values of specified attributes for all entries in a specified portion of the DIT.
  
  
• Stream Proxy Values -- Retrieves a list of entry DNs and/or the values for one or more attributes from the Directory Proxy Server. This is primarily intended for use in populating another Directory Proxy Server's global index.
  
  
• Validate TOTP Password -- Validates a TOTP password for a user. This may be used as an alternative to the UNBOUNDID-TOTP SASL mechanism if the user is already authenticated and wishes to step up their existing authentication.
  
  

Access to Monitor Data

The UnboundID LDAP SDK for Java provides access to the following types of monitor information:

• Active Operations -- Information about operations currently in progress in the Directory Server.
  
  
• Backend -- Information about configured Directory Server backends.
  
  
• Client Connection -- Information about all client connections currently established.
  
  
• Connection Handler -- Information about configured Directory Server connection handlers.
  
  
• Disk Space Usage -- Information about components of the server which may consume a significant amount of disk space.
  
  
• Entry Cache -- Information about the state of the Directory Server entry cache.
  
  
• FIFO Entry Cache -- Information about the state of a FIFO entry cache configured in the Directory Server.
  
  
• Gauge -- Provides information about a gauge defined in the server that may be used to trigger an alarm.
  
  
• General -- General information about the state of the server.
  
  
• Group Cache -- Information about the number and types of groups available in the server.
  
  
• Host System Recent CPU and Memory -- Information about recent CPU and memory utilization for the underlying system.
  
  
• Index -- Information about index content and usage in a Berkeley DB JE backend.
  
  
• JE Environment -- Information about the Berkeley DB Java Edition environment in use by a Directory Server backend.
  
  
• LDAP External Server -- Information about backend servers used by the Ping Identity, UnboundID, or Nokia/Alcatel-Lucent 8661 Directory Proxy Server.
  
  
• LDAP Statistics -- Information about the types of communication performed by an LDAP connection handler.
  
  
• Memory Usage -- Information about memory usage and garbage collection within the JVM.
  
  
• Per-Application Processing Time Histogram -- Information about the time required for the server to process various types of operation requested on a per-application basis.
  
  
• Processing Time Histogram -- Information about the time required for the server to process various types of operations.
  
  
• Replica -- Information about the sate of a replica for a portion of the replicated content.
  
  
• Replication Server -- Information about the state of a replication server for a portion of the replicated content.
  
  
• Replication Summary -- Information about the replication state for a specified portion of the server DIT.
  
  
• Result Code -- Information about the number of result codes of different types returned for each type of operation.
  
  
• Stack Trace -- A stack trace of all threads running in the Directory Server JVM.
  
  
• System Info -- Information about the underlying system and JVM used to run the Directory Server.
  
  
• Traditional Work Queue -- Information about the state of the Directory Server traditional work queue.
  
  
• UnboundID Work Queue -- Information about the state of the enhanced UnboundID Directory Server work queue.
  
  
• Version -- Information about the Directory Server version.
  
  

Support for Managing Tasks

The UnboundID LDAP SDK for Java provides support for scheduling and managing the following types of tasks:

• Add Schema File -- Add the contents of one or more schema files to the server schema.
  
  
• Alert -- Generate arbitrary administrative alerts and alter the the set of degraded and unavailable alert types for the server.
  
  
• Audit Data Security -- Provides the ability to initiate a data security audit in the server to identify information in entries that may have an impact on the security of the environment.
  
  
• Backup -- Back up the contents of one or more Directory Server backends.
  
  
• Collect Support Data -- Invoke the collect-support-data tool for the server instance.
  
  
• Delay -- Sleeps for a specified period of time, or until the work queue becomes idle. This is primarily intended for inserting a delay between other types of tasks.
  
  
• Disconnect Client -- Terminate a specified client connection.
  
  
• Dump DB Details -- Retrieve information about the state of the individual databases that comprise a Berkeley DB JE backend.
  
  
• Enter Lockdown Mode -- Cause the Directory Server to enter a restricted operation mode.
  
  
• Exec -- Executes a specified command on the system (if all of the necessary security preconditions are satisfied).
  
  
• Export -- Export the contents of a Directory Server backend to LDIF.
  
  
• File Retention -- Cleans up old versions of sets of files named with a given pattern, leaving a specified number or files younger than a given age.
  
  
• Groovy-Scripted -- Invokes a custom task written in the Groovy scripting language with the UnboundID Server SDK.
  
  
• Import -- Import LDIF data into a Directory Server backend.
  
  
• Leave Lockdown Mode -- Cause the Directory Server to leave the restricted operation mode.
  
  
• Rebuild -- Generate or rebuild indexes for a Berkeley DB Java Edition backend.
  
  
• Refresh Encryption Settings -- Causes the Directory Server to reload its encryption settings definitions after a change was made to the set of definitions.
  
  
• Reload Global Index -- Causes the Directory Proxy Server to reload its global index from backend Directory Server or Directory Proxy Server instances.
  
  
• Restore -- Restore a backup for a specified Directory Server backend.
  
  
• Rotate Log -- Triggers an immediate rotation of one or more server log files.
  
  
• Search -- Perform an internal search and write the results to a specified file on the server filesystem.
  
  
• Shutdown -- Shut down or restart the Directory Server.
  
  
• Synchronize Encryption Settings -- Ensures that two servers have a common set of encrpytion settings definitions.
  
  
• Third-Party -- Invokes a custom Java-based task written with the UnboundID Server SDK.
  
  

Support for SASL Mechanisms

The UnboundID LDAP SDK for Java provides support for the following SASL mechanisms that are proprietary to the Ping Identity Directory Server:

• UNBOUNDID-CERTIFICATE-PLUS-PASSWORD -- Authenticates to the server using both a certificate and a password.
  
  
• UNBOUNDID-DELIVERED-OTP -- Authenticates to the server using a one-time password that has been delivered to the user through an out-of-band mechanism (e.g., email, SMS, voice call, app notification, etc.) using the deliver one-time password extended operation.
  
  
• UNBOUNDID-TOTP -- Authenticates to the server using a time-based one-time password, optionally in conjunction with a static password.
  
  
• UNBOUNDID-YUBIKEY-OTP -- Authenticates to the server using a one-time password generated by a YubiKey device, optionally in conjunction with a static password.
  
  

Other UnboundID-Specific APIs

The UnboundID LDAP SDK for Java also provides support for the following additional capabilities that are specifically intended for use in conjunction with the Ping Identity, UnboundID, or Nokia/Alcatel-Lucent 8661 Directory Server:

• Alert Entry Parsing -- The LDAP SDK provides support for parsing alert entries as included in the Ping Identity, UnboundID, or Nokia/Alcatel-Lucent 8661 Directory Server's administrative alerts backend.
  
  
• Changelog Entry Parsing -- The LDAP SDK provides support for parsing UnboundID-proprietary attributes contained in changelog entries, including information about values of updated attributes before and after the change, and also about key attributes from the entry.
  
  
• JSON Object Filter Handling -- The LDAP SDK provides support for generating and evaluating JSON object filters, which can be used to search for entries containing JSON objects matching a given set of criteria.
  
  
• Log File Parsing -- The LDAP SDK provides support for parsing access and error log messages generated by the Ping Identity, UnboundID, or Nokia/Alcatel-Lucent 8661 Directory Server.