Guide to securing ForgeRock® Directory Services deployments.

Directory services are well suited as a central, distributed store for identity data and credentials.

In addition to the threats described in "Insecure Client Applications", client applications can abuse directory services.

Abuse can be innocent, where poorly constructed or incorrectly configured clients waste server resources. In such cases, you might help the owner fix the problem.

Abuse can be intentional, as in a denial-of-service attack. In such cases, you must aim to protect the directory service itself.

Despite efforts to improve how people manage passwords, users have more passwords than ever before, and many use weak passwords. In addition to consolidating identity providers, and using modern access management protocols like OAuth 2.0 to avoid password proliferation, you can ensure the safety of passwords that you cannot eliminate.

As a central source of authentication credentials, directory services provide excellent password management capabilities. DS servers have flexible password policy settings, and a wide range of safe password storage options. Be sure that the passwords stored in your directory service are appropriately strong and securely stored.

For details, see "Configuring Password Policy" and "Enforcing Strong Passwords and Strong Password Storage".

Manage passwords for server administration securely as well. Passwords supplied to directory server tools can be provided in files, interactively, through environment variables, or as system property values. Choose the approach that is most appropriate and secure for your deployment.

Also make sure that directory administrators manage their passwords well. To avoid password proliferation for directory administrators, consider assigning administration privileges and granting access to existing accounts for delegated administrative operations. For details, see "Securing Directory Administration" and "Securing Access to Directory Data".

With the power to administer directory services comes the responsibility to make sure the configuration is correct. Misconfiguration can arise from bad or mistaken configuration decisions, and from poor change management.

Data theft can occur from outside the directory service when access policies are too permissive, and when the credentials to gain access are too easily cracked. It can occur from inside when the data is not protected, when administrative roles are too permissive, and when administrative credentials are poorly managed.

To protect against unauthorized access over the network, see the suggestions in "Insecure Client Applications", "Weak Passwords and Bad Password Management", and "Securing Access to Directory Data".

To protect against unauthorized access from those inside the organization who might gain access to directory files, see the suggestions in "Protecting Directory Files", and "Securing Directory Administration". Encrypt backup files as described in "Protect DS Server Files".

In addition to the risks associated poor configuration management outlined in "Misconfiguration", threats can arise when plans fail to account for outside risks.

For a critical directory service, you must test both normal, expected operation as described in "Testing Secure Deployments", and procedures to recover from disaster.

DS servers use encryption in a number of ways. For example, the server can encrypt backend databases and backup files on disk. It can also encrypt password values. Another important use of encryption is to make network connections secure. For details about encryption keys, see "About Certificates, Private Keys, and Secret Keys". For information about symmetric key distribution, see "Cryptographic Key Management", and "How Secret Keys are Distributed".

DS server use digests in a number of ways. For example, the server can store salted password hashes instead of encrypted passwords, making the original passwords extremely hard to recover even given access to the values that are stored. (In this context, salt is random data used as additional input to a hash function to increase the difficulty of cracking the passwords by applying the hash function to common passwords and looking for matches.) It also uses digests for authentication as described in "Authenticating Using Digest MD5".

DS server management of incoming client connections is built on connection handlers. Each connection handler is responsible for accepting client connections, reading requests, and sending responses. Connection handlers are specific to the protocol used. In other words, the connection handlers for LDAP and HTTP are different.

When you configure a connection handler, you specify whether it secures incoming connections, and the security protocols and cipher suites that can be used to negotiate a secure connection. In practice, separate connection handlers are often set up for cleartext (LDAP, HTTP) and secure (LDAPS, HTTPS) traffic. (A cleartext LDAP connection handler can support the StartTLS LDAP extended operation to initiate security after the connection is established, but for security from the moment the connection is established, you configure a separate LDAPS connection handler with use-ssl: true in its configuration.)

When you configure a connection handler that secures incoming connections from the network, you specify a key manager provider and a trust manager provider. A key manager provider handles the key material that is used to authenticate a secure connection to its peer. This means providing access to the server certificate when negotiating a secure connection. A trust manager provider determines whether to trust a certificate presented by the peer. This involves determining whether to trust the client certificate issuer. For client certificates signed by a well-known CA, the decision to trust the issuer can be delegated to the JVM, which comes with its own set of trusted CA certificates. If the issuer is not well-known, its trusted certificate must be stored in a truststore, which is a keystore handled by a trust manager provider.

Configuration of outgoing connections depends on the feature, but generally includes a mechanism for securing the connection. Make sure you have a way of securing all connections that carry sensitive information.

For details, see "Securing Network Connections".

For all operations where data is stored in encrypted form, the secret key for encryption must be distributed to all replicas that need to decrypt the data.

Trust between servers for administrative and replication connections depends on a public key infrastructure involving instance key pairs. (This type of infrastructure is explained in more detail in "Public Key Infrastructure (PKI)".) Each server has an asymmetric key pair, its instance key pair, where the public key certificate is self-signed by default.

When you configure replication, which establishes trust between the servers, they exchange and trust each others' instance key certificates. This enables servers to secure subsequent network connections for replication, and also to distribute secret keys. Each secret key is encrypted with each server's public key, stored in the administrative data for the server, and replicated in encrypted form across the topology. When a server needs the private key for decryption or further encryption, it decrypts its copy with its own private instance key. For details about how secret keys are stored in the administrative data, see "How Secret Keys are Distributed".

The component that enables this replication-based secret key distribution mechanism is called the DS Crypto Manager. Beyond its role in secret key distribution, the Crypto Manager provides a common interface for performing compression, decompression, hashing, encryption, and other kinds of cryptographic operations.

Authentication is the act of confirming the identity of a principal, such as a user, application, or device. The main reason for authentication is to control access based on the identity of the principal.

Servers should require authentication before allowing access to any information that is not public.

Authentication mechanisms depend on the access protocol. HTTP has a number of mechanisms, such as HTTP Basic. LDAP has other mechanisms, such as anonymous bind and external SASL. For details on supported mechanisms, see "Securing Authentication".

Authorization is the act of determining whether to grant or to deny a principal access to a resource.

DS servers authorize access based these mechanisms:

ACIs are set as attributes on directory entries, either in the user data where they can apply to that data, or in the directory configuration where they can apply for an entire server.

ACI evaluation only allows access that is explicitly granted. Without ACIs, no regular users are allowed any access to directory data. (DS servers have default global settings that allow minimal access.) If access is denied according to an applicable ACI, then the denial takes precedence over any access granted. Only if all applicable ACIs grant access is the access allowed.

Global access control policies are similar to ACIs, but are implemented as entries in the server configuration, rather than attributes on entries. Global access control policies can only allow access, not deny it. This constraint makes them easier to read and to change in isolation.

For details and instructions on using ACIs with directory servers, or global access control policies with proxy servers, see "Securing Access to Directory Data".

Administrative privileges provide access control for server administration independently from ACIs and access control policies. Even if a principal is granted access through applicable ACIs and policies, administrative access is still prevented if the principal does not have the requisite privilege.

Privileges are also stored as attributes on directory entries.

For details and instructions on using privileges, see "Securing Directory Administration".

For details, see "Monitoring Directory Security".

Over the lifetime of a directory services deployment, vulnerabilities and security issues can be discovered in the host operating systems where DS software is deployed. Some of these issues require upgrades to the host operating system. Others require configuration changes. All updates require proactive planning and careful testing.

Keep in mind that operating system and software providers typically do not communicate what they know about a vulnerability until they have a way to mitigate or fix the problem. Once they do communicate about security issues, however, the information is likely to become public knowledge quickly. Make sure that you can expedite resolution of security issues.

In order to move resolve security issues quickly, make sure that you are ready to validate any changes that must be made. When you validate a change, check that the fix resolves the security issue, and that the system and DS software continue to function as expected in all the other ways that they are used.

By default, operating systems include many features, accounts, and services that are not required to run and manage DS software. Each optional feature, account, and service on the system brings a risk of additional vulnerabilities. To reduce the surface of attack, you enable only required features, system accounts, and services, and remove those that are not needed for the deployment.

Some server operating system distributions have minimal installation options that allow you to choose most of the system features to enable. Other operating system distributions require you to turn off services that you do not use. In either case, validate DS software and administrative operations with a minimal system.

In addition to limiting what is installed and running on the system, consider configuration options for system hardening to further limit access even to required services.

For each account used to run a necessary service, aim to limit the access granted to the account to what is required to run the service. This reduces the risk that a vulnerability in access to one account affects multiple services across the system.

Make sure that you validate the operating system behavior every time you deploy something that is new or that has changed. When preparing the deployment and when testing changes, maintain a full operating system with DS software that is not used for any publicly available services, but only for troubleshooting problems that might stem from the system being too minimally configured.

In addition to minimizing what the host system does as described in "Enabling Only Required Features, Accounts, and Services", limit access to the system by protecting network ports and reducing access granted to administrative accounts. This further reduces the attack surface and reduces the advantage to be gained from exploiting a vulnerability.

The TCP/IP ports that must be protected are described in "Server Ports". When protecting network ports, notice that some must be open to remote client applications, whereas you can restrict access to administrative ports to the localhost only, assuming administrative access to the host is protected with another protocol such as SSH.

When setting up system accounts to manage directory services, set up a separate account as described in "Setting Up a System Account for a Server". Prevent other system accounts from accessing DS files as further described in "Protect DS Server Files". Configure the system to prevent users from logging in as the DS system account user, and from performing other operations besides managing directory services when using the DS system account.

DS logs provide a record of directory service events, but they do not record system-level events. Use the auditing features of the host operating system to record access that is not recorded in DS logs.

System audit logs make it possible to uncover system-level security policy violations, such as unauthorized access to DS files, that would not be visible in DS logs and monitoring information.

In addition to configuring system audit logging, consider how you will prevent or at least detect tampering. A malicious user violating security policy is likely to try to remove evidence of how security was compromised.

Due to export control restrictions, some Java environments, such as the Oracle JRE, ship with a policy that allows only limited strength cryptography. This can prevent DS servers from being able to use some encryption algorithms at full strength.

Assuming your operations are in a location where unlimited strength cryptography is allowed, you can install an unlimited strength policy. For example, Oracle provides an unlimited strength JCE policy extension that unlocks the full cryptographic strength supported by their JVM.

The policy files and download links are specific to the JVM. You can find the appropriate versions online.

Installing the policy generally involves copying a jar file into the $JAVA_HOME/lib/security/ directory of the JVM. Read the instructions closely, taking care to copy the files to the correct directory, which is different for the JRE and JDK, as the JDK contains the JRE.

Each time you update the Java environment, you must copy the policy file again.

Security updates are regularly released for the Java runtime environment.

Make sure that your operational plans provide for deploying Java security updates to systems where you run DS software.

When you set up DS servers, the path to the Java runtime environment is saved in the configuration. The server continues to use that Java version until you change the configuration as described below.

Security settings are covered in the documentation for supported application servers.

Make sure the application server protects traffic to the gateway with HTTPS.

For details on settings, see "DSML Client Access" in the Administration Guide.

Make sure the application server protects traffic to the gateway with HTTPS.

For details on settings, see "REST to LDAP Configuration" in the Reference.

Do not run DS servers as the system superuser (root). When applications run as superuser, the system effectively does not control their actions. When running the server as superuser, a bug in the server could affect other applications or the system itself.

After setting up a system account for the server, and using that account only to run the server, you can use system controls to limit user access.

The user running the server must have access to use the configured ports. Make sure you configure the system to let the user access privileged ports such as 389 and 636 if necessary. Make sure you configure the firewall to permit access to the server ports.

The user running the server must have access to all server files, including configuration files, data files, log files, keystores, truststores and their password files, and other files. By default, DS software lets users in the same group as the user running the server read server files, though not directory data files.

The user running the server does not, however, need access to login from a remote system or to perform actions unrelated to the directory service.

Set up the user account to prevent other users from reading configuration files. On UNIX, set an appropriate umask such as 027 to prevent users in other groups from accessing server files. On Windows, use file access control to do the same. Do consider letting all users to run command-line tools. What a user can do with tools depends on server access control mechanisms. For details, see "Setting Appropriate File Permissions".

You can create a UNIX service script to start the server at system startup and stop the server at system shutdown by using the create-rc-script command. For details see "create-rc-script — script to manage OpenDJ as a service on UNIX" in the Reference.

You can use the windows-service command to register the DS server as a Windows service. For details, see "windows-service — register DS as a Windows Service" in the Reference.

By default, DS servers do not encrypt server files or directory data. The only attribute values stored in encrypted or digest form are passwords. For instructions on encrypting entries and index content, see "Encrypting Directory Data" in the Administration Guide. For instructions on encrypting change log content, see "To Encrypt External Change Log Data" in the Administration Guide.

If you set up an appropriate user account for the server as described in "Setting Up a System Account for a Server", and unpacked the server files as that user, then the system should prevent other users from having overly permissive access to server files.

Included in the files that the server does not encrypt are LDIF exports of directory data. LDIF export files are readable and writable depending on the UNIX umask or Windows file access control settings for the user who runs the command to export the LDIF. The export-ldif command can compress the LDIF, but does not have an option for encrypting LDIF.

Directory backup archives can be encrypted, but are not encrypted by default. Backup archive file permissions depend on the UNIX umask or Windows file access control settings. When using the backup command, run an online backup and supply the --encrypt option as shown in the following example:

$ backup \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword - \
 --backupAll \
 --backupDirectory /path/to/opendj/bak \
 --encrypt \
 --start 0
Password for user 'cn=Directory Manager':
Backup task <datestamp> scheduled to start...
 

The server uses its Crypto Manager configuration to determine how to encrypt the backup archive data. The --encrypt option is not available for offline back up. If you back up server data offline, plan to protect the files separately.

The setup process enables DS server connection handlers, enabling at least an administration connection handler. You can choose to disable other connection handlers after setting up the server. For example, if the setup process enables the (cleartext) LDAP connection handler, but only LDAPS or HTTPS is used, then set the LDAP connection handler property to enabled:false by using the dsconfig set-connection-handler-prop command.

Use the status command to check which connection handlers are enabled.

By default, DS servers write log messages to files when an error is encountered and when a server is accessed. Access logs tend to be much more intensively updated than error logs. You can also configure debug logging, generally too verbose for continuous use in production, and audit logging, which uses the access log mechanism to record changes. Debug and audit logs are not enabled by default. For details, see "Server Logs" in the Administration Guide.

The default DS server error log levels and log rotation and retention policies are set to prevent the logs from harming performance or filling up the disk while still making it possible to perform basic troubleshooting. If you must set a more verbose error log level or if you must activate debug logging on a production system for more advanced troubleshooting, be aware that extra logging can negatively impact performance and generate large files on heavily used servers. When finished troubleshooting, reset the log configuration for more conservative logging.

The audit log for DS servers is not for security audits. Instead it records changes in LDIF. The audit log is intended to help you as server administrator to diagnose problems in the way applications change directory data. For change notification as a service, use the external change log instead. For details about the external change log, see "Change Notification For Your Applications" in the Administration Guide.

For details, see "Default Global ACIs" in the Administration Guide.

If the default global access control settings do not match your requirements, make sure you change them on each server as the server configuration data is not replicated. Global ACIs have the same syntax as ACIs in the directory data. Global access policies are entries in the server configuration. For details about access control settings, see "Configuring Privileges and Access Control" in the Administration Guide.

Default global access control settings can and often do change between releases. Review the release notes when upgrading to a new release. For details, see "Compatibility" in the Release Notes.

Generally it is appropriate to allow anonymous applications to read the root DSE, and to request the StartTLS extended operation over a cleartext connection, even if read access to most directory data requires authorization. The operational attributes on the root DSE indicate the server capabilities, allowing applications to discover interactively how to use the server. The StartTLS extended operation lets an application initiate a secure session starting on a port that does not require encryption.

Authenticated applications should be allowed to read schema operational attributes. LDAP schema operational attributes describe the data stored in the directory. An application that can read schema attributes and check that changes to directory data respect the LDAP schema before sending an update request.

Make sure you keep passwords secret in production. The server configuration includes files that hold passwords. Command-line tools allow users to provide password credentials. Passwords are also stored in directory data. This section looks at how to protect passwords in each situation.

$ ldapsearch \
 --hostname opendj.example.com \
 --port 1389 \
 --bindDN "cn=Directory Manager" \
 --bindPassword - \
 --baseDN "cn=Directory Manager" \
 "(&)" \
 userPassword
Password for user 'cn=Directory Manager':
dn: cn=Directory Manager
userPassword: {PBKDF2}10000:<hash>
  

DS server configurations can be hardened for production environments as part of the installation process. When installing the server, use the setup command option, --productionMode.

This section describes how keys are used, stored, accessed, and distributed by DS servers.

# Java 11
$ keytool -list -cacerts -storepass changeit
# Java 8
$ keytool -list -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass changeit

7.1.2. How Keys are Stored and Accessed

DS servers do not store asymmetric keys and symmetric keys in the same way.

7.1.2.1. How Asymmetric Keys are Stored and Accessed

DS software stores asymmetric key pairs in keystores, and trusted certificates in truststores. In the DS server configuration, keystores are referenced by key manager providers. (Except for some ForgeRock Common Audit event handlers that manage their own keystores.) Truststores are referenced by trust manager providers. Components that need access to keys reference key manager providers for their certificates and private keys, and trust manager providers for trusted certificates. This enables, but does not require, reuse as shown in "Asymmetric Key Storage".

Asymmetric Key Storage

Keys used to communicate with clients and other services are stored by default in the config/keystore file. Keys used for directory administration and data replication are stored by default in other files.

DS servers use one keystore for key pairs to secure adminstration and client connections, and a separate keystore for replication, as shown in "Keystores and Truststores".

Keystores and Truststores

By default, DS servers use file-based keystores, /path/to/opendj/config/keystore and /path/to/opendj/db/ads-truststore:

• The keystore file holds keys for securing administrative and client connections.

  The key pair for the server has default alias server-cert.

  The cleartext password is stored in keystore.pin. This password serves as the password for the keystore and for any private keys it contains, including the server-cert key. The password for the keystore and for private keys must be the same. DS servers do not support using different passwords for the keystore and private keys.

  This is where you import trusted certificates for external applications.

• The ads-truststore file holds the server's key pair for securing replication connections, and other replicas' public key certificates.

  The key pair for the server has default alias ads-certificate.

  The cleartext password is stored in ads-truststore.pin. This password serves as the password for the keystore and for any private keys it contains, including the ads-certificate key. The password for the keystore and for private keys must be the same.

  This keystore is synchronized with the certificates under the base DN cn=admin data. Do not change this keystore directly unless you understand the impact on the server configuration.

7.1.2.2. How Symmetric Keys are Stored and Accessed

Symmetric keys, used for features such as data confidentiality and encrypted backup, are managed through the DS Crypto Manager described in "About Security Features". The Crypto Manager generates symmetric keys when necessary, such as the first time data must be encrypted. It stores symmetric keys under cn=secret keys,cn=admin data, keeping them secret by encrypting them for each server using the server's public key.

dn: ds-cfg-key-id=<key-id>,cn=secret keys,cn=admin data
objectClass: top
objectClass: ds-cfg-cipher-key
ds-cfg-symmetric-key: <local-server-key-id>:<metadata>:<base64-encoded-encrypted-key>
ds-cfg-symmetric-key: <remote-server-key-id>:<metadata>:<base64-encoded-encrypted-key>
ds-cfg-key-id: <key-id>
  

This section shows how to prepare the server to use a file-based keystore to manage the keys essential to secure communications. For more information about the keys, see "About Certificates, Private Keys, and Secret Keys".

For instructions on importing trusted certificates on PKCS#11 devices, see the documentation for the device.

DS servers implement an OpenDJ security provider for LDAP and LDIF-based keystore services. Its keystore type is LDAP. This section demonstrates how to work with an LDAP keystore.

Interface Stability: Evolving

An LDAP keystore can store trusted certificates, private keys, and secret keys. It stores key entries in the directory under a base DN that you specify. It protects private and secret keys by encrypting them with the keystore password.

You can store keys in a database backend or in an LDIF file. By storing keys in a database backend, you can take advantage of data replication to distribute the keys securely to all replicas. LDIF storage can be useful for testing purposes.

You can access an LDAP keystore using the Java keytool command, and using similar tools that work with Java keystores. The tool must have access to the security provider implementation in the server libraries, and to a configuration file for connecting to the LDAP or LDIF storage.

$ cat keystore.ldif
dn: ou=keystore,dc=example,dc=com
objectClass: organizationalUnit
objectClass: top
aci: (target = "ldap:///ou=keystore,dc=example,dc=com")(targetattr = "*")
 (version 3.0;acl "Cleartext LDAP to keystore only on localhost";
 deny(all)(ip != "127.0.0.1" and ssf <= "1");)
description: LDAP keystore
ou: keystore

$ ldapmodify \
 --port 1389 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 keystore.ldif
  

# Configuration file for LDAP keystore using the directory
org.forgerock.opendj.security.keyStoreBaseDn=ou=keystore,dc=example,dc=com
org.forgerock.opendj.security.host=localhost
org.forgerock.opendj.security.port=1389
org.forgerock.opendj.security.bindDn=cn=Directory Manager
org.forgerock.opendj.security.bindPassword=password

# Configuration file for LDAP keystore using LDIF
org.forgerock.opendj.security.ldif=/path/to/keystore.ldif
org.forgerock.opendj.security.keyStoreBaseDn=ou=keystore,dc=example,dc=com
  

$ touch /path/to/opendj/config/ldap.pin
$ chmod 600 /path/to/opendj/config/ldap.pin
# Add a password in cleartext on a single line:
$ vi /path/to/opendj/config/ldap.pin
  

$ keytool \
 -genkeypair \
 -alias "private-key" \
 -ext "san=dns:opendj.example.com" \
 -dname "CN=opendj.example.com,O=Example Corp,C=FR" \
 -J-cp -J/path/to/opendj/lib/bootstrap-client.jar \
 -providerName OpenDJ \
 -providerClass org.forgerock.opendj.security.OpenDjSecurityProvider \
 -providerArg keystore.conf \
 -storetype LDAP \
 -keystore NONE \
 -storepass:file /path/to/opendj/config/ldap.pin \
 -keypass:file /path/to/opendj/config/ldap.pin
  

$ keytool \
 -certreq \
 -alias "private-key" \
 -file private-key.csr \
 -J-cp -J/path/to/opendj/lib/bootstrap-client.jar \
 -providerName OpenDJ \
 -providerClass org.forgerock.opendj.security.OpenDjSecurityProvider \
 -providerArg keystore.conf \
 -storetype LDAP \
 -keystore NONE \
 -storepass:file /path/to/opendj/config/ldap.pin \
 -keypass:file /path/to/opendj/config/ldap.pin
  

$ keytool \
 -selfcert \
 -alias "private-key" \
 -J-cp -J/path/to/opendj/lib/bootstrap-client.jar \
 -providerName OpenDJ \
 -providerClass org.forgerock.opendj.security.OpenDjSecurityProvider \
 -providerArg keystore.conf \
 -storetype LDAP \
 -keystore NONE \
 -storepass:file /path/to/opendj/config/ldap.pin \
 -keypass:file /path/to/opendj/config/ldap.pin
  

$ keytool \
 -genseckey \
 -alias "secret-key" \
 -keyalg AES \
 -keysize 256 \
 -J-cp -J/path/to/opendj/lib/bootstrap-client.jar \
 -providerName OpenDJ \
 -providerClass org.forgerock.opendj.security.OpenDjSecurityProvider \
 -providerArg keystore.conf \
 -storetype LDAP \
 -keystore NONE \
 -storepass:file /path/to/opendj/config/ldap.pin \
 -keypass:file /path/to/opendj/config/ldap.pin
  

$ keytool \
 -importcert \
 -alias "trusted-cert" \
 -file cert.crt \
 -J-cp -J/path/to/opendj/lib/bootstrap-client.jar \
 -providerName OpenDJ \
 -providerClass org.forgerock.opendj.security.OpenDjSecurityProvider \
 -providerArg keystore.conf \
 -storetype LDAP \
 -keystore NONE \
 -storepass:file /path/to/opendj/config/ldap.pin \
 -keypass:file /path/to/opendj/config/ldap.pin \
 -noprompt
Certificate was added to keystore
  

$ keytool \
 -importcert \
 -alias "trusted-cert" \
 -file cert.pem \
 -J-cp -J/path/to/opendj/lib/bootstrap-client.jar \
 -providerName OpenDJ \
 -providerClass org.forgerock.opendj.security.OpenDjSecurityProvider \
 -providerArg keystore.conf \
 -storetype LDAP \
 -keystore NONE \
 -storepass:file /path/to/opendj/config/ldap.pin \
 -keypass:file /path/to/opendj/config/ldap.pin \
 -noprompt
Certificate was added to keystore
  

$ keytool \
 -list \
 -J-cp -J/path/to/opendj/lib/bootstrap-client.jar \
 -providerName OpenDJ \
 -providerClass org.forgerock.opendj.security.OpenDjSecurityProvider \
 -providerArg keystore.conf \
 -storetype LDAP \
 -keystore NONE \
 -storepass:file /path/to/opendj/config/ldap.pin \
 -keypass:file /path/to/opendj/config/ldap.pin \
 -noprompt
Keystore type: LDAP
Keystore provider: OpenDJ

Your keystore contains 3 entries

private-key, <date>, PrivateKeyEntry,
...
secret-key, <date>, SecretKeyEntry,
trusted-cert, <date>, trustedCertEntry,
...
  

$ keytool \
 -delete \
 -alias "private-key" \
 -J-cp -J/path/to/opendj/lib/bootstrap-client.jar \
 -providerName OpenDJ \
 -providerClass org.forgerock.opendj.security.OpenDjSecurityProvider \
 -providerArg keystore.conf \
 -storetype LDAP \
 -keystore NONE \
 -storepass:file /path/to/opendj/config/ldap.pin \
 -keypass:file /path/to/opendj/config/ldap.pin \
 -noprompt
  

$ dsconfig \
 create-key-manager-provider \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --provider-name LDAP \
 --type ldap \
 --set enabled:true \
 --set base-dn:ou=keystore,dc=example,dc=com \
 --set key-store-pin:"&{file:/path/to/opendj/config/ldap.pin}" \
 --trustAll \
 --no-prompt
  

$ dsconfig \
 set-connection-handler-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --handler-name LDAPS \
 --set key-manager-provider:LDAP \
 --set ssl-cert-nickname:private-key \
 --trustAll \
 --no-prompt
  

$ dsconfig \
 create-trust-manager-provider \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --provider-name LDAP \
 --type ldap \
 --set enabled:true \
 --set base-dn:ou=keystore,dc=example,dc=com \
 --set trust-store-pin:"&{file:/path/to/opendj/config/ldap.pin}" \
 --trustAll \
 --no-prompt
  

$ dsconfig \
 set-connection-handler-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --handler-name LDAPS \
 --set trust-manager-provider:LDAP \
 --trustAll \
 --no-prompt
  

This section demonstrates how to use a PKCS#11 device, such as a hardware security module (HSM), to store the keys used to secure communications.

DS servers support key management using a PKCS#11 token store. The PKCS#11 standard defines a cryptographic token interface, a platform-independent API for storing keys in an HSM, for example. HSMs logically and physically protect keys. HSMs can perform cryptographic calculations with the keys, potentially offloading the CPU for this purpose, but also preventing the keys from being accessible to other processes on the system.

This section demonstrates how to use the SoftHSM PKCS#11 software device for evaluation, development, and testing.

When a server and client negotiate a secure connection, they negotiate use of a common protocol and cipher suite. If they cannot negotiate a common protocol and cipher suite, they will fail to set up a secure connection.

Furthermore, researchers continue to find vulnerabilities in protocols and cipher suites. If the server continues to support those protocols and cipher suites, then clients can use them when negotiating connections. Attackers can then exploit the vulnerabilities. It is therefore important to understand how to read and to restrict the list of supported protocols and cipher suites.

DS servers depend on the underlying JVM to support security protocols and cipher suites. By default, all supported protocols and cipher suites are available. For details, see the documentation for the JVM. For Oracle Java, see the Java Cryptography Architecture Oracle Providers Documentation describing the The SunJSSE Provider.

Bear in mind that support for protocols and cipher suites can be added and removed in Java update releases. The protocols and cipher suites available are also determined by the security policy. For example, see "Using Unlimited Strength Cryptography".

This section reviews incoming and outgoing connections, and offers recommendations that depend on the deployment.

# Log in to opendj.example.com:
me@my-laptop $ ssh user@opendj.example.com
user@opendj.example.com's password:
# Logged in to opendj.example.com as user.
Last login: ... from ...
# Run dsconfig interactively as opendj:
user@opendj.example.com $ sudo -i -u opendj dsconfig
     

This section shows how to configure DS servers to require HTTPS connections from client applications.

After you make the changes, HTTP clients must connect to the HTTPS port.

For details on configuring the DS DSML gateway or DS REST to LDAP gateway to require HTTPS, see the documentation for the web application container as described in "Securing Web Applications".

After you make the changes, LDAP clients must connect to the LDAPS port.

When a client and server set up a secure HTTP (HTTPS) or LDAP (LDAPS) connection, they use a protocol to establish the security, and then encapsulate HTTP or LDAP messages using the secure protocol. This section explains the process, making it clear how client certificates are handled differently in mutual authentication and in an LDAP bind using a certificate.

A connection that uses TLS, a protocol based on the SSL protocol, is a connection that is private and reliable. Communications on the connection are kept private by being encrypted with a symmetric key for the session that only the client and server know. Communications are reliable because their integrity is checked by using a message authentication code (MAC).

The TLS protocol is independent of the application protocol. TLS encapsulates application level protocols like HTTP and LDAP. The client and server negotiate the secure connection before any messages are sent using the application protocol.

When a client and server set up a secure connection, they use the TLS handshake protocol to negotiate a secure session. During the handshake the server and client use asymmetric keys, their public key certificates and associated private keys, to authenticate (prove their identities).

The default configuration for DS servers and most web servers has the server sending its certificate during the handshake. The client is not required to send its certificate. This allows the client to authenticate the server when negotiating security. It does not allow the server to authenticate the client at this stage. It avoids requiring all clients, such as browsers, to manage keys and to get certificates signed by well-known CAs.

For client applications that are part of the software infrastructure rather than end user applications such as browsers, managing keys and getting certificates signed by well-known CAs can be a better choice for authentication than usernames and passwords. Such clients present their certificates during the handshake, allowing the server to authenticate the client. When both the server and client present certificates during the handshake, this is known as mutual authentication.

Once again, this handshake completes before any HTTP or LDAP messages are sent over the connection. In other words, HTTP authentications and LDAP binds happen after the secure connection has been established.

This section clarifies the roles that client applications' X.509 digital certificates play in establishing secure connections and in authenticating the client as a directory user. Be aware that establishing a secure connection happens before the server handles the LDAP or HTTP requests that the client sends over the secure connection. Establishing a secure connection is handled separately from authenticating a client as a directory user, even though both processes can involve the client's certificate.

When a client and a server negotiate a secure connection over LDAPS or HTTPS, or over LDAP using the StartTLS operation, they can use public key cryptography to authenticate each other. The server, client, or both present certificates to each other. By default, DS LDAPS and HTTPS connection handlers are configured to present the server certificate, and to consider the client certificate optional. The connection handler property ssl-client-auth-policy makes the latter behavior configurable. For the DSML and REST to LDAP gateways, HTTPS negotiation is handled by the web application container where the gateway runs. See the web application container documentation for details on configuring how the container handles the client certificate.

One step toward establishing a secure connection involves validating the certificate that was presented by the other party. Part of this is trusting the certificate. The certificate identifies the client or server and the CA certificate used to sign the client or server certificate. The validating party checks that the other party corresponds to the one identified by the certificate, and checks that the signature can be trusted. If the signature is valid, and the CA certificate used to sign the certificate can be trusted, then the certificate can be trusted. This part of the validation process is also described briefly in "How Keys are Used".

Certificates can be revoked after they are signed. Therefore, the validation process can involve checking whether the certificate is still valid. Two different methods for performing this validation use the Online Certificate Status Protocol (OCSP) or Certificate Revocation Lists (CRLs). OCSP is a newer solution that provides an online service to handle the revocation check for a specific certificate. CRLs are potentially large lists of user certificates that are no longer valid or that are on hold. A CRL is signed by the CA. The validating party obtains the CRL and checks that the certificate being validated is not listed. For a brief comparison, see OCSP: Comparison to CRLs. A certificate can include links to contact the OCSP responder or to the CRL distribution point. The validating party can use these links to check whether the the certificate is still valid.

In both cases, the CA who signed the certificate acts as the OCSP responder or publishes the CRLs. When establishing a secure connection with a client application, the server relies on the CA for OCSP and CRLs. This is the case even when the DS server is the repository for the CRLs.

DS directory services are logical repositories for certificates and CRLs. For example, your DS directory service can store CRLs in a certificateRevocationList attribute as in the following example entry:

dn: cn=My CA,dc=example,dc=com
objectClass: top
objectClass: applicationProcess
objectClass: certificationAuthority
cn: My CA
authorityRevocationList;binary: Base64-encoded ARL
cACertificate;binary:: Base64-encoded CA certificate
certificateRevocationList;binary:: Base64-encoded CRL
 

The CRL could then be replicated to other DS directory servers for high availability. (Notice the ARL in this entry. An ARL is like a CRL, but for CA certificates.)

Again, despite being a repository for CRLs, the DS directory service does not use the CRLs directly when checking a client certificate. Instead, when negotiating a secure connection, the server depends on the JVM security configuration. The JVM configuration governs whether validation uses OCSP, CRLs, or both. As described in the Java PKI Programmer's Guide under Support for the CRL Distribution Points Extension, and Appendix C: On-Line Certificate Status Protocol (OCSP) Support, the JVM relies on system properties that define whether to use the CRL distribution points defined in certificates, and how to handle OCSP requests. These system properties can be set system-wide in $JAVA_HOME/lib/security/java.security ($JAVA_HOME/jre/lib/security/java.security for JDK 8). The JVM handles revocation checking without the DS server's involvement.

After a connection is negotiated, the server can authenticate a client application at the LDAP level based on the certificate. For details, see "Authenticating Client Applications With a Certificate".

OCSP and obtaining CRLs depend on network access to the CA. If DS servers or the DSML or REST to LDAP gateways run on a network where the CA is not accessible, and the deployment nevertheless requires OSCP or checking CRLs for client application certificates, then you must provide some alternative means to handle OCSP or CRL requests. The JVM can be configured to use a locally available OCSP responder, for example, and that OCSP responder might depend on DS servers. If the solution depends on CRLs, you could regularly update the CRLs in the directory with copies of the CA CRLs obtained by other means.

When determining the connection configuration for the deployment, also set resource limits to prevent directory clients from using an unfair share of system resources.

In addition, you can further limit what clients can do using the configuration properties described in "Restricting Client Access" in the Administration Guide.

$ dsconfig \
 set-global-configuration-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --set max-allowed-client-connections:65536 \
 --trustAll \
 --no-prompt

$ dsconfig \
 set-global-configuration-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --set allowed-client:example.com \
 --trustAll \
 --no-prompt

$ dsconfig \
 set-global-configuration-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --set restricted-client:"10.0.0.*" \
 --set restricted-client-connection-limit:1000 \
 --trustAll \
 --no-prompt

$ dsconfig \
 set-global-configuration-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --set idle-time-limit:24h \
 --trustAll \
 --no-prompt
 

$ dsconfig \
 set-connection-handler-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --handler-name LDAP \
 --set max-request-size:20mb \
 --trustAll \
 --no-prompt
 

As directory administrator, you must determine the authentication mechanisms that the directory service allows and that you encourage client applications to use.

Authentication is the process of verifying who is requesting access to a resource. The user or application making the request presents credentials, making it possible to prove that the requester is who they claim to be. The goal is to authorize access to directory resources depending on the confirmed identity of the user or application making the request.

LDAP is a stateful protocol, where the client sets up and maintains a connection with the server, potentially performing many operations or long-lived operations before disconnecting from the LDAP server. One of the LDAP operations, a bind, authenticates the client to the server. A bind is generally one of the first operations that a client performs, and clients can bind again on the same connection to reauthenticate.

Below the LDAP protocol at the transport layer, DS servers support SSL and TLS protocols with mutual client authentication based on the client certificate and public key infrastructure. This level of authentication is useful to properly secure connections. For details, see "How Transport Layer Security is Established". The authentication at this level is handled by the underlying JVM, and the client identity verified at this level is not available to the DS server for the purpose of fine-grained authorization. For fine-grained authorization, you need LDAP authentication.

Anonymous access means access to the directory where the client making the request provides no credentials. In general, anonymous clients can read public information.

In LDAP, an anonymous bind is a bind operation using simple authentication with an empty DN and an empty password. DS servers apply access controls (ACIs) to allow anonymous clients access only to information that should be fully public, such as information about the directory server in the root DSE, and LDAP schema definitions.

ACIs have a user DN subject, ldap:///anyone, that matches anonymous and authenticated users. This is used in some global ACIs as described in "Default Global ACIs" in the Administration Guide. It can also be used in ACI in the directory data. For explanations and examples, see "Configuring ACIs" in the Administration Guide.

DS servers make it possible to disable anonymous access as shown in "ACI: Disable Anonymous Access" in the Administration Guide.

When a client accesses the directory over HTTP, anonymous operations can be mapped either to a specific user identity or to an anonymous user (default) by using the HTTP Anonymous authorization mechanism for the HTTP endpoint, mentioned in "About Authentication Mechanisms".

As described in "About Authentication Mechanisms", a simple bind in LDAP is name/password authentication, where the client application presents a bind DN/password combination, and the DS server checks that the password matches the password on the entry with the specified bind DN.

The LDAP connection transport layer must be secure for a simple bind. Otherwise, eavesdroppers can read the credentials.

The directory server is often where passwords are stored, so that passwords can be managed safely and that password policy can be defined and managed centrally. This section covers how to configure password policies for DS servers.

$ dsconfig \
 get-password-policy-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --policy-name "Default Password Policy" \
 --advanced \
 --trustAll \
 --no-prompt
Property                                  : Value(s)
------------------------------------------:------------------------------------
account-status-notification-handler       : -
allow-expired-password-changes            : false
allow-multiple-password-values            : false
allow-pre-encoded-passwords               : false
allow-user-password-changes               : true
default-password-storage-scheme           : Salted SHA-512
deprecated-password-storage-scheme        : -
expire-passwords-without-warning          : false
force-change-on-add                       : false
force-change-on-reset                     : false
grace-login-count                         : 0
idle-lockout-interval                     : 0 s
java-class                                : org.opends.server.core.PasswordPoli
                                          : cyFactory
last-login-time-attribute                 : -
last-login-time-format                    : -
lockout-duration                          : 0 s
lockout-failure-count                     : 0
lockout-failure-expiration-interval       : 0 s
max-password-age                          : 0 s
max-password-reset-age                    : 0 s
min-password-age                          : 0 s
password-attribute                        : userPassword
password-change-requires-current-password : false
password-expiration-warning-interval      : 5 d
password-generator                        : Random Password Generator
password-history-count                    : 0
password-history-duration                 : 0 s
password-validator                        : -
previous-last-login-time-format           : -
require-change-by-time                    : -
require-secure-authentication             : false
require-secure-password-changes           : false
skip-validation-for-administrators        : false
state-update-failure-policy               : reactive
  

$ ldapsearch \
 --port 1389 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --baseDN dc=example,dc=com \
 "(uid=bjensen)" \
 userpassword
dn: uid=bjensen,ou=People,dc=example,dc=com
userpassword: {SSHA512}<hash>
  

dn: cn=Subentry Password Policy with Validators,dc=example,dc=com
objectClass: top
objectClass: subentry
objectClass: pwdPolicy
objectClass: pwdValidatorPolicy
cn: Subentry Password Policy with Validators
pwdAttribute: userPassword
pwdLockout: TRUE
pwdMaxFailure: 3
pwdFailureCountInterval: 300
pwdLockoutDuration: 300
pwdAllowUserChange: TRUE
pwdSafeModify: TRUE
ds-cfg-password-validator: cn=Character Set,cn=Password Validators,cn=config
ds-cfg-password-validator: cn=Length-Based Password Validator,
 cn=Password Validators,cn=config
subtreeSpecification: {base "ou=people", specificationFilter
  "(isMemberOf=cn=Directory Administrators,ou=Groups,dc=example,dc=com)" }

$ cat manage-pwp.ldif
dn: ou=People,dc=example,dc=com
changetype: modify
add: aci
aci: (targetattr = "pwdPolicySubentry||ds-pwp-password-policy-dn")
 (version 3.0;acl "Allow Administrators to manage user's password policy";
 allow (all) (groupdn = "ldap:///cn=Directory Administrators,ou=Groups,dc=example,dc=com");)

$ ldapmodify \
 --port 1389 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 manage-pwp.ldif
$ ldapsearch \
 --port 1389 \
 --bindDN uid=kvaughan,ou=people,dc=example,dc=com \
 --bindPassword bribery \
 --baseDN dc=example,dc=com \
 "(uid=bjensen)" \
 pwdPolicySubentry
dn: uid=bjensen,ou=People,dc=example,dc=com
pwdPolicySubentry: cn=Default Password Policy,cn=Password Policies,cn=config
  

9.4.3. Assigning Password Policies

You assign subentry-based password policies for a subtree of the DIT by adding the policy to an LDAP subentry whose immediate superior is the root of the subtree. In other words, you can add the subentry-based password policy under ou=People,dc=example,dc=com to have it apply to all entries under ou=People,dc=example,dc=com. You can also use the capabilities of LDAP subentries to refine the scope of application.

You assign server-based password policies by using the ds-pwp-password-policy-dn attribute.

"Server-Based and Subentry Password Policies" compares the types of password policy.

Server-Based and Subentry Password Policies

To Assign a Password Policy to a User

1. Give administrators the right to manage users' password policies:

   $ cat manage-pwp.ldif
   dn: ou=People,dc=example,dc=com
   changetype: modify
   add: aci
   aci: (targetattr = "pwdPolicySubentry||ds-pwp-password-policy-dn")
    (version 3.0;acl "Allow Administrators to manage user's password policy";
    allow (all) (groupdn = "ldap:///cn=Directory Administrators,ou=Groups,dc=example,dc=com");)
   
   $ ldapmodify \
    --port 1389 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    manage-pwp.ldif
      

   Notice here that the directory superuser, cn=Directory Manager, assigns privileges to Kirsten Vaughan. Any administrator with the privilege-change privilege can assign other privileges. Assuming the administrator can update administrator privileges, they can assign themselves the bypass-acl privilege. Then they are no longer bound by access control instructions, including both user data ACIs and global ACIs. For this reason, avoid assigning the privilege-change privilege to normal administrator users.

2. Update the user's ds-pwp-password-policy-dn attribute:

   $ cat newuser.ldif
   dn: uid=newuser,ou=People,dc=example,dc=com
   uid: newuser
   objectClass: person
   objectClass: organizationalPerson
   objectClass: inetOrgPerson
   objectClass: top
   cn: New User
   sn: User
   ou: People
   mail: newuser@example.com
   userPassword: changeme
   ds-pwp-password-policy-dn: cn=New Account Password Policy,cn=Password Policies,cn=config
   
   $ ldapmodify \
    --port 1389 \
    --bindDN uid=kvaughan,ou=people,dc=example,dc=com \
    --bindPassword bribery \
    newuser.ldif
      

3. Check your work:

   $ ldapsearch \
    --port 1389 \
    --bindDN uid=kvaughan,ou=people,dc=example,dc=com \
    --bindPassword bribery \
    --baseDN dc=example,dc=com \
    "(uid=newuser)" \
    pwdPolicySubentry
   dn: uid=newuser,ou=People,dc=example,dc=com
   pwdPolicySubentry: cn=New Account Password Policy,cn=Password Policies,cn=config
      

To Assign a Password Policy to a Group

You can use a collective attribute to assign a password policy. Collective attributes provide a standard mechanism for defining attributes that appear on all the entries in a subtree. For details, see "Collective Attributes" in the Developer's Guide:

1. Give an administrator the privilege to write subentries, such as those used for setting collective attributes:

   $ cat subentry-write.ldif
   dn: uid=kvaughan,ou=People,dc=example,dc=com
   changetype: modify
   add: ds-privilege-name
   ds-privilege-name: subentry-write
   
   $ ldapmodify \
    --port 1389 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    subentry-write.ldif
      

   Notice here that the directory superuser, cn=Directory Manager, assigns privileges to Kirsten Vaughan. Any administrator with the privilege-change privilege can assign other privileges. Assuming the administrator can update administrator privileges, they can assign themselves the bypass-acl privilege. Then they are no longer bound by access control instructions, including both user data ACIs and global ACIs. For this reason, avoid assigning the privilege-change privilege to normal administrator users.

2. Create a subentry defining the collective attribute that sets the ds-pwp-password-policy-dn attribute for group members' entries:

   $ cat pwp-coll.ldif
   dn: cn=Password Policy for Dir Admins,dc=example,dc=com
   objectClass: collectiveAttributeSubentry
   objectClass: extensibleObject
   objectClass: subentry
   objectClass: top
   cn: Password Policy for Dir Admins
   ds-pwp-password-policy-dn;collective: cn=Root Password Policy,cn=Password Policies,cn=config
   subtreeSpecification: { base "ou=People", specificationFilter
     "(isMemberOf=cn=Directory Administrators,ou=Groups,dc=example,dc=com)"}
   
   $ ldapmodify \
    --port 1389 \
    --bindDN uid=kvaughan,ou=people,dc=example,dc=com \
    --bindPassword bribery \
    pwp-coll.ldif
      

3. Check your work:

   $ ldapsearch \
    --port 1389 \
    --bindDN uid=kvaughan,ou=people,dc=example,dc=com \
    --bindPassword bribery \
    --baseDN dc=example,dc=com \
    "(uid=kvaughan)" \
    pwdPolicySubentry
   dn: uid=kvaughan,ou=People,dc=example,dc=com
   pwdPolicySubentry: cn=Root Password Policy,cn=Password Policies,cn=config
      

To Assign Password Policy for an Entire Branch

A password policy subentry password policy to assign the policy to the entries under a base DN:

1. Give an administrator the privilege to write subentries, such as those used for setting password policies:

   $ cat subentry-write.ldif
   dn: uid=kvaughan,ou=People,dc=example,dc=com
   changetype: modify
   add: ds-privilege-name
   ds-privilege-name: subentry-write
   
   $ ldapmodify \
    --port 1389 \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    subentry-write.ldif
      

   Notice here that the directory superuser, cn=Directory Manager, assigns privileges to Kirsten Vaughan. Any administrator with the privilege-change privilege can assign other privileges. Assuming the administrator can update administrator privileges, they can assign themselves the bypass-acl privilege. Then they are no longer bound by access control instructions, including both user data ACIs and global ACIs. For this reason, avoid assigning the privilege-change privilege to normal administrator users.

2. Create a password policy with a subtreeSpecification to assign the policy to all entries under a base DN.

   The following example creates a password policy for entries under ou=People,dc=example,dc=com:

   $ cat people-pwp.ldif
   dn: cn=People Password Policy,dc=example,dc=com
   objectClass: top
   objectClass: subentry
   objectClass: pwdPolicy
   cn: People Password Policy
   pwdAttribute: userPassword
   pwdLockout: TRUE
   pwdMaxFailure: 3
   pwdFailureCountInterval: 300
   pwdLockoutDuration: 300
   pwdAllowUserChange: TRUE
   pwdSafeModify: TRUE
   subtreeSpecification: { base "ou=people" }
   
   $ ldapmodify \
    --port 1389 \
    --bindDN uid=kvaughan,ou=people,dc=example,dc=com \
    --bindPassword bribery \
    people-pwp.ldif
      

   Notice the subtree specification used to assign the policy, { base "ou=people" }. You can relax the subtree specification value to {} to apply the password policy to all sibling entries (all entries under dc=example,dc=com), or further restrict the subtree specification by adding a specificationFilter. See "Understanding Subentry Scope" for more information.

3. Check your work:

   $ ldapsearch \
    --port 1389 \
    --bindDN uid=kvaughan,ou=people,dc=example,dc=com \
    --bindPassword bribery \
    --baseDN dc=example,dc=com \
    "(uid=alutz)" \
    pwdPolicySubentry
   dn: uid=alutz,ou=People,dc=example,dc=com
   pwdPolicySubentry: cn=People Password Policy,dc=example,dc=com
      

   If everything is correctly configured, then the password policy should be assigned to users whose entries are under ou=People,dc=example,dc=com.

9.4.3.1. Understanding Subentry Scope

LDAP subentries reside with the user data and so are replicated. Subentries hold operational data. They are not visible in search results unless explicitly requested. This section describes how a subentry's subtreeSpecification attribute defines the scope of the subtree that the subentry applies to.

An LDAP subentry's subtree specification identifies a subset of entries in a branch of the DIT. The subentry scope is these entries. In other words, these are the entries that the subentry affects.

The attribute value for a subtreeSpecification optionally includes the following parameters:

base

Indicates the entry, relative to the subentry's parent, at the base of the subtree.

By default, the base is the subentry's parent.

specificationFilter

Indicates an LDAP filter. Entries matching the filter are in scope.

By default, all entries under the base entry are in scope.

"Subtree Associated With a Subentry" illustrates these characteristics for an example collective attribute subentry.

Subtree Associated With a Subentry

Notice that the base of ou=People on the subentry cn=Silver Class of Service,dc=example,dc=com indicates that the base entry is ou=People,dc=example,dc=com.

The filter "(classOfService=silver)" means that Kirsten Vaughan and Sam Carter's entries are in scope. Babs Jensen's entry, with classOfService: bronze does not match and is therefore not in scope. The ou=People organizational unit entry does not have a classOfService attribute, and so is not in scope, either.

The difficulty with passwords is that they tend to be relatively easy to guess. Despite decades of advice on how to pick strong passwords, people still routinely pick very weak passwords using common words and phrases or simple variations of those. This makes them extremely easy to guess. Attackers with access to even modest hardware can make billions of guesses per second.

DS servers provide flexible password validation to fit your policies about password content and to reject weak passwords when users try to save them. It also provides a variety of one-way and reversible password storage schemes. Password strength is a function both of password minimum length, which you can set as part of password policy described in "Configuring Password Policy", and of password quality, which requires password validation. This section covers password validation for enforcing strong passwords, and protecting stored passwords with password storage schemes.

$ dsconfig \
 list-password-validators \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --trustAll \
 --no-prompt
Password Validator                  : Type                : enabled
------------------------------------:---------------------:--------
Attribute Value                     : attribute-value     : true
Character Set                       : character-set       : true
Dictionary                          : dictionary          : false
Length-Based Password Validator     : length-based        : true
Repeated Characters                 : repeated-characters : true
Similarity-Based Password Validator : similarity-based    : true
Unique Characters                   : unique-characters   : true
 

$ dsconfig \
 create-password-validator \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --validator-name "Custom Character Set Password Validator" \
 --set allow-unclassified-characters:true \
 --set enabled:true \
 --set character-set:0:abcdefghijklmnopqrstuvwxyz \
 --set character-set:0:ABCDEFGHIJKLMNOPQRSTUVWXYZ \
 --set character-set:0:0123456789 \
 --set character-set:0:\!\"#\$%\&\'\(\)\*+\,-./:\;\\\<=\>\?@\[\]\^_\`\{\|\}~ \
 --set min-character-sets:3 \
 --type character-set \
 --trustAll \
 --no-prompt
$ dsconfig \
 set-password-policy-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --policy-name "Default Password Policy" \
 --set password-validator:"Custom Character Set Password Validator" \
 --trustAll \
 --no-prompt
$ ldappasswordmodify \
 --port 1389 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --authzID "u:bjensen" \
 --newPassword '!ABcd$%^'
 

$ ldappasswordmodify \
 --port 1389 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --authzID "u:bjensen" \
 --newPassword hifalutin
The LDAP password modify operation failed with result code 19
Error Message:  The provided new password failed the validation checks defined
in the server: The provided password did not contain characters from at least
3 of the following character sets or ranges: '0123456789',
'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz',
'!"#$%&'()*+,-./:;\<=>?@[]^_`{|}~'
 

$ dsconfig \
 list-password-storage-schemes \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --trustAll
Password Storage Scheme : Type          : enabled
------------------------:---------------:--------
3DES                    : triple-des    : true
AES                     : aes           : true
Base64                  : base64        : true
Bcrypt                  : bcrypt        : true
Blowfish                : blowfish      : true
Clear                   : clear         : true
CRYPT                   : crypt         : true
MD5                     : md5           : true
PBKDF2                  : pbkdf2        : true
PKCS5S2                 : pkcs5s2       : true
RC4                     : rc4           : true
Salted MD5              : salted-md5    : true
Salted SHA-1            : salted-sha1   : true
Salted SHA-256          : salted-sha256 : true
Salted SHA-384          : salted-sha384 : true
Salted SHA-512          : salted-sha512 : true
SHA-1                   : sha1          : true
 

$ dsconfig \
 set-password-policy-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --policy-name "Default Password Policy" \
 --set default-password-storage-scheme:pbkdf2 \
 --trustAll \
 --no-prompt
 

$ ldapsearch \
 --port 1389 \
 --bindDN uid=bjensen,ou=people,dc=example,dc=com \
 --bindPassword hifalutin \
 --baseDN dc=example,dc=com \
 "(uid=bjensen)" \
 userPassword
dn: uid=bjensen,ou=People,dc=example,dc=com
userPassword: {SSHA512}<hash>
 

$ ldappasswordmodify \
 --port 1389 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --authzID "u:bjensen" \
 --newPassword changeit
The LDAP password modify operation was successful
$ ldapsearch \
 --port 1389 \
 --bindDN uid=bjensen,ou=people,dc=example,dc=com \
 --bindPassword changeit \
 --baseDN dc=example,dc=com \
 "(uid=bjensen)" \
 userPassword
dn: uid=bjensen,ou=People,dc=example,dc=com
userPassword: {PBKDF2}10000:<hash>
 

$ ldapsearch \
 --port 1389 \
 --bindDN uid=kvaughan,ou=people,dc=example,dc=com \
 --bindPassword bribery \
 --baseDN dc=example,dc=com \
 "(uid=kvaughan)" \
 userPassword
dn: uid=kvaughan,ou=People,dc=example,dc=com
userPassword: {SSHA512}<hash>
$ dsconfig \
 set-password-policy-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --policy-name "Default Password Policy" \
 --set deprecated-password-storage-scheme:"Salted SHA-1" \
 --trustAll \
 --no-prompt
$ ldapsearch \
 --port 1389 \
 --bindDN uid=kvaughan,ou=people,dc=example,dc=com \
 --bindPassword bribery \
 --baseDN dc=example,dc=com \
 "(uid=kvaughan)" \
 userPassword
dn: uid=kvaughan,ou=People,dc=example,dc=com
userPassword: {PBKDF2}10000:<hash>
 

One alternative to simple binds with user name/password combinations consists of storing a digital certificate on the user entry, and using the certificate as credentials during the bind. You can use this mechanism, for example, to let applications bind without using passwords.

By setting up a secure connection with a certificate, the client is in effect authenticating to the server. The server must close the connection if it cannot trust the client certificate. However, in the process of establishing a secure connection, it does not identify the client to the DS server, because the secure connection is established by the JVM at the transport layer, independently of the LDAP protocol.

When binding with a certificate, the client must request the SASL External mechanism by which the DS server maps the certificate to the client entry in the directory. When it finds a match, the DS server sets the authorization identity for the connection to that of the client, and the bind is successful.

For the whole process of authenticating with a certificate to work smoothly, the DS server and the client must trust each others' certificates, the client certificate must be stored on the client entry in the directory, and the DS server must be configured to map the certificate to the client entry.

$ touch /path/to/my-keystore.pin
$ chmod 600 /path/to/my-keystore.pin
# Add the PIN (changeit) in cleartext on first and only line in the file:
$ vi /path/to/my-keystore.pin
  

$ keytool \
 -export \
 -alias server-cert \
 -file server-cert.crt \
 -keystore /path/to/opendj/config/keystore \
 -storepass:file /path/to/opendj/config/keystore.pin \
 -storetype PKCS12
$ keytool \
 -import \
 -trustcacerts \
 -alias server-cert \
 -file server-cert.crt \
 -keystore /path/to/my-keystore \
 -storepass:file /path/to/my-keystore.pin \
 -noprompt
  

$ keytool \
 -import \
 -trustcacerts \
 -alias ca-cert \
 -file ca-cert.crt \
 -keystore /path/to/my-keystore \
 -storepass:file /path/to/my-keystore.pin
  

$ ldapsearch \
 --hostname opendj.example.com \
 --port 1389 \
 --baseDN dc=example,dc=com \
 --useStartTLS \
 --trustStorePath /path/to/my-keystore \
 --trustStorePasswordFile /path/to/my-keystore.pin \
 "(cn=My App)" \
 userPassword
dn: cn=My App,ou=Apps,dc=example,dc=com
  

$ ldapsearch \
 --hostname opendj.example.com \
 --port 1389 \
 --baseDN dc=example,dc=com \
 --useStartTLS \
 --saslOption mech="EXTERNAL" \
 --certNickName myapp-cert \
 --keyStorePath /path/to/my-keystore \
 --keyStorePasswordFile /path/to/my-keystore.pin \
 --trustStorePath /path/to/my-keystore \
 --trustStorePasswordFile /path/to/my-keystore.pin \
 "(cn=My App)" \
 userPassword
dn: cn=My App,ou=Apps,dc=example,dc=com
userPassword: {SSHA512}<hash>
  

$ dsconfig \
 set-sasl-mechanism-handler-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --handler-name External \
 --set certificate-mapper:"Fingerprint Mapper" \
 --trustAll \
 --no-prompt
$ ldapsearch \
 --hostname opendj.example.com \
 --port 1389 \
 --baseDN dc=example,dc=com \
 --useStartTLS \
 --saslOption mech="EXTERNAL" \
 --certNickName myapp-cert \
 --keyStorePath /path/to/my-keystore \
 --keyStorePasswordFile /path/to/my-keystore.pin \
 --trustStorePath /path/to/my-keystore \
 --trustStorePasswordFile /path/to/my-keystore.pin \
 "(cn=My App)" \
 userPassword
dn: cn=My App,ou=Apps,dc=example,dc=com
userPassword: {SSHA512}<hash>
  

$ dsconfig \
 set-sasl-mechanism-handler-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --handler-name External \
 --set certificate-mapper:"Subject Attribute to User Attribute" \
 --trustAll \
 --no-prompt
$ ldapsearch \
 --hostname opendj.example.com \
 --port 1389 \
 --baseDN dc=example,dc=com \
 --useStartTLS \
 --saslOption mech="EXTERNAL" \
 --certNickName myapp-cert \
 --keyStorePath /path/to/my-keystore \
 --keyStorePasswordFile /path/to/my-keystore.pin \
 --trustStorePath /path/to/my-keystore \
 --trustStorePasswordFile /path/to/my-keystore.pin \
 "(cn=My App)" \
 userPassword
dn: cn=My App,ou=Apps,dc=example,dc=com
userPassword: {SSHA512}<hash>
  

$ dsconfig \
 set-sasl-mechanism-handler-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --handler-name External \
 --set certificate-mapper:"Subject DN to User Attribute" \
 --trustAll \
 --no-prompt
$ ldapsearch \
 --hostname opendj.example.com \
 --port 1389 \
 --baseDN dc=example,dc=com \
 --useStartTLS \
 --saslOption mech="EXTERNAL" \
 --certNickName myapp-cert \
 --keyStorePath /path/to/my-keystore \
 --keyStorePasswordFile /path/to/my-keystore.pin \
 --trustStorePath /path/to/my-keystore \
 --trustStorePasswordFile /path/to/my-keystore.pin \
 "(cn=My App)" \
 userPassword
dn: cn=My App,ou=Apps,dc=example,dc=com
userPassword: {SSHA512}<hash>
  

Digest MD5 authentication allows password-based authentication without exposing the password on the network in the clear. It does require that both the client application and the DS server have access to the cleartext password, however. Passwords must be stored with a reversible password storage scheme.

Rather than including the password in the bind request, Digest MD5 authentication uses a two-step process where the client needs only to prove that it knows the password. The mechanism uses data that is randomly generated by the DS server to make it resistant to replay attacks. It also includes randomly generated data from the client, which makes it also resistant to problems resulting from weak server-side random number generation.

DS servers support Digest MD5 authentication through its DIGEST-MD5 SASL authentication mechanism. This mechanism is enabled by default unless the server was installed with the setup command option, --productionMode.

The default password policy prevents Digest MD5 authentication, as it uses a one-way hash rather than a reversible scheme. If you plan to use Digest MD5 authentication, set the password storage scheme for the users involved to a reversible mechanism before storing the their passwords. (Once the passwords have been stored with a one-way hash mechanism, the passwords will not be stored using a new mechanism until they are modified. Alternatively, DS servers can store the password with the new mechanism when the user authenticates. To enable this feature, configure the deprecated-password-storage-scheme property of the applicable password policy as described in "Configuring Password Storage".) For example, the following command sets the default password storage scheme to use the Advanced Encryption Standard (AES) reversible scheme:

$ dsconfig \
 set-password-policy-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --policy-name "Default Password Policy" \
 --set default-password-storage-scheme:aes \
 --trustAll \
 --no-prompt
  

Once the scheme is defined, you can test Digest MD5 authentication by changing a user's password to ensure that it is stored with the reversible scheme, and then authenticating as the user. When reading the following example it is important to realize that, although the user provides their password to the client application, the password is never sent in the clear over the connection:

# Make sure the password is encoded with a reversible scheme:
$ ldappasswordmodify \
 --port 1389 \
 --authzID "dn:uid=bjensen,ou=people,dc=example,dc=com" \
 --currentPassword hifalutin \
 --newPassword password
The LDAP password modify operation was successful

# Use Digest MD5 authentication:
$ ldapsearch \
 --hostname opendj.example.com \
 --port 1389 \
 --baseDN dc=example,dc=com \
 --saslOption mech=DIGEST-MD5 \
 --saslOption authid=u:bjensen \
 --bindPassword password \
 uid=bjensen \
 userPassword
dn: uid=bjensen,ou=People,dc=example,dc=com
userPassword: {AES}<encrypted>
  

The preceding example sets only the authentication ID with the --saslOption authid option. It is also possible to set the authorization ID separately by using the --saslOption authzid option.

Windows, UNIX, and Linux systems support Kerberos v5 authentication, which can operate safely on an open, unprotected network. In Kerberos authentication, the client application obtains temporary credentials for a service from an authorization server, in the form of tickets and session keys. The service server must be able to handle its part of the Kerberos mutual authentication process.

DS servers can interoperate with Kerberos systems through their GSSAPI SASL authentication mechanism.

When DS servers are first installed, only one directory administrator account is created. This administrator, by default cn=Directory Manager, is a directory superuser administrator capable of unrestricted changes to the directory service, including bypassing access control and augmenting its own list of administrative privileges.

Some deployments require only one administrator. For example, in deployments where the server configuration is never changed in production or where the server is embedded as part of a single application, additional administrators might be unnecessary.

For any directory service with more than one administrator, however, it makes sense to limit what individual administrators can do. When each administrator only has access to perform their individual duties, there is less risk of accidental or intentional abuse. In addition, problems arising from administrative errors or bugs can be easier to characterize when each administrator has a specific role with only necessary administrative privileges and access.

Specifying administrative roles for your deployment is beyond the scope of this guide. It helps to understand what tasks directory administrators can perform, however, and how the roles might be distinguished from one another. The broadest distinction to make is between administrators who manage the directory service, which is a container for user data, and administrators who manage user data.

Administrators who manage the directory service should usually not have all the privileges of default directory manager. The tasks they complete and the privileges required are described in "Directory Service Administration".

Administrators who manage user data usually make changes through remote applications. The tasks they complete and the privileges required are described in "Directory Data Administration".

Depending on the complexity of the directory service and the number of different administrators, it could make sense to subdivide administrative roles and limit the specific tasks each administrator can perform.

Many operations require both privileges and also ACIs. For example, in order to reset user's passwords, an administrator needs the password-reset privilege and access control to write userPassword values on the user entries. By combining ACIs with privileges, the administrator can effectively restrict the scope of a privilege.

The rest of this chapter covers how to manage administrator accounts, set privileges, and limit administrative access.

DS server administrators can either have a directory superuser account, or a regular user account with privileges and access to perform administrative tasks.

As described in "About the Roles Directory Administrators Play", DS server administrative privileges govern the administrative tasks that users can perform.

DS software provides the tools and features needed to manage user and administrator accounts individually or in groups. If the deployment calls for provisioning and workflow capabilities, or custom tools for day-to-day administration, then other tools are available to help manage groups and users systematically, including administrator accounts.

Some deployments require automation of provisioning and workflow operations, and management of many different user roles. In such cases, identity management software, such as ForgeRock Identity Management, can help. For details, see the IDM documentation.

Simple or local deployments might require a GUI for generic or system-specific administrative operations. In such cases, DS software's adherence to standards like LDAP v3 makes it interoperable with many third-party tools.

When you set up DS servers for evaluation, the settings can allow all client applications to read most user data. This makes it easier to become familiar with DS server features before you fully understand how the server works.

ACIs apply to directory data, providing fine-grained control over what a user or group member is authorized to do in terms of LDAP operations. Most access control instructions specify scopes (targets) so that an even an administrative user with full access to all data in dc=example,dc=com might have not access at all to data in dc=example,dc=org.

ACIs are implemented as attributes on DS server entries. This means they can be updated over protocol while the server is running. ACI attribute values are written in a special domain-specific language that is described in this section.

Global access control policies are similar to ACIs. They are configured as entries in the server configuration, and apply to DS servers. They provide coarse-grained access control suitable for use on proxy servers, where the lack of local access to directory data makes ACIs a poor fit.

Some operations require both privileges and access control. For example, in order to reset user's passwords, an administrator needs the password-reset privilege and access to write userPassword values on user entries. By combining access control and privileges, you can effectively restrict scope of privileges to a particular branch of the Directory Information Tree. Privileges are described in "Securing Directory Administration".

dn: dc=example,dc=com
objectClass: domain
objectClass: top
dc: example
aci: (target ="ldap:///dc=example,dc=com")
 (targetattr != "userPassword")(version 3.0;acl "Anonymous read-search access";
 allow(read, search, compare)(userdn = "ldap:///anyone");)
aci: (target="ldap:///dc=example,dc=com")
 (targetattr = "*")(version 3.0; acl "allow all Admin group";
 allow(all) groupdn = "ldap:///cn=Directory Administrators,ou=Groups,dc=example,dc=com";)
 

targets(version 3.0;acl "name";permissions subjects;)

allow(action[, action …])

deny(action[, action …])

aci: (target ="ldap:///dc=example,dc=com")
 (targetattr != "authPassword || userPassword")
 (version 3.0;acl "Anonymous read-search access";
 allow (read, search, compare)(userdn = "ldap:///anyone");)

$ dsconfig \
 get-access-control-handler-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --property global-aci \
 --trustAll
  

#
# Edit Access Control Handler global-aci attributes, replacing
# userdn="ldap:///anyone" (anonymous) with userdn="ldap:///all" (authenticated)
# in "Anonymous read access" and "User-Visible Operational Attributes" ACIs.
#
# To make this change, you remove existing values, and add edited values:
#
$ dsconfig \
 set-access-control-handler-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --remove global-aci:\(targetattr!=\"userPassword\|\|authPassword\|\|debugsearchindex\|\|changes\|\|changeNumber\|\|changeType\|\|changeTime\|\|targetDN\|\|newRDN\|\|newSuperior\|\|deleteOldRDN\"\)\(version\ 3.0\;\ acl\ \"Anonymous\ read\ access\"\;\ allow\ \(read,search,compare\)\ userdn=\"ldap:///anyone\"\;\) \
 --remove global-aci:\(targetattr=\"createTimestamp\|\|creatorsName\|\|modifiersName\|\|modifyTimestamp\|\|entryDN\|\|entryUUID\|\|subschemaSubentry\|\|etag\|\|governingStructureRule\|\|structuralObjectClass\|\|hasSubordinates\|\|numSubordinates\|\|isMemberOf\|\|alive\|\|healthy\"\)\(version\ 3.0\;\ acl\ \"User-Visible\ Operational\ Attributes\"\;\ allow\ \(read,search,compare\)\ userdn=\"ldap:///anyone\"\;\) \
 --add global-aci:\(targetattr!=\"userPassword\|\|authPassword\|\|debugsearchindex\|\|changes\|\|changeNumber\|\|changeType\|\|changeTime\|\|targetDN\|\|newRDN\|\|newSuperior\|\|deleteOldRDN\"\)\(version\ 3.0\;\ acl\ \"Anonymous\ read\ access\"\;\ allow\ \(read,search,compare\)\ userdn=\"ldap:///all\"\;\) \
 --add global-aci:\(targetattr=\"createTimestamp\|\|creatorsName\|\|modifiersName\|\|modifyTimestamp\|\|entryDN\|\|entryUUID\|\|subschemaSubentry\|\|etag\|\|governingStructureRule\|\|structuralObjectClass\|\|hasSubordinates\|\|numSubordinates\|\|isMemberOf\|\|alive\|\|healthy\"\)\(version\ 3.0\;\ acl\ \"User-Visible\ Operational\ Attributes\"\;\ allow\ \(read,search,compare\)\ userdn=\"ldap:///all\"\;\) \
 --trustAll \
 --no-prompt
  

$ cat remove-anon.ldif
dn: dc=example,dc=com
changetype: modify
delete: aci
aci: (target ="ldap:///dc=example,dc=com")(targetattr != "userPassword")(version 3.0;acl "Anonymous read-search access";allow (read, search, compare)(userdn = "ldap:///anyone");)
-
add: aci
aci: (target ="ldap:///dc=example,dc=com")(targetattr != "userPassword")(version 3.0;acl "Anonymous read-search access";allow (read, search, compare)(userdn = "ldap:///all");)

$ ldapmodify \
 --port 1389 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 remove-anon.ldif
  

$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(uid=bjensen)"
$ ldapsearch  \
 --port 1389 \
 --bindDN uid=bjensen,ou=people,dc=example,dc=com \
 --bindPassword hifalutin \
 --baseDN dc=example,dc=com \
 "(uid=bjensen)" cn uid
dn: uid=bjensen,ou=People,dc=example,dc=com
cn: Barbara Jensen
cn: Babs Jensen
uid: bjensen
  

$ dsconfig \
 set-global-configuration-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --set unauthenticated-requests-policy:allow-discovery \
 --trustAll \
 --no-prompt
  

$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(uid=bjensen)"
# The LDAP search request failed: 53 (Unwilling to Perform)
# Additional Information:  Rejecting the requested operation because the connection has not been authenticated
  

aci: (target="ldap:///dc=example,dc=com")
 (targetattr = "* || +")
 (version 3.0;acl "Admins can run amok";
  allow(all, proxy, import, export)
  groupdn = "ldap:///cn=Directory Administrators,ou=Groups,dc=example,dc=com";)

aci: (target ="ldap:///ou=People,dc=example,dc=com")
 (targetattr = "authPassword || userPassword")
 (version 3.0;acl "Allow users to change pass words";
   allow (write)(userdn = "ldap:///self");)
  

aci: (target ="ldap:///ou=Self Service,ou=Groups,dc=example,dc=com")
 (targetattr = "member")
 (version 3.0;acl "Self registration"; allow(selfwrite)
 (userdn = "ldap:///uid=*,ou=People,dc=example,dc=com");)
  

aci: (target ="ldap:///ou=Self Service,ou=Groups,dc=example,dc=com")
 (targattrfilters="add=objectClass:(objectClass=groupOfNames)")
 (version 3.0; acl "All can create self service groups";
   allow (add)(userdn= "ldap:///uid=*,ou=People,dc=example,dc=com");)
aci: (target ="ldap:///ou=Self Service,ou=Groups,dc=example,dc=com")
 (version 3.0; acl "Owner can delete self service groups";
   allow (delete)(userattr= "owner#USERDN");)
  

aci: (target = "ldap:///dc=example,dc=com")
 (targetattr = "*")
 (version 3.0;acl "Use loopback only for LDAP in the clear";
   deny (all)(ip != "127.0.0.1" and ssf <= "1");)
  

aci: (target = "ldap:///dc=example,dc=com")
 (targetattr = "aci") (version 3.0;acl "Modify ACIs"; allow (all)
 (groupdn = "ldap:///cn=Directory Administrators,ou=Groups,dc=example,dc=com";)
  

$ dsconfig \
 delete-global-access-control-policy \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --policy-name "Anonymous access all entries" \
 --trustAll \
 --no-prompt
$ dsconfig \
 delete-global-access-control-policy \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --policy-name "Authenticated access all entries" \
 --trustAll \
 --no-prompt
$ dsconfig \
 create-global-access-control-policy \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --policy-name "Authenticated access all entries" \
 --set authentication-required:true \
 --set request-target-dn-not-equal-to:"**,cn=changelog" \
 --set permission:read \
 --set allowed-attribute:"*" \
 --set allowed-attribute:createTimestamp \
 --set allowed-attribute:creatorsName \
 --set allowed-attribute:entryDN \
 --set allowed-attribute:entryUUID \
 --set allowed-attribute:etag \
 --set allowed-attribute:governingStructureRule \
 --set allowed-attribute:hasSubordinates \
 --set allowed-attribute:isMemberOf \
 --set allowed-attribute:modifiersName \
 --set allowed-attribute:modifyTimestamp \
 --set allowed-attribute:numSubordinates \
 --set allowed-attribute:structuralObjectClass \
 --set allowed-attribute:subschemaSubentry \
 --set allowed-attribute-exception:authPassword \
 --set allowed-attribute-exception:userPassword \
 --set allowed-attribute-exception:debugSearchIndex \
 --set allowed-attribute-exception:@changeLogEntry \
 --set allowed-control:Assertion \
 --set allowed-control:AuthorizationIdentity \
 --set allowed-control:Csn \
 --set allowed-control:ManageDsaIt \
 --set allowed-control:MatchedValues \
 --set allowed-control:Noop \
 --set allowed-control:PasswordPolicy \
 --set allowed-control:PermissiveModify \
 --set allowed-control:PostRead \
 --set allowed-control:PreRead \
 --set allowed-control:ProxiedAuthV2 \
 --set allowed-control:RealAttributesOnly \
 --set allowed-control:ServerSideSort \
 --set allowed-control:SimplePagedResults \
 --set allowed-control:TransactionId \
 --set allowed-control:VirtualAttributesOnly \
 --set allowed-control:Vlv \
 --set allowed-extended-operation:GetSymmetricKey \
 --set allowed-extended-operation:PasswordModify \
 --set allowed-extended-operation:PasswordPolicyState \
 --set allowed-extended-operation:StartTls \
 --set allowed-extended-operation:WhoAmI \
 --trustAll \
 --no-prompt
$ dsconfig \
 create-global-access-control-policy \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --policy-name "Anonymous extended operation access" \
 --set authentication-required:false \
 --set allowed-extended-operation:GetSymmetricKey \
 --set allowed-extended-operation:StartTls \
 --trustAll \
 --no-prompt
  

$ dsconfig \
 create-global-access-control-policy \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --policy-name "Require secure connections for example.com data" \
 --set request-target-dn-equal-to:"**,dc=example,dc=com" \
 --set request-target-dn-equal-to:dc=example,dc=com \
 --set connection-minimum-ssf:128 \
 --trustAll \
 --no-prompt
  

$ dsconfig \
 set-global-access-control-policy-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --policy-name "Anonymous extended operation access" \
 --set connection-client-address-equal-to:.example.com \
 --trustAll \
 --no-prompt
$ dsconfig \
 set-global-access-control-policy-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --policy-name "Root DSE access" \
 --set connection-client-address-equal-to:.example.com \
 --trustAll \
 --no-prompt
  

Misconfiguration can potentially put the DS server in a state where you must intervene, and where you need to prevent users and applications from accessing the directory until you are done fixing the problem.

DS servers provide a lockdown mode that allows connections only on the loopback address, and allows only operations requested by superusers, such as cn=Directory Manager. You can use lockdown mode to prevent all but administrative access while you repair a server.

To put the DS server into lockdown mode, the server must be running. You cause the server to enter lockdown mode by using a task. Notice that the modify operation is performed over the loopback address (accessing the DS server on the local host):

$ cat enter-lockdown.ldif
dn: ds-task-id=Enter Lockdown Mode,cn=Scheduled Tasks,cn=tasks
objectClass: top
objectClass: ds-task
ds-task-id: Enter Lockdown Mode
ds-task-class-name: org.opends.server.tasks.EnterLockdownModeTask

$ ldapmodify \
 --hostname localhost \
 --port 1389 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 enter-lockdown.ldif
 

The DS server logs a notice message in logs/errors when lockdown mode takes effect:

...msg=Lockdown task Enter Lockdown Mode finished execution

Client applications that request operations get a message concerning lockdown mode:

$ ldapsearch --port 1389 --baseDN "" --searchScope base "(objectclass=*)" +
The LDAP search request failed: 53 (Unwilling to Perform)
Additional Information:  Rejecting the requested operation because the server
is in lockdown mode and will only accept requests from root users over
loopback connections
 

You also leave lockdown mode by using a task:

$ cat leave-lockdown.ldif
dn: ds-task-id=Leave Lockdown Mode,cn=Scheduled Tasks,cn=tasks
objectClass: top
objectClass: ds-task
ds-task-id: Leave Lockdown Mode
ds-task-class-name: org.opends.server.tasks.LeaveLockdownModeTask

$ ldapmodify \
 --hostname localhost \
 --port 1389 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 leave-lockdown.ldif
 

The DS server logs a notice message when leaving lockdown mode:

...msg=Leave Lockdown task Leave Lockdown Mode finished execution

DS directory servers can encrypt directory data before storing it in a database backend on disk, keeping the data confidential until it is accessed by a directory client.

As explained in "Protect DS Server Files", DS directory servers do not encrypt directory data by default. This means that any user with system access to read directory files can potentially access directory data in cleartext.

You can verify what a system user could see with read access to backend database files by using the backendstat dump-raw-db command. The backendstat subcommands list-raw-dbs and dump-raw-db help you list and view the low-level databases within a backend. Unlike the output of other subcommands, the output of the dump-raw-db subcommand is neither decrypted nor formatted for readability. Instead, you can see values as they are stored in the backend file.

In a backend database, the id2entry index holds LDIF representations of directory entries. For a database that is not encrypted, the corresponding low-level database shows the cleartext strings, as is evident in the following example:

$ stop-ds --quiet
$ backendstat list-raw-dbs --backendId dsEvaluation
...
/dc=com,dc=example/id2entry...
...
$ backendstat \
 dump-raw-db \
 --backendId dsEvaluation \
 --dbName /dc=com,dc=example/id2entry
...
Key (len 8):
 00 00 00 00 00 00 00 1E                          ........
 Value (len 437):
 02 00 81 B1 03 01 06 27 75 69 64 3D 62 6A 65 6E  .......'uid=bjen
 73 65 6E 2C 6F 75 3D 50 65 6F 70 6C 65 2C 64 63  sen,ou=People,dc
 3D 65 78 61 6D 70 6C 65 2C 64 63 3D 63 6F 6D 01  =example,dc=com.
 06 11 01 08 01 13 62 6A 65 6E 73 65 6E 40 65 78  ......bjensen@ex
 61 6D 70 6C 65 2E 63 6F 6D 01 09 01 04 30 32 30  ample.com....020
 39 01 16 01 0C 65 6E 2C 20 6B 6F 3B 71 3D 30 2E  9....en, ko;q=0.
 38 01 10 01 29 75 69 64 3D 74 72 69 67 64 65 6E  8...)uid=trigden
 2C 20 6F 75 3D 50 65 6F 70 6C 65 2C 20 64 63 3D  , ou=People, dc=
 65 78 61 6D 70 6C 65 2C 64 63 3D 63 6F 6D 01 04  example,dc=com..
 02 13 50 72 6F 64 75 63 74 20 44 65 76 65 6C 6F  ..Product Develo
 70 6D 65 6E 74 06 50 65 6F 70 6C 65 01 0B 01 07  pment.People....
 42 61 72 62 61 72 61 01 0C 01 0F 2B 31 20 34 30  Barbara....+1 40
 38 20 35 35 35 20 31 38 36 32 01 0D 01 06 4A 65  8 555 1862....Je
 6E 73 65 6E 01 07 02 0E 42 61 72 62 61 72 61 20  nsen....Barbara
 4A 65 6E 73 65 6E 0B 42 61 62 73 20 4A 65 6E 73  Jensen.Babs Jens
 65 6E 01 0E 01 0D 2F 68 6F 6D 65 2F 62 6A 65 6E  en..../home/bjen
 73 65 6E 01 0F 01 0F 2B 31 20 34 30 38 20 35 35  sen....+1 408 55
 35 20 31 39 39 32 01 11 01 04 31 30 30 30 01 12  5 1992....1000..
 01 2E 7B 53 53 48 41 7D 33 45 66 54 62 33 70 37  ..{SSHA}3EfTb3p7
 71 75 6F 75 73 4B 35 34 2B 41 4F 34 71 44 57 6C  quousK54+AO4qDWl
 56 33 4F 39 54 58 48 57 49 4A 49 32 4E 41 3D 3D  V3O9TXHWIJI2NA==
 01 13 01 04 31 30 37 36 01 05 01 14 4F 72 69 67  ....1076....Orig
 69 6E 61 6C 20 64 65 73 63 72 69 70 74 69 6F 6E  inal description
 01 14 01 07 62 6A 65 6E 73 65 6E 01 15 01 0D 53  ....bjensen....S
 61 6E 20 46 72 61 6E 63 69 73 63 6F 01 01 02 01  an Francisco....
 24 38 38 37 37 33 32 65 38 2D 33 64 62 32 2D 33  $887732e8-3db2-3
 31 62 62 2D 62 33 32 39 2D 32 30 63 64 36 66 63  1bb-b329-20cd6fc
 65 63 63 30 35                                   ecc05
...
 

To maintain data confidentiality on disk, you must configure it explicitly. In addition to preventing read access by other users as described in "Setting Up a System Account for a Server", you can configure confidentiality for database backends. When confidentiality is enabled for a backend, the directory server encrypts entries before storing them in the backend.

Enable backend confidentiality with the default encryption settings as shown in the following example:

$ dsconfig \
 set-backend-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --backend-name dsEvaluation \
 --set confidentiality-enabled:true \
 --no-prompt \
 --trustAll
 

After confidentiality is enabled, entries are encrypted when next written. That is, the DS directory server does not automatically rewrite all entries in encrypted form. Instead, it encrypts each entry on update, for example, when a user updates their entry or when you import data.

If you import the data again after enabling confidentiality, you can see with the backendstat dump-raw-db command that the low-level database for id2index no longer contains cleartext:

$ stop-ds --quiet
$ [../resources/tests/admin-guide/import_export.bash:#export-backup-ldif]
$ [../resources/tests/admin-guide/import_export.bash:#import-backup-ldif]
$ backendstat \
 dump-raw-db \
 --backendId dsEvaluation \
 --dbName /dc=com,dc=example/id2entry
...
Key (len 8):
 00 00 00 00 00 00 00 C2                          ........
 Value (len 437):
 02 02 81 82 01 C4 95 87 5B A5 2E 47 97 80 23 F4  ........[..G..#.
 CE 5D 93 25 97 D4 13 F9 0A A3 A8 31 9A D9 7A 70  .].%.......1..zp
 FE 3E AC 9D 64 41 EB 7B D5 7F 7E B8 B7 74 52 B8  .>..dA.{.^?~..tR.
 C7 7F C8 79 19 46 7D C5 5D 5B 83 9C 5B 9F 85 28  .^?.y.F}.][..[..(
 83 A2 5F A0 C1 B1 09 FC 2F E3 D8 82 4A AA 8B D9  .._...../...J...
 78 43 34 50 AE A1 52 88 5B 70 97 D2 E1 EA 87 CA  xC4P..R.[p......
 3B 4D 07 DC F9 F8 30 BB D2 76 51 C8 75 FF FA 80  ;M....0..vQ.u...
 77 E1 6A 8B 5B 8F DA A4 F4 0B B5 20 56 B3 19 19  w.j.[...... V...
 22 D8 9D 38 04 E3 4D 94 A7 99 4B 81 16 AD 88 46  "..8..M...K....F
 FC 3F 7E 78 66 B8 D1 E9 86 A0 F3 AC B6 68 0D A9  .?~xf........h..
 9A A7 3C 30 40 37 97 4E 90 DD 63 16 8E 11 0F 5E  ..<0@7.N..c....^
 9D 5B 86 90 AF 4E E2 1F 9E 70 73 14 0A 11 5C DB  .[...N...ps...\.
 B7 BC B8 A9 31 3F 74 8D 0A 9F F4 6C E1 B0 36 78  ....1?t....l..6x
 F0 5A 5E CD 7C B3 A2 36 66 8E 88 86 A0 8B 9A 77  .Z^.|..6f......w
 D5 CD 7E 9C 4E 62 20 0E D0 DB AD E7 7E 99 46 4F  ..~.Nb .....~.FO
 67 C7 A6 7E 2C 24 82 50 51 9F A7 B2 02 44 5B 30  g..~,$.PQ....D[0
 74 41 99 D9 83 69 EF AE 2E C0 FF C4 E6 4F F2 2F  tA...i.......O./
 95 FB 93 65 30 2A 2D 8D 20 88 83 B5 DE 35 B6 20  ...e0*-. ....5.
 47 17 30 25 60 FD E3 43 B9 D6 A4 F7 47 B6 6C 9F  G.0%`..C....G.l.
 47 FD 63 8E 7F A5 00 CE 6C 3E BC 95 23 69 ED D0  G.c.^?...l>..#i..
 69 4F BE 61 BD 30 C2 40 66 F6 F9 C3 3E C1 D7 8C  iO.a.0.@f...>...
 B0 C8 4A 2E 27 BE 13 6C 40 88 B0 13 A3 12 F4 50  ..J.'..l@......P
 CA 92 D8 EB 4A E5 3F E2 64 A3 76 C7 5C 2B D8 89  ....J.?.d.v.\+..
 A3 6E C1 F7 0A C2 37 7A BD AF 14 4B 52 04 6B F2  .n....7z...KR.k.
 8F 4F C3 F8 00 90 BA 0F EC 6D B1 2D A8 18 0C A6  .O.......m.-....
 29 96 82 3B 5C BC D0 F4 2B BE 9C C5 8B 18 7A DE  )..;\...+.....z.
 C7 B5 10 2D 45 50 4F 77 ED F7 23 34 95 AF C3 2E  ...-EPOw..#4....
 B0 9B FA E9 DF                                   .....
...
  

Similar checks can be run on other low-level databases if you enable confidentiality by backend indexes as described below.

The default settings for confidentiality are cipher-transformation: AES/CBC/PKCS5Padding and cipher-key-length: 128. This means the algorithm is the Advanced Encryption Standard (AES), the cipher mode is Cipher Block Chaining (CBC), and the padding is PKCS#5 padding as described in RFC 2898: PKCS #5: Password-Based Cryptography Specification. The syntax for the cipher-transformation is algorithm/mode/padding, and all three must be specified. When the algorithm does not require a mode, use NONE. When the algorithm does not require padding, use NoPadding. Use of larger cipher-key-length values can require that you install JCE policy files such as those for unlimited strength, as described in "Using Unlimited Strength Cryptography".

DS servers encrypt data using a symmetric key that is stored with the server configuration. The symmetric key is encrypted in turn with the server's public key that is also stored with the server configuration. When multiple servers are configured to replicate data as described in "Configuring Replication Settings" in the Administration Guide, the servers replicate the keys as well, allowing any server replica to decrypt the data.

In addition to entry encryption, you can enable confidentiality by backend index, as long as confidentiality is enabled for the backend itself. Confidentiality hashes keys for equality type indexes using SHA-1, and encrypts the list of entries matching a substring key for substring indexes. The following example shows how to enable confidentiality for the mail index:

$ dsconfig \
 set-backend-index-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --backend-name dsEvaluation \
 --index-name mail \
 --set confidentiality-enabled:true \
 --no-prompt \
 --trustAll
  

After changing the index configuration, you can rebuild the index to enforce confidentiality immediately. For details, see "Configuring and Rebuilding Indexes" in the Administration Guide.

Avoid using sensitive attributes in VLV indexes. Confidentiality cannot be enabled for VLV indexes.

Encrypting and decrypting data comes with costs in terms of cryptographic processing that reduces throughput and of extra space for larger encrypted values. In general, tests with default settings show that the cost of enabling confidentiality can be quite modest, but your results can vary based on your systems and on the settings used for cipher-transformation and cipher-key-length. Make sure you test your deployment to qualify the impact of confidentiality before enabling it in production.

Appropriate file permissions grant access to authorized users and deny access by unauthorized users. For example, all users on the system might have access to run the ldapsearch command, but only a few users should be able to read the log files, and only the user running the DS server should be able to read a file containing a keystore PIN code.

When installing and setting up DS servers, you should use system accounts specific to the server, as described in "Setting Up a System Account for a Server". Having a specific account makes it possible to set appropriate file permissions.

Many DS server file permissions depend on the software distribution, and not the UNIX file mode creation mask. For example, the server commands are generally executable by all users, and the PIN code files are read-write only for the server user. You can affect the file permissions for several types of server files. "File Permission Settings" indicates the impact of recommended permissions settings on these files.

When taking input directly from a user or another program, handle the input securely by using appropriate methods to sanitize the data.

When writing command-line or HTTP clients, make sure you sanitize the input.

Failure to sanitize the input data can leave your application vulnerable to injection attacks.

Use secure connections except when reading public information anonymously. Always use secure connections when sending credentials for authentication, and when reading or writing any data that is not public.

For LDAP applications, either connect to the directory server's LDAPS port, or if possible, begin each session with the StartTLS extended operation on the (cleartext) LDAP port.

For HTTP clients, use HTTPS.

Unless your application only reads public information, authenticate to the directory server.

Use an account that is specific to your application when authenticating. This helps avoid risks involved in sharing credentials between accounts. Furthermore, it makes debugging easier by associating traces of your application's actions with its specific account.

LDAP applications can avoid username/password credentials by authenticating using digital certificates as described in "Authenticating Client Applications With a Certificate".

DS servers support OAuth 2.0 for HTTP authorization, where the directory acts as an OAuth 2.0 resource server as described in "To Set Up HTTP Authorization" in the Administration Guide.

An OAuth 2.0 client application gets authorization from the resource owner, such as the user, device, or thing whose account it needs to access, and presents the OAuth 2.0 bearer access token to get access to the account. This allows the HTTP application to access directory data through REST calls without having to have its own account.

Access tokens give the bearer access, regardless of the bearer's identity. Send access tokens only over secure HTTPS connections to prevent eavesdroppers from stealing the token.

DS servers support the use of proxied authorization as described in "Configuring Proxied Authorization" in the Developer's Guide. With proxied authorization, an LDAP application binds to the directory using its own account, and sends requests on behalf of applications users by attaching the user authorization ID in a request control.

When the user is already safely authenticated by other means, proxied authorization makes it easy to reuse a connection that is dedicated and bound to the application.

LDAP client applications can set time limits and size limits on search requests to avoid overuse of server resources. Setting limits is appropriate when the searches your application performs are not fixed, but instead partially or fully determined by user input.

The Directory Services ldapsearch command has --sizeLimit and --timeLimit options.

Keep in mind when you see evidence of what looks like a security problem that it might be explained by a mistake made by an administrator or an application developer. Whether the problem is due to malice or user error, you can nevertheless use monitoring information to guide corrective actions.

DS servers publish whether the server is alive and able to handle requests in the root DSE. They publish monitoring information over LDAP under the entry cn=monitor. The LDAP Schema Reference describes attributes and object classes used.

Many different types of information are exposed. For details, see "Monitoring Metrics" in the Reference.

The following example assigns the required privilege to Kirsten Vaughan's entry to read monitoring data, and shows monitoring information for the backend holding Example.com data:

$ cat monitor-read.ldif
dn: uid=kvaughan,ou=People,dc=example,dc=com
changetype: modify
add: ds-privilege-name
ds-privilege-name: monitor-read

$ ldapmodify \
 --port 1389 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 monitor-read.ldif
$ ldapsearch \
 --port 1389 \
 --bindDN uid=kvaughan,ou=People,dc=example,dc=com \
 --bindPassword bribery \
 --baseDN cn=monitor \
 "(cn=dsEvaluation backend)"
dn: cn=dsEvaluation backend,cn=Disk Space Monitor,cn=monitor
objectClass: top
objectClass: ds-monitor-entry
objectClass: extensibleObject
disk-dir: /path/to/opendj/db/dsEvaluation
disk-free: <bytes>
disk-state: normal
cn: dsEvaluation backend

dn: cn=dsEvaluation Backend,cn=monitor
objectClass: top
objectClass: ds-monitor-entry
objectClass: ds-backend-monitor-entry
ds-backend-id: dsEvaluation
ds-backend-base-dn: dc=example,dc=com
ds-backend-is-private: false
ds-backend-entry-count: <count>
ds-base-dn-entry-count: <count> dc=example,dc=com
ds-backend-writability-mode: enabled
cn: dsEvaluation Backend
 

Notice that users must have the monitor-read privilege to read monitoring data.

As an alternative, you can add a monitoring account when setting up the server. For an example, see "To Set Up a Directory Server" in the Installation Guide.

$ ldapsearch \
 --port 1389 \
 --baseDN "" \
 --searchScope base \
 "(&)" \
 alive
dn:
alive: true

$ ldapsearch \
 --port 1389 \
 --bindDN uid=monitor \
 --bindPassword password \
 --baseDN "cn=health status,cn=monitor" \
 --searchScope base \
 "(&)"
dn: cn=health status,cn=monitor
ds-mon-alive: true
ds-mon-healthy: true
objectClass: top
objectClass: ds-monitor
objectClass: ds-monitor-health-status
cn: health status

$ ldapsearch \
 --port 1389 \
 --bindDN uid=monitor \
 --bindPassword password \
 --baseDN cn=monitor \
 "(ds-mon-current-delay=*)" \
 ds-mon-current-delay
dn: ds-mon-domain-name=cn=admin data,cn=replicas,cn=replication,cn=monitor
ds-mon-current-delay: <delay>

dn: ds-mon-domain-name=cn=schema,cn=replicas,cn=replication,cn=monitor
ds-mon-current-delay: <delay>

dn: ds-mon-domain-name=dc=example\,dc=com,cn=replicas,cn=replication,cn=monitor
ds-mon-current-delay: <delay>

dn: ds-mon-server-id=<id>,cn=remote replicas,ds-mon-domain-name=dc=example\,dc=com,cn=replicas,cn=replication,cn=monitor
ds-mon-current-delay: <delay>
  

DS servers support SNMP, including the Management Information Base described in RFC 2605: Directory Server Monitoring MIB.

SNMP is not enabled by default. SNMP-based monitoring depends on an OpenDMK library. The OpenDMK binary bundle containing this library ships with DS servers as snmp/opendmk.jar. Installation requires that you accept the OpenDMK Binary License, and so OpenDMK installation is a separate step that you must perform before you can use SNMP.

To run the OpenDMK installer and accept the license, use the self-extracting .jar:

$ java -jar /path/to/opendj/snmp/opendmk.jar
 

Install OpenDMK, and then copy the libraries to the /path/to/opendj/extlib directory. For example, if you install OpenDMK in the /path/to directory, copy the libraries from the /path/to/OpenDMK-bin/lib directory:

$ cp /path/to/OpenDMK-bin/lib/* /path/to/opendj/extlib/
 

After installing OpenDMK, set up an SNMP connection handler:

$ dsconfig \
 set-connection-handler-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --handler-name SNMP \
 --set enabled:true \
 --trustAll \
 --no-prompt
 

By default, the SNMP connection handler listens on port 161 and uses port 162 for traps. On UNIX and Linux systems, only root can normally open these ports. To install as a normal user, change the listen and trap ports:

$ dsconfig \
 set-connection-handler-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --handler-name SNMP \
 --set listen-port:11161 \
 --set trap-port:11162 \
 --trustAll \
 --no-prompt
 

Restart the SNMP connection handler to take the changes into account:

$ dsconfig \
 set-connection-handler-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --handler-name SNMP \
 --set enabled:false \
 --trustAll \
 --no-prompt

$ dsconfig \
 set-connection-handler-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --handler-name SNMP \
 --set enabled:true \
 --trustAll \
 --no-prompt
 

To check that connection handler works as expected, use a command such as snmpwalk to read the response on the SNMP listen port:

$ snmpwalk -v 2c -c OpenDJ@OpenDJ localhost:11161
iso.3.6.1.2.1.66.1.1.1.1 = STRING: "ForgeRock Directory Services version"
iso.3.6.1.2.1.66.1.1.2.1 = STRING: "/path/to/opendj"
...

DS servers support JMX-based monitoring. A number of tools support JMX, including the jconsole and jvisualvm commands bundled with the Sun/Oracle Java platform. JMX is not configured by default.

Before enabling JMX, set server Java arguments appropriately to avoid regular full garbage collection events as described in "To Set Up JMX Access" in the Administration Guide.

Use the dsconfig command to configure the JMX connection handler:

$ dsconfig \
 create-connection-handler \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --handler-name JMX \
 --type jmx \
 --set enabled:true \
 --set listen-port:1689 \
 --trustAll \
 --no-prompt
 

By default, no users have privileges to access the JMX connection. The following commands add JMX privileges for Directory Manager:

$ cat jmx-privileges.ldif
dn: cn=Directory Manager
changetype: modify
add: ds-privilege-name
ds-privilege-name: jmx-notify
ds-privilege-name: jmx-read
ds-privilege-name: jmx-write

$ ldapmodify \
 --port 1389 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 jmx-privileges.ldif
 

Also configure security to login remotely. See the section on Using SSL in Monitoring and Management Using JMX Technology for hints.

Alternatively, connect to a local server process using the process ID:

$ jvisualvm --openpid $(</path/to/opendj/logs/server.pid)
 

DS servers have commands for monitoring server processes and tasks. The status command, described in "status — display basic OpenDJ server information" in the Reference, displays basic information about the local server. The manage-tasks command, described in "manage-tasks — manage server administration tasks" in the Reference, lets you manage tasks scheduled on a server, such as nightly backup.

The status command takes administrative credentials to read the configuration:

$ status \
 --bindDn "cn=Directory Manager" \
 --bindPassword password \
 --hostname opendj.example.com \
 --port 4444 \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePasswordFile /path/to/opendj/config/keystore.pin \
 --script-friendly
{
  "isRunning" : true,
  "hostname" : "opendj.example.com",
  "adminConnectorPort" : 4444,
  "openConnections" : <count>,
  "version" : "ForgeRock Directory Services 6.5.6",
  "installPath" : "/path/to/opendj",
  "instancePath" : "/path/to/opendj",
  "javaVersion" : "<version>",
  "javaVendor" : "<vendor>",
  "jvmCpus" : <count>,
  "jvmMaxHeapSizeBytes" : <size>,
  "connectionHandlers" : [ {
    "name" : "LDAP",
    "port" : 1389,
    "type" : "LDAP",
    "security" : "NONE",
    "enabled" : true,
    "avgLoadM1Rate" : <rate>,
    "avgLoadM5Rate" : <rate>
  }, {
    "name" : "LDAPS",
    "port" : 1636,
    "type" : "LDAPS",
    "security" : "SSL",
    "enabled" : true,
    "avgLoadM1Rate" : <rate>,
    "avgLoadM5Rate" : <rate>
  }, {
    "name" : "LDIF",
    "port" : null,
    "type" : "LDIF",
    "security" : null,
    "enabled" : false,
    "avgLoadM1Rate" : null,
    "avgLoadM5Rate" : null
  }, {
    "name" : "SNMP",
    "port" : 161,
    "type" : "SNMP",
    "security" : null,
    "enabled" : false,
    "avgLoadM1Rate" : null,
    "avgLoadM5Rate" : null
  } ],
  "backends" : [ {
    "name" : "rootUser",
    "type" : "LDIF",
    "enabled" : true,
    "dbCacheSizeBytes" : null,
    "baseDNs" : [ {
      "dn" : "cn=Directory Manager",
      "entryCount" : 1,
      "replicationStatus" : null,
      "replicationDelayMs" : null
    } ]
  }, {
    "name" : "dsEvaluation",
    "type" : "DB",
    "enabled" : true,
    "dbCacheSizeBytes" : <size>,
    "baseDNs" : [ {
      "dn" : "dc=example,dc=com",
      "entryCount" : <count>,
      "replicationStatus" : null,
      "replicationDelayMs" : null
    } ]
  } ],
  "disks" : [ {
    "root" : "<directory>",
    "state" : "normal",
    "freeSpaceRemainingBytes" : <size>
  } ]
}
 

The manage-tasks command connects to the administration port, and so can connect to both local and remote servers:

$ manage-tasks \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --trustAll \
 --no-prompt
 

The Graphite application stores numeric time-series data of the sort produced by monitoring metrics, and allows you to render graphs of that data.

Your applications, in this case DS servers, push data into Graphite. You do this by configuring the "Graphite Monitor Reporter Plugin" with the host and port number of the Graphite service, and with a prefix for your server, such as its FQDN. By default, the plugin pushes all metrics it produces to the Graphite service. You can opt to limit this by setting the excluded-metric-pattern or included-metric-pattern properties.

The following example configures the plugin to push metrics to Graphite at graphite.example.com:2004 every 10 seconds (default):

$ dsconfig \
 create-plugin \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --plugin-name Graphite \
 --type graphite-monitor-reporter \
 --set enabled:true \
 --set graphite-server:graphite.example.com:2004 \
 --set metric-name-prefix:opendj.example.com \
 --trustAll \
 --no-prompt
 

To view metrics stored in Graphite, you can use the Graphite render API or Grafana, for example. See the Graphite and Grafana documentation for details.

Logs are handled by log publishers. Log publishers determine which messages to publish, where to publish them, and what output format to use.

The server's logging system supports extensibility through the ForgeRock Common Audit event framework. (Common Audit deals with any event you can audit, not only the directory data changes recorded in a directory audit log.) The ForgeRock Common Audit event framework provides log handlers for publishing to local files or to remote systems, as described in "Common ForgeRock Access Logs".

You configure logging using the dsconfig command. In addition to configuring how messages are published, you can configure policies for log file rotation and retention.

{
    "eventName": "DJ-LDAP",
    "client": {
        "ip": string,                         // Client IP address
        "port": number                        // Client port number
    },
    "server": {
        "ip": string,                         // Server IP address
        "port": number                        // Server port number
    },
    "request": {                              // LDAP request
        "attrs": [ string ],                  // Requested attributes
        "authType": string,                   // Bind type such as "SIMPLE"
        "connId": number,                     // Connection ID
        "controls": string,                   // Request controls
        "deleteOldRDN": boolean,              // For a modify DN request
        "dn": string,                         // Bind DN
        "filter": string,                     // Search filter
        "idToAbandon": number,                // ID to use to abandon operation
        "message": string,                    // Localized request message
        "msgId": number,                      // Message ID
        "name": string,                       // Operation name
        "newRDN": string,                     // For a modify DN request
        "newSup": string,                     // For a modify DN request
        "oid": string,                        // Operation name or OID
        "operation": string,                  // Examples: "CONNECT", "BIND", "SEARCH"
        "opType": "sync",                     // Replication operation
        "protocol": "LDAP",
        "runAs": string,                      // Authorization ID
        "scope": string,                      // Search scope such as "sub"
        "version": string                     // Version "2", "3"
    },
    "response": {
        "additionalItems": string             // Additional information
        "controls": string,                   // Response controls
        "elapsedTime": number,                // Number of time units
        "elapsedTimeUnits": string,           // Time unit such as "MILLISECONDS"
        "failureReason": string,              // Human-readable information
        "maskedMessage": string,              // Real, masked result message
        "maskedResult": string,               // Real, masked result code
        "nentries": number,                   // Number of entries returned
        "reason": string,                     // Reason for disconnect
        "status": string,                     // "SUCCESSFUL", "FAILED"
        "statusCode": string                  // For example, "0" for success
    },
    "timestamp": string,                      // UTC date
    "transactionId": string,                  // Unique ID for the transaction
    "userId": string,                         // User who requested the operation
    "_id": string                             // Unique ID for the operation
}
 

{
    "eventName": "DJ-HTTP",
    "client": {
        "ip": string,                         // Client IP address
        "port": number                        // Client port number
    },
    "server": {
        "ip": string,                         // Server IP address
        "port": number                        // Server port number
    },
    "http": {                                 // HTTP request and response
      "request": {
        "secure": boolean,                    // HTTP: false; HTTPS: true
        "method": string,                     // Examples: "GET", "POST", "PUT"
        "path": string,                       // URL
        "queryParameters": map,               // map: { key-string: [ value-string ] }
        "cookies": map                        // map: { key-string: [ value-string ] }
      },
      "response": {
        "headers": map                        // map: { key-string: [ value-string ] }
      }
    },
    "response": {
        "detail": string,                     // Human-readable information
        "elapsedTime": number,                // Number of time units
        "elapsedTimeUnits": string,           // Time unit such as "MILLISECONDS"
        "status": string,                     // "SUCCESSFUL", "FAILED"
        "statusCode": string                  // For example, "0" for success
    },
    "timestamp": string,                      // UTC date
    "transactionId": string,                  // Unique ID for the transaction
    "trackingIds": [ string ],                // Unique IDs from the transaction context
    "userId": string,                         // User who requested the operation
    "_id": string                             // Unique ID for the operation
}
 

{
  "class": "org.forgerock.audit.handlers.elasticsearch.ElasticsearchAuditEventHandler",
  "config": {
    "name": string,               // Handler name, such as "elasticsearch".
    "topics": [ string, ...],     // LDAP: "ldap-access"; HTTP: "http-access".
    "enabled": boolean,           // Is the handler enabled?
    "connection": {               // (Optional) Connect using default settings.
      "host": string,             // Elasticsearch host. Default: localhost.
      "port": number,             // Elasticsearch host. Default: 9200.
      "useSSL": boolean,          // Connect to Elasticsearch over HTTPS? Default: false.
      "username": string,         // (Optional) User name for HTTP Basic auth.
      "password": string          // (Optional) Password for HTTP Basic auth.
    },
    "indexMapping": {             // (Optional) No mapping specified.
      "indexName": string         // Name of the Elasticsearch index.
    },
    "buffering": {                // (Optional) Default: write each message separately, no buffering.
      "enabled": boolean,         // Buffer messages to be sent? Default: false.
      "maxSize": number,          // Maximum number of buffered events.
      "writeInterval": duration,  // Interval between sending batch of events.
      "maxBatchedEvents": number  // Number of events to send per interval.
    }
  }
}
 

$ curl --user bjensen:hifalutin http://opendj.example.com:8080/api/users/bjensen
  

$ curl 'localhost:9200/audit/_search?q=*&pretty'
 

{
    "class": "org.forgerock.audit.handlers.jdbc.JdbcAuditEventHandler",
    "config": {
        "name": string,                    // Handler name, such as "jdbc".
        "topics": array,                   // LDAP: "ldap-access"; HTTP: "http-access".
        "databaseType": string,            // Supported by default: "h2", "mysql", "oracle", "postgres".
        "enabled": boolean,                // Is the handler enabled?
        "buffering": {                     // (Optional) Default: write each message separately, no buffering.
            "enabled": boolean,            // Buffer messages to be sent? Default: false.
            "writeInterval": duration,     // Duration; must be > 0 if buffering is enabled.
            "autoFlush": boolean,          // Flush messages automatically? Default: true.
            "maxBatchedEvents": number,    // Maximum messages in prepared statement. Default: 100.
            "maxSize": number,             // Maximum number of buffered messages. Default: 5000.
            "writerThreads": number        // Threads to write buffered messages: Default: 1.
        },
        "connectionPool": {
            "dataSourceClassName": string, // Either set this to the class name of the data source...
            "jdbcUrl": string,             // ...or set this to the JDBC URL to connect to the database.
            "username": string,            // Username to connect to the database.
            "password": string,            // Password to connect to the database.
            "autoCommit": boolean,         // (Optional) Commit transactions automatically? Default: true.
            "connectionTimeout": number,   // (Optional) Milliseconds to wait before timing out. Default: 30,000.
            "idleTimeout": number,         // (Optional) Milliseconds to wait before timing out. Default: 600,000.
            "maxLifetime": number,         // (Optional) Milliseconds thread remains in pool. Default: 1,800,000.
            "minIdle": number,             // (Optional) Minimum connections in pool. Default: 10.
            "maxPoolSize": number,         // (Optional) Maximum number of connections in pool. Default: 10.
            "poolName": string,            // (Optional) Name of connection pool. Default: audit.
            "driverClassName": string      // (Optional) Class name of database driver. Default: null.
        },
        "tableMappings": [                 // Correspondence of message fields to database columns.
            {
                "event": string,           // LDAP: "ldap-access"; HTTP: "http-access".
                "table": string,           // LDAP: "ldapaccess"; HTTP: "httpaccess".
                "fieldToColumn": {         // Map of field names to database column names.
                    "event-field": "database-column" // Event-field takes JSON pointer.
                }
            }
        ]
    }
}
 

{
    "class": "org.forgerock.audit.handlers.jms.JmsAuditEventHandler",
    "config": {
        "name": string,                    // Handler name, such as "jms".
        "enabled": boolean,                // Is the handler enabled?
        "topics": array,                   // LDAP: "ldap-access"; HTTP: "http-access".
        "deliveryMode": string,            // One of "NON_PERSISTENT", "PERSISTENT".
        "sessionMode": string,             // One of "AUTO", "CLIENT", "DUPS_OK".
        "batch": {                         // (Optional) Default: no batching.
            "batchEnabled": boolean,       // Batch messages to publish? Default: false.
            "capacity": number,            // Maximum capacity of publishing queue. Default: 1.
            "maxBatchedEvents": number,    // Maximum events to deliver in single publishing call. Default: 1.
            "threadCount": number,         // Worker threads to process publishing queue. Default: 1.
            "insertTimeoutSec": number,    // Seconds queue can block before adding new item. Default: 60.
            "pollTimeoutSec": number,      // Seconds worker threads wait for new item. Default: 10.
            "shutdownTimeoutSec": number   // Seconds publisher waits for threads at shutdown. Default: 60.
        },
        "jndi": {                          // (Optional) Default: Use default settings.
            "connectionFactoryName": string, // JNDI name for JMS connection factory. Default: "ConnectionFactory".
            "topicName": string            // (Optional) Match the value in the context. Default: "audit".
            "contextProperties": {         // JNDI InitialContext properties.
                // These depend on the JNDI provider. See the provider documentation for details.
            }
        }
    }
}
 

{
  "class": "org.forgerock.audit.handlers.json.stdout.JsonStdoutAuditEventHandler",
  "config": {
    "enabled": boolean,                   // Is the handler enabled?
    "name": string,                       // Handler name, such as "json.stdout".
    "elasticsearchCompatible" : boolean,  // If true, the message ID field is named _eventId. (Default: _id)
    "topics": array,                      // LDAP: "ldap-access"; HTTP: "http-access".
  }
}

{
    "class": "org.forgerock.audit.handlers.splunk.SplunkAuditEventHandler",
    "config": {
        "name": string,                    // Handler name, such as "splunk".
        "enabled": boolean,                // Is the handler enabled?
        "topics": array,                   // LDAP: "ldap-access"; HTTP: "http-access".
        "authzToken": string,              // Splunk authorization token for HTTP requests.
        "buffering": {                     // Required message buffering configuration.
            "maxBatchedEvents": number,    // Maximum messages in prepared statement.
            "maxSize": number,             // Maximum number of buffered messages.
            "writeInterval": duration      // Duration as described below.
        },
        "connection": {                    // (Optional) Default: Use default settings.
            "host": string,                // Splunk host name. Default: "localhost".
            "port": number,                // Splunk port number. Default: "8088".
            "useSSL": boolean              // Use secure connection to Splunk? Default: false.
        }
    }
}
 

{
    "class": "org.forgerock.audit.handlers.syslog.SyslogAuditEventHandler",
    "config": {
        "name": string,            // Handler name, such as "syslog".
        "enabled": boolean,        // Default: false.
        "topics": array,           // LDAP: "ldap-access"; HTTP: "http-access".
        "protocol": string,        // "TCP" or "UDP".
        "host": string,            // Syslog daemon host, such as localhost; must resolve to IP address.
        "port": number,            // Syslog daemon port number, such as 514; range: 0 to 65535.
        "connectTimeout": number,  // If using TCP, milliseconds to wait before timing out.
        "facility": string,        // Syslog facility to use for event messages.
        "buffering": {             // (Optional) Default: write each message separately, no buffering.
            "enabled": boolean,    // Buffer messages to be sent? Default: false.
            "maxSize": number      // Maximum number of buffered messages. Default: 5000.
        }
    }
}
 

$ dsconfig \
 set-log-publisher-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --publisher-name "Json File-Based HTTP Access Logger" \
 --set log-field-blacklist:/http/response/headers \
 --set log-field-blacklist:/http/response/queryParameters \
 --trustAll \
 --no-prompt

$ dsconfig \
 set-log-publisher-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --publisher-name "File-Based Access Logger" \
 --set enabled:true \
 --trustAll \
 --no-prompt
 

$ dsconfig \
 set-log-publisher-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --publisher-name "File-Based Audit Logger" \
 --set enabled:true \
 --trustAll \
 --no-prompt
 

$ cat bjensen-new-description.ldif
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: modify
replace: description
description: New description

$ ldapmodify \
 --hostname opendj.example.com \
 --port 1389 \
 --bindDN "uid=bjensen,ou=People,dc=example,dc=com" \
 --bindPassword hifalutin \
 bjensen-new-description.ldif
 

$ # <datestamp>; conn=<number>; op=<number>
dn: cn=File-Based Audit Logger,cn=Loggers,cn=config
changetype: modify
replace: ds-cfg-enabled
ds-cfg-enabled: true
-

# <datestamp>; conn=<number>; op=<number>
dn: uid=bjensen,ou=people,dc=example,dc=com
changetype: modify
add: description
description: New description
-
 

$ dsconfig \
 set-log-publisher-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --publisher-name "File-Based HTTP Access Logger" \
 --set enabled:true \
 --trustAll \
 --no-prompt