CR-7396 OPENDJ-2095 Improve aci targetcontrol doc

Mark Craig

25.58.2015 18658270ef5faba47b0f165c1b83956329d1d839

CR-7396 OPENDJ-2095 Improve aci targetcontrol doc

This patch clarifies that to use controls (and extops),
an ACI granting read access is required.

This patch also tries to further clarify what the right to
the proxy auth control means.

 opendj-server-legacy/src/main/docbkx/admin-guide/chap-privileges-acis.xml

@@ -251,6 +251,12 @@
     <listitem>
      <para>Replace <replaceable>OID</replaceable> with the object identifier
      for the LDAP control to target. Separate multiple OIDs with ||.</para>

      <para>
       To use an LDAP control, the bind DN user must have
       <literal>allow(read)</literal> permissions.
      </para>

      <para>This target cannot be restricted to a specific subtree by combining
      it with another target.</para>
     </listitem>
@@ -260,6 +266,12 @@
     <listitem>
      <para>Replace <replaceable>OID</replaceable> with the object identifier
      for the extended operation to target. Separate multiple OIDs with ||.</para>

      <para>
       To use an LDAP extended operation, the bind DN user must have
       <literal>allow(read)</literal> permissions.
      </para>

      <para>This target cannot be restricted to a specific subtree by combining
      it with another target.</para>
     </listitem>
@@ -342,7 +354,9 @@
    <varlistentry>
     <term><literal>read</literal></term>
     <listitem>
      <para>Read entries and attributes</para>
      <para>
       Read entries and attributes, or use an LDAP control or extended operation
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
@@ -721,6 +735,28 @@
      </programlisting>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>Use Control or Extended Operation</term>
     <listitem>
      <para>
       The ACI must allow the <literal>read</literal> permission
       to the <literal>targetcontrol</literal> or <literal>extop</literal> OIDs.
      </para>

      <para>
       For example, the ACI required to allow
       <literal>uid=bjensen,ou=People,dc=example,dc=com</literal>
       to use the Persistent Search Request Control with OID
       <literal>2.16.840.1.113730.3.4.3</literal> is:
      </para>

      <programlisting language="ldif">
aci: (targetcontrol = "2.16.840.1.113730.3.4.3")(version 3.0;acl
 "Request Persistent Search"; allow (read)(userdn =
 "ldap:///uid=bjensen,ou=People,dc=example,dc=com");)
      </programlisting>
     </listitem>
    </varlistentry>
   </variablelist>
  </section>
 </section>

 opendj-server-legacy/src/main/docbkx/server-dev-guide/chap-ldap-operations.xml

@@ -1400,6 +1400,84 @@
  authorization, for example, to bind your application with its credentials,
  then carry out operations as the users who login to the application.</para>
  
  <para>
   Proxied authorization is similar to the UNIX <command>sudo</command> command.
   The proxied operation is performed as if it were requested
   not by the user who did the bind, but by the proxied user.
   <xref linkend="proxy-authz-permissions" /> shows how this affects permissions.
  </para>

  <table xml:id="proxy-authz-permissions">
   <title>Whether Proxy Authorization Allows an Operation on the Target</title>

   <tgroup cols="3">
    <colspec colnum="1" colwidth="1*" />
    <colspec colnum="2" colwidth="1*" />
    <colspec colnum="3" colwidth="1*" />

    <thead>
     <row>
      <entry>
       &#160;
      </entry>

      <entry>
       Bind DN no access
      </entry>

      <entry>
       Bind DN has access
      </entry>
     </row>
    </thead>

    <tbody>
     <row>
      <entry>
       <emphasis role="bold">Proxy ID no access</emphasis>
      </entry>

      <entry>
       No
      </entry>

      <entry>
       No
      </entry>
     </row>

     <row>
      <entry>
       <emphasis role="bold">Proxy ID has access</emphasis>
      </entry>

      <entry>
       Yes
      </entry>

      <entry>
       Yes
      </entry>
     </row>
    </tbody>
   </tgroup>
  </table>

  <note>
   <para>
    When you configure resource limits as described in the chapter on
    <link
     xlink:href="admin-guide#chap-resource-limits"
     xlink:role="http://docbook.org/xlink/role/olink"
     xlink:show="new"
    ><citetitle>Setting Resource Limits</citetitle></link>,
    know that the resource limits do not change
    when the user proxies as another user.
    In other words, resource limits depend on the bind DN,
    not the proxy authorization identity.
   </para>
  </note>

  <para>Suppose you have an administrative directory client application that
  has an entry in the directory with DN
  <literal>cn=My App,ou=Apps,dc=example,dc=com</literal>. You can give that
@@ -1411,12 +1489,64 @@
  in to your application to change Babs Jensen's entry, your application looks
  up Kirsten's entry, and finds that she has DN
  <literal>uid=kvaughan,ou=People,dc=example,dc=com</literal>. For the example
  commands in the following procedure. My App uses proxied authorization to
  commands in <xref linkend="setup-proxied-authz" />
  My App uses proxied authorization to
  make a change to Babs's entry as Kirsten.</para>
  
  <procedure xml:id="setup-proxied-authz">
   <title>To Configure Proxied Authorization</title>

   <itemizedlist>
    <para>
     In order to carry out LDAP operations on behalf of another user,
     the user binding to OpenDJ directory server needs:
    </para>

    <listitem>
     <para>
      Permission to use the LDAP Proxy Authorization Control.
     </para>

     <para>
      Permissions are granted using access control instructions (ACIs).
      This calls for an ACI with a <literal>targetcontrol</literal> list
      that includes the Proxy Authorization Control OID
      <literal>2.16.840.1.113730.3.4.18</literal>
      that grants <literal>allow(read)</literal> permission
      to the user binding to the directory.
     </para>
    </listitem>

    <listitem>
     <para>
      Permission to proxy as the given authorization user.
     </para>

     <para>
      This calls for an ACI with
      a target scope that includes the entry of the authorization user
      that grants <literal>allow(proxy)</literal> permission
      to the user binding to the directory.
     </para>
    </listitem>

    <listitem>
     <para>
      The privilege to use proxied authorization.
     </para>

     <para>
      Privileges are granted using the <literal>ds-privilege-name</literal> attribute.
     </para>
    </listitem>
   </itemizedlist>

   <para>
    Follow these steps to configure proxied authorization
    for applications with DNs that match
    <literal>cn=*,ou=Apps,dc=example,dc=com</literal>.
   </para>

   <step performance="optional">
    <para>
     If the global ACIs do not allow access to use the Proxy Authorization Control,
@@ -1502,25 +1632,6 @@
   </step>
  </procedure>

  <note>
   <para>
    When you configure resource limits as described in the chapter on
    <link
     xlink:href="admin-guide#chap-resource-limits"
     xlink:role="http://docbook.org/xlink/role/olink"
     xlink:show="new"
    ><citetitle>Setting Resource Limits</citetitle></link>,
    know that the resource limits do not change
    when the user proxies as another user.
    In other words, resource limits depend on the bind DN,
    not the proxy authorization identity.
    In the examples in the procedure <xref linkend="setup-proxied-authz" />
    the resource limits would be those set for
    <literal>cn=My App,ou=Apps,dc=example,dc=com</literal>,
    not <literal>uid=kvaughan,ou=People,dc=example,dc=com</literal>.
   </para>
  </note>

  <para>If you need to map authorization identifiers using the
  <literal>u:</literal> form rather than using <literal>dn:</literal>, you can
  set the identity mapper with the global configuration setting,