<?xml version="1.0" encoding="UTF-8"?>
|
<!--
|
! CCPL HEADER START
|
!
|
! This work is licensed under the Creative Commons
|
! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
|
! To view a copy of this license, visit
|
! http://creativecommons.org/licenses/by-nc-nd/3.0/
|
! or send a letter to Creative Commons, 444 Castro Street,
|
! Suite 900, Mountain View, California, 94041, USA.
|
!
|
! You can also obtain a copy of the license at legal-notices/CC-BY-NC-ND.txt.
|
! See the License for the specific language governing permissions
|
! and limitations under the License.
|
!
|
! If applicable, add the following below this CCPL HEADER, with the fields
|
! enclosed by brackets "[]" replaced with your own identifying information:
|
! Portions Copyright [yyyy] [name of copyright owner]
|
!
|
! CCPL HEADER END
|
!
|
! Copyright 2011-2015 ForgeRock AS.
|
!
|
-->
|
<chapter xml:id='chap-controls'
|
xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
|
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
|
xsi:schemaLocation='http://docbook.org/ns/docbook
|
http://docbook.org/xml/5.0/xsd/docbook.xsd'
|
xmlns:xlink='http://www.w3.org/1999/xlink'>
|
<title>Working With Controls</title>
|
<indexterm>
|
<primary>Controls</primary>
|
</indexterm>
|
<indexterm>
|
<primary>LDAP</primary>
|
<secondary>Controls</secondary>
|
</indexterm>
|
|
<para>This chapter demonstrates how to use LDAP controls.</para>
|
|
<para>
|
For complete examples corresponding to the excerpts shown below, see
|
<link
|
xlink:href="../resources/org/forgerock/opendj/examples/Controls.java"
|
xlink:show="new">Controls.java</link>.
|
</para>
|
|
<section xml:id="about-ldap-controls">
|
<title>About LDAP Controls</title>
|
<para>Controls provide a mechanism whereby the semantics and arguments of
|
existing LDAP operations may be extended. One or more controls may be
|
attached to a single LDAP message. A control only affects the semantics of
|
the message it is attached to. Controls sent by clients are termed
|
<emphasis>request controls</emphasis>, and those sent by servers are termed
|
<emphasis>response controls</emphasis>.</para>
|
</section>
|
|
<section xml:id="get-supported-controls">
|
<title>Determining Supported Controls</title>
|
<indexterm>
|
<primary>Controls</primary>
|
<secondary>Supported</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>LDAP</primary>
|
<secondary>Checking supported features</secondary>
|
</indexterm>
|
|
<para>For OpenDJ, the controls supported are listed in the
|
<citetitle>Administration Guide</citetitle> appendix, <link xlink:show="new"
|
xlink:href="${serverDocBase}admin-guide/#appendix-controls"><citetitle>LDAP
|
Controls</citetitle></link>. You can access the list of OIDs for
|
supported LDAP controls by reading the <literal>supportedControl</literal>
|
attribute of the root DSE.</para>
|
|
<screen>
|
$ <userinput>ldapsearch \
|
--baseDN "" \
|
--searchScope base \
|
--port 1389 \
|
"(objectclass=*)" supportedControl</userinput>
|
<computeroutput>dn:
|
supportedControl: 1.2.826.0.1.3344810.2.3
|
supportedControl: 1.2.840.113556.1.4.1413
|
supportedControl: 1.2.840.113556.1.4.319
|
supportedControl: 1.2.840.113556.1.4.473
|
supportedControl: 1.2.840.113556.1.4.805
|
supportedControl: 1.3.6.1.1.12
|
supportedControl: 1.3.6.1.1.13.1
|
supportedControl: 1.3.6.1.1.13.2
|
supportedControl: 1.3.6.1.4.1.26027.1.5.2
|
supportedControl: 1.3.6.1.4.1.42.2.27.8.5.1
|
supportedControl: 1.3.6.1.4.1.42.2.27.9.5.2
|
supportedControl: 1.3.6.1.4.1.42.2.27.9.5.8
|
supportedControl: 1.3.6.1.4.1.4203.1.10.1
|
supportedControl: 1.3.6.1.4.1.4203.1.10.2
|
supportedControl: 1.3.6.1.4.1.7628.5.101.1
|
supportedControl: 2.16.840.1.113730.3.4.12
|
supportedControl: 2.16.840.1.113730.3.4.16
|
supportedControl: 2.16.840.1.113730.3.4.17
|
supportedControl: 2.16.840.1.113730.3.4.18
|
supportedControl: 2.16.840.1.113730.3.4.19
|
supportedControl: 2.16.840.1.113730.3.4.2
|
supportedControl: 2.16.840.1.113730.3.4.3
|
supportedControl: 2.16.840.1.113730.3.4.4
|
supportedControl: 2.16.840.1.113730.3.4.5
|
supportedControl: 2.16.840.1.113730.3.4.9</computeroutput>
|
</screen>
|
|
<para>The following excerpt shows couple of methods to check whether the
|
directory server supports a control.</para>
|
|
<programlisting language="java"
|
>[jcp:org.forgerock.opendj.examples.Controls:--- JCite check support ---]</programlisting>
|
</section>
|
|
<section xml:id="use-assertion-request-control">
|
<title>Assertion Request Control</title>
|
<indexterm>
|
<primary>Controls</primary>
|
<secondary>Assertion</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>Assertions</primary>
|
</indexterm>
|
|
<para>The <link xlink:href="http://tools.ietf.org/html/rfc4528"
|
xlink:show="new" >LDAP assertion control</link> lets you specify a condition
|
that must be true in order for the operation you request to be processed
|
normally. The following excerpt shows, for example, how you might check
|
that no description exists on the entry before adding your description.</para>
|
|
<programlisting language="java"
|
>[jcp:org.forgerock.opendj.examples.Controls:--- JCite assertion ---]</programlisting>
|
|
<para>OpenDJ directory server supports the LDAP assertion control:</para>
|
|
<programlisting language="ldif">dn: uid=bjensen,ou=People,dc=example,dc=com
|
description: Created using LDAP assertion control</programlisting>
|
</section>
|
|
<section xml:id="use-authorization-identity-control">
|
<title>Authorization Identity Controls</title>
|
<indexterm>
|
<primary>Controls</primary>
|
<secondary>Authorization ID</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>Authorizations</primary>
|
</indexterm>
|
|
<para>The <link xlink:href="http://tools.ietf.org/html/rfc3829"
|
xlink:show="new">LDAP Authorization Identity Controls</link> let you get the
|
authorization identity established when you bind to the directory server.
|
The following excerpt shows simple use of the controls.</para>
|
|
<programlisting language="java"
|
>[jcp:org.forgerock.opendj.examples.Controls:--- JCite authzid ---]</programlisting>
|
|
<para>OpenDJ directory server supports the LDAP Authorization Identity
|
Controls:</para>
|
|
<programlisting>Binding as uid=bjensen,ou=People,dc=example,dc=com
|
Authorization ID returned: dn:uid=bjensen,ou=People,dc=example,dc=com</programlisting>
|
</section>
|
|
<section xml:id="use-entry-change-notification-control">
|
<title>Entry Change Notification Response Controls</title>
|
<indexterm>
|
<primary>Controls</primary>
|
<secondary>Entry change notification</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>Searches</primary>
|
<secondary>Entry change notification</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>Change notification</primary>
|
</indexterm>
|
|
<para>When performing a persistent search, your application can retrieve
|
information using this response control about why the directory server
|
returned the entry. See the Internet-Draft on <link xlink:show="new"
|
xlink:href="http://tools.ietf.org/html/draft-ietf-ldapext-psearch">persistent
|
searches</link> for background information.</para>
|
|
<programlisting language="java"
|
>[jcp:org.forgerock.opendj.examples.Controls:--- JCite psearch ---]</programlisting>
|
|
<para>OpenDJ directory server supports persistent searches and the entry
|
change notification response control. When another application renames
|
Anne-Louise Barnes's entry, the sample code picks up information from the
|
entry change notification response control:</para>
|
|
<programlisting>Entry changed: uid=bdobbs,ou=People,dc=example,dc=com
|
Change type: modifyDN
|
Previous DN: uid=abarnes,ou=People,dc=example,dc=com
|
Change number: -1</programlisting>
|
|
<para>In this case, <literal>Change number: -1</literal> because the server
|
did not set a change number value. OpenDJ directory server does not set the
|
change number value in the response control. If you need to track the order
|
of changes with OpenDJ directory server, read the external change log instead
|
of using the entry change notification response control.</para>
|
</section>
|
|
<section xml:id="use-get-effective-rights-control">
|
<title>GetEffectiveRights Request Control</title>
|
<indexterm>
|
<primary>Controls</primary>
|
<secondary>GetEffectiveRights</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>Authorizations</primary>
|
</indexterm>
|
|
<para>Your application can attach the GetEffectiveRights request control to
|
retrieve information about what the directory server permits a user to do.
|
Use this control during a search to see permissions on the entries returned.
|
See the Internet-Draft on the <link xlink:show="new"
|
xlink:href="http://tools.ietf.org/html/draft-ietf-ldapext-acl-model">Access
|
Control Model for LDAP</link> for background.</para>
|
|
<programlisting language="java"
|
>[jcp:org.forgerock.opendj.examples.Controls:--- JCite effective rights ---]</programlisting>
|
|
<para>OpenDJ SDK currently implements the request control, but not the
|
response control. The results are shown as values of the
|
<literal>aclRights</literal> and more verbose <literal>aclRightsInfo</literal>
|
attributes.</para>
|
|
<programlisting language="ldif">
|
dn: uid=bjensen,ou=People,dc=example,dc=com
|
aclRightsInfo;logs;attributeLevel;selfwrite_delete;cn: acl_summary(main)
|
: access allowed(write) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com
|
, distinguishedName) to (uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
|
) ( reason: evaluated allow , deciding_aci: allow all Admin group)
|
aclRightsInfo;logs;entryLevel;read: acl_summary(main): access allowed(read
|
) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, objectClass) to (
|
uid=kvaughan,ou=People,dc=example,dc=com) (not proxied) ( reason
|
: evaluated allow , deciding_aci: Anonymous read-search access)
|
aclRightsInfo;logs;attributeLevel;proxy;cn: acl_summary(main)
|
: access not allowed(proxy) on entry/attr(uid=bjensen,ou=People,dc=example,
|
dc=com, cn) to (uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
|
) (reason: no acis matched the subject )
|
aclRights;attributeLevel;cn: search:1,read:1,compare:1,write:1,selfwrite_add:1,
|
selfwrite_delete:1,proxy:0
|
aclRightsInfo;logs;attributeLevel;write;cn: acl_summary(main): access allowed
|
(write) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, cn) to (
|
uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
|
) ( reason: evaluated allow , deciding_aci: allow all Admin group)
|
aclRights;entryLevel: add:1,delete:1,read:1,write:1,proxy:0
|
aclRightsInfo;logs;attributeLevel;search;cn: acl_summary(main): access allowed(
|
search) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, cn) to (
|
uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
|
) ( reason: evaluated allow , deciding_aci: Anonymous read-search access)
|
aclRightsInfo;logs;entryLevel;write: acl_summary(main): access allowed(write
|
) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, NULL) to (
|
uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
|
) ( reason: evaluated allow , deciding_aci: allow all Admin group)
|
aclRightsInfo;logs;attributeLevel;selfwrite_add;cn: acl_summary(main
|
): access allowed(write) on entry/attr(uid=bjensen,ou=People,dc=example,
|
dc=com, distinguishedName) to (uid=kvaughan,ou=People,dc=example,dc=com) (
|
not proxied) ( reason: evaluated allow , deciding_aci: allow all Admin group)
|
aclRightsInfo;logs;entryLevel;add: acl_summary(main): access allowed(add
|
) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, NULL) to (
|
uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
|
) ( reason: evaluated allow , deciding_aci: allow all Admin group)
|
aclRightsInfo;logs;attributeLevel;read;cn: acl_summary(main): access allowed(
|
read) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, cn) to (
|
uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
|
) ( reason: evaluated allow , deciding_aci: Anonymous read-search access)
|
cn: Barbara Jensen
|
cn: Babs Jensen
|
aclRightsInfo;logs;entryLevel;proxy: acl_summary(main): access not allowed(
|
proxy) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, NULL) to (
|
uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
|
) ( reason: no acis matched the subject )
|
aclRightsInfo;logs;attributeLevel;compare;cn: acl_summary(main): access allowed
|
(compare) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, cn) to (
|
uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
|
) ( reason: evaluated allow , deciding_aci: Anonymous read-search access)
|
aclRightsInfo;logs;entryLevel;delete: acl_summary(main): access allowed(
|
delete) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, NULL) to (
|
uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
|
) ( reason: evaluated allow , deciding_aci: allow all Admin group)
|
</programlisting>
|
</section>
|
|
<section xml:id="use-managedsait-control">
|
<title>ManageDsaIT Request Control</title>
|
<indexterm>
|
<primary>Controls</primary>
|
<secondary>ManageDsaIT</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>Referrals</primary>
|
</indexterm>
|
|
<para>The ManageDsaIT control, described in <link xlink:show="new"
|
xlink:href="http://tools.ietf.org/html/rfc3296">RFC 3296, <citetitle>Named
|
Subordinate References in LDAP Directories</citetitle></link>, lets your
|
application handle references and other special entries as normal entries.
|
Use it when you want to read from or write to reference or special
|
entry.</para>
|
|
<programlisting language="java"
|
>[jcp:org.forgerock.opendj.examples.Controls:--- JCite manage DsaIT ---]</programlisting>
|
|
<para>OpenDJ directory server supports the ManageDsaIT Request Control. To use
|
the example entry create a new base DN, <literal>dc=ref,dc=com</literal>
|
before you import the data:</para>
|
|
<programlisting language="none">Referral without the ManageDsaIT control.
|
Reference: [ldap:///dc=example,dc=com??sub?]
|
Referral with the ManageDsaIT control.
|
dn: dc=references,dc=ref,dc=com</programlisting>
|
</section>
|
|
<section xml:id="use-matched-values-request-control">
|
<title>Matched Values Request Control</title>
|
<indexterm>
|
<primary>Controls</primary>
|
<secondary>Matched values</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>Groups</primary>
|
</indexterm>
|
|
<para>RFC 3876, <link xlink:href="http://tools.ietf.org/html/rfc3876"
|
xlink:show="new"><citetitle>Returning Matched Values with the
|
LDAPv3</citetitle></link>, describes a control that lets your application
|
pass a filter in a search request getting a multivalued attribute such that
|
the directory server only returns attribute values that match the
|
filter.</para>
|
|
<para>Barbara Jensen's entry contains two common name values,
|
<literal>Barbara Jensen</literal> and <literal>Babs Jensen</literal>. The
|
following excerpt retrieves only the latter.</para>
|
|
<programlisting language="java"
|
>[jcp:org.forgerock.opendj.examples.Controls:--- JCite matched values ---]</programlisting>
|
|
<para>OpenDJ directory server supports the matched values request
|
control.</para>
|
|
<programlisting language="ldif">Reading entry with matched values request.
|
dn: uid=bjensen,ou=People,dc=example,dc=com
|
cn: Babs Jensen
|
</programlisting>
|
</section>
|
|
<section xml:id="use-ad-notification-request-control">
|
<title>Microsoft LDAP Server Notification Control</title>
|
<indexterm>
|
<primary>Controls</primary>
|
<secondary>Microsoft LDAP Server Notification Control</secondary>
|
</indexterm>
|
|
<para>
|
The Microsoft <link xlink:show="new"
|
xlink:href="http://msdn.microsoft.com/en-us/library/windows/desktop/aa366983(v=vs.85).aspx"
|
>LDAP Server Notification Control</link>
|
with OID <literal>1.2.840.113556.1.4.528</literal>
|
can be used to register a change notification request
|
for a search on Microsoft Active Directory.
|
</para>
|
|
<programlisting language="java"
|
>[jcp:org.forgerock.opendj.examples.Controls:--- JCite ADNotification ---]</programlisting>
|
|
<para>
|
When you run the search against Active Directory
|
and then create, update, and delete a new user
|
Active Directory notifies you of changes to directory data.
|
</para>
|
|
</section>
|
|
<section xml:id="use-password-expired-control">
|
<title>Password Expired Response Control</title>
|
<indexterm>
|
<primary>Controls</primary>
|
<secondary>Password expired</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>LDAP</primary>
|
<secondary>Password policy</secondary>
|
</indexterm>
|
|
<para>A directory server can return the Password Expired Response Control,
|
described in the Internet-Draft <link xlink:show="new"
|
xlink:href="http://tools.ietf.org/html/draft-vchu-ldap-pwd-policy"><citetitle
|
>Password Policy for LDAP Directories</citetitle></link>, when a bind fails
|
because the password has expired. In order to see this, you must configure
|
the directory to expire Barbara Jensen's password.</para>
|
|
<programlisting language="java"
|
>[jcp:org.forgerock.opendj.examples.Controls:--- JCite password expired ---]</programlisting>
|
|
<para>OpenDJ directory server supports the Password Expired Response Control.
|
To obtain the following output from the excerpt, you can change the default
|
password policy configuration to set a short maximum password age, change
|
Barbara Jensen's password, and wait for it to expire. See the OpenDJ
|
<citetitle>Administration Guide</citetitle> procedure explaining how
|
<link xlink:href="${serverDocBase}admin-guide/#default-pwp" xlink:show="new"
|
><citetitle>To Adjust the Default Password Policy</citetitle></link> for an
|
example of how to adjust the maximum password age.</para>
|
|
<programlisting language="none"
|
>Password expired for uid=bjensen,ou=People,dc=example,dc=com</programlisting>
|
</section>
|
|
<section xml:id="use-password-expiring-control">
|
<title>Password Expiring Response Control</title>
|
<indexterm>
|
<primary>Controls</primary>
|
<secondary>Password expiring</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>LDAP</primary>
|
<secondary>Password policy</secondary>
|
</indexterm>
|
|
<para>The Password Expiring Response Control, described in the Internet-Draft
|
<link xlink:href="http://tools.ietf.org/html/draft-vchu-ldap-pwd-policy"
|
xlink:show="new" ><citetitle>Password Policy for LDAP
|
Directories</citetitle></link>, warns your application during a bind
|
that the password used will soon expire.</para>
|
|
<programlisting language="java"
|
>[jcp:org.forgerock.opendj.examples.Controls:--- JCite password expiring ---]</programlisting>
|
|
<para>OpenDJ directory server supports the Password Expiring Response Control.
|
To obtain the following output from the excerpt, you can change the default
|
password policy configuration to set a maximum password age and a warning
|
interval, change Barbara Jensen's password, and wait until you enter the
|
warning interval before password expiration. See the OpenDJ
|
<citetitle>Administration Guide</citetitle> procedure explaining how
|
<link xlink:href="${serverDocBase}admin-guide/#default-pwp"
|
xlink:show="new"><citetitle>To Adjust the Default Password Policy</citetitle></link>
|
for an example of how to adjust the maximum password age. Also set a short
|
<literal>password-expiration-warning-interval</literal> value.</para>
|
|
<programlisting language="none">Password for uid=bjensen,ou=People,dc=example,dc=com
|
expires in 237 seconds.</programlisting>
|
</section>
|
|
<section xml:id="use-password-policy-controls">
|
<title>Password Policy Controls</title>
|
<indexterm>
|
<primary>Controls</primary>
|
<secondary>Password policy</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>LDAP</primary>
|
<secondary>Password policy</secondary>
|
</indexterm>
|
|
<para>The Behera Internet-Draft, <link xlink:show="new"
|
xlink:href="http://tools.ietf.org/html/draft-behera-ldap-password-policy"
|
><citetitle>Password Policy for LDAP Directories</citetitle></link>, describes
|
Password Policy Request and Response Controls. You send the request control
|
with a request to let the directory server know that your application can
|
handle the response control. The directory server sends the response control
|
on applicable operations to communicate warnings and errors.</para>
|
|
<programlisting language="java"
|
>[jcp:org.forgerock.opendj.examples.Controls:--- JCite password policy ---]</programlisting>
|
|
<para>OpenDJ directory server supports the Password Policy Controls. To obtain
|
the output from the excerpt, you can change the default password policy
|
configuration to set a maximum password age and a warning interval, change
|
Barbara Jensen's password, and then run the example during the warning
|
interval and after the password has expired. See the OpenDJ
|
<citetitle>Administration Guide</citetitle> procedure explaining how
|
<link xlink:href="${serverDocBase}admin-guide/#default-pwp" xlink:show="new"><citetitle
|
>To Adjust the Default Password Policy</citetitle></link> for an example
|
of how to adjust the maximum password age. Also set a short
|
<literal>password-expiration-warning-interval</literal> value.</para>
|
|
<para>For a warning:</para>
|
<programlisting language="none">Password policy warning timeBeforeExpiration, value 237 for
|
uid=bjensen,ou=People,dc=example,dc=com</programlisting>
|
|
<para>For an error:</para>
|
<programlisting language="none">Password policy error passwordExpired for
|
uid=bjensen,ou=People,dc=example,dc=com</programlisting>
|
</section>
|
|
<section xml:id="use-permissive-modify-request-control">
|
<title>Permissive Modify Request Control</title>
|
<indexterm>
|
<primary>Controls</primary>
|
<secondary>Permissive modify</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>Modifications</primary>
|
<secondary>Permissive modify</secondary>
|
</indexterm>
|
|
<para>Microsoft defined a Permissive Modify Request Control that relaxes
|
some constraints when your application performs a modify operation and
|
tries to <literal>add</literal> an attribute that already exists, or to
|
<literal>delete</literal> an attribute that does not exist.</para>
|
|
<programlisting language="java"
|
>[jcp:org.forgerock.opendj.examples.Controls:--- JCite permissive modify ---]</programlisting>
|
|
<para>OpenDJ directory server supports the Permissive Modify Request
|
Control:</para>
|
|
<programlisting language="none">Permissive modify did not complain about attempt to add
|
uid: bjensen to uid=bjensen,ou=People,dc=example,dc=com.</programlisting>
|
</section>
|
|
<section xml:id="use-persistent-search-request-control">
|
<title>Persistent Search Request Control</title>
|
<indexterm>
|
<primary>Controls</primary>
|
<secondary>Persistent search</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>Searches</primary>
|
<secondary>Persistent search</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>Change notification</primary>
|
</indexterm>
|
|
<para>See <xref linkend="use-entry-change-notification-control" />.</para>
|
</section>
|
|
<section xml:id="use-post-read-control">
|
<title>Post-Read Controls</title>
|
<indexterm>
|
<primary>Controls</primary>
|
<secondary>Post-read</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>Searches</primary>
|
<secondary>Handling results</secondary>
|
</indexterm>
|
|
<para>RFC 4527, <link xlink:href="http://tools.ietf.org/html/rfc4527"
|
xlink:show="new"><citetitle>LDAP Read Entry Controls</citetitle></link>,
|
describes the post-read controls that let your application get the content
|
of an entry immediately after modifications are applied.</para>
|
|
<programlisting language="java"
|
>[jcp:org.forgerock.opendj.examples.Controls:--- JCite post read ---]</programlisting>
|
|
<para>OpenDJ directory server supports these controls:</para>
|
|
<programlisting language="ldif">dn: uid=bjensen,ou=People,dc=example,dc=com
|
description: Using the PostReadRequestControl</programlisting>
|
</section>
|
|
<section xml:id="use-pre-read-control">
|
<title>Pre-Read Controls</title>
|
<indexterm>
|
<primary>Controls</primary>
|
<secondary>Pre-read</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>Assertions</primary>
|
</indexterm>
|
|
<para>RFC 4527, <link xlink:href="http://tools.ietf.org/html/rfc4527"
|
xlink:show="new"><citetitle>LDAP Read Entry Controls</citetitle></link>,
|
describes the pre-read controls that let your application get the content
|
of an entry immediately before modifications are applied.</para>
|
|
<programlisting language="java"
|
>[jcp:org.forgerock.opendj.examples.Controls:--- JCite pre read ---]</programlisting>
|
|
<para>OpenDJ directory server supports these controls:</para>
|
|
<programlisting language="ldif">dn: uid=bjensen,ou=People,dc=example,dc=com
|
mail: bjensen@example.com</programlisting>
|
</section>
|
|
<section xml:id="use-proxy-authz-control">
|
<title>Proxied Authorization Request Controls</title>
|
<indexterm>
|
<primary>Controls</primary>
|
<secondary>Proxied authorization</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>Authorizations</primary>
|
</indexterm>
|
|
<para>Proxied authorization provides a standard control as defined in
|
<link xlink:href="http://tools.ietf.org/html/rfc4370" xlink:show="new">RFC
|
4370</link> (and an earlier Internet-Draft) for binding with the user
|
credentials of a proxy, who carries out LDAP operations on behalf of other
|
users. You might use proxied authorization, for example, to have your
|
application bind with its credentials, and then carry out operations as the
|
users who login to the application.</para>
|
|
<programlisting language="java"
|
>[jcp:org.forgerock.opendj.examples.Controls:--- JCite proxied authzv2 ---]</programlisting>
|
|
<para>OpenDJ supports proxied authorization, and the example works with the
|
sample data:</para>
|
|
<programlisting language="ldif">dn: uid=bjensen,ou=People,dc=example,dc=com
|
description: Done with proxied authz</programlisting>
|
</section>
|
|
<section xml:id="use-server-side-sort-control">
|
<title>Server-Side Sort Controls</title>
|
<indexterm>
|
<primary>Controls</primary>
|
<secondary>Server-side sort</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>Searches</primary>
|
<secondary>Server-side sort</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>Browsing</primary>
|
</indexterm>
|
<indexterm>
|
<primary>Sorting</primary>
|
</indexterm>
|
|
<para>The server-side sort controls are described in RFC 2891, <link
|
xlink:show="new" xlink:href="http://tools.ietf.org/html/rfc2891"><citetitle
|
>LDAP Control Extension for Server Side Sorting of Search
|
Results</citetitle></link>. If possible, sort on the client side instead to
|
reduce load on the server. If not, then you can request a server-side
|
sort.</para>
|
|
<programlisting language="java"
|
>[jcp:org.forgerock.opendj.examples.Controls:--- JCite server-side sort ---]</programlisting>
|
|
<para>OpenDJ directory server supports server-side sorting:</para>
|
|
<programlisting language="ldif">dn: uid=ajensen,ou=People,dc=example,dc=com
|
cn: Allison Jensen
|
|
dn: uid=bjensen,ou=People,dc=example,dc=com
|
cn: Barbara Jensen
|
cn: Babs Jensen
|
|
dn: uid=bjense2,ou=People,dc=example,dc=com
|
cn: Bjorn Jensen
|
|
dn: uid=gjensen,ou=People,dc=example,dc=com
|
cn: Gern Jensen
|
|
dn: uid=jjensen,ou=People,dc=example,dc=com
|
cn: Jody Jensen
|
|
dn: uid=kjensen,ou=People,dc=example,dc=com
|
cn: Kurt Jensen
|
|
dn: uid=rjense2,ou=People,dc=example,dc=com
|
cn: Randy Jensen
|
|
dn: uid=rjensen,ou=People,dc=example,dc=com
|
cn: Richard Jensen
|
|
dn: uid=tjensen,ou=People,dc=example,dc=com
|
cn: Ted Jensen
|
|
# Entries are sorted.</programlisting>
|
</section>
|
|
<section xml:id="use-simple-paged-results-control">
|
<title>Simple Paged Results Control</title>
|
<indexterm>
|
<primary>Controls</primary>
|
<secondary>Simple paged results</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>Searches</primary>
|
<secondary>Simple paged results</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>Browsing</primary>
|
</indexterm>
|
|
<para>RFC 2696, <link xlink:href="http://tools.ietf.org/html/rfc2696"
|
xlink:show="new"><citetitle>LDAP Control Extension for Simple Paged Results
|
Manipulation</citetitle></link>, defines a control for simple paging of
|
search results that works with a cookie mechanism.</para>
|
|
<programlisting language="java"
|
>[jcp:org.forgerock.opendj.examples.Controls:--- JCite simple paged results ---]</programlisting>
|
|
<para>OpenDJ directory server supports getting simple paged results:</para>
|
|
<programlisting language="ldif"># Simple paged results: Page 1
|
dn: uid=ajensen,ou=People,dc=example,dc=com
|
cn: Allison Jensen
|
|
dn: uid=bjense2,ou=People,dc=example,dc=com
|
cn: Bjorn Jensen
|
|
dn: uid=bjensen,ou=People,dc=example,dc=com
|
cn: Barbara Jensen
|
cn: Babs Jensen
|
|
# Simple paged results: Page 2
|
dn: uid=gjensen,ou=People,dc=example,dc=com
|
cn: Gern Jensen
|
|
dn: uid=jjensen,ou=People,dc=example,dc=com
|
cn: Jody Jensen
|
|
dn: uid=kjensen,ou=People,dc=example,dc=com
|
cn: Kurt Jensen
|
|
# Simple paged results: Page 3
|
dn: uid=rjense2,ou=People,dc=example,dc=com
|
cn: Randy Jensen
|
|
dn: uid=rjensen,ou=People,dc=example,dc=com
|
cn: Richard Jensen
|
|
dn: uid=tjensen,ou=People,dc=example,dc=com
|
cn: Ted Jensen
|
</programlisting>
|
</section>
|
|
<section xml:id="use-subentry-request-control">
|
<title>Subentries Request Control</title>
|
<indexterm>
|
<primary>Controls</primary>
|
<secondary>Subentries</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>LDAP</primary>
|
<secondary>Subentries</secondary>
|
</indexterm>
|
|
<para>RFC 3672, <link xlink:href="http://tools.ietf.org/html/rfc3672"
|
xlink:show="new"><citetitle>Subentries in LDAP</citetitle></link>, describes
|
subentries and also the subentries request control. When you perform a search
|
without the control and visibility set to <literal>TRUE</literal>, subentries
|
are only visible in searches with
|
<literal>SearchScope.BASE_OBJECT</literal>.</para>
|
|
<programlisting language="java"
|
>[jcp:org.forgerock.opendj.examples.Controls:--- JCite subentries ---]</programlisting>
|
|
<para>OpenDJ directory server supports the control.</para>
|
|
<programlisting language="ldif">dn: cn=Bronze Class of Service,dc=example,dc=com
|
cn: Bronze Class of Service
|
subtreeSpecification: { base "ou=People", specificationFilter "(classOfService=
|
bronze)" }
|
|
dn: cn=Silver Class of Service,dc=example,dc=com
|
cn: Silver Class of Service
|
subtreeSpecification: { base "ou=People", specificationFilter "(classOfService=
|
silver)" }
|
|
dn: cn=Gold Class of Service,dc=example,dc=com
|
cn: Gold Class of Service
|
subtreeSpecification: { base "ou=People", specificationFilter "(classOfService=
|
gold)" }
|
</programlisting>
|
</section>
|
|
<section xml:id="use-subtree-delete-control">
|
<title>Subtree Delete Request Control</title>
|
<indexterm>
|
<primary>Controls</primary>
|
<secondary>Subtree delete</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>Deletes</primary>
|
<secondary>Subtree delete</secondary>
|
</indexterm>
|
|
<para>The subtree delete request control, described in the Internet-Draft
|
<link xlink:href="http://tools.ietf.org/html/draft-armijo-ldap-treedelete"
|
xlink:show="new"><citetitle>Tree Delete Control</citetitle></link>, lets
|
your application delete an entire branch of entries starting with the entry
|
you target for deletion.</para>
|
|
<programlisting language="java"
|
>[jcp:org.forgerock.opendj.examples.Controls:--- JCite tree delete ---]</programlisting>
|
|
<para>OpenDJ directory server supports the subtree delete control:</para>
|
|
<programlisting language="none"
|
>Successfully deleted ou=Apps,dc=example,dc=com and all entries below.</programlisting>
|
</section>
|
|
<section xml:id="use-vlv-control">
|
<title>Virtual List View Controls</title>
|
<indexterm>
|
<primary>Controls</primary>
|
<secondary>Virtual list view</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>Searches</primary>
|
<secondary>Virtual list view</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>Browsing</primary>
|
</indexterm>
|
<indexterm>
|
<primary>Sorting</primary>
|
</indexterm>
|
|
<para>The virtual list view controls are intended to be used by applications
|
that let users browse lists of directory entries. The Internet-Draft <link
|
xlink:href="http://tools.ietf.org/html/draft-ietf-ldapext-ldapv3-vlv"
|
xlink:show="new"><citetitle>LDAP Extensions for Scrolling View Browsing of
|
Search Results</citetitle></link> describes the controls. The virtual list
|
view request control is used in conjunction with the server-side sort
|
control such that the subset of entries the directory server returns from
|
a search are a window into the full sorted list.</para>
|
|
<programlisting language="java"
|
>[jcp:org.forgerock.opendj.examples.Controls:--- JCite vlv ---]</programlisting>
|
|
<para>OpenDJ directory server supports the virtual list view controls.
|
In order to set up OpenDJ directory server to produce the following output
|
with the example code, use OpenDJ Control Panel > Manage Indexes > New
|
VLV Index... to set up a virtual list view index for people by last name,
|
using the filter <literal>(|(givenName=*)(sn=*))</literal>, and sorting first
|
by surname, <literal>sn</literal>, in ascending order, then by given name
|
also in ascending order.</para>
|
|
<programlisting language="ldif">dn: uid=skellehe,ou=People,dc=example,dc=com
|
givenName: Sue
|
sn: Kelleher
|
|
dn: uid=ejohnson,ou=People,dc=example,dc=com
|
givenName: Emanuel
|
sn: Johnson
|
|
dn: uid=ajensen,ou=People,dc=example,dc=com
|
givenName: Allison
|
sn: Jensen
|
|
dn: uid=bjense2,ou=People,dc=example,dc=com
|
givenName: Bjorn
|
sn: Jensen
|
|
dn: uid=bjensen,ou=People,dc=example,dc=com
|
givenName: Barbara
|
sn: Jensen
|
|
# Entries are sorted.
|
# Position in list: 92/150</programlisting>
|
</section>
|
|
<section xml:id="use-generic-control">
|
<title>Using a Generic Control</title>
|
<indexterm>
|
<primary>Controls</primary>
|
<secondary>Generic</secondary>
|
</indexterm>
|
|
<para>OpenDJ LDAP SDK supports many controls, but you might still need to
|
work with additional controls. If so, then in some cases you can use the
|
<literal>GenericControl</literal> class when adding the control to your
|
request.</para>
|
|
<para>
|
The following example uses a <literal>GenericControl</literal>
|
to add a pre-read request control when replacing the description
|
on a user's entry.
|
OpenDJ LDAP SDK already implements the pre-read request control,
|
as shown in <xref linkend="use-pre-read-control" />.
|
The example is of interest mainly because it shows
|
that the values that you pass when using a <literal>GenericControl</literal>
|
must be prepared as indicated in the specification of the control.
|
</para>
|
|
<programlisting language="java"
|
>[jcp:org.forgerock.opendj.examples.UseGenericControl:--- JCite ---]</programlisting>
|
|
<para>
|
When you run this example against a user entry in OpenDJ directory server,
|
you see something like the following result.
|
</para>
|
|
<programlisting language="ldif"># Before modification
|
dn: uid=bjensen,ou=People,dc=example,dc=com
|
description: Original description
|
|
# After modification
|
dn: uid=bjensen,ou=People,dc=example,dc=com
|
description: A new description</programlisting>
|
|
<para>The <literal>GenericControl</literal> class is useful with controls that
|
do not require you to encode complex request values, or decode complex
|
response values. If the control you want to you requires complex encoding
|
or decoding, you might have to implement
|
<literal>org.forgerock.opendj.ldap.controls.Control</literal>.</para>
|
</section>
|
</chapter>
|
