CR-1475 Fix for OPENDJ-829: Document how to configure the commons REST base...

Mark Craig

26.42.2013 a8904ae7dedca654b3d04166f41ecbe1754681a3

CR-1475 Fix for OPENDJ-829: Document how to configure the commons REST based HTTP connection handler

 opendj3/src/main/docbkx/admin-guide/appendix-ports-used.xml

@@ -80,6 +80,15 @@
    traffic on port 1689 by default. JMX is not enabled by default.</para>
   </listitem>
  </varlistentry>
  <varlistentry xml:id="http-port">
   <term>HTTP: 8080</term>
   <listitem>
    <indexterm><primary>Ports</primary><secondary>8080</secondary></indexterm>
    <para>OpenDJ directory server can listen for HTTP client requests to the
    RESTful API. The default port is 8080, but HTTP access is not enabled by
    default.</para>
   </listitem>
  </varlistentry>
  <varlistentry xml:id="repl-port">
   <term>Replication: 8989</term>
   <listitem>

 opendj3/src/main/docbkx/admin-guide/appendix-rest2ldap.xml

@@ -29,16 +29,33 @@
          xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
          xmlns:xlink='http://www.w3.org/1999/xlink'
          xmlns:xinclude='http://www.w3.org/2001/XInclude'>
 <title>REST LDAP Gateway Configuration</title>
 <indexterm><primary>REST LDAP gateway</primary></indexterm>
 <title>REST LDAP Configuration</title>
 <indexterm><primary>REST</primary></indexterm>
 <indexterm><primary>HTTP</primary></indexterm>
 <!-- This belongs in an OpenDJ reference. Ultimately this doc should
      be generated, too, rather than written by hand. CREST-71? -->

 <para>The OpenDJ REST LDAP gateway runs as a Servlet independent from your
 directory service. You configure the gateway to access your directory service
 by editing <filename>opendj-rest2ldap-servlet.json</filename> where you deploy
 the gateway web application.</para>
 <itemizedlist>
  <para>OpenDJ offers two alternatives for RESTful access to directory
  data.</para>

  <listitem>
   <para>OpenDJ directory server has an HTTP connection handler that exposes
   the RESTful API over HTTP (or HTTPS). You configure the mapping between
   JSON resources and LDAP entries by editing the configuration file for the
   HTTP connection handler, by default
   <filename>/path/to/OpenDJ/config/http-config.json</filename>.</para>
  </listitem>

  <listitem>
   <para>The OpenDJ REST LDAP gateway runs as a Servlet independent from your
   directory service. You configure the gateway to access your directory service
   by editing <filename>opendj-rest2ldap-servlet.json</filename> where you
   deploy the gateway web application.</para>
  </listitem>
 </itemizedlist>

 <!-- To be updated, pending OPENDJ-828 -->
 <variablelist>
  <para>The JSON format configuration can hold the following configuration
  objects.</para>

 opendj3/src/main/docbkx/admin-guide/chap-listeners.xml

@@ -818,6 +818,7 @@

 <section xml:id="setup-rest2ldap">
  <title>RESTful Client Access</title>
  <indexterm><primary>HTTP</primary></indexterm>
  <indexterm><primary>JSON</primary></indexterm>
  <indexterm><primary>REST</primary></indexterm>

@@ -826,7 +827,7 @@
   to directory data as JSON resources.</para>

   <listitem>
    <para>Configure an additional listener on the directory server to respond
    <para>Enable the listener on OpenDJ directory server to respond
    to REST requests.</para>

    <para>With this approach, you do not need to install additional
@@ -844,11 +845,94 @@
  <procedure xml:id="setup-rest2ldap-connection-handler">
   <title>To Set Up REST Access to OpenDJ Directory Server</title>

   <para>Follow these steps to configure a listener for REST access directly
   to an OpenDJ server.</para>
   <para>OpenDJ directory server has a handler for HTTP connections, where it
   exposes the RESTful API demonstrated in the chapter on
   <link xlink:href="admin-guide#chap-rest-operations" xlink:show="new"
   xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Performing
   RESTful Operations</citetitle></link>. The HTTP connection handler is not
   enabled by default.</para>

   <para>You configure the mapping between JSON resources and LDAP entries
   by editing the configuration file for the HTTP connection handler, by
   default <filename>/path/to/OpenDJ/config/http-config.json</filename>. The
   configuration is described in the appendix, <link xlink:show="new"
   xlink:href="admin-guide#appendix-rest2ldap"
   xlink:role="http://docbook.org/xlink/role/olink"><citetitle>REST LDAP
   Configuration</citetitle></link>.</para>

   <step>
    <para>TODO, https://bugster.forgerock.org/jira/browse/OPENDJ-688</para>
    <para>Enable the connection handler.</para>

    <screen>$ dsconfig
 set-connection-handler-prop
 --hostname opendj.example.com
 --port 4444
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --handler-name "HTTP Connection Handler"
 --set enabled:true
 --no-prompt</screen>

    <para>The HTTP connection handler paths start by default at the root
    context, as shown in the following example.</para>

    <screen>$ curl http://opendj.example.com:8080/users/bjensen?_prettyPrint=true
{
  "_rev" : "00000000315fb731",
  "schemas" : [ "urn:scim:schemas:core:1.0" ],
  "manager" : [ {
    "_id" : "trigden",
    "displayName" : "Torrey Rigden"
  } ],
  "contactInformation" : {
    "telephoneNumber" : "+1 408 555 1862",
    "emailAddress" : "bjensen@example.com"
  },
  "_id" : "bjensen",
  "name" : {
    "familyName" : "Jensen",
    "givenName" : "Barbara"
  },
  "userName" : "bjensen@example.com",
  "displayName" : "Barbara Jensen"
}</screen>
   </step>

   <step performance="optional">
    <para>If necessary, change the connection handler configuration using the
    <command>dsconfig</command> command.</para>

<!-- The example I would like to use does not quite work for me, yet.

    <para>The following example shows how to set the port to 8443, and to
    configure the connection handler to do SSL (using the default server
    certificate).</para>

    <screen>$ dsconfig
 set-connection-handler-prop
 - -hostname opendj.example.com
 - -port 4444
 - -bindDN "cn=Directory Manager"
 - -bindPassword password
 - -handler-name "HTTP Connection Handler"
 - -set listen-port:8443
 - -set use-ssl:true
 - -set key-manager-provider:JKS
 - -set trust-manager-provider:"Blind Trust"
 - -no-prompt
$ stop-ds - -restart
$ keytool
 -export
 -rfc
 -alias server-cert
 -keystore /path/to/OpenDJ/config/keystore
 -storepass `cat /path/to/OpenDJ/config/keystore.pin`
 -file server-cert.pem
Certificate stored in file &lt;server-cert.pem&gt;
$ curl - -cacert server-cert.pem https://opendj.example.com:8443/users/bjensen?_prettyPrint
curl: (35) error:140770FC:SSL routines:SSL23_GET_SERVER_HELLO:unknown protocol</screen>

-->
   </step>
  </procedure>

@@ -869,7 +953,7 @@
    <para>Adjust the configuration for your directory service as described in
    <link xlink:href="admin-guide#appendix-rest2ldap"
    xlink:role="http://docbook.org/xlink/role/olink"><citetitle>REST LDAP
    Gateway Configuration</citetitle></link>.</para>
    Configuration</citetitle></link>.</para>
   </step>
  </procedure>
 </section>

 opendj3/src/main/docbkx/admin-guide/chap-rest-operations.xml

@@ -30,18 +30,19 @@
         xmlns:xlink='http://www.w3.org/1999/xlink'
         xmlns:xinclude='http://www.w3.org/2001/XInclude'>
 <title>Performing RESTful Operations</title>
 <indexterm><primary>HTTP</primary></indexterm>
 <indexterm><primary>JSON</primary></indexterm>
 <indexterm><primary>REST</primary></indexterm>

 <para>OpenDJ lets you access directory data as JSON resources over HTTP. To
 configure this capability, see <link xlink:href="admin-guide#setup-rest2ldap"
 xlink:role="http://docbook.org/xlink/role/olink"><citetitle>REST Client
 Access</citetitle></link> for instructions.</para>

 <para>This chapter demonstrates basic RESTful client operations using the
 <para>OpenDJ lets you access directory data as JSON resources over HTTP.
 This chapter demonstrates basic RESTful client operations using the
 default configuration and sample directory data imported into OpenDJ from
 <link xlink:show="new" xlink:href="http://opendj.forgerock.org/Example.ldif"
 >Example.ldif</link>.</para>
 >Example.ldif</link>. Before trying the examples, enable HTTP access to
 OpenDJ directory server as described in procedure, <link xlink:show="new"
 xlink:href="admin-guide#setup-rest2ldap-connection-handler"
 xlink:role="http://docbook.org/xlink/role/olink"><citetitle>To Set Up REST
 Access to OpenDJ Directory Server</citetitle></link>.</para>

 <section xml:id="understand-rest">
  <title>Understanding the OpenDJ REST API</title>
@@ -127,7 +128,7 @@
 <section xml:id="authenticate-rest">
  <title>Authenticating Over REST</title>

  <para>TODO, https://bugster.forgerock.org/jira/browse/OPENDJ-694</para>
  <para>TODO, https://bugster.forgerock.org/jira/browse/OPENDJ-828</para>
 </section>

 <section xml:id="create-rest">
@@ -167,10 +168,14 @@
    }
  ]
 }'
 http://opendj.example.com:8080/rest2ldap/users/newuser?_prettyPrint=true
 http://opendj.example.com:8080/users/newuser?_prettyPrint=true
{
  "_rev" : "0000000037453cac",
  "_rev" : "0000000035c03ca9",
  "schemas" : [ "urn:scim:schemas:core:1.0" ],
  "manager" : [ {
    "_id" : "kvaughan",
    "displayName" : "Kirsten Vaughan"
  } ],
  "contactInformation" : {
    "telephoneNumber" : "+1 408 555 1212",
    "emailAddress" : "newuser@example.com"
@@ -183,12 +188,8 @@
  "userName" : "newuser@example.com",
  "displayName" : "New User",
  "meta" : {
    "created" : "2013-03-11T16:49:42Z"
  },
  "manager" : [ {
    "_id" : "kvaughan",
    "displayName" : "Kirsten Vaughan"
  } ]
    "created" : "2013-03-26T10:44:26Z"
  }
}</screen>
   </listitem>

@@ -205,10 +206,14 @@

  <para>To read a resource, perform an HTTP GET.</para>

  <screen>$ curl http://opendj.example.com:8080/rest2ldap/users/bjensen?_prettyPrint=true
  <screen>$ curl http://opendj.example.com:8080/users/bjensen?_prettyPrint=true
{
  "_rev" : "000000002ee3b764",
  "_rev" : "00000000315fb731",
  "schemas" : [ "urn:scim:schemas:core:1.0" ],
  "manager" : [ {
    "_id" : "trigden",
    "displayName" : "Torrey Rigden"
  } ],
  "contactInformation" : {
    "telephoneNumber" : "+1 408 555 1862",
    "emailAddress" : "bjensen@example.com"
@@ -219,11 +224,7 @@
    "givenName" : "Barbara"
  },
  "userName" : "bjensen@example.com",
  "displayName" : "Barbara Jensen",
  "manager" : [ {
    "_id" : "trigden",
    "displayName" : "Torrey Rigden"
  } ]
  "displayName" : "Barbara Jensen"
}</screen>
 </section>

@@ -278,11 +279,15 @@
      "displayName": "Kirsten Vaughan"
    }
  ]
}'
 "http://opendj.example.com:8080/rest2ldap/users?_action=create&amp;_prettyPrint=true"
 }'
 "http://opendj.example.com:8080/users?_action=create&amp;_prettyPrint=true"
{
  "_rev" : "0000000035383ca8",
  "_rev" : "00000000343b3ca6",
  "schemas" : [ "urn:scim:schemas:core:1.0" ],
  "manager" : [ {
    "_id" : "kvaughan",
    "displayName" : "Kirsten Vaughan"
  } ],
  "contactInformation" : {
    "telephoneNumber" : "+1 408 555 1212",
    "emailAddress" : "newuser@example.com"
@@ -295,12 +300,8 @@
  "userName" : "newuser@example.com",
  "displayName" : "New User",
  "meta" : {
    "created" : "2013-03-11T16:56:22Z"
  },
  "manager" : [ {
    "_id" : "kvaughan",
    "displayName" : "Kirsten Vaughan"
  } ]
    "created" : "2013-03-26T10:52:42Z"
  }
}</screen>

  <para>TODO, https://bugster.forgerock.org/jira/browse/OPENDJ-695</para>
@@ -310,8 +311,8 @@
  <title>Querying Resource Collections</title>

  <para>To query resource collections, perform an HTTP GET with a
  <literal>_filter=<replaceable>filter</replaceable></literal> parameter in
  your query string.</para>
  <literal>_queryFilter=<replaceable>filter</replaceable></literal> parameter
  in your query string.</para>

  <variablelist>
   <para>For query operations, your <replaceable>filter</replaceable>
@@ -342,13 +343,16 @@
        <para>Matches when the pointer equals the value, as in the following
        example.</para>

        <screen>$ curl 'http://opendj.example.com:8080/rest2ldap
/users?_filter=userName+eq+"bjensen@example.com"
  &amp;_prettyPrint=true'
        <screen>$ curl 'http://opendj.example.com:8080
 /users?_queryFilter=userName+eq+"bjensen@example.com"&amp;_prettyPrint=true'
{
  "result" : [ {
    "_rev" : "000000002ee3b764",
    "_rev" : "00000000315fb731",
    "schemas" : [ "urn:scim:schemas:core:1.0" ],
    "manager" : [ {
      "_id" : "trigden",
      "displayName" : "Torrey Rigden"
    } ],
    "contactInformation" : {
      "telephoneNumber" : "+1 408 555 1862",
      "emailAddress" : "bjensen@example.com"
@@ -359,11 +363,7 @@
      "givenName" : "Barbara"
    },
    "userName" : "bjensen@example.com",
    "displayName" : "Barbara Jensen",
    "manager" : [ {
      "_id" : "trigden",
      "displayName" : "Torrey Rigden"
    } ]
    "displayName" : "Barbara Jensen"
  } ],
  "resultCount" : 1,
  "pagedResultsCookie" : null,
@@ -378,10 +378,8 @@
        <para>Matches when the pointer contains the value, as in the following
        example.</para>

        <screen>$ curl 'http://opendj.example.com:8080/rest2ldap
 /users?_filter=userName+co+"jensen"
 &amp;_fields=userName
 &amp;_prettyPrint=true'
        <screen>$ curl 'http://opendj.example.com:8080
 /users?_queryFilter=userName+co+"jensen"&amp;_fields=userName&amp;_prettyPrint=true'
{
  "result" : [ {
    "userName" : "ajensen@example.com"
@@ -411,10 +409,8 @@
        <para>Matches when the pointer starts with the value, as in the
        following example.</para>

        <screen>$ curl 'http://opendj.example.com:8080/rest2ldap
 /users?_filter=userName+sw+"ab"
 &amp;_fields=userName
 &amp;_prettyPrint=true'
        <screen>$ curl 'http://opendj.example.com:8080
 /users?_queryFilter=userName+sw+"ab"&amp;_fields=userName&amp;_prettyPrint=true'
{
  "result" : [ {
    "userName" : "abarnes@example.com"
@@ -434,10 +430,8 @@
        <para>Matches when the pointer is less than the value, as in the
        following example.</para>

        <screen>$ curl 'http://opendj.example.com:8080/rest2ldap
 /users?_filter=userName+lt+"ac"
 &amp;_fields=userName
 &amp;_prettyPrint=true'
        <screen>$ curl 'http://opendj.example.com:8080
 /users?_queryFilter=userName+lt+"ac"&amp;_fields=userName&amp;_prettyPrint=true'
{
  "result" : [ {
    "userName" : "abarnes@example.com"
@@ -457,10 +451,8 @@
        <para>Matches when the pointer is less than or equal to the value, as
        in the following example.</para>

        <screen>$ curl 'http://opendj.example.com:8080/rest2ldap
 /users?_filter=userName+le+"ad"
 &amp;_fields=userName
 &amp;_prettyPrint=true'
        <screen>$ curl 'http://opendj.example.com:8080
 /users?_queryFilter=userName+le+"ad"&amp;_fields=userName&amp;_prettyPrint=true'
{
  "result" : [ {
    "userName" : "abarnes@example.com"
@@ -482,10 +474,8 @@
        <para>Matches when the pointer is greater than the value, as in the
        following example.</para>

        <screen>$ curl 'http://opendj.example.com:8080/rest2ldap
 /users?_filter=userName+gt+"tt"
 &amp;_fields=userName
 &amp;_prettyPrint=true'
        <screen>$ curl 'http://opendj.example.com:8080
 /users?_queryFilter=userName+gt+"tt"&amp;_fields=userName&amp;_prettyPrint=true'
{
  "result" : [ {
    "userName" : "ttully@example.com"
@@ -507,10 +497,8 @@
        <para>Matches when the pointer is greater than or equal to the value,
        as in the following example.</para>

        <screen>$ curl 'http://opendj.example.com:8080/rest2ldap
 /users?_filter=userName+ge+"tw"
 &amp;_fields=userName
 &amp;_prettyPrint=true'
        <screen>$ curl 'http://opendj.example.com:8080
 /users?_queryFilter=userName+ge+"tw"&amp;_fields=userName&amp;_prettyPrint=true'
{
  "result" : [ {
    "userName" : "tward@example.com"
@@ -544,18 +532,28 @@
     any resource on which the <replaceable>json-pointer</replaceable> is
     present, as in the following example.</para>

     <screen>$ curl 'http://opendj.example.com:8080/rest2ldap
 /users?_filter=userName%20pr&amp;_prettyPrint=true'
{
     <screen>$ curl 'http://opendj.example.com:8080
 /users?_queryFilter=userName%20pr&amp;_prettyPrint=true'
{
  "result" : [ {
    "_rev" : "000000002370a4d8",
    "_rev" : "000000002210a544",
    "schemas" : [ "urn:scim:schemas:core:1.0" ],
    "manager" : [ {
      "_id" : "scarter",
      "displayName" : "Sam Carter"
    } ],
    "contactInformation" : {
      "telephoneNumber" : "+1 408 555 9445",
      "emailAddress" : "abarnes@example.com"
    },
... many entries omitted ...
    "_id" : "abarnes",
    "name" : {
      "familyName" : "Barnes",
      "givenName" : "Anne-Louise"
    },
    "userName" : "abarnes@example.com",
    "displayName" : "Anne-Louise Barnes"
  },... many entries omitted ...
    "_id" : "newuser",
    "name" : {
      "familyName" : "New",
@@ -564,7 +562,7 @@
    "userName" : "newuser@example.com",
    "displayName" : "New User",
    "meta" : {
      "created" : "2013-03-11T16:56:22Z"
      "created" : "2013-03-26T10:52:42Z"
    }
  } ],
  "resultCount" : 152,
@@ -583,8 +581,8 @@
     <para>In other words you can list all resources in a collection as in the
     following example.</para>

     <screen>$ curl 'http://opendj.example.com:8080/rest2ldap
 /groups?_filter=true&amp;_fields=displayName&amp;_prettyPrint=true'
     <screen>$ curl 'http://opendj.example.com:8080
 /groups?_queryFilter=true&amp;_fields=displayName&amp;_prettyPrint=true'
{
  "result" : [ {
    "displayName" : "Accounting Managers"
@@ -618,8 +616,8 @@
     nested inside the <literal>name</literal> and <literal>manager</literal>
     objects.</para>

     <screen>$ curl 'http://opendj.example.com:8080/rest2ldap
 /users?_filter=(userName+co+"jensen"+and+manager/displayName+sw+"Sam")
     <screen>$ curl 'http://opendj.example.com:8080
 /users?_queryFilter=(userName+co+"jensen"+and+manager/displayName+sw+"Sam")
 &amp;_fields=displayName&amp;_prettyPrint=true'
{
  "result" : [ {

 opendj3/src/main/docbkx/install-guide/chap-install-cli.xml

@@ -470,12 +470,13 @@
  <indexterm><primary>REST LDAP gateway</primary></indexterm>

  <para>The OpenDJ REST LDAP gateway functions as a web application in a web
  application container, running independently of OpenDJ. <!-- Alternatively,
  you can add an HTTP listener directly to OpenDJ. See <link
  xlink:href="admin-guide#setup-rest2ldap"
  xlink:role="http://docbook.org/xlink/role/olink"><citetitle>REST Client
  Access</citetitle></link> for instructions.--> You configure the gateway
  to access your directory service by editing
  application container, running independently of OpenDJ. Alternatively,
  you can use the HTTP connection handler in OpenDJ directory server. See the
  procedure, <link xlink:href="admin-guide#setup-rest2ldap-connection-handler"
  xlink:role="http://docbook.org/xlink/role/olink"><citetitle>To Set Up REST
  Access to OpenDJ Directory Server</citetitle></link>, for instructions.</para>

  <para>You configure the gateway to access your directory service by editing
  <filename>opendj-rest2ldap-servlet.json</filename> where you deploy the
  gateway web application.</para>

@@ -496,7 +497,7 @@
   data. The default <literal>mappings</literal> are built to work with
   generated example data and also the sample content in <link xlink:show="new"
   xlink:href="http://opendj.forgerock.org/Example.ldif"
    >Example.ldif</link>.</para>
   >Example.ldif</link>.</para>

   <para>At minimum, make sure that the host name and port numbers for
   <literal>primaryLDAPServers</literal> are properly configured, that
@@ -507,7 +508,7 @@
   <para>For details on the configuration, see <link
   xlink:href="admin-guide#appendix-rest2ldap"
   xlink:role="http://docbook.org/xlink/role/olink"><citetitle>REST LDAP
   Gateway Configuration</citetitle></link>.</para>
   Configuration</citetitle></link>.</para>
  </step>

  <step>