CR-1403 Fix for OPENDJ-811: Update REST LDAP gateway doc for DN reference m...

Mark Craig

12.17.2013 407e0cf52bfc29a9fb93101f59c26a2018e93c4a

CR-1403 Fix for OPENDJ-811: Update REST LDAP gateway doc for DN reference mapping & other config changes

 opendj3/pom.xml

@@ -102,6 +102,7 @@
    <currentServerVersion>2.5.0-SNAPSHOT</currentServerVersion>
    <stableServerVersion>2.4.6</stableServerVersion>
    <docTargetVersion>2.5.0</docTargetVersion>
    <sdkDocTargetVersion>3.0.0</sdkDocTargetVersion>
    <siteDistributionURL>scp://forgerock.org/var/www/vhosts/opendj.forgerock.org/httpdocs</siteDistributionURL>
    <i18nFrameworkVersion>1.4.0</i18nFrameworkVersion>
    <grizzlyFrameworkVersion>2.2.19</grizzlyFrameworkVersion>

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

@@ -167,13 +167,15 @@

          <listitem>
           <para>(Optional) "isRequired": true means the LDAP attribute is
           mandatory and must be provided to create the resource.</para>
            mandatory and must be provided to create the resource; false means
            it is optional.</para>
          </listitem>

          <listitem>
           <para>(Optional) "isSingleValued": true means represent a possibly
           multi-valued LDAP attribute as a single value, rather than an array
           of values.</para>
            of values; false means represent a multi-valued attribute as an
            array of values.</para>
          </listitem>

          <listitem>
@@ -221,14 +223,122 @@
        </listitem>
       </varlistentry>

       <!-- More to come?
       <varlistentry>
        <term></term>
         <term>"reference"</term>
        <listitem>
         <para></para>
          <para>Maps a JSON field to an LDAP entry found by reference.</para>

          <para>This mapping works for LDAP attributes whose values reference
          other entries. This is shown in the following example from the default
          configuration. The LDAP <literal>manager</literal> attribute values
          are user entry DNs. Here, the JSON <literal>manager</literal> field
          takes the user ID and name from the entry referenced by the LDAP
          attribute. On updates, changes to the JSON manager
          <literal>_id</literal> affect which manager entry is referenced, yet
          any changes to the manager's name are discarded, because changing
          managers only affects which user entry to point to, not the referenced
          user's name.</para>

          <programlisting language="javascript">{
    "manager": {
        "reference": {
            "ldapAttribute": "manager",
            "baseDN": "ou=people,dc=example,dc=com",
            "primaryKey": "uid",
            "mapper": {
                "object": {
                    "_id": {
                        "simple": {
                            "ldapAttribute": "uid",
                            "isSingleValued": true,
                            "isRequired": true
                        }
                    },
                    "displayName": {
                        "simple": {
                            "ldapAttribute": "cn",
                            "isSingleValued": true,
                            "writability": "readOnlyDiscardWrites"
                        }
                    }
                }
            }
        }
    }
}</programlisting>

          <para>Babs Jensen's manager in the sample LDAP data is Torrey Rigden,
          who has user ID <literal>trigden</literal>. Babs's entry has
          <literal>manager: uid=trigden,ou=People,dc=example,dc=com</literal>.
          With this mapping, the resulting JSON field is the following.</para>

          <programlisting language="javascript">{
    "manager": [
        {
            "_id": "trigden",
            "displayName": "Torrey Rigden"
        }
    ]
}</programlisting>

          <itemizedlist>
           <para>Reference mapping objects have the following fields.</para>

           <listitem>
            <para>(Required) "baseDN": indicates the base LDAP DN under which
            to find entries referenced by the JSON resource.</para>
           </listitem>

           <listitem>
            <para>(Required) "ldapAttribute": specifies the LDAP attribute in
            the entry underlying the JSON resource whose value points to the
            referenced entry.</para>
           </listitem>

           <listitem>
            <para>(Required) "mapper": describes how the referenced entry
            content maps to the content of this JSON field.</para>
           </listitem>

           <listitem>
            <para>(Required) "primaryKey": indicates which LDAP attribute in
            the mapper holds the primary key to the referenced entry.</para>
           </listitem>

           <listitem>
            <para>(Optional) "filter": specifies the LDAP filter to use to
            search for the referenced entry. The default is
            <literal>"(objectClass=*)"</literal>.</para>
           </listitem>

           <listitem>
            <para>(Optional) "isRequired": true means the LDAP attribute is
            mandatory and must be provided to create the resource; false means
            it is optional.</para>
           </listitem>

           <listitem>
            <para>(Optional) "isSingleValued": true means represent a possibly
            multi-valued LDAP attribute as a single value, rather than an array
            of values; false means represent a multi-valued attribute as an
            array of values.</para>
           </listitem>

           <listitem>
            <para>(Optional) "scope": indicates the scope of the LDAP search to
            find the referenced entry. The default is
            <literal>"SearchScope.WHOLE_SUBTREE"</literal>.</para>
           </listitem>

           <listitem>
            <para>(Optional) "writability": indicates whether the mapping
            supports updates, as described above for the simple mapping. The
            default is "readWrite".</para>
           </listitem>
          </itemizedlist>
        </listitem>
       </varlistentry>
       -->

       </variablelist>
      </listitem>
     </varlistentry>
@@ -353,7 +463,7 @@
     </varlistentry>
    </variablelist>

    <para>The default mapping exposes a SCIM view of sample data.</para>
    <para>The default mappings expose a SCIM view of user and group data.</para>

    <programlisting language="javascript">{
    "/users": {
@@ -381,7 +491,7 @@
                    "urn:scim:schemas:core:1.0"
                ]
            },
            "id": {
            "_id": {
                "simple": {
                    "ldapAttribute": "uid",
                    "isSingleValued": true,
@@ -389,7 +499,7 @@
                    "writability": "createOnly"
                }
            },
            "rev": {
            "_rev": {
                "simple": {
                    "ldapAttribute": "etag",
                    "isSingleValued": true,
@@ -427,6 +537,49 @@
                    }
                }
            },
            "manager": {
                "reference": {
                    "ldapAttribute": "manager",
                    "baseDN": "ou=people,dc=example,dc=com",
                    "primaryKey": "uid",
                    "mapper": {
                        "object": {
                            "_id": {
                                "simple": {
                                    "ldapAttribute": "uid",
                                    "isSingleValued": true,
                                    "isRequired": true
                                }
                            },
                            "displayName": {
                                "simple": {
                                    "ldapAttribute": "cn",
                                    "isSingleValued": true,
                                    "writability": "readOnlyDiscardWrites"
                                }
                            }
                        }
                    }
                }
            },
            "groups": {
                "reference": {
                    "ldapAttribute": "isMemberOf",
                    "baseDN": "ou=groups,dc=example,dc=com",
                    "writability": "readOnly",
                    "primaryKey": "cn",
                    "mapper": {
                        "object": {
                            "_id": {
                                "simple": {
                                    "ldapAttribute": "cn",
                                    "isSingleValued": true
                                }
                            }
                        }
                    }
                }
            },
            "contactInformation": {
                "object": {
                    "telephoneNumber": {
@@ -442,6 +595,115 @@
                        }
                    }
                }
            },
            "meta": {
                "object": {
                    "created": {
                        "simple": {
                            "ldapAttribute": "createTimestamp",
                            "isSingleValued": true,
                            "writability": "readOnly"
                        }
                    },
                    "lastModified": {
                        "simple": {
                            "ldapAttribute": "modifyTimestamp",
                            "isSingleValued": true,
                            "writability": "readOnly"
                        }
                    }
                }
            }
        }
    },
    "/groups": {
        "baseDN": "ou=groups,dc=example,dc=com",
        "readOnUpdatePolicy": "controls",
        "additionalLDAPAttributes": [
            {
                "type": "objectClass",
                "values": [
                    "top",
                    "groupOfUniqueNames"
                ]
            }
        ],
        "namingStrategy": {
            "strategy": "clientDNNaming",
            "dnAttribute": "cn"
        },
        "etagAttribute": "etag",
        "attributes": {
            "schemas": {
                "constant": [
                    "urn:scim:schemas:core:1.0"
                ]
            },
            "_id": {
                "simple": {
                    "ldapAttribute": "cn",
                    "isSingleValued": true,
                    "isRequired": true,
                    "writability": "createOnly"
                }
            },
            "_rev": {
                "simple": {
                    "ldapAttribute": "etag",
                    "isSingleValued": true,
                    "writability": "readOnly"
                }
            },
            "displayName": {
                "simple": {
                    "ldapAttribute": "cn",
                    "isSingleValued": true,
                    "isRequired": true,
                    "writability": "readOnly"
                }
            },
            "members": {
                "reference": {
                    "ldapAttribute": "uniqueMember",
                    "baseDN": "dc=example,dc=com",
                    "primaryKey": "uid",
                    "mapper": {
                        "object": {
                            "_id": {
                                "simple": {
                                    "ldapAttribute": "uid",
                                    "isSingleValued": true,
                                    "isRequired": true
                                }
                            },
                            "displayName": {
                                "simple": {
                                    "ldapAttribute": "cn",
                                    "isSingleValued": true,
                                    "writability": "readOnlyDiscardWrites"
                                }
                            }
                        }
                    }
                }
            },
            "meta": {
                "object": {
                    "created": {
                        "simple": {
                            "ldapAttribute": "createTimestamp",
                            "isSingleValued": true,
                            "writability": "readOnly"
                        }
                    },
                    "lastModified": {
                        "simple": {
                            "ldapAttribute": "modifyTimestamp",
                            "isSingleValued": true,
                            "writability": "readOnly"
                        }
                    }
                }
            }
        }
    }

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

@@ -150,7 +150,7 @@
 --header "Content-Type: application/json"
 --header "If-None-Match: *"
 --data '{
  "id": "newuser",
  "_id": "newuser",
  "contactInformation": {
    "telephoneNumber": "+1 408 555 1212",
    "emailAddress": "newuser@example.com"
@@ -159,23 +159,36 @@
    "familyName": "New",
    "givenName": "User"
  },
  "displayName": "New User"
  "displayName": "New User",
  "manager": [
    {
      "_id": "kvaughan",
      "displayName": "Kirsten Vaughan"
    }
  ]
 }'
 http://opendj.example.com:8080/rest2ldap/users/newuser?_prettyPrint=true
{
  "id" : "newuser",
  "rev" : "0000000049522179",
  "_rev" : "0000000037453cac",
  "schemas" : [ "urn:scim:schemas:core:1.0" ],
  "contactInformation" : {
    "telephoneNumber" : "+1 408 555 1212",
    "emailAddress" : "newuser@example.com"
  },
  "_id" : "newuser",
  "name" : {
    "familyName" : "New",
    "givenName" : "User"
  },
  "userName" : "newuser@example.com",
  "displayName" : "New User"
  "displayName" : "New User",
  "meta" : {
    "created" : "2013-03-11T16:49:42Z"
  },
  "manager" : [ {
    "_id" : "kvaughan",
    "displayName" : "Kirsten Vaughan"
  } ]
}</screen>
   </listitem>

@@ -194,19 +207,23 @@

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

@@ -241,11 +258,11 @@
  readability.</para>

  <para>TODO, fix pending https://bugster.forgerock.org/jira/browse/OPENDJ-775</para>
  <screen>$ curl
  <screen width="82">$ curl
 --request POST
 --header "Content-Type: application/json"
 --data '{
  "id": "newuser",
  "_id": "newuser",
  "contactInformation": {
    "telephoneNumber": "+1 408 555 1212",
    "emailAddress": "newuser@example.com"
@@ -254,25 +271,36 @@
    "familyName": "New",
    "givenName": "User"
  },
  "displayName": "New User"
}'
 http://opendj.example.com:8080/rest2ldap/users?_action=create&amp;_prettyPrint=true
  "displayName": "New User",
  "manager": [
{
  "id": "newuser",
  "rev": "0000000049522179",
  "schemas": [
    "urn:scim:schemas:core:1.0"
  ],
      "_id": "kvaughan",
      "displayName": "Kirsten Vaughan"
    }
  ]
}'
 "http://opendj.example.com:8080/rest2ldap/users?_action=create&amp;_prettyPrint=true"
{
  "_rev" : "0000000035383ca8",
  "schemas" : [ "urn:scim:schemas:core:1.0" ],
  "contactInformation": {
    "telephoneNumber": "+1 408 555 1212",
    "emailAddress": "newuser@example.com"
  },
  "_id" : "newuser",
  "name": {
    "familyName": "New",
    "givenName": "User"
  },
  "userName": "newuser@example.com",
  "displayName": "New User"
  "displayName" : "New User",
  "meta" : {
    "created" : "2013-03-11T16:56:22Z"
  },
  "manager" : [ {
    "_id" : "kvaughan",
    "displayName" : "Kirsten Vaughan"
  } ]
}</screen>

  <para>TODO, https://bugster.forgerock.org/jira/browse/OPENDJ-695</para>
@@ -319,19 +347,23 @@
  &amp;_prettyPrint=true'
{
  "result" : [ {
    "id" : "bjensen",
    "rev" : "000000002f43b789",
    "_rev" : "000000002ee3b764",
    "schemas" : [ "urn:scim:schemas:core:1.0" ],
    "contactInformation" : {
      "telephoneNumber" : "+1 408 555 1862",
      "emailAddress" : "bjensen@example.com"
    },
    "_id" : "bjensen",
    "name" : {
      "familyName" : "Jensen",
      "givenName" : "Barbara"
    },
    "userName" : "bjensen@example.com",
    "displayName" : "Barbara Jensen"
    "displayName" : "Barbara Jensen",
    "manager" : [ {
      "_id" : "trigden",
      "displayName" : "Torrey Rigden"
    } ]
  } ],
  "resultCount" : 1,
  "pagedResultsCookie" : null,
@@ -515,16 +547,27 @@
     <screen>$ curl 'http://opendj.example.com:8080/rest2ldap
 /users?_filter=userName%20pr&amp;_prettyPrint=true'
{
{
  "result" : [ {
    "id" : "abarnes",
    "rev" : "000000002609a565",
    "_rev" : "000000002370a4d8",
    "schemas" : [ "urn:scim:schemas:core:1.0" ],
    "contactInformation" : {
      "telephoneNumber" : "+1 408 555 9445",
      "emailAddress" : "abarnes@example.com"
    },
... many entries omitted ...
    "userName" : "fdupont@example.fr",
    "displayName" : "Frederique Dupont"
    "_id" : "newuser",
    "name" : {
      "familyName" : "New",
      "givenName" : "User"
    },
    "userName" : "newuser@example.com",
    "displayName" : "New User",
    "meta" : {
      "created" : "2013-03-11T16:56:22Z"
    }
  } ],
  "resultCount" : 151,
  "resultCount" : 152,
  "pagedResultsCookie" : null,
  "remainingPagedResults" : -1
}</screen>
@@ -540,8 +583,24 @@
     <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/users?_filter=true
... much output omitted ...</screen>
     <screen>$ curl 'http://opendj.example.com:8080/rest2ldap
 /groups?_filter=true&amp;_fields=displayName&amp;_prettyPrint=true'
{
  "result" : [ {
    "displayName" : "Accounting Managers"
  }, {
    "displayName" : "Directory Administrators"
  }, {
    "displayName" : "HR Managers"
  }, {
    "displayName" : "PD Managers"
  }, {
    "displayName" : "QA Managers"
  } ],
  "resultCount" : 5,
  "pagedResultsCookie" : null,
  "remainingPagedResults" : -1
}</screen>
    </listitem>
   </varlistentry>

@@ -553,23 +612,22 @@
     (not), using parentheses,
     <literal>(<replaceable>expression</replaceable>)</literal>, to group
     expressions. The following example queries resources with last name
     Jensen and first name starting with <literal>Bar</literal>. Notice that the
     filters use the JSON pointers <literal>name/familyName</literal> and
     <literal>name/givenName</literal> to identify the fields that are nested
     inside the <literal>name</literal> object.</para>
     Jensen and manager name starting with <literal>Bar</literal>. Notice that
     the filters use the JSON pointers <literal>name/familyName</literal> and
     <literal>manager/displayName</literal> to identify the fields that are
     nested inside the <literal>name</literal> and <literal>manager</literal>
     objects.</para>

     <screen>$ curl 'http://opendj.example.com:8080/rest2ldap
 /users?_filter=(name/familyName+eq+"jensen"+and+name/givenName+sw+"Bar")
 &amp;_fields=name
 &amp;_prettyPrint=true'
 /users?_filter=(userName+co+"jensen"+and+manager/displayName+sw+"Sam")
 &amp;_fields=displayName&amp;_prettyPrint=true'
{
  "result" : [ {
    "name" : {
      "familyName" : "Jensen",
      "givenName" : "Barbara"
    }
    "displayName" : "Jody Jensen"
  }, {
    "displayName" : "Ted Jensen"
  } ],
  "resultCount" : 1,
  "resultCount" : 2,
  "pagedResultsCookie" : null,
  "remainingPagedResults" : -1
}</screen>
@@ -590,21 +648,21 @@
   <varlistentry>
    <term><literal>__pagedResultsCookie=<replaceable>string</replaceable></literal></term>
    <listitem>
     <para></para>
     <para>TODO</para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>__pagedResultsOffset=<replaceable>string</replaceable></literal></term>
    <listitem>
     <para></para>
     <para>TODO</para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>__pagedResultsCookie=<replaceable>string</replaceable></literal></term>
    <listitem>
     <para></para>
     <para>TODO</para>
    </listitem>
   </varlistentry>
  </variablelist>

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

@@ -481,7 +481,7 @@

  <step>
   <para>Deploy
   <filename>opendj-rest2ldap-servlet-<?eval ${docTargetVersion}?>-servlet.war</filename>
   <filename>opendj-rest2ldap-servlet-<?eval ${sdkDocTargetVersion}?>-servlet.war</filename>
   according to the instructions for your application server.</para>
  </step>

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

   <para>If you generated example data, Babs Jensen's entry is not included.