From ff8f7a57618c615b2b12db1ca9982fbd47ba19b4 Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Thu, 25 Jun 2015 15:58:19 +0000
Subject: [PATCH] CR-7396 OPENDJ-2095 Improve aci targetcontrol doc
---
opendj-sdk/opendj-server-legacy/src/main/docbkx/admin-guide/chap-privileges-acis.xml | 38 +++++++++
opendj-sdk/opendj-server-legacy/src/main/docbkx/server-dev-guide/chap-ldap-operations.xml | 153 +++++++++++++++++++++++++++++++++-----
2 files changed, 169 insertions(+), 22 deletions(-)
diff --git a/opendj-sdk/opendj-server-legacy/src/main/docbkx/admin-guide/chap-privileges-acis.xml b/opendj-sdk/opendj-server-legacy/src/main/docbkx/admin-guide/chap-privileges-acis.xml
index b406c52..0402d72 100644
--- a/opendj-sdk/opendj-server-legacy/src/main/docbkx/admin-guide/chap-privileges-acis.xml
+++ b/opendj-sdk/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>
diff --git a/opendj-sdk/opendj-server-legacy/src/main/docbkx/server-dev-guide/chap-ldap-operations.xml b/opendj-sdk/opendj-server-legacy/src/main/docbkx/server-dev-guide/chap-ldap-operations.xml
index 9adcaa7..cb86eb3 100644
--- a/opendj-sdk/opendj-server-legacy/src/main/docbkx/server-dev-guide/chap-ldap-operations.xml
+++ b/opendj-sdk/opendj-server-legacy/src/main/docbkx/server-dev-guide/chap-ldap-operations.xml
@@ -1400,23 +1400,153 @@
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>
+  
+ </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
application the access rights and privileges to use proxied authorization.
The default access control for OpenDJ lets authenticated users
use the proxied authorization control.</para>
-
+
<para>Suppose also that when directory administrator, Kirsten Vaughan, logs
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,
--
Gitblit v1.10.0