From a8904ae7dedca654b3d04166f41ecbe1754681a3 Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Tue, 26 Mar 2013 17:42:11 +0000
Subject: [PATCH] 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 | 9 +
opendj3/src/main/docbkx/admin-guide/chap-rest-operations.xml | 152 ++++++++++++------------
opendj3/src/main/docbkx/admin-guide/appendix-rest2ldap.xml | 29 +++-
opendj3/src/main/docbkx/admin-guide/chap-listeners.xml | 94 ++++++++++++++
opendj3/src/main/docbkx/install-guide/chap-install-cli.xml | 17 +-
5 files changed, 205 insertions(+), 96 deletions(-)
diff --git a/opendj3/src/main/docbkx/admin-guide/appendix-ports-used.xml b/opendj3/src/main/docbkx/admin-guide/appendix-ports-used.xml
index 2579103..bdf9c3c 100644
--- a/opendj3/src/main/docbkx/admin-guide/appendix-ports-used.xml
+++ b/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>
diff --git a/opendj3/src/main/docbkx/admin-guide/appendix-rest2ldap.xml b/opendj3/src/main/docbkx/admin-guide/appendix-rest2ldap.xml
index 01d46b5..70fa564 100644
--- a/opendj3/src/main/docbkx/admin-guide/appendix-rest2ldap.xml
+++ b/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>
diff --git a/opendj3/src/main/docbkx/admin-guide/chap-listeners.xml b/opendj3/src/main/docbkx/admin-guide/chap-listeners.xml
index 98dae99..cda8388 100644
--- a/opendj3/src/main/docbkx/admin-guide/chap-listeners.xml
+++ b/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 <server-cert.pem>
+$ 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>
diff --git a/opendj3/src/main/docbkx/admin-guide/chap-rest-operations.xml b/opendj3/src/main/docbkx/admin-guide/chap-rest-operations.xml
index 149aad6..b8002ac 100644
--- a/opendj3/src/main/docbkx/admin-guide/chap-rest-operations.xml
+++ b/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&_prettyPrint=true"
+ }'
+ "http://opendj.example.com:8080/users?_action=create&_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"
- &_prettyPrint=true'
+ <screen>$ curl 'http://opendj.example.com:8080
+ /users?_queryFilter=userName+eq+"bjensen@example.com"&_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"
- &_fields=userName
- &_prettyPrint=true'
+ <screen>$ curl 'http://opendj.example.com:8080
+ /users?_queryFilter=userName+co+"jensen"&_fields=userName&_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"
- &_fields=userName
- &_prettyPrint=true'
+ <screen>$ curl 'http://opendj.example.com:8080
+ /users?_queryFilter=userName+sw+"ab"&_fields=userName&_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"
- &_fields=userName
- &_prettyPrint=true'
+ <screen>$ curl 'http://opendj.example.com:8080
+ /users?_queryFilter=userName+lt+"ac"&_fields=userName&_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"
- &_fields=userName
- &_prettyPrint=true'
+ <screen>$ curl 'http://opendj.example.com:8080
+ /users?_queryFilter=userName+le+"ad"&_fields=userName&_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"
- &_fields=userName
- &_prettyPrint=true'
+ <screen>$ curl 'http://opendj.example.com:8080
+ /users?_queryFilter=userName+gt+"tt"&_fields=userName&_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"
- &_fields=userName
- &_prettyPrint=true'
+ <screen>$ curl 'http://opendj.example.com:8080
+ /users?_queryFilter=userName+ge+"tw"&_fields=userName&_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&_prettyPrint=true'
-{
+ <screen>$ curl 'http://opendj.example.com:8080
+ /users?_queryFilter=userName%20pr&_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&_fields=displayName&_prettyPrint=true'
+ <screen>$ curl 'http://opendj.example.com:8080
+ /groups?_queryFilter=true&_fields=displayName&_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")
&_fields=displayName&_prettyPrint=true'
{
"result" : [ {
diff --git a/opendj3/src/main/docbkx/install-guide/chap-install-cli.xml b/opendj3/src/main/docbkx/install-guide/chap-install-cli.xml
index a084876..f9e429c 100644
--- a/opendj3/src/main/docbkx/install-guide/chap-install-cli.xml
+++ b/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>
--
Gitblit v1.10.0