You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by er...@apache.org on 2006/01/27 21:13:36 UTC
svn commit: r372968 [6/6] - in /directory/trunks/apacheds/src/site: ./
resources/ resources/developers/ resources/images/ resources/users/ xdoc/
xdoc/developers/ xdoc/drafts/ xdoc/images/ xdoc/projects/ xdoc/rfcs/
xdoc/users/
Added: directory/trunks/apacheds/src/site/xdoc/users/enablesearchforallusers.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/xdoc/users/enablesearchforallusers.xml?rev=372968&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/xdoc/users/enablesearchforallusers.xml (added)
+++ directory/trunks/apacheds/src/site/xdoc/users/enablesearchforallusers.xml Fri Jan 27 12:11:10 2006
@@ -0,0 +1,322 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+ <properties>
+ <author email="akarasulu">akarasulu</author>
+
+ </properties>
+ <body>
+ <section heading="h1" name="Enable Authenticated Users to Browse and Read Entries in a Subtree">
+ <table>
+ <tr>
+ <th>
+ <img src="http://docs.safehaus.org/images/icons/emoticons/warning.png"/>
+ </th>
+ <th>
+ <center>The first time is always the hardest!</center>
+ </th>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ <p>
+We presume this is your first encounter and so many bases will be covered this
+time around. Every other trail will build on this information. So expect a
+little less to read as you gain
+momentum.</p>
+ </td>
+ </tr>
+ </table>
+ <p>
+Since the entire directory is locked down for all but the superuser, you're
+going to want to grant read and browse access to users for certain regions of
+the DIT. This will probably be the first thing you'll want to do after turning
+on access
+controls.</p>
+ <subsection heading="h2" name="Check for insufficientAccessRights for Normal Users">
+ <p>
+Just to make sure everything is locked down login as admin and create a new
+non-superuser. For more information on how to do this
+see
+ <a href="./authentication.html">Authentication</a>
+. After creating the normal user make sure you cannot bind to dc=example,dc=com
+with access controls enabled. You should get an error trying to bind with a
+result code of 50 (insufficientAccessRights). If using JNDI to connect to the
+server you should get a NoPermissionException. After we apply the following ACI
+you can check
+again.
+ </p>
+ </subsection>
+ <subsection heading="h2" name="Partition and Access Control Area Setup">
+ <p>
+For this example we presume you have setup a partition at the namingContext
+dc=example,dc=com and have turned on access controls. Now you want to grant
+browse and read access to entries and their
+attributes.</p>
+ <p>
+Before you can add a subentry with the prescriptiveACI you'll need to create an
+administrative area. For now we'll make the root of the partition the
+adminstrative point (AP). Every entry including this entry and those underneath
+it will be part of the autonous administrative area for managing access
+controls. To do this we must add the administrativeRole operational attribute to
+the AP entry.
+See
+ <a href="./acarea.html">ACArea</a>
+for code and information about creating access control administrative
+areas.
+ </p>
+ </subsection>
+ <subsection heading="h2" name="Adding the Subentry">
+ <p>
+The subentry can be added using an LDIF or via code. We'll show the code but the
+LDIF can be accessed
+here
+ <a href="./enablesearchforallusers.ldif.html">enableSearchForAllUsers.ldif</a>
+:
+ </p>
+ <source> // Get a DirContext on the dc=example,dc=com entry
+ Hashtable env = new Hashtable();
+ env.put( "java.naming.factory.initial", "com.sun.jndi.ldap.LdapCtxFactory" );
+ env.put( "java.naming.provider.url", "ldap://localhost:" + port + "/dc=example,dc=com" );
+ env.put( "java.naming.security.principal", "uid=admin,ou=system" );
+ env.put( "java.naming.security.credentials", "secret" );
+ env.put( "java.naming.security.authentication", "simple" );
+ ctx = new InitialDirContext( env );
+
+ // now add the A/C subentry below dc=example,dc=com
+ Attributes subentry = new BasicAttributes( "cn", "enableSearchForAllUsers", true );
+ Attribute objectClass = new BasicAttribute( "objectClass" );
+ subentry.put( objectClass );
+ objectClass.add( "top" );
+ objectClass.add( "subentry" );
+ objectClass.add( "accessControlSubentry" );
+ subentry.put( "subtreeSpecification", "{}" );
+ subentry.put( "prescriptiveACI", "{ \n" +
+ " identificationTag \"enableSearchForAllUsers\",\n" +
+ " precedence 14,\n" +
+ " authenticationLevel simple,\n" +
+ " itemOrUserFirst userFirst: \n" +
+ " { \n" +
+ " userClasses { allUsers }, \n" +
+ " userPermissions \n" +
+ " { \n" +
+ " {\n" +
+ " protectedItems {entry, allUserAttributeTypesAndValues}, \n" +
+ " grantsAndDenials { grantRead, grantReturnDN, grantBrowse } \n" +
+ " }\n" +
+ " } \n" +
+ " } " );
+ ctx.createSubcontext( "cn=enableSearchForAllUsers", subentry );
+</source>
+ <p>
+Before we cover the anatomy of this ACIItem, you might want to add the subentry
+and test access with a normal non-super user to make sure access is now
+granted.</p>
+ </subsection>
+ </section>
+ <section heading="h1" name="ACIItem Description">
+ <p>
+Here's the ACIItem you just added above without all the Java
+clutter:</p>
+ <source>{
+ identificationTag "enableSearchForAllUsers",
+ precedence 14,
+ authenticationLevel simple,
+ itemOrUserFirst userFirst:
+ {
+ userClasses { allUsers },
+ userPermissions
+ {
+ {
+ protectedItems {entry, allUserAttributeTypesAndValues},
+ grantsAndDenials { grantRead, grantReturnDN, grantBrowse }
+ }
+ }
+ }
+}
+</source>
+ <p>
+There are several parameters to this simple ACIItem. Here's a breif
+exaplanation of each field and it's meaning or
+significance.</p>
+ <table>
+ <tr>
+ <th>
+Fields</th>
+ <th>
+Description</th>
+ </tr>
+ <tr>
+ <td>
+identificationTag</td>
+ <td>
+Identifies the ACIItem within an
+entry.</td>
+ </tr>
+ <tr>
+ <td>
+precedence</td>
+ <td>
+Determine which ACI to apply with conflicting
+ACIItems.</td>
+ </tr>
+ <tr>
+ <td>
+authenticationLevel</td>
+ <td>
+User's level of trust with values of none, simple,
+strong</td>
+ </tr>
+ <tr>
+ <td>
+itemOrUserFirst</td>
+ <td>
+Determines order of item permissions or user
+permissions.</td>
+ </tr>
+ <tr>
+ <td>
+userClasses</td>
+ <td>
+The set of users the permissions apply
+to.</td>
+ </tr>
+ <tr>
+ <td>
+userPermissions</td>
+ <td>
+Permissions on protected
+items</td>
+ </tr>
+ </table>
+ <subsection heading="h2" name="identificationTag">
+ <p>
+The identificationTag is just that a tag. It's often used with a subtring
+search filter to lookup a specific ACIItem within an entry. One or more
+ACIItems may be present within a subentry, zero or more in entries, so this
+serves as a means to address the ACIItem within
+entries.</p>
+ </subsection>
+ <subsection heading="h2" name="precedence">
+ <p>
+Precendence is used to determine the ACI to apply when two or more ACIItem's
+applied to an entry conflict. The ACIItem with the highest precedence is
+applied over other conflicting
+ACIItems.</p>
+ <table>
+ <tr>
+ <th>
+ <img src="http://docs.safehaus.org/images/icons/emoticons/warning.png"/>
+ </th>
+ <th>
+ <center>Denials Overpower Grants</center>
+ </th>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ <p>
+When two or more conflicting ACIItems are encountered with the same precedence
+the ACIItems with denials overpower ACIItems with
+grants.</p>
+ </td>
+ </tr>
+ </table>
+ <p>
+Right now the use of this field may not mean too much to you. We're dealing
+with a very simple situation with a single access control area. Later as you
+add more subentries their subtreeSpecifications may define collections that
+intersect. When this happens two or more conflicting ACIItems may apply to the
+same entry. Precendence is then applied to determine which permissions
+apply.</p>
+ <p>
+Another complex situation requiring precedence is the use of inner areas. These
+nested inner administrative areas overlap and so do their effects. The
+authority within an AA may deny some operation to all entries but grant access
+to subentries of inner areas so minor authorities can control access to inner
+areas. Their grants to users may need to have a higher precedence over denials
+in outer areas. Such situations will arise and precedence will need to be used.
+In this example we just assign an arbitrary value to the
+precedence.</p>
+ </subsection>
+ <subsection heading="h2" name="authenticationLevel">
+ <p>
+The authenticationLevel is the minimum authentication requirement for requestor
+for the ACI to by applied: According to
+X.501:</p>
+ <table>
+ <tr>
+ <th>
+ <img src="http://docs.safehaus.org/images/icons/emoticons/information.png"/>
+ </th>
+ <th>
+ <center>18.4.2.3 Authentication Level</center>
+ </th>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ <p>
+... Strong authentication of the requestor is considered to exceed a requirement
+for simple or no authentication, and simple authentication exceeds a requirement
+for no authentication
+...</p>
+ </td>
+ </tr>
+ </table>
+ <p>
+The authenticationLevel can have three values: none, simple and strong. It's
+used to be able to associate permissions with the level of trust in users. For
+none, the identity of the user is anonymous or does not matter. The user can be
+anyone. The simple authenticationLevel means the user has authenticated but is
+using a simple bind with clear text passwords. The strong authenticationLevel
+represents users that bind to the directory using strong authentication
+mechanisms via
+SASL.</p>
+ <p>
+SASL can allow annonynous binds as well so there is a distinction here. Using
+SASL alone does not mean the authenticationLevel is strong. As we add SASL
+mechanisms to the server, we'll qualify each one with none, simple or strong.
+This will be reflected in the authenticationLevel property of the principal
+making
+requests.</p>
+ </subsection>
+ <subsection heading="h2" name="itemOrUserFirst">
+ <p>
+This field describes the order of information within the ACI whether protected
+items are described first or user classes and permissions are described first.
+For simplicity we will only describe the userFirst configuration in this
+tutorial.</p>
+ </subsection>
+ <subsection heading="h2" name="userClasses">
+ <p>
+UserClasses is used to list the sets of users to which this permission applies.
+Several mechanisms can be used here to define userClasses. They can be defined
+by name per user, by group membership, or by the superset of all users possible
+and many more. In our example we have applied the ACI to all users that have
+authenticated by simple or strong
+means.</p>
+ <p>
+For more information
+see
+ <a href="./userclasses.html">UserClasses</a>
+.
+ </p>
+ </subsection>
+ <subsection heading="h2" name="userPermissions">
+ <p>
+These are the permissions granted or denied to those users included by the
+userClasses field. The grants or denials however are qualified by the protected
+items operated upon. In our example we grant read, return DN and browse to all
+entries, their attributes and all possible values they may
+have.</p>
+ <p>
+For more information
+see
+ <a href="./userpermissions.html">UserPermissions</a>
+.
+ </p>
+ </subsection>
+ </section>
+ </body>
+</document>
Added: directory/trunks/apacheds/src/site/xdoc/users/grantadddelmodtogroup.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/xdoc/users/grantadddelmodtogroup.xml?rev=372968&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/xdoc/users/grantadddelmodtogroup.xml (added)
+++ directory/trunks/apacheds/src/site/xdoc/users/grantadddelmodtogroup.xml Fri Jan 27 12:11:10 2006
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+ <properties>
+ <author email="akarasulu">akarasulu</author>
+
+ </properties>
+ <body>
+ <section heading="h1" name="Coming soon ..."/>
+ </body>
+</document>
Added: directory/trunks/apacheds/src/site/xdoc/users/grantmodtoentry.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/xdoc/users/grantmodtoentry.xml?rev=372968&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/xdoc/users/grantmodtoentry.xml (added)
+++ directory/trunks/apacheds/src/site/xdoc/users/grantmodtoentry.xml Fri Jan 27 12:11:10 2006
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+ <properties>
+ <author email="akarasulu">akarasulu</author>
+
+ </properties>
+ <body>
+ <section heading="h1" name="Coming soon ..."/>
+ </body>
+</document>
Added: directory/trunks/apacheds/src/site/xdoc/users/index.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/xdoc/users/index.xml?rev=372968&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/xdoc/users/index.xml (added)
+++ directory/trunks/apacheds/src/site/xdoc/users/index.xml Fri Jan 27 12:11:10 2006
@@ -0,0 +1,92 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+ <properties>
+ <author email="akarasulu">akarasulu</author>
+
+ </properties>
+ <body>
+ <section heading="h1" name="User's Guide">
+ <p>
+This is a simple guide to various ApacheDS features to help users get going.
+It's be no means
+extensive.</p>
+ <table>
+ <tr>
+ <th>
+Topic</th>
+ <th>
+Description</th>
+ </tr>
+ <tr>
+ <td>
+ <a href="./building.html">Building</a>
+ </td>
+ <td>
+How to build the directory server from the
+repository.</td>
+ </tr>
+ <tr>
+ <td>
+ <a href="./authentication.html">Authentication</a>
+ </td>
+ <td>
+How to bind to the server and setup custom
+authenticators.</td>
+ </tr>
+ <tr>
+ <td>
+ <a href="./authorization.html">Authorization</a>
+ </td>
+ <td>
+How to enable basic access controls and what you get without
+them.</td>
+ </tr>
+ <tr>
+ <td>
+ <a href="./subentries.html">Subentries</a>
+and the Administrative
+Model
+ </td>
+ <td>
+What they are and how to specify their scope via
+subtreeSpecifications.</td>
+ </tr>
+ <tr>
+ <td>
+ <a href="./collective.html">Collective</a>
+Attributes
+ </td>
+ <td>
+How to use collective
+attributes.</td>
+ </tr>
+ <tr>
+ <td>
+ <a href="./configuration.html">Configuration</a>
+ </td>
+ <td>
+How to configure and control the
+server.</td>
+ </tr>
+ <tr>
+ <td>
+ <a href="./partitions.html">Partitions</a>
+ </td>
+ <td>
+How to add new partitions besides the system
+partition.</td>
+ </tr>
+ <tr>
+ <td>
+Maven
+ <a href="./plugin.html">Plugin</a>
+ </td>
+ <td>
+How to use the plugin to extends the
+schema.</td>
+ </tr>
+ </table>
+ </section>
+ </body>
+</document>
Added: directory/trunks/apacheds/src/site/xdoc/users/newuser.ldif
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/xdoc/users/newuser.ldif?rev=372968&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/xdoc/users/newuser.ldif (added)
+++ directory/trunks/apacheds/src/site/xdoc/users/newuser.ldif Fri Jan 27 12:11:10 2006
@@ -0,0 +1,18 @@
+dn: uid=jdoe,ou=users,ou=system
+cn: John Doe
+sn: Doe
+givenname: John
+objectclass: top
+objectclass: person
+objectclass: organizationalPerson
+objectclass: inetOrgPerson
+ou: Human Resources
+ou: People
+l: Las Vegas
+uid: jdoe
+mail: jdoe@apachecon.comm
+telephonenumber: +1 408 555 5555
+facsimiletelephonenumber: +1 408 555 5556
+roomnumber: 4613
+userpassword: test
+
Added: directory/trunks/apacheds/src/site/xdoc/users/partitions.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/xdoc/users/partitions.xml?rev=372968&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/xdoc/users/partitions.xml (added)
+++ directory/trunks/apacheds/src/site/xdoc/users/partitions.xml Fri Jan 27 12:11:10 2006
@@ -0,0 +1,157 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+ <properties>
+ <author email="akarasulu">akarasulu</author>
+
+ </properties>
+ <body>
+ <section heading="h1" name="Introduction">
+ <p>
+Partitions are entry stores assigned to a naming context. The idea behind a
+partition is that it stores a subset of the Directory Information Base (DIB).
+Partitions can be implemented in any way so long as they adhere to
+interfaces.</p>
+ <subsection heading="h2" name="Status">
+ <p>
+Presently the server has a single partition implementation. This implementation
+is used for both the system partition and user partitions. It
+uses
+ <a href="http://jdbm.sourceforge.net/">JDBM</a>
+as the underlying B+Tree implementation for storing
+entries.
+ </p>
+ <p>
+Other implementations are possible like in memory based partitions either BTree
+based or based on something
+like
+ <a href="http://www.prevayler.org/wiki.jsp">Prevayler</a>
+.
+ </p>
+ <p>
+Partitions have simple interfaces that can be used to align any data source to
+the LDAP data model thereby accessing it via JNDI or via LDAP over the wire.
+This makes the server very flexible as a bridge to standardize access to
+disparate data sources and formats. Dynamic mapping based backends are also
+interesting.</p>
+ </subsection>
+ <subsection heading="h2" name="System Partitions">
+ <p>
+The system partition is a very special partition that is hardcoded to hang off
+of the *ou=system* naming context. It is always present and contains
+administrative and operational informations needed by the server to operate.
+Hence its
+name.</p>
+ <p>
+The server's subsystems will use this partition to store informations critical
+to its
+operation.</p>
+ </subsection>
+ <subsection heading="h2" name="Root Nexus">
+ <p>
+Several partitions can be assigned to different naming contexts within the
+server so long as their names do not overlap such that one partition's naming
+context is contained within another's. The root nexus is a fake partition that
+does not really store entries. It maps other entry storing partitions to naming
+contexts and routes backing store calls to the partition containing the entry
+associated with the
+operation.</p>
+ </subsection>
+ <subsection heading="h2" name="User Partitions">
+ <p>
+User partitions are partitions added by users. When you download and start using
+the server you may want to create a separate partition to store the entries of
+your application. To us user (sometimes also referred to as application)
+partitions are those that are not the system partition! In the following section
+we describe how a user partition can be created in the
+server.</p>
+ </subsection>
+ </section>
+ <section heading="h1" name="Adding User Partitions">
+ <p>
+Adding new application partitions to the server is a matter of adding
+DirectoryPartitionConfiguration objects to the StartupConfigration added to the
+JNDI environment. These properties are used in both standalone and in embedded
+configurations. You'll see how to configure partitions by example using xml
+configuration files with the standalone application and programatically for
+embedding.</p>
+ <p>
+Until this section is filled with more specific examples just geared towards the
+configuration of partitions please
+see
+ <a href="./configuration.html">Configuration</a>
+.
+ </p>
+ </section>
+ <section heading="h1" name="Future">
+ <p>
+Things we'd like to do with the existing partitioning scheme and
+beyond.</p>
+ <subsection heading="h2" name="Partition Nesting">
+ <p>
+Today we have some limitations to the way we can partition the DIB. Namely we
+can't have a partition within a partition and sometimes this makes sense.
+Eventually we intend to enable this kind of functionality using a special type
+of nexus which is both a router and a backing store for entries. It's smart
+enough to know what to route verses when to use its own database. Here's
+a
+ <a href="http://issues.apache.org/jira/browse/DIREVE-23">JIRA improvement</a>
+specifically aimed at achieving this
+goal.
+ </p>
+ </subsection>
+ <subsection heading="h2" name="Partition Implementations">
+ <p>
+Obviously we want as many different kinds of partitions as possible. Some really
+cool ideas have floated around out there for a while. Here's a list of
+theoretically possible partition types that might be useful or just
+cool:</p>
+ <ul nesting="1">
+ <li>
+Partitions that use JDBC to store entries. These would probably be way too slow.
+However they might be useful if some mapping were to be used to represent an
+existing application's database schema as an LDAP DIT. This would allow us to
+expose any database data via LDAP. Great for
+virtualization.</li>
+ <li>
+Partitions using other LDAP servers to store their entries. Why do this when
+introducing latency? Perhaps you want to proxy other servers or make other
+servers behave like the personality of another server all
+together.</li>
+ <li>
+A partition that serves out the Windows registry via LDAP. A standard mechanism
+to map the Windows registry to an LDAP DIT is pretty simple. This would be a
+neat way to expose client machine registry
+management.</li>
+ <li>
+A partition based on an in-memory BTree implementation. This would be fast and
+really cool for storing things like schema info. It would also be cool for
+staging data between memory and
+disk.</li>
+ <li>
+A partition based
+on
+ <a href="http://www.prevayler.org/wiki.jsp">Prevayler</a>
+. This is like an in-memory partition but you can save it at the end of the day.
+This might be really useful especially for things the system partition which
+almost always need to be in memory. The system partition can do this by using
+really large caches equal to the number of entries in the system
+partition.
+ </li>
+ </ul>
+ </subsection>
+ <subsection heading="h2" name="Partitioning Entries Under a Single Context">
+ <p>
+Other aspirations include entry partitioning within a container context. Imagine
+having 250 million entries under '*ou=citizens,dc=census,dc=gov*'. You don't
+want all 250 million in one partition but would like to subpartition these
+entries under the same context based on some attribute. Basically we will be
+using the attribute's value to implement subpartitioning where within a single
+context we are partitioning entries. The value is used to hash entries across
+buckets (the buckets are other partitions). Yes, this is a bit on the heavy duty
+end but it would be useful in several
+situations.</p>
+ </subsection>
+ </section>
+ </body>
+</document>
Added: directory/trunks/apacheds/src/site/xdoc/users/plugin.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/xdoc/users/plugin.xml?rev=372968&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/xdoc/users/plugin.xml (added)
+++ directory/trunks/apacheds/src/site/xdoc/users/plugin.xml Fri Jan 27 12:11:10 2006
@@ -0,0 +1,267 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+ <properties>
+ <author email="akarasulu">akarasulu</author>
+
+ </properties>
+ <body>
+ <section heading="h1" name="Maven Directory Plugin">
+ <p>
+Currently the primary function of the plugin is to generate server class files
+for OpenLDAP schemas. These class files contain hard coded schema objects
+representing those found in the OpenLDAP files. Why bother you may ask? There
+are a few reasons for
+this:</p>
+ <ol nesting="0">
+ <li>
+Compiled hard coded files load into the server really fast in
+theory.</li>
+ <li>
+Published schemas never really change so why do they need to be in a human
+readable
+form?</li>
+ <li>
+Eventually, schema changes made through LDAP will be preserved through
+restarts.</li>
+ <li>
+Extra code generation phase is not that hard with a plugin
+tool.</li>
+ <li>
+Schema verification can occur before deploying schemas into the
+server.</li>
+ <li>
+This was really easy for now but if people don't like it we can change
+it.</li>
+ </ol>
+ <subsection heading="h2" name="Properties">
+ <table>
+ <tr>
+ <th>
+Property</th>
+ <th>
+Optional?</th>
+ <th>
+Description</th>
+ </tr>
+ <tr>
+ <td>
+maven.ldap.server.schema.target.dir</td>
+ <td>
+Yes</td>
+ <td>
+Default value is
+target/schema</td>
+ </tr>
+ <tr>
+ <td>
+maven.ldap.server.schema.ownerDefault</td>
+ <td>
+Yes</td>
+ <td>
+Default value is
+uid=admin,ou=system.</td>
+ </tr>
+ <tr>
+ <td>
+maven.ldap.server.schema.dir</td>
+ <td>
+Yes</td>
+ <td>
+Default value is
+src/schema.</td>
+ </tr>
+ <tr>
+ <td>
+maven.ldap.server.schema.packageDefault</td>
+ <td>
+Yes</td>
+ <td>
+Default value is
+org.apache.ldap.server.schema.bootstrap.</td>
+ </tr>
+ </table>
+ </subsection>
+ <subsection heading="h2" name="Goals">
+ <table>
+ <tr>
+ <th>
+Goal</th>
+ <th>
+Description</th>
+ </tr>
+ <tr>
+ <td>
+directory:generate</td>
+ <td>
+Generates class files for OpenLDAP
+schemas.</td>
+ </tr>
+ <tr>
+ <td>
+directory:init</td>
+ <td>
+Finds the required parameters needed for the goals of the
+plugin.</td>
+ </tr>
+ <tr>
+ <td>
+directory:prepare-filesystem</td>
+ <td>
+Creates source output directories used to deposite schema files that are
+generated.</td>
+ </tr>
+ <tr>
+ <td>
+directory:schema</td>
+ <td>
+Top level schema generating function that uses other goals to coordinate
+generation.</td>
+ </tr>
+ </table>
+ <p>
+Take a look at how we integrate this into the directory server
+build
+ <a href="http://svn.apache.org/viewcvs.cgi/directory/apacheds/trunk/core/">here</a>
+.
+ </p>
+ </subsection>
+ </section>
+ <section heading="h1" name="How to Integrate Plugin Into Your Own Projects">
+ <p>
+You want to use the plugin to generate classes for your own schema. Here's a
+step wise process you can follow to do that using
+maven:</p>
+ <ol nesting="0">
+ <li>
+Place your schema files (i.e. *foo.schema*) with the schema extension into
+$\{basedir\}/src/main/schema. If you opt to store it in another location you
+must override the maven.ldap.server.schema.dir property in your
+project.properties file. For each schema file add the file base name to the
+maven.ldap.server.schemas property which is a space separated
+list.</li>
+ <li>
+The plugin will by default generate java files within the
+$\{basedir\}/target/schema directory. If you would like to generate code
+elsewhere you must override the maven.ldap.server.schema.target.dir property in
+your project.properties
+file.</li>
+ <li>
+By default the plugin generates code in a server schema package:
+org.apache.ldap.server.schema.bootstrap. If you want generated code for a schema
+to be put into a package other than this, then you're going to need to set the
+package property for the schema. The package property key is composed of the
+following base, maven.ldap.server.schema.package. with the name of the schema
+(without the extension) appended to it. So for schema file foo.schema the
+following property key would be used: maven.ldap.server.schema.package.foo where
+foo is the schema
+name.</li>
+ <li>
+Using the same pattern above for all schema specific properties you can set
+other per schema properties as well. One of these properties is the dependency
+list for a schema. Schemas can obviously depend on others. The schema dependency
+list is a comma separated list of other schema names. These schemas need not be
+present in your project to generate the code for your schema. The dependent
+schema classes must however be present within the server at start up time in
+order to load and use your schema. At the end we list the default schemas
+already packaged into the server's jar. You can use any one of these schemas as
+dependencies needed by your schema and not worry about their presence. The
+property key base for the schema dependency list is
+maven.ldap.server.schema.deps. and for a foo.schema file the full key would be
+maven.ldap.server.schema.deps.foo</li>
+ <li>
+Each schema has an owner associated with it. If you want the owner to be
+anything other than the server's super user you may want to set the owner
+property for the schema in your project.properties file. The property key base
+for the schema is maven.ldap.server.schema.owner. so don't forget to append the
+schema name to
+it.</li>
+ </ol>
+ <p>
+Once setup you can invoke maven to generate the schema sources like
+so:</p>
+ <source>[akarasulu@newton dib]$ maven directory:schema
+ __ __
+| \/ |__ _Apache__ ___
+| |\/| / _` \ V / -_) ' \ ~ intelligent projects ~
+|_| |_\__,_|\_/\___|_||_| v. 1.0.2
+
+Attempting to download ldap-common-0.8.0-SNAPSHOT.jar.
+Attempting to download apacheds-shared-0.8.0-SNAPSHOT.jar.
+Attempting to download apacheds-protocol-0.8.0-SNAPSHOT.jar.
+Attempting to download snickers-codec-0.2.0-SNAPSHOT.jar.
+Attempting to download ldap-snickers-provider-0.8.0-SNAPSHOT.jar.
+Attempting to download snickers-ber-0.2.0-SNAPSHOT.jar.
+Attempting to download seda-0.2.0-SNAPSHOT.jar.
+Attempting to download maven-directory-plugin-0.8.0-SNAPSHOT.jar.
+Attempting to download ldap-common-0.8.0-SNAPSHOT.jar.
+Attempting to download apacheds-shared-0.8.0-SNAPSHOT.jar.
+build:start:
+
+directory:schema:
+directory:init:
+
+directory:prepare-filesystem:
+
+directory:generate:
+ [echo] Generated schema producer classes for autofs.schema
+ [echo] Generated schema producer classes for core.schema
+ [echo] Generated schema producer classes for cosine.schema
+ [echo] Generated schema producer classes for corba.schema
+ [echo] Generated schema producer classes for eve.schema
+ [echo] Generated schema producer classes for inetorgperson.schema
+ [echo] Generated schema producer classes for java.schema
+ [echo] Generated schema producer classes for krb5kdc.schema
+ [echo] Generated schema producer classes for nis.schema
+ [echo] Generated schema producer classes for system.schema
+ [echo] Generated schema producer classes for scheduleworld.schema
+ [touch] Creating /home/akarasulu/projects/directory/server/trunk/core/target/schema/.flagfile
+BUILD SUCCESSFUL
+Total time: 28 seconds
+Finished at: Tue Dec 14 15:26:26 EST 2004
+</source>
+ <p>
+The example above is from the server's core project. If you would like to look
+at how to use this plugin best the server
+core
+ <a href="http://svn.apache.org/viewcvs.cgi/directory/apacheds/trunk/core/project.properties?rev=125094&view=auto">project.properties</a>
+file here is perhaps the best place to look. Also from the output above you can
+see the schema files that are used and packaged into the server by default. This
+may however change in the future to restrict the
+set.
+ </p>
+ <p>
+WARNING: As a last bit of advice make note that the plugin may be sensitive to
+case for keywords in the OpenLDAP file. For example the prefix before an
+objectClass or an attributeType must be in all lowercase. However words like
+MUST, and MAY and SUP should all be in uppercase. So if plugin bombs just check
+out where this happens and play with the case. Another thing to watch out for is
+the order of terms. This we follow the RFC for which is pretty much the same as
+the OpenLDAP format minus the objectclass and attributetype prefixes to the
+descriptions. We figure the OpenLDAP parser is less complex if the prefixes are
+there (where the parser is told if the description is an objectclass or
+attributetype and does not have to figure this out). However I have encountered
+schemas whose formats do not comply with standards in with respect to the order
+of description fields and had to edit the files. This issue did not occur when
+the files were from the OpenLDAP Foundation which means they do it right but
+overlook schema objects that are not correctly
+formated.</p>
+ </section>
+ <section heading="h1" name="Functionality for the Future">
+ <ul nesting="1">
+ <li>
+Compile triggers and install them into the
+server.</li>
+ <li>
+Compile and load stored
+procedures.</li>
+ <li>
+Test stored procedures and
+triggers.</li>
+ <li>
+Generate JNDI Object and State factories from
+schemas.</li>
+ </ul>
+ </section>
+ </body>
+</document>
Added: directory/trunks/apacheds/src/site/xdoc/users/subentries.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/xdoc/users/subentries.xml?rev=372968&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/xdoc/users/subentries.xml (added)
+++ directory/trunks/apacheds/src/site/xdoc/users/subentries.xml Fri Jan 27 12:11:10 2006
@@ -0,0 +1,514 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+ <properties>
+ <author email="akarasulu">akarasulu</author>
+
+ </properties>
+ <body>
+ <section heading="h2" name="Introduction">
+ <p>
+Subentries are used for managing the administration of different aspects of the
+directory. LDAP has just recently formalized the notion of subentires
+in
+ <a href="http://www.faqs.org/rfcs/rfc3672.html">RFC 3672</a>
+. Subentries have existed within X.500 Directories for years with clear
+specifications for administering collective attributes, schema, and access
+controls. With the exception of managing collective attributes LDAP has no
+equivalent *yet* for administering these aspects. However with RFC 3672, LDAP
+is on its way towards adopting and adapting these mechanisms from X.500
+Directories. It is only a matter of
+time.
+ </p>
+ <p>
+For this reason we intend to remain ahead of the curve by implementing these
+aspects of administration using Subentries and Administrative Areas similar to
+X.500
+Directories.</p>
+ </section>
+ <section heading="h2" name="What exactly are subentries?">
+ <p>
+To explain this properly we're going to need to discuss a couple other things
+like administrative areas (AA) and administrative points (AP) within the
+directory. However for the impatient here's a quick attempt to describe what
+subentries
+are:</p>
+ <p>
+Subentries are hidden leaf entries (which cannot have children). These entries
+immediately subordinate to an administrative point (AP) within the directory.
+They are used to specify administrative information for a part of the Directory
+Information Tree (DIT). Subentries can contain administrative information for
+aspects of access control, schema administration, and collective attributes (and
+others which have not been defined in any specification
+yet).</p>
+ </section>
+ <section heading="h2" name="Administrative Areas, Entries and Points">
+ <p>
+First some definitions as provided by
+X.501:</p>
+ <ul nesting="1">
+ <li>
+11.1.1 administrative area: A subtree of the DIT considered from the perspective
+of
+administration.</li>
+ <li>
+11.1.2 administrative entry: An entry located at an administrative
+point.</li>
+ <li>
+11.1.3 administrative point: The root vertex of an administrative
+area.</li>
+ <li>
+11.1.5 autonomous administrative area: A subtree of the DIT whose entries are
+all administered by the same Administrative Authority. Autonomous administrative
+areas are
+non-overlapping.</li>
+ <li>
+11.1.11 inner administrative area: A specific administrative area whose scope is
+wholly contained within the scope of another specific administrative area of the
+same
+type.</li>
+ <li>
+11.1.17 specific administrative area: A subset (in the form of a subtree) of an
+autonomous administrative area defined for a particular aspect of
+administration: access control, subschema or entry collection administration.
+When defined, specific administrative areas of a particular kind partition an
+autonomous administrative
+area.</li>
+ <li>
+11.1.18 specific administrative point: The root vertex of a specific
+administrative
+area.</li>
+ </ul>
+ <p>
+Now take a step back because the above definitions are, well, from a sleep
+inducing spec. Let's just talk about some
+situations.</p>
+ <p>
+Presume you're the uber directory administrator over at WallyWorld (a Walmart
+competitor). Let's say WallyWorld uses their corporate directory for various
+things including their product catalog. As the uber admin you're going to have a
+bunch of people wanting access, update and even administer your directory.
+Entire departments within WallyWorld are going to want to control different
+parts of the directory. Sales may want to manage the product catalog, while
+operations may want to manage information in other areas dealing with suppliers
+and store locations. Whatever the domain some department will need to manage the
+information as the
+authority.</p>
+ <p>
+Each department will probably designate different people to manage different
+aspects of their domain. You're not going to want to deal with their little
+fiefdoms instead you can delegate the administration of access control policy to
+a departmental contact. You will want to empower your users and administrative
+contacts in these departments so they can do part of the job for you. Plus it's
+much better than having to communicate with everyone in the company to meet
+their needs. This is where the delegation of authority comes into the
+picture.</p>
+ <p>
+Usually administrators do this already to an extent without defining
+administrative areas. Giving users the ability to change their own passwords for
+example is a form of delegation. This is generally a good idea because you don't
+want to set passwords for people. First because you don't want to see the
+password and secondly because of the management nightmare you'd have to deal
+with. Expand this idea out a little further and think about delegating
+administration not of users on their passwords but of entire subtrees in the
+directory to administrative contacts in various
+departments.</p>
+ <p>
+Do you really want to manage the corporate product catalog or just let the sales
+department manage it? But what do we mean by manage? You want sales people to
+create, and delete entries but they may only trust a few people to do this.
+Others may just view the catelog. Who are the people with add/remove powers and
+why should you have to be involved with deciding this ever changing departmental
+policy? Instead you can delegate the management of access controls in this area
+to a administrative contact in the sales department. The sales contact can then
+administer access controls for their department. They're closer to the people in
+sales than you are and they probably have more bandwidth to handle sales related
+needs than you do. Delegating authority in this fashion is what X.500 engineers
+pioneered in the early 80's with the telecom boom in Europe. They knew different
+authorities will want to manage different aspects of directory administration
+for themselves. These X.500 definitions are there to be able to talk about
+administrative areas within the directory. Now let's get back to what these
+things are
+exactly.</p>
+ <p>
+An administrative area is some part of the directory tree that is arbitrarily
+defined. The tree can be split into different administrative areas to delegate
+authority for managing various aspects of administration. For example you can
+have a partition hanging off of *'dc=example,dc=com'* with an *'ou=product
+catalog'* area. You may want this area to be managed by the sales department
+with respect to the content, schema, it's visibility, and collective attributes.
+Perhaps you only want to delegate only one aspect of administration , access
+control, since you don't want people messing around with schema. To do so you
+can define everything under *'ou=product catalog'* to be an administrative area
+specifically for access control and delegate that aspect only. In that case the
+entry, *'ou=product catalog,dc=example,dc=com'* becomes an administrative entry.
+It is also the administrative point for the area which is the tree rooted at
+this
+entry.</p>
+ <p>
+Not all administrative areas are equal. There are really two kinds :
+*autonomous* and *inner* areas. Autonomous areas are areas of administration
+that cannot overlap. Meaning someone is assigned as the supreme authority for
+that subtree. Inner areas are, as their name suggests, nested administrative
+areas within autonomous areas and other inner areas. Yes, you can nest these
+inner areas as deep as you like. You may be asking yourself what the point to
+all this is. Well, say you're the supreme admin of admins. You delegate the
+authority to manage access control for the corporate catalog to the sales admin.
+That admin may in turn decide to delegate yet another area of the catalog to
+another contact within a different department. You delegate access control
+management to the sales admin over the product catalog. The sales admin realizes
+that the job is way bigger than he can manage so he delegates administration of
+subtrees in the catalog to various contacts in different departments. For
+example regions of the catalog under *'ou=electronics' and 'ou=produce'* may be
+delegated to different contacts in their respective departments. However the
+sales admin still reserves the ability to override access controls in the
+catalog. The sales admin can change who manages access controls for different
+parts of the catalog. This chain of delegation is possible using inner
+administrative
+areas.</p>
+ </section>
+ <section heading="h2" name="How are administrative areas defined?">
+ <p>
+Usually an entry is selected as the administrative point and marked with an
+operational attribute. The attributeType of the operational attribute is
+'administrativeRole'. This attribute can have the following
+values:</p>
+ <table>
+ <tr>
+ <th>
+OID</th>
+ <th>
+NAME</th>
+ </tr>
+ <tr>
+ <td>
+2.5.23.1</td>
+ <td>
+autonomousArea</td>
+ </tr>
+ <tr>
+ <td>
+2.5.23.2</td>
+ <td>
+accessControlSpecificArea</td>
+ </tr>
+ <tr>
+ <td>
+2.5.23.3</td>
+ <td>
+accessControlInnerArea</td>
+ </tr>
+ <tr>
+ <td>
+2.5.23.4</td>
+ <td>
+subschemaAdminSpecificArea</td>
+ </tr>
+ <tr>
+ <td>
+2.5.23.5</td>
+ <td>
+collectiveAttributeSpecificArea</td>
+ </tr>
+ <tr>
+ <td>
+2.5.23.6</td>
+ <td>
+collectiveAttributeInnerArea</td>
+ </tr>
+ </table>
+ <p>
+As you can see, 3 aspects, *schema*, *collective attributes*, and *access
+control* are considered. An autonomous administrative area can hence be
+considered with respect to all three specific aspect of administration. If an AP
+is marked as an autonomousArea it generally means that administration of all
+aspects are allowed by the authority. If marked with a specific aspect then only
+that aspect of administration is delegated. The administrativeRole operational
+attribute is multivalued so the uber admin can delegate any number of specific
+administration aspects as he
+likes.</p>
+ <p>
+Also notice that two aspects, collective attribute and access controls, allow
+administrative points to be inner areas. Delegated authorities for these two
+aspects can create inner administrative areas to further delegate their
+administrative powers. The schema aspect unlike the others cannot have inner
+areas because of potential conflicts this may cause which would lead to data
+integrity issues. For this reason only the authority of an automomous area can
+manage schema for the entire
+subtree.</p>
+ <p>
+An autonomous administrative area (AAA) includes the AP and spans all
+descendants below the AP down to the leaf entries of the subtree with one
+exception. If another AAA, let's call it AAA' (prime) is present and rooted
+below the first AAA then the first AAA does not include the entries of AAA'.
+Translation: an AAA spans down until other AAAs or leaf entries are encountered
+within the subtree. This is due to the fact that AAAs do not overlap as do inner
+AAs
+(IAA).</p>
+ </section>
+ <section heading="h2" name="Subentries under an IAA or an AAA">
+ <p>
+Subentries hold administrative information for an IAA or an AAA. These entries
+are of the objectClass 'subentry'. The subentry must contain two attributes: a
+*commonName* and a *subtreeSpecification*. The commonName (or cn) is used as the
+subentry's rdn attribute. The subtreeSpecification describes the collection of
+entries within the AA (IAA or AAA) that the administrative instruction applies
+to.</p>
+ <p>
+A subtree specification uses various parameters described below to define the
+set of entries. Note that entries need not exist for them to be included in the
+collection on
+addition.</p>
+ <subsection heading="h3" name="Base parameter">
+ <p>
+This is the relative name of the root vertex of the subtree relative to the AP.
+So if the AP is *'ou=system'* and the base is *'ou=users'*, the subtree begins
+at *'ou=users,ou=system'*. The base can be any length of name components
+including 0 where it's the empty name "". In this case, the subtree begins at
+the AP, *'ou=system'* in the example
+above.</p>
+ </subsection>
+ <subsection heading="h3" name="Chop parameters">
+ <p>
+Chop specification parameters define specific nodes to be excluded from the
+collection as well as how deep the subtree spans and even where it starts
+relative to the
+base.</p>
+ <subsection heading="h4" name="chopBefore and chopAfter">
+ <p>
+These parameters are names relative to the root vertex of the subtree, hence
+they are relative to the base parameter. They specify whether or not an entry
+and its descendants are to be excluded from the
+collection.</p>
+ <p>
+When *chopBefore* is used, the entry specified is excluded from the collection.
+When *chopAfter* is used the entry is included however all descendants below the
+entry are
+excluded.</p>
+ </subsection>
+ <subsection heading="h4" name="minimum and maximum">
+ <p>
+The minimum parameter describes the minimum DN length required to include
+entries within the selection. The maximum parameter describes the maximum DN
+length allowed before entries are excluded from the
+collection.</p>
+ </subsection>
+ </subsection>
+ <subsection heading="h3" name="Specification filter parameter">
+ <p>
+The specification filter is a unique beast. It's a filter like a search filter,
+however its syntax and expressivity is radically different. Think of a
+specification filter as a simplified form of search filters where all terms only
+test the objectClass attribute and only equality checks can be performed. Oh and
+yes, you do have logical operators like *and*, *or* and
+*not*.</p>
+ <p>
+So with a filter you have the ability to "refine" the subtree already specified
+with chop, and base parameters. This "refinement" makes it so the collection is
+not really a contiguous subtree of entries but a possibly disconnected set of
+selected based on the objectClass characteristics of entries. This feature of a
+subtreeSpecification is very powerful. For example, I can define a subtree to
+cover a region of an AA yet include only inetOrgPersons within this
+region.</p>
+ </subsection>
+ <subsection heading="h3" name="Subentry types in ApacheDS">
+ <p>
+Different subentry objectClasses exist for applying different aspects of
+administration to the entry collection described by their subtreeSpecification
+attribute. By the way the subtreeSpecification attribute is single valued so
+there can only be one in a subentry. However you can have several subentries of
+various kinds under an AP. Furthermore their collections can
+intersect.</p>
+ <p>
+The kinds of subentries allowed though are limited by the administrativeRole of
+the AP. If the AP is for an access control AA then you can't add a subentry to
+it for schema administration. The AP must have the role for schema
+administration as well to allow both types of
+subentries.</p>
+ <p>
+ApacheDS does not manage schema using subentries in the formal X.500 sense right
+now. There is a single global subentry defined at *'cn=schema'* for the entire
+DSA. The schema is static and cannot be updated at runtime even by the
+administrator. Pretty rough for now but it's the only lagging subsystem. We'll
+of course make sure this subsystem catches
+up.</p>
+ <p>
+ApacheDS does however manage collective attributes using subentries. An AP that
+takes the administrativeRole for managing collective attributes can have
+subentries added. These subentries are described in greater detail
+here:
+ <a href="./collective.html">Collective</a>
+. In short, collective attributes added to subentries show up within entries
+included by the subtreeSpecification. Adding, removing, and modifying the values
+of collective attributes within the subentries instantly manifest changes in the
+entries selected by the subtreeSpecification. Again
+consult
+ <a href="./collective.html">Collective</a>
+for a hands on explanation of how to use this
+feature.
+ </p>
+ <p>
+ApacheDS performs access control and allows delegation using subentries, AAAs,
+and IAAs. ApacheDS uses the Basic Access Control Scheme from X.501 to manage
+access control. By default this subsystem is deactivated because it locks down
+everything except access by the admin. More information about hands on use is
+available
+here:
+ <a href="./authorization.html">Authorization</a>
+. However to summarize its association with subentries, access control
+information (ACI) can be added to subentries under an AP for access control AAs.
+When one or more ACI are added in this fashion, the access rules of the ACI set
+apply to all entries selected by the subtreeSpecification. Even with this
+powerful feature individual entries can have ACI added to them for controlling
+access to them. Also there are things you can do with ACI added to subentries
+that cannot be done with entry level ACI. For example you cannot allow entry
+addition with entry ACI. You must use subtreeSpecifications to define where
+entries may be added because those entries and their parents may not exist
+yet.
+ </p>
+ </subsection>
+ <subsection heading="h3" name="How to specify a subentry's subtreeSpecification">
+ <p>
+The best way to demonstrate subtreeSpecification values are through examples.
+Here's the simplest filter of them
+all:</p>
+ <source>{}
+</source>
+ <p>
+This basically selects the entire contiguous subtree below the AP. The base is
+the empty name and it's rooted at the
+AP.</p>
+ <p>
+Next step let's add a
+base:</p>
+ <source>{ base "ou=users" }
+</source>
+ <p>
+If this is the subtreeSpecification under the AP, *'ou=system'*, then it selects
+every entry under
+*'ou=users,ou=system'*.</p>
+ <p>
+OK that was easy so now let's slice and dice the tree now using the minimum and
+maximum chop
+parameters.</p>
+ <source>{ minimum 3, maximum 5 }
+</source>
+ <p>
+This selects all entries below *'ou=system'* which have a DN size equal to 3
+name components, but no more than 5. So for example
+*'uid=jdoe,ou=users,ou=system'* would be included but
+*'uid=jack,ou=do,ou=not,ou=select,ou=users,ou=system'* would not be included.
+Let's continue and combine the base with just a minimum
+parameter:</p>
+ <source>{ base "ou=users", minimum 4 }
+</source>
+ <p>
+Here the subtree starts at *'ou=users,ou=system'* if the subentry subordinates
+to the AP at *'ou=system'*. The user
+*'uid=jdoe,ou=deepenough,ou=users,ou=system'* is selected by the spec where as
+*'uid=jbean,ou=users,ou=system'* is
+not.</p>
+ <p>
+It's time to add some chop
+exclusions:</p>
+ <source>{
+ base "ou=users",
+ minimum 4,
+ specificExclusions { chopBefore: "ou=untrusted" }
+}
+</source>
+ <p>
+Again if placed at the AP *'ou=system'* this subtree would begin at
+*'ou=users,ou=system'*. It would not include users that subordinate to it though
+because of the minimum constraint since these users would have 3 components in
+their DN. The specific exclusions prevent *'ou=untrusted,ou=users,ou=system'*
+and all its descendants from being included in the collection. However
+*'uid=jbean,ou=trusted,ou=users,ou=system'* would be included since it meets the
+minimum requirement, is a descendant of *'ou=users,ou=system'* and is not under
+the excluded DN,
+*'ou=untrusted,ou=users,ou=system'*.</p>
+ <p>
+Note that you can add as many exclusions as you like by comma delimiting them.
+For
+example:</p>
+ <source>{
+ base "ou=users",
+ minimum 4,
+ specificExclusions { chopBefore: "ou=untrusted", chopAfter: "ou=ugly", chopBefore: "ou=bad" }
+}
+</source>
+ <p>
+The final example includes a refinement. Again any combination of chop, filter
+and base parameters can be used. The following refinement makes sure the users
+selected are of the objectClass inetOrgPerson and specialUser where the OID for
+the specialUser class is 32.5.2.1
+(fictitious).</p>
+ <source>{
+ base "ou=users",
+ minimum 4,
+ specificExclusions { chopBefore: "ou=untrusted", chopAfter: "ou=ugly", chopBefore: "ou=bad" }
+ specificationFilter and:{ item:32.5.2.1, item:inetOrgPerson }
+}
+</source>
+ <p>
+If you'd like to see the whole specification of the grammar used for the
+subtreeSpecification take a look at Appendix A
+in
+ <a href="http://www.faqs.org/rfcs/rfc3672.html">RFC 3672</a>
+.
+ </p>
+ </subsection>
+ </section>
+ <section heading="h2" name="Future Possibilities">
+ <p>
+In the immediate future we intend to
+introduce
+ <a href="./triggers.html">Triggers</a>
+, stored procedures and views into ApacheDS. Subentries will play a critical
+role in the administration and application of these features. For example a
+Trigger specification need not include information on what entries it applies to
+since the subtreeSpecification handles this. The question of "on what" a trigger
+applies to is nicely disassociated from the "which operation" part of the
+specification. This makes for much better reuse of triggers. It also allows for
+the pin point application of triggers to entries in the DIT. Likewise a view
+itself will be defined by a specification. A view for example in a subentry can
+define a region of the tree that does not exist but is shadowed from another
+region all together. The possibilities here are
+limitless.
+ </p>
+ <p>
+Of course we will revamp the schema subsystem of ApacheDS to use subentries in
+AAA to manage the schema in effect within different regions of the DIT. Today
+most LDAP servers just have a global scheme in effect for the entire DIT served
+by a DSA. We don't think that is reasonable at all. So expect some serious
+advances in the design of a new schema subsystem based on
+subentries.</p>
+ <p>
+Replication is yet another excellent candidate for using subentries. Replication
+of specific collections of entries can be managed for each cluster rather than
+replicating the entire DIT served by a DSA to replicas. This way we don't only
+control what is replicated but we can also control how and where it is
+replicated.</p>
+ </section>
+ <section heading="h2" name="Conclusions">
+ <p>
+ApacheDS has implemented subentries for the administration of various aspects of
+the directory and gains several powerful features as a result: namely precision
+application of control to entry collections and the ability to delegate
+administrative authority. For details on the administration of each aspect using
+subentries
+(
+ <a href="./collective.html">Collective</a>
+and
+ <a href="./authorization.html">Authorization</a>
+) please see the respective
+documentation.
+ </p>
+ <p>
+As ApacheDS progresses it will gain an immense advantage from subentries. Both
+for existing LDAP features like scheme and for new experimental features like
+triggers, and
+replication.</p>
+ </section>
+ </body>
+</document>
Added: directory/trunks/apacheds/src/site/xdoc/users/subtreespecificationgrammar.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/xdoc/users/subtreespecificationgrammar.xml?rev=372968&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/xdoc/users/subtreespecificationgrammar.xml (added)
+++ directory/trunks/apacheds/src/site/xdoc/users/subtreespecificationgrammar.xml Fri Jan 27 12:11:10 2006
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+ <properties>
+ <author email="elecharny">elecharny</author>
+
+ </properties>
+ <body>
+ <section heading="h1" name="Subtree Specification LL(1) Grammar">
+ <p>
+Here is the LL(1) grammar used to decode a subtreeSpecification as described
+by
+ <a href="http://www.faqs.org/rfcs/rfc3672.html">RFC 3672</a>
+ </p>
+ <source><SubtreeSpecification> ::= '{' <spse> <base-e> <chopSpecification> <spse> <refinement-e> '}'
+
+<base-e> ::=
+ «base» <sps> <localName> <spse> ',' <spse> |
+ e
+
+<chopSpecification> ::= «chopSpecification» '{' <spse> <chopSpecification-in> '}'
+
+<chopSpecification-in> ::=
+ «specificExclusions» <spse> <chop-set-of-choice> <spse> <specificExclusions-follower> |
+ «minimum» <sps> <number> <spse> <minimum-follower> |
+ «maximum» <sps> <number> <spse>
+
+<specificExclusions-follower> ::=
+ ',' <spse> «minimum» <sps> <number> <spse> <minimum-follower> |
+ ',' <spse> «maximum» <sps> <number> <spse>
+
+<minimum-follower> ::= ',' <spse> «maximum» <sps> <number> <spse>
+
+<refinement-e> ::=
+ «specificationFilter» <sps> <refinement> |
+ e
+
+<refinement> ::=
+ «item» <spse> ':' <spse> OID <spse> |
+ «and» <spse> ':' <spse> <set-of-refinement> |
+ «or» <spse> ':' <spse> <set-of-refinement> |
+ «not» <spse> ':' <spse> <refinement> |
+
+<set-of-refinement> ::= '{' <spse> <refinement> <refinements> '}' <spse>
+
+<refinements> ::=
+ ',' <spse> <refinement> |
+ e
+
+<localName> ::= '"' DN '"'
+</source>
+ </section>
+ </body>
+</document>
Added: directory/trunks/apacheds/src/site/xdoc/users/userclasses.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/xdoc/users/userclasses.xml?rev=372968&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/xdoc/users/userclasses.xml (added)
+++ directory/trunks/apacheds/src/site/xdoc/users/userclasses.xml Fri Jan 27 12:11:10 2006
@@ -0,0 +1,166 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+ <properties>
+ <author email="akarasulu">akarasulu</author>
+
+ </properties>
+ <body>
+ <section heading="h2" name="What are User Classes?">
+ <p>
+A large part of managing access control information involves the specification
+of *who* can perform *which* operation on *what* protected resource (entries,
+attributes, values etc). At evaluation time a requestor of an operation is
+known. The identity of the requestor is checked to see if it falls into the set
+of users authorized to perform the operation. User classes are hence definitions
+of a set of zero or more users permissions apply to. Several constructs exist
+for specifying a user
+class.</p>
+ </section>
+ <section heading="h2" name="Simple User Classes">
+ <p>
+There are 3 really simple constructs for specifying the user. These constructs
+are listed in the table
+below:</p>
+ <table>
+ <tr>
+ <th>
+User Class
+Construct</th>
+ <th>
+Meaning</th>
+ <th>
+Example</th>
+ </tr>
+ <tr>
+ <td>
+allUsers</td>
+ <td>
+Any user with possible requirements for
+AuthenticationLevel</td>
+ <td>
+*allUsers*</td>
+ </tr>
+ <tr>
+ <td>
+thisEntry</td>
+ <td>
+The user with the same DN as the entry being
+accessed</td>
+ <td>
+*thisEntry*</td>
+ </tr>
+ <tr>
+ <td>
+name</td>
+ <td>
+The user with the specified
+DN</td>
+ <td>
+*name* \{ "uid=admin,ou=system"
+\}</td>
+ </tr>
+ </table>
+ <p>
+These are pretty intuitive. Two other user classes may be a bit less easy to
+understand or may require some explanation. For these we discuss them in the
+sections
+below.</p>
+ </section>
+ <section heading="h2" name="User Class: userGroup">
+ <p>
+The *userGroup* user class construct is also pretty intuitive. It does however
+require some background information about how group membership is determined for
+this
+purpose.</p>
+ <p>
+ApacheDS associates users within a group using the *groupOfNames* and
+*groupOfUniqueNames* objectClasses. To define groups an entry of either of these
+objectClasses is added anywhere in the server's DIT. *member* or *uniqueMember*
+attributes whose values are the DN of user entries are present within the entry
+to represent membership within the
+group.</p>
+ <table>
+ <tr>
+ <td>
+ <img src="http://docs.safehaus.org/images/icons/emoticons/warning.png"/>
+ </td>
+ <td>
+ <p>
+Although such group entries can be added anywhere within the DIT to be
+recognized by the Authorization subsystem, a recommended convention exists. Use
+the 'ou=groups' container under a namingContext/partition within the server to
+localize groups. Most of the time group information can be stored under
+'ou=groups,ou=system'.</p>
+ </td>
+ </tr>
+ </table>
+ <p>
+Just like the *name* construct, the *userGroup* construct takes a single
+parameter: the DN of the group entry. During ACI evaluation ApacheDS checks to
+see if the requestor's DN is contained within the group. Below is a section from
+X.501 specification which explains just how this is
+done:</p>
+ <p>
+In order to determine whether the requestor is a member of a userGroup user
+class, the following criteria
+apply:</p>
+ </section>
+ <section heading="h2" name="User Class: subtree">
+ <p>
+Here the user class specification construct is a subtree specification without a
+refinement filter. Such a specification is simple yet very powerful. The subtree
+defines a collection of entries. During ACI evaluation, ApacheDS will check to
+see if the requestor's DN is included by this
+collection.</p>
+ <p>
+For more information on how to define a subtreeSpecification please
+see
+ <a href="./subentries.html">Subentries</a>
+and the Administrative
+Model.
+ </p>
+ <table>
+ <tr>
+ <td>
+ <img src="http://docs.safehaus.org/images/icons/emoticons/warning.png"/>
+ </td>
+ <td>
+ <p>
+For this purpose a subtree is not refined. Meaning it does not evaluate
+refinement filters. This is to restrict the information needed to make a
+determination to just the DN of the requestor and not the entry of the
+requestor.</p>
+ </td>
+ </tr>
+ </table>
+ </section>
+ <section heading="h2" name="Combining Multiple UserClass Specification Mechanisms">
+ <p>
+The same userClass mechanism can be specified more than once if it makes sense.
+There is no reason to specify allUsers more than once. More than one type of
+user class mechanism can be used as well. Again some combinations just will not
+make sense like having a name based userClass then allUsers. The following
+ACIItem grants delete abilities to a set of users using more than one machanism.
+It allows jbean, jdoe, all users in the Administrators group to delete entries.
+It also allows requestors to delete their own user
+entry.</p>
+ <source>{ identificationTag "deleteAci"
+ precedence 255,
+ authenticationLevel simple,
+ itemOrUserFirst userFirst:
+ {
+ userClasses
+ {
+ thisEntry,
+ name { "uid=jbean,ou=users,ou=system" },
+ name { "uid=jdoe,ou=users,ou=system" },
+ userGroup { "cn=Administrators,ou=groups,ou=system" }
+ },
+ userPermissions { { protectedItems {entry}, grantsAndDenials { grantRemove } } }
+ }
+}
+</source>
+ </section>
+ </body>
+</document>
Added: directory/trunks/apacheds/src/site/xdoc/users/userpermissions.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/xdoc/users/userpermissions.xml?rev=372968&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/xdoc/users/userpermissions.xml (added)
+++ directory/trunks/apacheds/src/site/xdoc/users/userpermissions.xml Fri Jan 27 12:11:10 2006
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+ <properties>
+ <author email="akarasulu">akarasulu</author>
+
+ </properties>
+ <body>
+ <section heading="h1" name="Coming soon ..."/>
+ </body>
+</document>