51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! CCPL HEADER START
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! This work is licensed under the Creative Commons
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! To view a copy of this license, visit
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! or send a letter to Creative Commons, 444 Castro Street,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Suite 900, Mountain View, California, 94041, USA.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! You can also obtain a copy of the license at
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! See the License for the specific language governing permissions
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! and limitations under the License.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! If applicable, add the following below this CCPL HEADER, with the fields
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! enclosed by brackets "[]" replaced with your own identifying information:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Portions Copyright [yyyy] [name of copyright owner]
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! CCPL HEADER END
57d6342a74476c0bf2200992e778229d62ab1fa6mark ! Copyright 2011-2015 ForgeRock AS.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm><primary>Ports</primary><secondary>Configuring</secondary></indexterm>
ec40cc0dc62425cea5d63fd9d984f8614479de25mark This chapter shows you how to configure OpenDJ directory server
ec40cc0dc62425cea5d63fd9d984f8614479de25mark to listen for directory client requests, using connection handlers.
ec40cc0dc62425cea5d63fd9d984f8614479de25mark You can view information about connection handlers in the OpenDJ Control Panel,
ec40cc0dc62425cea5d63fd9d984f8614479de25mark and update the configuration using the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You configure LDAP client access by using the command-line tool
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <command>dsconfig</command>. By default you configure OpenDJ to listen for
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark LDAP when you install.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The standard port number for LDAP client access is 389. If you
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark install OpenDJ directory server as a user who can use port 389 and the port
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark is not yet in use, then 389 is the default port number presented at
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark installation time. If you install as a user who cannot use a port < 1024,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark then the default port number presented at installation time is 1389.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Change the port number using the <command>dsconfig</command>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark command.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-connection-handler-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --handler-name "LDAP Connection Handler" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set listen-port:11389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>This example changes the port number to 11389 in the configuration.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Restart the connection handler so the change takes effect.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para> To restart the connection handler, you disable it, then enable
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark it again.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-connection-handler-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --handler-name "LDAP Connection Handler" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set enabled:false \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-connection-handler-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --handler-name "LDAP Connection Handler" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set enabled:true \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>One common way to protect connections between OpenDJ and client
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark applications involves using StartTLS for LDAP or LDAPS to secure
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark connections. OpenDJ and client applications use X.509 digital certificates
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to set up secure connections.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Both OpenDJ and client applications check that certificates are signed
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark by a trusted party before accepting them. Merely setting up a secure
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark connection therefore involves a sort of authentication using certificates.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark If either OpenDJ or the client application cannot trust the peer certificate,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark then the attempt to set up a secure connection must fail.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>By default OpenDJ client tools prompt you if they do not recognize the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark server certificate. Other clients might not prompt you. OpenDJ server has no
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark one to prompt when a client presents a certificate that cannot be
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark trusted, so it must simply refuse to set up the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark connection.<footnote><para>Unless you use the Blind Trust Manager
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Provider, which is recommended only for test purposes.</para></footnote>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark In other words, it is important for both OpenDJ and client applications
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to be able to verify that peer certificates exchanged have been signed by
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark a trusted party.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In practice this means that both OpenDJ and client applications must
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark put the certificates that were used to sign each others' certificates in their
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark respective trust stores. Conventionally, certificates are therefore signed by
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark a Certificate Authority (CA). A CA is trusted to sign other certificates. The
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Java runtime environment for example comes with a trust store holding
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark certificates from many well-known CAs.<footnote><para><filename
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark >$JAVA_HOME/jre/lib/security/cacerts</filename> holds the CA certificates.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark To read the full list, use the following command.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>keytool \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -storepass changeit</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark certificate signed by one of these CAs, then OpenDJ can verify the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark certificate without additional configuration, because OpenDJ can find
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the CA certificate in the Java CA certificate trust store. Likewise if
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark you set up StartTLS or LDAPS in OpenDJ using a valid certificate signed
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark by one of these CAs, then many client applications can verify the OpenDJ
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark server certificate without further configuration.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In summary, if you need a certificate to be recognized automatically,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark get the certificate signed by a well-known CA.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You can, however, choose to have your certificates signed some other
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark way. You can set up your own CA. You can use a CA whose signing certificate
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark is not widely distributed. You can also use self-signed certificates. In each
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark case, you must add the signing certificates into the trust store of each
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark peer making secure connections.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>For OpenDJ directory server, you can choose to import your own CA-signed
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark certificate as part of the installation process, or later using command-line
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark tools. Alternatively, you can let the OpenDJ installation program create a
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark self-signed certificate as part of the OpenDJ installation process. In
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark addition, you can add a signing certificate to the OpenDJ trust store using
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example shows the <command>keytool</command> command to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark add a client application's binary format, self-signed certificate to the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark OpenDJ trust store (assuming OpenDJ is already configured to use secure
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark connections). This enables OpenDJ to recognize the self-signed client
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark application certificate. (By definition a self-signed certificate is itself
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the signing certificate. Notice that the Owner and the Issuer are the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark same.)</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>keytool \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -alias myapp-cert \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -storepass `cat /path/to/opendj/config/keystore.pin`</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Owner: CN=My App, OU=Apps, DC=example, DC=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkIssuer: CN=My App, OU=Apps, DC=example, DC=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkSerial number: 5ae2277
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkValid from: Fri Jan 18 18:27:09 CET 2013 until: Thu Jan 13 18:27:09 CET 2033
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkCertificate fingerprints:
08248b5c5b494aff8d1922e8e0b5777796d7450dmark MD5: 48:AC:F9:13:11:E0:AB:C4:65:A2:83:9E:DB:FE:0C:37
08248b5c5b494aff8d1922e8e0b5777796d7450dmark SHA1: F9:61:54:37:AA:C1:BC:92:45:07:64:4B:23:6C:BC:C9:CD:1D:44:0F
08248b5c5b494aff8d1922e8e0b5777796d7450dmark SHA256: 2D:B1:58:CD:33:40:E9:ED:...:EA:C9:FF:6A:19:93:FE:E4:84:E3
08248b5c5b494aff8d1922e8e0b5777796d7450dmark Signature algorithm name: SHA256withRSA
08248b5c5b494aff8d1922e8e0b5777796d7450dmark Version: 3
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkExtensions:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark#1: ObjectId: 2.5.29.14 Criticality=false
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkSubjectKeyIdentifier [
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkKeyIdentifier [
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark0000: 54 C0 C5 9C 73 37 85 4B F2 3B D3 37 FD 45 0A AB T...s7.K.;.7.E..
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark0010: C9 6B 32 95 .k2.
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkTrust this certificate? [no]:</computeroutput> <userinput>yes</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Certificate was added to keystore</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>When working with a certificate in printable encoding format (.pem)
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark rather than binary format, use the <option>-rfc</option> option, too.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Restart OpenDJ after adding certificates to the trust store to make
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark sure that OpenDJ reads the updated trust store file.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>On the client side, if your applications are also Java applications,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark then you can also import the OpenDJ signing certificate into the trust
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark store for the applications using the <command>keytool</command>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark command.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example shows the <command>keytool</command> command
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to export the OpenDJ self-signed certificate in binary format.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>keytool \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -alias server-cert \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -storepass `cat /path/to/opendj/config/keystore.pin`</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Certificate stored in file <server-cert.crt></computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Importing the server certificate is similar to importing the client
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark certificate, as shown above.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following sections describe how to get and install certificates
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark for OpenDJ directory server on the command line, for use when setting up
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark StartTLS or LDAPS.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <title>To Request and Install a CA-Signed Certificate</title>
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark First you create a server private key and public key certificate
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark in a Java Key Store.
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark Next you issue a signing request to the CA,
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark and get the CA-signed certificate as a reply.
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark Then you set up the Key Manager Provider and Trust Manager Provider
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark to rely on your new server certificate stored in the OpenDJ key store.
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark Generate the server private key and public key certificate
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark The FQDN for OpenDJ directory server,
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark which you can see under Server Details in the OpenDJ Control Panel,
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark in the certificate's <literal>SubjectAlternativeName</literal> list,
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark and also in the CN of the certificate's subject name DN
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark for backwards compatibility.
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>keytool \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -alias server-cert \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -keyalg rsa \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark -ext "san=dns:opendj.example.com" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -dname "CN=opendj.example.com,O=Example Corp,C=FR" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -storepass changeit \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -keypass changeit</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <note><para>Notice that the <option>-storepass</option> and
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <option>-keypass</option> options take identical password arguments.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark OpenDJ requires that you use the same password to protect both the keystore
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark If the server can respond on multiple FQDNs,
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark then specify multiple subject alternative names
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark In the following example
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark the primary FQDN is <literal>opendj.example.com</literal>
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark and the alternative is <literal>ldap.example.com</literal>.
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark$ <userinput>keytool \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark -alias server-cert \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark -keyalg rsa \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark -ext "san=dns:opendj.example.com,dns:ldap.example.com" \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark -dname "CN=opendj.example.com,O=Example Corp,C=FR" \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark -storepass changeit \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark -keypass changeit</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Create a certificate signing request file for the certificate you
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark generated.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>keytool \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -certreq \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -alias server-cert \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -storepass changeit \
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Have the CA sign the request
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>See the instructions from your CA on how to provide the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark request.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <!-- Create a CA cert for signing certificates.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkNot part of the procedure, but helpful when trying this out:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ openssl genrsa -des3 -out ca.key 4096
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkGenerating RSA private key, 4096 bit long modulus
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark.......................++
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarke is 65537 (0x10001)
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkEnter pass phrase for ca.key:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkVerifying - Enter pass phrase for ca.key:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ openssl req -new -x509 -days 7300 -key ca.key -out ca.crt
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkEnter pass phrase for ca.key:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkYou are about to be asked to enter information that will be incorporated
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkinto your certificate request.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkWhat you are about to enter is what is called a Distinguished Name or a DN.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkThere are quite a few fields but you can leave some blank
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkFor some fields there will be a default value,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkIf you enter '.', the field will be left blank.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkCountry Name (2 letter code) [AU]:FR
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkState or Province Name (full name) [Some-State]:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkLocality Name (eg, city) []:Grenoble
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkOrganization Name (eg, company) [Internet Widgits Pty Ltd]:Example Corp
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkOrganizational Unit Name (eg, section) []:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkCommon Name (eg, YOUR name) []:Example CA
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkEmail Address []:mark.craig@forgerock.com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ openssl x509 -req -in server-cert.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out server-cert.crt
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkSignature ok
fa45b27dca2b25b4974c90ff996278a3e4305fd1marksubject=/C=FR/O=Example Corp/CN=opendj.example.com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkGetting CA Private Key
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkEnter pass phrase for ca.key:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ openssl x509 -req -in myapp-cert.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out myapp-cert.crt
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkSignature ok
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkGetting CA Private Key
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkEnter pass phrase for ca.key:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If you have set up your own CA and signed the certificate, or are
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark using a CA whose signing certificate is not included in the Java runtime
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark environment, import the CA certificate into the key store so that it can be
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark trusted.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Otherwise, when you import the signed certificate in the reply from
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the (unknown) CA, <command>keytool</command> fails to import the signed
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark certificate with the message <literal>keytool error: java.lang.Exception:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example illustrates import of a CA certificate created
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <command>openssl</command> documentation for instructions on creating CAs
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark and on signing other certificates with the CA you created.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>keytool \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark -trustcacerts \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -alias ca-cert \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -storepass changeit</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Owner: EMAILADDRESS=admin@example.com, CN=Example CA, O=Example Corp, C=FR
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkIssuer: EMAILADDRESS=admin@example.com, CN=Example CA, O=Example Corp, C=FR
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkSerial number: d4586ea05c878b0c
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkValid from: Tue Jan 29 09:30:31 CET 2013 until: Mon Jan 24 09:30:31 CET 2033
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkCertificate fingerprints:
08248b5c5b494aff8d1922e8e0b5777796d7450dmark MD5: 8A:83:61:9B:E7:18:A2:21:CE:92:94:96:59:68:60:FA
08248b5c5b494aff8d1922e8e0b5777796d7450dmark SHA1: 01:99:18:38:3A:57:D7:92:7B:D6:03:8C:7B:E4:1D:37:45:0E:29:DA
08248b5c5b494aff8d1922e8e0b5777796d7450dmark SHA256: 5D:20:F1:86:CC:CD:64:50:...:DF:15:43:07:69:44:00:FB:36:CF
08248b5c5b494aff8d1922e8e0b5777796d7450dmark Signature algorithm name: SHA1withRSA
08248b5c5b494aff8d1922e8e0b5777796d7450dmark Version: 3
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkExtensions:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark#1: ObjectId: 2.5.29.35 Criticality=false
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkAuthorityKeyIdentifier [
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkKeyIdentifier [
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark0000: 30 07 67 7D 1F 09 B6 E6 90 85 95 58 94 37 FD 31 0.g........X.7.1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark0010: 03 D4 56 7B ..V.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark[EMAILADDRESS=admin@example.com, CN=Example CA, O=Example Corp, C=FR]
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkSerialNumber: [ d4586ea0 5c878b0c]
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark#2: ObjectId: 2.5.29.19 Criticality=false
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkBasicConstraints:[
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark PathLen:2147483647
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark#3: ObjectId: 2.5.29.14 Criticality=false
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkSubjectKeyIdentifier [
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkKeyIdentifier [
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark0000: 30 07 67 7D 1F 09 B6 E6 90 85 95 58 94 37 FD 31 0.g........X.7.1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark0010: 03 D4 56 7B ..V.
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkTrust this certificate? [no]:</computeroutput> <userinput>yes</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Certificate was added to keystore</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Import the signed certificate from the CA reply into the keystore
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark where you generated the server certificate.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In this example the certificate from the reply is
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <filename>~/Downloads/server-cert.crt</filename>.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>keytool \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -trustcacerts \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -alias server-cert \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -storepass changeit \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -keypass changeit</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Certificate reply was installed in keystore</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Configure the File Based Key Manager Provider for JKS to use the file
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark name and key store PIN that you set up with the <command>keytool</command>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark command.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-key-manager-provider-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --provider-name JKS \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set enabled:true \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set key-store-pin:changeit \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark Configure the File Based Trust Manager Provider.
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark By convention and by default,
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark the OpenDJ File Based Trust Manager Provider uses a Java Key Store file,
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark to hold trusted public key certificates.
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark Follow these steps to set up the trust store file,
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark and to configure the trust manager provider.
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark <substeps>
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark If you imported your own CA certificate into the key store,
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark also import the file into the trust store.
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark$ <userinput>keytool \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark -trustcacerts \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark -alias ca-cert \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark -storepass changeit</userinput>
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark<computeroutput>Owner: EMAILADDRESS=admin@example.com, CN=Example CA, O=Example Corp, C=FR
fa45b27dca2b25b4974c90ff996278a3e4305fd1markIssuer: EMAILADDRESS=admin@example.com, CN=Example CA, O=Example Corp, C=FR
fa45b27dca2b25b4974c90ff996278a3e4305fd1markSerial number: d4586ea05c878b0c
fa45b27dca2b25b4974c90ff996278a3e4305fd1markValid from: Tue Jan 29 09:30:31 CET 2013 until: Mon Jan 24 09:30:31 CET 2033
fa45b27dca2b25b4974c90ff996278a3e4305fd1markCertificate fingerprints:
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark MD5: 8A:83:61:9B:E7:18:A2:21:CE:92:94:96:59:68:60:FA
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark SHA1: 01:99:18:38:3A:57:D7:92:7B:D6:03:8C:7B:E4:1D:37:45:0E:29:DA
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark SHA256: 5D:20:F1:86:CC:CD:64:50:...:DF:15:43:07:69:44:00:FB:36:CF
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark Signature algorithm name: SHA1withRSA
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark Version: 3
fa45b27dca2b25b4974c90ff996278a3e4305fd1markExtensions:
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark#1: ObjectId: 2.5.29.35 Criticality=false
fa45b27dca2b25b4974c90ff996278a3e4305fd1markAuthorityKeyIdentifier [
fa45b27dca2b25b4974c90ff996278a3e4305fd1markKeyIdentifier [
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark0000: 30 07 67 7D 1F 09 B6 E6 90 85 95 58 94 37 FD 31 0.g........X.7.1
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark0010: 03 D4 56 7B ..V.
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark[EMAILADDRESS=admin@example.com, CN=Example CA, O=Example Corp, C=FR]
fa45b27dca2b25b4974c90ff996278a3e4305fd1markSerialNumber: [ d4586ea0 5c878b0c]
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark#2: ObjectId: 2.5.29.19 Criticality=false
fa45b27dca2b25b4974c90ff996278a3e4305fd1markBasicConstraints:[
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark PathLen:2147483647
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark#3: ObjectId: 2.5.29.14 Criticality=false
fa45b27dca2b25b4974c90ff996278a3e4305fd1markSubjectKeyIdentifier [
fa45b27dca2b25b4974c90ff996278a3e4305fd1markKeyIdentifier [
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark0000: 30 07 67 7D 1F 09 B6 E6 90 85 95 58 94 37 FD 31 0.g........X.7.1
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark0010: 03 D4 56 7B ..V.
fa45b27dca2b25b4974c90ff996278a3e4305fd1markTrust this certificate? [no]:</computeroutput> <userinput>yes</userinput>
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark<computeroutput>Certificate was added to keystore</computeroutput>
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark Import the signed server certificate into the trust store.
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark$ <userinput>keytool \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark -trustcacerts \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark -alias server-cert \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark -storepass changeit \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark -keypass changeit</userinput>
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark<computeroutput>Certificate was added to keystore</computeroutput>
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark Configure the File Based Trust Manager Provider to use the trust store.
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-trust-manager-provider-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --provider-name JKS \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set enabled:true \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set trust-store-pin:changeit \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark </substeps>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>At this point, OpenDJ directory server can use your new CA-signed
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark certificate, for example for StartTLS and LDAPS connection handlers.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If you use a CA certificate that is not known to clients, such as a
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark CA that you set up yourself rather than a well-known CA whose certificate
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark is included with the client system, import the CA certificate into the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark client application trust store. Otherwise the client application cannot
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark trust the signature on the OpenDJ CA-signed server certificate.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <title>To Create & Install a Self-Signed Certificate</title>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If you choose to configure LDAP Secure Access when setting up OpenDJ
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark directory server, the setup program generates a key pair in the Java Key
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Store <filename>/path/to/opendj/config/keystore</filename>, and self-signs
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the public key certificate, which has the alias <literal>server-cert</literal>.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark The password for the key store and the private key is stored in clear text
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark in the file <filename>/path/to/opendj/config/keystore.pin</filename>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If you want to secure communications, but did not chose to configure
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark LDAP Secure Access at setup time, this procedure can help. The following
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark steps explain how to create and install a key pair with a self-signed
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark certificate in preparation to configure LDAPS or HTTPS. First you create a
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark key pair in a new Java Key Store, and then self-sign the certificate. Next,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark you set up the Key Manager Provider and Trust Manager Provider to access
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the new server certificate in the new key store.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If instead you want to <emphasis>replace the existing server key pair
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark with self-signed certificate</emphasis>, then first use <command>keytool
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -delete -alias server-cert</command> to delete the existing keys before you
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark generate a new key pair with the same alias. You can also either reuse the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark existing password in <filename>keystore.pin</filename>, or use a new password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark as shown in the steps below.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Generate the server certificate using the Java
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>keytool \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -alias server-cert \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -keyalg rsa \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark -ext "san=dns:opendj.example.com" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -dname "CN=opendj.example.com,O=Example Corp,C=FR" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -storepass changeit \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -keypass changeit</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In this example, OpenDJ is running on a system with fully qualified
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark host name <literal>opendj.example.com</literal>. The Java Key Store (JKS)
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark is created in the <filename>config</filename> directory where OpenDJ is
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark installed, which is the default value for JKS.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <option>-keypass</option> options take identical password arguments.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark OpenDJ requires that you use the same password to protect both the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark key store and also the private key.</para>
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark If the server can respond on multiple FQDNs,
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark then specify multiple subject alternative names
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark In the following example
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark the primary FQDN is <literal>opendj.example.com</literal>
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark and the alternative is <literal>ldap.example.com</literal>.
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark$ <userinput>keytool \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark -alias server-cert \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark -keyalg rsa \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark -ext "san=dns:opendj.example.com,dns:ldap.example.com" \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark -dname "CN=opendj.example.com,O=Example Corp,C=FR" \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark -storepass changeit \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark -keypass changeit</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Keep track of the password provided to the <option>-storepass</option>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>keytool \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -selfcert \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -alias server-cert \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -storepass changeit</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Configure the File Based Key Manager Provider for JKS to access the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Java Key Store with key store/private key password.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In this example, the alias is <literal>server-cert</literal> and the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If you are replacing a key pair with a self-signed certificate,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark reusing the <literal>server-cert</literal> alias and password stored in
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <filename>keystore.pin</filename>, then you can skip this step.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>echo changeit > /path/to/opendj/config/keystore.pin</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>chmod 600 /path/to/opendj/config/keystore.pin</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-key-manager-provider-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --provider-name JKS \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set enabled:true \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark Configure the File Based Trust Manager Provider for JKS
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark to use the new server certificate.
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark By convention and by default,
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark the OpenDJ File Based Trust Manager Provider uses a Java Key Store file,
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark to hold trusted public key certificates.
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark Follow these steps to set up the trust store file,
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark and to configure the trust manager provider.
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark <substeps>
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark Set up a trust store containing the server's public key certificate.
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark$ <userinput>keytool \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark -alias server-cert \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark -storepass changeit \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark<computeroutput>Certificate stored in file <server-cert.crt></computeroutput>
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark$ <userinput>keytool \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark -trustcacerts \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark -alias server-cert \
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark -storepass changeit</userinput>
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark<computeroutput>...
fa45b27dca2b25b4974c90ff996278a3e4305fd1markTrust this certificate? [no]: </computeroutput><userinput>yes</userinput>
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark<computeroutput>Certificate was added to keystore</computeroutput>
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark Configure the trust manager provider to use the trust store.
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark$ <userinput>echo changeit > /path/to/opendj/config/truststore.pin</userinput>
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark$ <userinput>chmod 600 /path/to/opendj/config/truststore.pin</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-trust-manager-provider-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --provider-name JKS \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set enabled:true \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
fa45b27dca2b25b4974c90ff996278a3e4305fd1mark </substeps>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>At this point, OpenDJ directory server can use your new self-signed
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark certificate, for example for StartTLS and LDAPS or HTTPS connection
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark handlers.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <title>LDAP Client Access With Transport Layer Security</title>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>StartTLS (Transport Layer Security) negotiations start on the unsecure
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark LDAP port, and then protect communication with the client. You can opt to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark configure StartTLS during installation, or later using the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Make sure you have a server certificate installed.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>keytool \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -alias server-cert \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -storepass `cat /path/to/opendj/config/keystore.pin`</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>server-cert, Jun 17, 2013, PrivateKeyEntry,
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkCertificate fingerprint (SHA1): 92:B7:4C:4F:2E:24:...:EB:7C:22:3F</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Activate StartTLS on the current LDAP port.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-connection-handler-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --handler-name "LDAP Connection Handler" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set allow-start-tls:true \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set key-manager-provider:JKS \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set trust-manager-provider:JKS \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The change takes effect. No need to restart the server.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You configure LDAPS (LDAP/SSL) client access by using the command-line
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark tool <command>dsconfig</command>. You can opt to configure LDAPS access
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark when you install.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The standard port number for LDAPS client access is 636. If you
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark install OpenDJ directory server as a user who can use port 636 and the port
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark is not yet in use, then 636 is the default port number presented at
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark installation time. If you install as a user who cannot use a port < 1024,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark then the default port number presented at installation time is 1636.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Make sure you have a server certificate installed.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>keytool \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -alias server-cert \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -storepass `cat /path/to/opendj/config/keystore.pin`</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>server-cert, Jun 17, 2013, PrivateKeyEntry,
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkCertificate fingerprint (SHA1): 92:B7:4C:4F:2E:24:...:EB:7C:22:3F</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Configure the server to activate LDAPS access.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-connection-handler-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --handler-name "LDAPS Connection Handler" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set listen-port:1636 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set enabled:true \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set use-ssl:true \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>This example changes the port number to 1636 in the configuration.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Change the port number using the <command>dsconfig</command>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark command.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-connection-handler-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --handler-name "LDAPS Connection Handler" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set listen-port:11636 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>This example changes the port number to 11636 in the configuration.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Restart the connection handler so the change takes effect.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para> To restart the connection handler, you disable it, then enable
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark it again.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-connection-handler-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --handler-name "LDAPS Connection Handler" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set enabled:false \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-connection-handler-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --handler-name "LDAPS Connection Handler" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set enabled:true \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm><primary>Access control</primary></indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Using the OpenDJ directory server global configuration properties, you
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark can add global restrictions on how clients access the server. These settings
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark are per server, and so much be set independently on each server in replication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark topology.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>These global settings are fairly coarse-grained. For a full discussion
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark of the rich set of administrative privileges and fine-grained access control
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark instructions that OpenDJ supports, see the chapter on <link
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Privileges & Access Control</citetitle></link>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <variablelist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Consider the following global configuration settings.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
ec40cc0dc62425cea5d63fd9d984f8614479de25mark xlink:href="${configRefBase}global.html#bind-with-dn-requires-password"
ec40cc0dc62425cea5d63fd9d984f8614479de25mark ><literal>bind-with-dn-requires-password</literal></link></term>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Whether the directory server should reject any simple bind request
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark that contains a DN but no password. Default: <literal>true</literal></para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>To change this setting use the following command.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-global-configuration-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set bind-with-dn-requires-password:false \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
ec40cc0dc62425cea5d63fd9d984f8614479de25mark xlink:href="${configRefBase}global.html#max-allowed-client-connections"
ec40cc0dc62425cea5d63fd9d984f8614479de25mark ><literal>max-allowed-client-connections</literal></link></term>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Restricts the number of concurrent client connections to the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark directory server. Default: 0, meaning no limit is set</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>To set a limit of 32768 use the following command.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-global-configuration-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set max-allowed-client-connections:32768 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
ec40cc0dc62425cea5d63fd9d984f8614479de25mark xlink:href="${configRefBase}global.html#reject-unauthenticated-requests"
ec40cc0dc62425cea5d63fd9d984f8614479de25mark ><literal>reject-unauthenticated-requests</literal></link></term>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Rejects any request (other than bind or StartTLS requests) received
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark from a client that has not yet been authenticated, whose last
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark authentication attempt was unsuccessful, or whose last authentication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark attempt used anonymous authentication. Default: <literal>false</literal></para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>To shut down anonymous binds use the following command.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-global-configuration-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set reject-unauthenticated-requests:true \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
ec40cc0dc62425cea5d63fd9d984f8614479de25mark xlink:href="${configRefBase}global.html#return-bind-error-messages"
ec40cc0dc62425cea5d63fd9d984f8614479de25mark ><literal>return-bind-error-messages</literal></link></term>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Does not restrict access, but by default prevents OpenDJ directory
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark server from returning extra information about why a bind failed, as that
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark information could be used by an attacker. Instead, the information is
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark written to the server errors log. Default: <literal>false</literal></para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>To have OpenDJ return additional information about why a bind failed
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark use the following command.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-global-configuration-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set return-bind-error-messages:true \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </variablelist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>By default OpenDJ supports the SSL and TLS protocols and the cipher
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark suites supported by the underlying Java virtual machine. For details see the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark documentation for the Java virtual machine in which you run OpenDJ. For Oracle
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Java, see the <citetitle>Java Cryptography Architecture Oracle Providers
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Documentation</citetitle> for the <link xlink:show="new"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:href="http://docs.oracle.com/javase/7/docs/technotes/guides/security/SunProviders.html#SunJSSEProvider"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark >The <literal>SunJSSE</literal> Provider</link>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>To list the available protocols and cipher suites, read the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>supportedTLSCiphers</literal> attributes of the root DSE. Install
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark unlimited strength Java cryptography extensions for stronger ciphers.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch --port 1389 --baseDN "" --searchScope base "(objectclass=*)" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark supportedTLSCiphers supportedTLSProtocols</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: TLS_RSA_WITH_AES_128_CBC_SHA256
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: TLS_RSA_WITH_AES_128_CBC_SHA
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: TLS_ECDH_RSA_WITH_AES_128_CBC_SHA
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: TLS_DHE_RSA_WITH_AES_128_CBC_SHA
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: TLS_DHE_DSS_WITH_AES_128_CBC_SHA
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: TLS_ECDHE_ECDSA_WITH_RC4_128_SHA
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: TLS_ECDHE_RSA_WITH_RC4_128_SHA
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: SSL_RSA_WITH_RC4_128_SHA
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: TLS_ECDH_ECDSA_WITH_RC4_128_SHA
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: TLS_ECDH_RSA_WITH_RC4_128_SHA
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: SSL_RSA_WITH_3DES_EDE_CBC_SHA
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: SSL_RSA_WITH_RC4_128_MD5
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSCiphers: TLS_EMPTY_RENEGOTIATION_INFO_SCSV
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSProtocols: SSLv2Hello
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSProtocols: SSLv3
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSProtocols: TLSv1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksupportedTLSProtocols: TLSv1.1
08248b5c5b494aff8d1922e8e0b5777796d7450dmarksupportedTLSProtocols: TLSv1.2</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You can restrict the list of protocols and cipher suites used by setting
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the <literal>ssl-protocol</literal> and <literal>ssl-cipher-suite</literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark connection handler properties to include only the protocols or cipher suites
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark you want.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>For example, to restrict the cipher suites to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>TLS_EMPTY_RENEGOTIATION_INFO_SCSV</literal> and
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>TLS_RSA_WITH_AES_256_CBC_SHA</literal> use the <command>dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-connection-handler-prop</command> command as shown in the following
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark example.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-connection-handler-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --handler-name "LDAPS Connection Handler" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --add ssl-cipher-suite:TLS_EMPTY_RENEGOTIATION_INFO_SCSV \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --add ssl-cipher-suite:TLS_RSA_WITH_AES_256_CBC_SHA \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <orderedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ offers two ways to give RESTful client applications HTTP access
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to directory data as JSON resources.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Enable the listener on OpenDJ directory server to respond
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to REST requests.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>With this approach, you do not need to install additional
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark software.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Configure the external REST LDAP gateway Servlet to access your
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark directory service.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>With this approach, you must install the gateway separately.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </orderedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <procedure xml:id="setup-rest2ldap-connection-handler">
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <title>To Set Up REST Access to OpenDJ Directory Server</title>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ directory server has a handler for HTTP connections, where it
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark exposes the RESTful API demonstrated in the chapter on
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <link xlink:href="admin-guide#chap-rest-operations" xlink:show="new"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Performing
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark RESTful Operations</citetitle></link>. The HTTP connection handler is not
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark enabled by default.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You configure the mapping between JSON resources and LDAP entries
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark by editing the configuration file for the HTTP connection handler, by
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark default <filename>/path/to/opendj/config/http-config.json</filename>. The
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark configuration is described in the appendix, <link xlink:show="new"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:role="http://docbook.org/xlink/role/olink"><citetitle>REST LDAP
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Configuration</citetitle></link>. The default mapping works out of the box
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark with Example.com data generated as part of the setup process and with
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <link xlink:show="new" xlink:href="http://opendj.forgerock.org/Example.ldif"
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-connection-handler-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --handler-name "HTTP Connection Handler" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set enabled:true \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-log-publisher-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --publisher-name "File-Based HTTP Access Logger" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set enabled:true \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>This enables the HTTP access log,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <filename>opendj/logs/http-access</filename>. For details on the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark format of the HTTP access log, see the section on <link xlink:show="new"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The HTTP connection handler paths start by default at the root
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark context, as shown in the following example.</para>
11c8879df183d75f9c77c3d31a385d29dc530120mark$ <userinput>curl http://bjensen:hifalutin@opendj.example.com:8080/users/bjensen</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_rev" : "00000000315fb731",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "schemas" : [ "urn:scim:schemas:core:1.0" ],
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "manager" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "trigden",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Torrey Rigden"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "contactInformation" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "telephoneNumber" : "+1 408 555 1862",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "emailAddress" : "bjensen@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "bjensen",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "name" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "familyName" : "Jensen",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "givenName" : "Barbara"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "bjensen@example.com",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Barbara Jensen"
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If necessary, change the connection handler configuration using the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example shows how to set the port to 8443, and to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark configure the connection handler to do SSL (using the default server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark certificate). If you did not generate a default, self-signed certificate
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark when installing OpenDJ directory server see the instructions, <link
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:show="new" xlink:href="admin-guide#new-self-signed-cert"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:role="http://docbook.org/xlink/role/olink"><citetitle>To Create &
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Install a Self-Signed Certificate</citetitle></link>, and more generally the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Preparing For
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Secure Communications</citetitle></link> for additional instructions
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark including how to import a CA-signed certificate.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-trust-manager-provider-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --provider-name "Blind Trust" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set enabled:true \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-connection-handler-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --handler-name "HTTP Connection Handler" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set listen-port:8443 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set use-ssl:true \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set key-manager-provider:JKS \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set trust-manager-provider:"Blind Trust" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Stopping Server...
08248b5c5b494aff8d1922e8e0b5777796d7450dmark.... The Directory Server has started successfully</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>keytool \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -alias server-cert \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Certificate stored in file <server-cert.pem></computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>curl \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --user bjensen:hifalutin \
11c8879df183d75f9c77c3d31a385d29dc530120mark https://opendj.example.com:8443/users/bjensen</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>{
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_rev" : "0000000018c8b685",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "schemas" : [ "urn:scim:schemas:core:1.0" ],
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "contactInformation" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "telephoneNumber" : "+1 408 555 1862",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "emailAddress" : "bjensen@example.com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "bjensen",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "name" : {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "familyName" : "Jensen",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "givenName" : "Barbara"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "userName" : "bjensen@example.com",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Barbara Jensen",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "manager" : [ {
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "_id" : "trigden",
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "displayName" : "Torrey Rigden"
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark Notice the <option>--cacert server-cert.pem</option> option
08248b5c5b494aff8d1922e8e0b5777796d7450dmark This is the way to specify a self-signed server certificate
08248b5c5b494aff8d1922e8e0b5777796d7450dmark when using HTTPS.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Follow these steps to set up OpenDJ REST LDAP gateway Servlet to access
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark your directory service.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Download and install the gateway as described in <link
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:role="http://docbook.org/xlink/role/olink"><citetitle>To Install
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Adjust the configuration for your directory service as described in
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:role="http://docbook.org/xlink/role/olink"><citetitle>REST LDAP
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Directory Services Markup Language (DSML) client access is implemented
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark as a servlet that runs in a web application container.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You configure DSML client access by editing the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <filename>WEB-INF/web.xml</filename> after you deploy the web
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark application. In particular, you must at least set the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>ldap.host</literal> and <literal>ldap.port</literal> parameters
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark if they differ from the default values, which are
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>localhost</literal> and <literal>389</literal>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <variablelist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The list of DSML configuration parameters, including those that are
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark optional, consists of the following.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Required parameter indicating the host name of the underlying
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark directory server. Default: <literal>localhost</literal>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Required parameter indicating the LDAP port of the underlying
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark directory server. Default: 389.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Optional parameter specifying the DN used by the DSML gateway to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark bind to the underlying directory server. Not used by default.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Optional parameter specifying the password used by the DSML gateway
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to bind to the underlying directory server. Not used by default.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>This parameter can help you set up the DSML gateway to do HTTP
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Basic Access Authentication, given the appropriate mapping between the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark user ID, and the user's entry in the directory.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Required boolean parameter specifying whether the HTTP Authorization
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark header field's Basic credentials in the request hold a plain ID, rather
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark than a DN. If set to <literal>true</literal>, then the gateway performs an
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark LDAP SASL bind using SASL plain, enabled by default in OpenDJ to look for
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark an exact match between a <literal>uid</literal> value and the plain ID
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark value from the header. In other words, if the plain ID is
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>bjensen</literal>, and that corresponds in the directory server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to Babs Jensen's entry with DN
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>uid=bjensen,ou=people,dc=example,dc=com</literal>, then the bind
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark happens as Babs Jensen. Note also that you can configure OpenDJ identity
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark mappers for scenarios that use a different attribute than
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>uid</literal>, such as the <literal>mail</literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark attribute.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Required parameter indicating whether <literal>ldap.port</literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark points to a port listening for LDAPS (LDAP/SSL) traffic. Default:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Required parameter indicating whether to use StartTLS to connect
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to the specified <literal>ldap.port</literal>. Default:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Required parameter indicating whether blindly to trust all
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark certificates presented to the DSML gateway when using secure connections
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark (LDAPS or StartTLS). Default: <literal>false</literal>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Optional parameter indicating the trust store used to verify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark certificates when using secure connections. If you want to connect
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark using LDAPS or StartTLS, and do not want the gateway blindly to trust
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark all certificates, then you must set up a trust store. Not used by
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark default.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <term><literal>ldap.truststore.password</literal></term>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Optional parameter indicating the trust store password. If you
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set up and configure a trust store, then you need to set this as well.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Not used by default.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </variablelist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The DSML servlet translates between DSML and LDAP, and passes requests
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to the directory server. For initial testing purposes, you might try
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <link xlink:href="http://jxplorer.org/">JXplorer</link>, where DSML Service:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark /<replaceable>webapp-dir</replaceable>/DSMLServlet. Here,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <replaceable>webapp-dir</replaceable> refers to the name of the directory
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark in which you unpacked the DSML .war file.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <imageobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <imagedata fileref="images/JXplorer-dsml.png" format="PNG" />
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </imageobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <caption><para>JXplorer accessing OpenDJ through DSML</para></caption>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </mediaobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You configure Java Management Extensions (JMX) client access by using
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the command-line tool, <command>dsconfig</command>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Configure the server to activate JMX access.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-connection-handler-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --handler-name "JMX Connection Handler" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set enabled:true \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>This example uses the default port number, 1689.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Restart the server so the change takes effect.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>After you set up OpenDJ directory server to listen for JMX connections,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark you must assign privileges in order to allow a user to connect over
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark protocol.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Assign the privileges, <literal>jmx-notify</literal>,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>jmx-read</literal>, and <literal>jmx-write</literal> as
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark necessary to the user who connects over JMX.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>See the section on <link xlink:href="admin-guide#configure-privileges"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Connect using the service URI, user name, and password.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <variablelist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Full URI to the service including the hostname or IP address
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark and port number for JMX where OpenDJ directory server listens for
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark connections. For example, if the server IP is
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>192.168.0.10</literal> and you configured OpenDJ to listen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark for JMX connections on port 1689, then the service URI is
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>service:jmx:rmi:///jndi/rmi://192.168.0.10:1689/org.opends.server.protocols.jmx.client-unknown</literal>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The full DN of the user with privileges to connect over JMX such
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark as <literal>uid=kvaughan,ou=People,dc=example,dc=com</literal>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </variablelist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The LDIF connection handler lets you make changes to directory data
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark by placing LDIF in a file system directory that OpenDJ server regularly
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark polls for changes. The LDIF, once consumed, is deleted.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You configure LDIF file access by using the command-line tool
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-connection-handler-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --handler-name "LDIF Connection Handler" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set enabled:true \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Add the directory where you put LDIF to be processed.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>mkdir /path/to/opendj/config/auto-process-ldif</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>This example uses the default value of the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>ldif-directory</literal> property for the LDIF connection
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark handler.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>For instructions on setting up the SNMP Connection Handler, see the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark section, <link xlink:href="admin-guide#snmp-monitoring"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:role="http://docbook.org/xlink/role/olink"><citetitle>SNMP-Based
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>