CR-1768 Fix for OPENDJ-956: Finish documenting HTTPS for HTTP connection ha...

Mark Craig

05.49.2013 656f8f5a55b4a329afb1acabf11c2b0e118186da

CR-1768 Fix for OPENDJ-956: Finish documenting HTTPS for HTTP connection handler

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

@@ -55,19 +55,75 @@
  </listitem>
 </itemizedlist>

 <!-- To be updated, pending OPENDJ-828 -->
 <variablelist>
  <para>The JSON format configuration can hold the following configuration
  objects.</para>
  objects. Some of the configuration settings are available only in the REST
  LDAP gateway configuration. The order here is the order shown in the default
  configuration file.</para>

  <para>Interface stability: <link xlink:href="admin-guide#interface-stability"
  xlink:show="new" xlink:role="http://docbook.org/xlink/role/olink"
  >Evolving</link></para>

  <varlistentry>
   <term>"primaryLDAPServers" (required)</term>
   <term>"ldapConnectionFactories" (required, gateway only)</term>
   <listitem>
    <para>The gateway accesses this array of LDAP servers before failing over
    to the secondary LDAP servers. These might be LDAP servers in the same
    data center for example.</para>
    <para>Configures how the gateway connects to LDAP servers. This entire
    configuration object applies only to the REST LDAP gateway.</para>

    <programlisting language="javascript">{
    <variablelist>
     <para>Configures at least a connection factory for unauthenticated
     connections that are used for bind requests. By default, also configures a
     factory for authenticated connections that are used for searches during
     authentication and for proxied authorization operations.</para>

     <para>The default configuration is set to connect to a local directory
     server listening for LDAP connections on port 1389, authenticating as the
     root DN user <literal>cn=Directory Manager</literal>, with the password
     <literal>password</literal>.</para>

     <varlistentry>
      <term>"default"</term>
       <listitem>
        <para>Configures the unauthenticated connection factory for bind
        operations.</para>

        <variablelist>
         <varlistentry>
          <term>"connectionPoolSize" (optional)</term>
          <listitem>
           <para>The gateway creates connection pools to the primary and
           secondary LDAP servers that maintain up to
           <literal>connectionPoolSize</literal> connections to the
           servers.</para>

           <para>Default: 10</para>

           <programlisting language="javascript">"connectionPoolSize": 10</programlisting>
          </listitem>
         </varlistentry>

         <varlistentry>
          <term>"heartBeatIntervalSeconds" (optional)</term>
          <listitem>
           <para>The gateway tests its connections every
           <literal>heartBeatIntervalSeconds</literal> seconds to detect whether
           the connection is still alive.</para>

           <para>Default: 30 (seconds)</para>

           <programlisting language="javascript">"heartBeatIntervalSeconds": 30</programlisting>
          </listitem>
         </varlistentry>

         <varlistentry>
          <term>"primaryLDAPServers" (required)</term>
          <listitem>
           <para>The gateway accesses this array of LDAP servers before failing
           over to the secondary LDAP servers. These might be LDAP servers in
           the same data center for example.</para>

           <programlisting language="javascript">{
    "primaryLDAPServers": [
        {
            "hostname": "local1.example.com",
@@ -80,82 +136,534 @@
    ]
}</programlisting>

    <para>By default, the gateway connects to the directory server listening
    on port 1389 on the local host.</para>
   </listitem>
  </varlistentry>
           <para>By default, the gateway connects to the directory server
           listening on port 1389 on the local host.</para>
          </listitem>
         </varlistentry>

  <varlistentry>
   <!-- TODO: change when we get more authentication options. -->
   <term>"authentication" (required)</term>
   <listitem>
    <para>The gateway authenticates by simple bind using the credentials
    specified.</para>
         <varlistentry>
          <term>"secondaryLDAPServers" (optional)</term>
          <listitem>
           <para>The gateway accesses this array of LDAP servers if primary LDAP
           servers cannot be contacted. These might be LDAP servers in the same
           data center for example.</para>

    <programlisting language="javascript">{
           <programlisting language="javascript">{
    "secondaryLDAPServers": [
        {
            "hostname": "remote1.example.com",
            "port": 1389
        },
        {
            "hostname": "remote2.example.com",
            "port": 1389
        }
    ]
}</programlisting>

           <para>No secondary LDAP servers are configured by default.</para>
          </listitem>
         </varlistentry>
        </variablelist>
       </listitem>
     </varlistentry>

     <varlistentry>
      <term>"root"</term>
       <listitem>
        <para>Configures the authenticated connection factory.</para>

        <variablelist>
         <varlistentry>
          <term>"inheritFrom" (optional)</term>
          <listitem>
           <para>Identifies the unauthenticated connection factory from which
           to inherit settings. If this connection factory does not inherit from
           another configuration object, then you must specify the configuration
           here.</para>

           <para>Default: "default"</para>
          </listitem>
         </varlistentry>

         <varlistentry>
          <term>"authentication" (required)</term>
          <listitem>
           <para>The gateway authenticates by simple bind using the credentials
           specified.</para>

           <programlisting language="javascript">{
    "authentication": {
        "bindDN": "cn=Directory Manager",
        "password": "password"
    }
}</programlisting>
          </listitem>
         </varlistentry>
        </variablelist>
       </listitem>
     </varlistentry>
    </variablelist>
   </listitem>
  </varlistentry>

  <varlistentry>
   <term>"mappings"</term>
   <term>"authenticationFilter" (required)</term>
   <listitem>
    <para>For each gateway collection URI such as <literal>/users</literal> and
    <literal>/groups</literal>, you configure a mapping between the JSON
    resource returned by the gateway, and the LDAP entry returned by the
    directory service.</para>
    <para>Configures the REST LDAP authentication filter. If the configuration
    is not present, the filter is disabled.</para>

    <para>The default configuration allows HTTP Basic authentication where user
    entries are <literal>inetOrgPerson</literal> entries expected to have
    <literal>uid=<replaceable>username</replaceable></literal>, and to be found
    under <literal>ou=people,dc=example,dc=com</literal>. The default
    configuration also allows alternative, HTTP header based authentication in
    the style of OpenIDM.</para>

    <para>By default, authentication is required both for the gateway and for
    the HTTP connection handler. When the HTTP connection handler property
    <literal>authentication-required</literal> is set to
    <literal>false</literal> (default: <literal>true</literal>), the HTTP
    connection handler accepts both authenticated and unauthenticated requests.
    All requests are subject to access control and resource limit settings in
    the same way as LDAP client requests to the directory server. The
    <literal>authentication-required</literal> setting can be overridden by the
    global configuration property
    <literal>reject-unauthenticated-requests</literal> (default:
    <literal>false</literal>), described in the section on <link
    xlink:show="new" xlink:href="admin-guide#restrict-clients"
    xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Restricting
    Client Access</citetitle></link>.</para>

    <para>To protect passwords, configure HTTPS for the HTTP connection handler
    or for the container where the REST LDAP gateway runs.</para>

    <variablelist>
     <para>Each mapping has a number of configuration elements.</para>
     <para>The filter has the following configuration fields.</para>

     <varlistentry>
      <term>"baseDN" (required)</term>
      <listitem>
       <para>The base DN where LDAP entries are found for this mapping.</para>
      </listitem>
      <term>"supportHTTPBasicAuthentication"</term>
       <listitem>
        <para>Whether to support HTTP Basic authentication. If this is set to
        <literal>true</literal>, then the entry corresponding to the user name
        is found using the "searchBaseDN", "searchScope", and
        "searchFilterTemplate" settings.</para>

        <para>Default: <literal>true</literal></para>
       </listitem>
     </varlistentry>

     <varlistentry>
      <term>"attributes" (required)</term>
      <term>"supportAltAuthentication"</term>
       <listitem>
        <para>Whether to allow alternative, HTTP header based authentication. If
        this is set to <literal>true</literal>, then the headers to use are
        specified in the "altAuthenticationUsernameHeader" and
        "altAuthenticationPasswordHeader" values, and the bind DN is resolved
        using the "searchFilterTemplate" value.</para>

        <para>Default: <literal>true</literal></para>
       </listitem>
     </varlistentry>

     <varlistentry>
      <term>"altAuthenticationUsernameHeader"</term>
       <listitem>
        <para>Specifies the HTTP header containing the username for
        authentication when alternative, HTTP-header based authentication is
        allowed.</para>

        <para>Default: "X-OpenIDM-Username"</para>
       </listitem>
     </varlistentry>

     <varlistentry>
      <term>"altAuthenticationPasswordHeader"</term>
       <listitem>
        <para>Specifies the HTTP header containing the password for
        authentication when alternative, HTTP-header based authentication is
        allowed.</para>

        <para>Default: "X-OpenIDM-Password"</para>
       </listitem>
     </varlistentry>

     <varlistentry>
      <term>"reuseAuthenticatedConnection" (gateway only)</term>
       <listitem>
        <para>Whether to use authenticated LDAP connections for subsequent LDAP
        operations. If this is set to <literal>true</literal>, the gateway does
        not need its own connection factory, nor does it need to use proxied
        authorization for LDAP operations. Instead, it performs the operations
        as the user on the authenticated connection.</para>

        <para>Default: <literal>true</literal></para>
       </listitem>
     </varlistentry>

     <varlistentry>
      <term>"method" (gateway only)</term>
       <listitem>
        <para>Specifies the authentication method used by the gateway. The
        following values are supported.</para>

        <itemizedlist>
         <listitem>
          <para>"search-simple" (default) means the user name is resolved to
          an LDAP bind DN by a search using the "searchFilterTemplate" value.</para>
         </listitem>
         <listitem>
          <para>"sasl-plain" means the user name is resolved to an
          authorization ID (authzid) using the "saslAuthzIdTemplate" value.</para>
         </listitem>
         <listitem>
          <para>"simple" means the user name is the LDAP bind DN.</para>
         </listitem>
        </itemizedlist>
       </listitem>
     </varlistentry>

     <varlistentry>
      <term>"bindLDAPConnectionFactory" (gateway only)</term>
       <listitem>
        <para>Identifies the factory providing connections used for bind
        operations to authenticate users to LDAP servers.</para>

        <para>Default: "default"</para>
       </listitem>
     </varlistentry>

     <varlistentry>
      <term>"saslAuthzIdTemplate" (gateway only)</term>
       <listitem>
        <para>Sets how to resolve the authorization ID when the authentication
        "method" is set to "sasl-plain", substituting <literal>%s</literal>
        in the template with the user name provided. The user name provided by
        is DN escaped before the value is returned.</para>

        <para>Default: "dn:uid=%s,ou=people,dc=example,dc=com"</para>
       </listitem>
     </varlistentry>

     <varlistentry>
      <term>"searchLDAPConnectionFactory" (gateway only)</term>
       <listitem>
        <para>Identifies the factory providing connections used to find
        user entries in the directory server when the "method" is set to
        "search-simple".</para>

        <para>Default: "root"</para>
       </listitem>
     </varlistentry>

     <varlistentry>
      <term>"searchBaseDN"</term>
       <listitem>
        <para>Sets the base DN to search for user entries. For the gateway,
        this applies when the "method" is set to "search-simple". This always
        applies for the HTTP connection handler.</para>

        <para>Default: "ou=people,dc=example,dc=com"</para>
       </listitem>
     </varlistentry>

     <varlistentry>
      <term>"searchScope"</term>
       <listitem>
        <para>Sets the search scope below the base DN such as "sub" (subtree
        search) or "one" (one-level search) to search for user entries. For the
        gateway, this applies when the "method" is set to "search-simple". This
        always applies for the HTTP connection handler.</para>

        <para>Default: "sub"</para>
       </listitem>
     </varlistentry>

     <varlistentry>
      <term>"searchFilterTemplate"</term>
       <listitem>
        <para>Sets the search filter used to find the user entry, substituting
        <literal>%s</literal> in the template with the user name provided. The
        user name provided by is DN escaped before the value is returned. For
        the gateway, this applies when the "method" is set to "search-simple".
        This always applies for the HTTP connection handler.</para>

        <para>Default: "(&amp;(objectClass=inetOrgPerson)(uid=%s))"</para>
       </listitem>
     </varlistentry>
    </variablelist>
   </listitem>
  </varlistentry>

  <varlistentry>
   <term>"servlet" (required)</term>
   <listitem>
    <para>Configures how HTTP resources map to LDAP entries, and for the gateway
    how to connect to LDAP servers and how to use proxied authorization.</para>

    <para>The default gateway configuration tries to reuse authenticated
    connections for LDAP operations, falling back to a connection authenticated
    as root DN using proxied authorization for LDAP operations.</para>

    <variablelist>
     <varlistentry>
      <term>"ldapConnectionFactory" (gateway only)</term>
       <listitem>
        <para>Specifies the connection factory used by the gateway to perform
        LDAP operations if an authenticated connection is not passed from the
        authentication filter according to the setting for
        "reuseAuthenticatedConnection".</para>

        <para>Default: "root"</para>
       </listitem>
     </varlistentry>

     <varlistentry>
      <term>"authorizationPolicy" (gateway only)</term>
       <listitem>
        <para>Specifies how to handle LDAP authorization. The following values
        are supported.</para>

        <itemizedlist>
         <listitem>
          <para>"proxy" (default) means use proxied authorization when no
          authenticated connection is provided for reuse, resolving the
          authorization ID according to the setting for
          "proxyAuthzIdTemplate".</para>
         </listitem>

         <listitem>
          <para>"none" means do not use proxied authorization and do not reuse
          authenticated connections, but instead use connections from the
          factory specified in "ldapConnectionFactory".</para>
         </listitem>

         <listitem>
          <para>"reuse" means reuse an authenticated connection passed by the
          filter, and fail if no connection was passed by the filter.</para>
         </listitem>
        </itemizedlist>
       </listitem>
     </varlistentry>

     <varlistentry>
      <term>"proxyAuthzIdTemplate" (gateway only)</term>
       <listitem>
        <para>Specifies the template to derive the authorization ID from the
        security context created during authentication. Use
        <literal>{dn}</literal> to indicate the user's bind DN or
        <literal>{id}</literal> to indicate the user name provided for
        authentication.</para>

        <para>Default: "dn:{dn}"</para>
       </listitem>
     </varlistentry>

     <varlistentry>
      <term>"mappings"</term>
      <listitem>
       <para>How the JSON resource fields map to attributes on LDAP
       entries, each taking the form "<replaceable>field-name</replaceable>":
       <replaceable>mapping-object</replaceable>. A number of
       <replaceable>mapping-object</replaceable>s are supported.</para>
       <para>For each collection URI such as <literal>/users</literal> and
       <literal>/groups</literal>, you configure a mapping between the JSON
       resource returned over HTTP, and the LDAP entry returned by the
       directory service.</para>

       <variablelist>
        <para>Each mapping has a number of configuration elements.</para>

        <varlistentry>
        <term>"constant"</term>
        <listitem>
         <para>Maps a single JSON attribute to a fixed value.</para>
         <term>"baseDN" (required)</term>
         <listitem>
          <para>The base DN where LDAP entries are found for this mapping.</para>
         </listitem>
        </varlistentry>

         <para>This can be useful as in the default case where each JSON
         resource "schemas" takes the SCIM URN, and so the value is not related
         to the underlying LDAP entries.</para>
        <varlistentry>
         <term>"readOnUpdatePolicy" (optional)</term>
         <listitem>
          <para>The policy used to read an entry before it is deleted, or to
          read an entry after it is added or modified. One of the following.</para>

         <programlisting language="javascript">{
          <itemizedlist>
           <listitem>
            <para>"controls": (default) use RFC 4527 read-entry controls to
            reflect the state of the resource at the time the update was
            performed.</para>
            <para>The directory service must support RFC 4527.</para>
           </listitem>

           <listitem>
            <para>"disabled": do not read the entry or return the resource on
            update.</para>
           </listitem>

           <listitem>
            <para>"search": perform an LDAP search to retrieve the entry before
            deletion or after it is added or modified.</para>
            <para>The JSON resource returned might differ from the LDAP entry
            that was updated.</para>
           </listitem>
          </itemizedlist>
         </listitem>
        </varlistentry>

        <varlistentry>
         <term>"useSubtreeDelete" (required)</term>
         <listitem>
          <para>Whether to use the LDAP Subtree Delete Request Control (OID:
          <literal>1.2.840.113556.1.4.805</literal>) for LDAP delete operations
          resulting from delete operations on resources.</para>

          <para>Default: <literal>false</literal>. The default configuration
          uses <literal>false</literal>.</para>

          <para>Set this to <literal>true</literal> if you want this behavior,
          if your directory server supports the control, and if clients that
          request delete operations have access to use the control.</para>
         </listitem>
        </varlistentry>

        <varlistentry>
         <term>"usePermissiveModify" (required)</term>
         <listitem>
          <para>Whether to use the LDAP Permissive Modify Request Control (OID:
          <literal>1.2.840.113556.1.4.1413</literal>) for LDAP modify operations
          resulting from patch and update operations on resources.</para>

          <para>Default: <literal>false</literal>. The default configuration
          uses <literal>true</literal>.</para>

          <para>Set this to <literal>false</literal> when using the gateway if
          your directory server does not support the control.</para>
         </listitem>
        </varlistentry>

        <varlistentry>
         <term>"etagAttribute" (optional)</term>
         <listitem>
          <para>The LDAP attribute to use for multi-version concurrency control
          (MVCC).</para>

         <para>Default: "etag"</para>
         </listitem>
        </varlistentry>

        <varlistentry>
         <term>"namingStrategy" (required)</term>
         <listitem>
          <para>The approach used to map LDAP entry names to JSON resources. The
          following naming strategies are supported.</para>

          <itemizedlist>
           <listitem>
            <para>RDN and resource ID are both derived from a single user
            attribute in the LDAP entry, as in the following example, where the
            <literal>uid</literal> attribute is the RDN and its value is the
            JSON resource ID.</para>

            <programlisting language="javascript">{
    "namingStrategy": {
        "strategy": "clientDNNaming",
        "dnAttribute": "uid"
    }
}</programlisting>
           </listitem>

           <listitem>
            <para>RDN and resource ID are derived from separate user attributes
            in the LDAP entry, as in the following example where the RDN
            attribute is <literal>uid</literal> but the JSON resource ID is the
            value of the <literal>mail</literal> attribute.</para>

            <programlisting language="javascript">{
    "namingStrategy": {
        "strategy": "clientNaming",
        "dnAttribute": "uid",
        "idAttribute": "mail"
    }
}</programlisting>
           </listitem>

           <listitem>
            <para>RDN is derived from a user attribute and the resource ID from
            an operational attribute in the LDAP entry, as in the following
            example, where the RDN attribute is <literal>uid</literal> but the
            JSON resource ID is the value of the <literal>entryUUID</literal>
            operational attribute.</para>

            <programlisting language="javascript">{
    "namingStrategy": {
        "strategy": "serverNaming",
        "dnAttribute": "uid",
        "idAttribute": "entryUUID"
    }
}</programlisting>
           </listitem>
          </itemizedlist>
         </listitem>
        </varlistentry>

        <varlistentry>
         <term>"additionalLDAPAttributes" (optional, but necessary)</term>
         <listitem>
          <para>LDAP attributes to include during LDAP add operations as an
          array of type-value lists, such as the following example.</para>

          <programlisting language="javascript">{
    "additionalLDAPAttributes": [
        {
            "type": "objectClass",
            "values": [
                "top",
                "person",
                "organizationalPerson",
                "inetOrgPerson"
            ]
        }
    ]
}</programlisting>

          <para>This configuration element is useful to set LDAP object classes
          for example, which are not present in JSON resources.</para>
         </listitem>
        </varlistentry>

        <varlistentry>
         <term>"attributes" (required)</term>
         <listitem>
          <para>How the JSON resource fields map to attributes on LDAP
          entries, each taking the form "<replaceable>field-name</replaceable>":
          <replaceable>mapping-object</replaceable>. A number of
          <replaceable>mapping-object</replaceable>s are supported.</para>

          <variablelist>
           <varlistentry>
           <term>"constant"</term>
           <listitem>
            <para>Maps a single JSON attribute to a fixed value.</para>

            <para>This can be useful as in the default case where each JSON
            resource "schemas" takes the SCIM URN, and so the value is not
            related to the underlying LDAP entries.</para>

            <programlisting language="javascript">{
    "schemas": {
        "constant": [
            "urn:scim:schemas:core:1.0"
        ]
    }
}</programlisting>
         </listitem>
        </varlistentry>
            </listitem>
           </varlistentry>

        <varlistentry>
         <term>"simple"</term>
         <listitem>
          <para>Maps a JSON field to an LDAP attribute.</para>
           <varlistentry>
            <term>"simple"</term>
            <listitem>
             <para>Maps a JSON field to an LDAP attribute.</para>

          <para>Simple mappings are used where the correspondence between JSON
          fields and LDAP attributes is one-to-one.</para>
             <para>Simple mappings are used where the correspondence between
             JSON fields and LDAP attributes is one-to-one.</para>

          <programlisting language="javascript">{
             <programlisting language="javascript">{
    "userName": {
        "simple": {
            "ldapAttribute": "mail",
@@ -165,97 +673,108 @@
    }
}</programlisting>

          <itemizedlist>
           <para>Simple mappings can take a number of fields.</para>
             <itemizedlist>
              <para>Simple mappings can take a number of fields.</para>

           <listitem>
            <para>(Required) "ldapAttribute": the name of LDAP attribute.</para>
           </listitem>
              <listitem>
               <para>(Required) "ldapAttribute": the name of LDAP attribute.</para>
              </listitem>

           <listitem>
            <para>(Optional) "defaultValue": the JSON value if no LDAP attribute
            is available on the entry.</para>
           </listitem>
              <listitem>
               <para>(Optional) "defaultValue": the JSON value if no LDAP
               attribute is available on the entry.</para>

           <listitem>
            <para>(Optional) "isBinary": true means the LDAP attribute is
            binary and the JSON field gets the base64-encoded value.</para>
           </listitem>
               <para>No default is set if this is omitted.</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) "isBinary": true means the LDAP attribute is
               binary and the JSON field gets the base64-encoded value.</para>

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

           <listitem>
            <para>(Optional) "writability": indicates whether the LDAP attribute
            supports updates. This field can take the following values.</para>
              <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>

            <itemizedlist>
             <listitem>
              <para>"createOnly": This attribute can be set only when the
              entry is created. Attempts to update this attribute thereafter
              result in errors.</para>
             </listitem>
             <listitem>
              <para>"createOnlyDiscardWrites": This attribute can be set only
              when the entry is created. Attempts to update this attribute
              thereafter do not result in errors. Instead the update value
              is discarded.</para>
             </listitem>
             <listitem>
              <para>"readOnly": This attribute cannot be updated. Attempts to
              update this attribute result in errors.</para>
             </listitem>
             <listitem>
              <para>"readOnlyDiscardWrites": This attribute cannot be updated.
              Attempts to update this attribute do not result in errors. Instead
              the update value is discarded.</para>
             </listitem>
             <listitem>
              <para>"readWrite": This attribute can be set at creation and
              updated thereafter.</para>
             </listitem>
            </itemizedlist>
           </listitem>
          </itemizedlist>
         </listitem>
        </varlistentry>
               <para>Default: <literal>false</literal></para>
              </listitem>

        <varlistentry>
         <term>"object"</term>
         <listitem>
          <para>Maps a JSON object to LDAP attributes.</para>
              <listitem>
               <para>(Optional) "isSingleValued": true means represent a
               possibly multi-valued LDAP attribute as a single value; false
               means represent it as an array of values.</para>

          <para>This mapping lets you create JSON objects whose fields themselves
          have mappings to LDAP attributes.</para>
         </listitem>
        </varlistentry>
               <para>Default: determine the representation based on the LDAP
               schema, so SINGLE-VALUE attributes take single values, and
               multi-valued attributes take arrays.</para>
              </listitem>

        <varlistentry>
         <term>"reference"</term>
         <listitem>
          <para>Maps a JSON field to an LDAP entry found by reference.</para>
              <listitem>
               <para>(Optional) "writability": indicates whether the LDAP
               attribute supports updates. This field can take the following
               values.</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>
               <itemizedlist>
                <listitem>
                 <para>"createOnly": This attribute can be set only when the
                 entry is created. Attempts to update this attribute thereafter
                 result in errors.</para>
                </listitem>
                <listitem>
                 <para>"createOnlyDiscardWrites": This attribute can be set only
                 when the entry is created. Attempts to update this attribute
                 thereafter do not result in errors. Instead the update value
                 is discarded.</para>
                </listitem>
                <listitem>
                 <para>"readOnly": This attribute cannot be written. Attempts to
                 write this attribute result in errors.</para>
                </listitem>
                <listitem>
                 <para>"readOnlyDiscardWrites": This attribute cannot be written.
                 Attempts to write this attribute do not result in errors.
                 Instead the value to write is discarded.</para>
                </listitem>
                <listitem>
                 <para>"readWrite": (default) This attribute can be set at
                 creation and updated thereafter.</para>
                </listitem>
               </itemizedlist>
              </listitem>
             </itemizedlist>
            </listitem>
           </varlistentry>

          <programlisting language="javascript">{
           <varlistentry>
            <term>"object"</term>
            <listitem>
             <para>Maps a JSON object to LDAP attributes.</para>

             <para>This mapping lets you create JSON objects whose fields
             themselves have mappings to LDAP attributes.</para>
            </listitem>
           </varlistentry>

           <varlistentry>
            <term>"reference"</term>
            <listitem>
             <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",
@@ -283,12 +802,12 @@
    }
}</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>
             <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">{
             <programlisting language="javascript">{
    "manager": [
        {
            "_id": "trigden",
@@ -297,193 +816,86 @@
    ]
}</programlisting>

          <itemizedlist>
           <para>Reference mapping objects have the following fields.</para>
             <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) "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) "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) "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>(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) "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) "isRequired": true means the LDAP attribute is
               mandatory and must be provided to create the resource; false
               means it is optional.</para>

           <listitem>
            <para>(Optional) "isSingleValued": true means represent a possibly
            multi-valued LDAP attribute as a single value; false means represent
            it as an array of values.</para>
           </listitem>
               <para>Default: <literal>false</literal></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) "isSingleValued": true means represent a
               possibly multi-valued LDAP attribute as a single value; false
               means represent it as an array of values.</para>

           <listitem>
            <para>(Optional) "writability": indicates whether the mapping
            supports updates, as described above for the simple mapping. The
            default is "readWrite".</para>
           </listitem>
          </itemizedlist>
               <para>Default: <literal>false</literal></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>

       </variablelist>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>"namingStrategy" (required)</term>
      <listitem>
       <para>The approach used to map LDAP entry names to JSON resources. One
       of the following.</para>

       <itemizedlist>
        <listitem>
         <para>RDN and resource ID are both derived from a single user attribute
         in the LDAP entry, as in the following example, where the
         <literal>uid</literal> attribute is the RDN and its value is the
         JSON resource ID.</para>

         <programlisting language="javascript">{
    "namingStrategy": {
        "strategy": "clientDNNaming",
        "dnAttribute": "uid"
    }
}</programlisting>
        </listitem>

        <listitem>
         <para>RDN and resource ID are derived from separate user attributes in
         the LDAP entry, as in the following example where the RDN attribute is
         <literal>uid</literal> but the JSON resource ID is the value of the
         <literal>mail</literal> attribute.</para>

         <programlisting language="javascript">{
    "namingStrategy": {
        "strategy": "clientNaming",
        "dnAttribute": "uid",
        "idAttribute": "mail"
    }
}</programlisting>
        </listitem>

        <listitem>
         <para>RDN is derived from a user attribute and the resource ID from an
         operational attribute in the LDAP entry, as in the following example,
         where the RDN attribute is <literal>uid</literal> but the JSON resource
         ID is the value of the <literal>entryUUID</literal> operational
         attribute.</para>

         <programlisting language="javascript">{
    "namingStrategy": {
        "strategy": "serverNaming",
        "dnAttribute": "uid",
        "idAttribute": "entryUUID"
    }
}</programlisting>
        </listitem>
       </itemizedlist>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>"additionalLDAPAttributes" (optional, but necessary)</term>
      <listitem>
       <para>LDAP attributes to include during LDAP add operations as an
       array of type-value lists, such as the following example.</para>
       <para>The default mappings expose a SCIM view of user and group
       data.</para>

       <programlisting language="javascript">{
    "additionalLDAPAttributes": [
        {
            "type": "objectClass",
            "values": [
                "top",
                "person",
                "organizationalPerson",
                "inetOrgPerson"
            ]
        }
    ]
}</programlisting>

       <para>This configuration element is useful to set LDAP object classes
       for example, which are not present in JSON resources.</para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>"etagAttribute" (optional)</term>
      <listitem>
       <para>The LDAP attribute to use for multi-version concurrency control
       (MVCC).</para>

      <para>Default: "etag"</para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>"readOnUpdatePolicy" (optional)</term>
      <listitem>
       <para>The policy used to read an entry before it is deleted, or to
       read an entry after it is added or modified. One of the following.</para>

       <itemizedlist>
        <listitem>
         <para>"controls": use RFC 4527 read-entry controls to reflect the
         state of the resource at the time the update was performed.</para>
         <para>The directory service must support RFC 4527.</para>
         <para>This is the default if no policy is specified.</para>
        </listitem>

        <listitem>
         <para>"disabled": do not read the entry or return the resource on
         update.</para>
        </listitem>

        <listitem>
         <para>"search": perform an LDAP search to retrieve the entry before
         deletion or after it is added or modified.</para>
         <para>The JSON resource returned might differ from the LDAP entry that
         was updated.</para>
        </listitem>
       </itemizedlist>
      </listitem>
     </varlistentry>
    </variablelist>

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

    <programlisting language="javascript">{
    "/users": {
        "baseDN": "ou=people,dc=example,dc=com",
        "readOnUpdatePolicy": "controls",
        "useSubtreeDelete": false,
        "usePermissiveModify": true,
        "etagAttribute": "etag",
        "namingStrategy": {
            "strategy": "clientDNNaming",
            "dnAttribute": "uid"
        },
        "additionalLDAPAttributes": [
            {
                "type": "objectClass",
@@ -495,11 +907,6 @@
                ]
            }
        ],
        "namingStrategy": {
            "strategy": "clientDNNaming",
            "dnAttribute": "uid"
        },
        "etagAttribute": "etag",
        "attributes": {
            "schemas": {
                "constant": [
@@ -634,6 +1041,13 @@
    "/groups": {
        "baseDN": "ou=groups,dc=example,dc=com",
        "readOnUpdatePolicy": "controls",
        "useSubtreeDelete": false,
        "usePermissiveModify": true,
        "etagAttribute": "etag",
        "namingStrategy": {
            "strategy": "clientDNNaming",
            "dnAttribute": "cn"
        },
        "additionalLDAPAttributes": [
            {
                "type": "objectClass",
@@ -643,11 +1057,6 @@
                ]
            }
        ],
        "namingStrategy": {
            "strategy": "clientDNNaming",
            "dnAttribute": "cn"
        },
        "etagAttribute": "etag",
        "attributes": {
            "schemas": {
                "constant": [
@@ -723,67 +1132,9 @@
        }
    }
}</programlisting>
   </listitem>
  </varlistentry>

  <!--
  <varlistentry>
   <term>"useSSL" (optional)</term>
   <listitem>
    <para>If the gateway connects with StartTLS or SSL to the directory
    service, then you must specify how it uses SSL.</para>
    <para>TODO: Not yet implemented.</para>
   </listitem>
  </varlistentry>
  -->

  <varlistentry>
   <term>"secondaryLDAPServers" (optional)</term>
   <listitem>
    <para>The gateway accesses this array of LDAP servers if primary LDAP
    servers cannot be contacted. These might be LDAP servers in the same
    data center for example.</para>

    <programlisting language="javascript">{
    "secondaryLDAPServers": [
        {
            "hostname": "remote1.example.com",
            "port": 1389
        },
        {
            "hostname": "remote2.example.com",
            "port": 1389
        }
    ]
}</programlisting>

    <para>No secondary LDAP servers are configured by default.</para>
   </listitem>
  </varlistentry>

  <varlistentry>
   <term>"connectionPoolSize" (optional)</term>
   <listitem>
    <para>The gateway creates connection pools to the primary and secondary
    LDAP servers that maintain up to <literal>connectionPoolSize</literal>
    connections to the servers.</para>

    <para>Default: 10</para>

    <programlisting language="javascript">"connectionPoolSize": 10</programlisting>
   </listitem>
  </varlistentry>

  <varlistentry>
   <term>"heartBeatIntervalSeconds" (optional)</term>
   <listitem>
    <para>The gateway tests its connections every
    <literal>heartBeatIntervalSeconds</literal> seconds to detect whether the
    connection is still alive.</para>

    <para>Default: 30 (seconds)</para>

    <programlisting language="javascript">"heartBeatIntervalSeconds": 30</programlisting>
      </listitem>
     </varlistentry>
    </variablelist>
   </listitem>
  </varlistentry>
 </variablelist>

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

@@ -640,8 +640,8 @@
  </procedure>
 </section>

 <section xml:id="restrict-ldap-clients">
  <title>Restricting LDAP Client Access</title>
 <section xml:id="restrict-clients">
  <title>Restricting Client Access</title>
  <indexterm><primary>Access control</primary></indexterm>

  <para>Using the OpenDJ directory server global configuration properties, you

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

@@ -128,7 +128,101 @@
 <section xml:id="authenticate-rest">
  <title>Authenticating Over REST</title>

  <para>TODO, https://bugster.forgerock.org/jira/browse/OPENDJ-828</para>
  <para>When you first try to get a resource that you can read as an LDAP
  entry with an anonymous search, you might be surprised that you must
  authenticate.</para>

  <screen>$ curl http://opendj.example.com:8080/users/bjensen?_prettyPrint=true
{
  "code" : 401,
  "reason" : "Unauthorized",
  "message" : "Unauthorized"
}</screen>

  <para>HTTP status code 401 tells your HTTP client that the request requires
  user authentication. You can change this behavior by setting the HTTP
  connection handler property, <literal>authentication-required</literal>,
  to <literal>false</literal>.</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 authentication-required:false
 --no-prompt
 --trustAll</screen>

  <para>Out of the box both the HTTP Connection Handler and also the REST LDAP
  gateway are configured to allow HTTP Basic authentication and HTTP header
  based authentication in the style of OpenIDM. The authentication mechanisms
  translate HTTP authentication to LDAP authentication on the directory server
  side.</para>

  <para>When you install OpenDJ either with generated sample user entries or
  with data from <link xlink:href="http://opendj.forgerock.org/Example.ldif"
  xlink:show="new">Example.ldif</link>, the relative distinguished name
  attribute for the sample user entries is the user ID (<literal>uid</literal>)
  attribute. For example, the DN and user ID for Babs Jensen are as
  follows.</para>

  <programlisting language="ldif">dn: uid=bjensen,ou=People,dc=example,dc=com
uid: bjensen</programlisting>

  <para>Given this pattern in the user entries, the default REST to LDAP
  configuration assumes that the user name on the HTTP side is the value of
  the user ID, and that user entries can be found under
  <literal>ou=People,dc=example,dc=com</literal>. In other words, Babs Jensen
  authenticates as <literal>bjensen</literal> (password:
  <literal>hifalutin</literal>) over HTTP. This is mapped for an LDAP bind
  to the bind DN <literal>uid=bjensen,ou=People,dc=example,dc=com</literal>.</para>

  <para>With HTTP Basic authentication, it looks like this.</para>

  <screen>$ curl
 --user bjensen:hifalutin
 http://opendj.example.com:8080/users/bjensen?_prettyPrint=true
{
  "_rev" : "0000000016cbb68c",
  ...
}</screen>

  <para>Or, using the HTTP Basic
  <replaceable>username</replaceable>:<replaceable>password</replaceable>@ form
  in the URL, it looks like this.</para>

  <screen>$ curl
http://bjensen:hifalutin@opendj.example.com:8080/users/bjensen?_prettyPrint=true
{
  "_rev" : "0000000016cbb68c",
  ...
}</screen>

  <para>With HTTP header based authentication, it looks like this.</para>

  <screen>$ curl
 --header "X-OpenIDM-Username: bjensen"
 --header "X-OpenIDM-Password: hifalutin"
 http://opendj.example.com:8080/users/bjensen?_prettyPrint=true
{
  "_rev" : "0000000016cbb68c",
  ...
}</screen>

  <para>If your directory data are laid out differently, or if your user names
  are email addresses rather than user IDs for example, then you must update
  the configuration in order for authentication to work.</para>

  <para>The REST LDAP gateway can also translate HTTP user name and password
  authentication to PLAIN SASL authentication on the LDAP side. Moreover, the
  gateway can fall back to proxied authorization as necessary, using a root DN
  authenticated connection to LDAP servers. See <link xlink:show="new"
  xlink:href="admin-guide#appendix-rest2ldap"
  xlink:role="http://docbook.org/xlink/role/olink"><citetitle>REST LDAP
  Configuration</citetitle></link> for details on all configuration
  choices.</para>
 </section>

 <section xml:id="create-rest">