directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From akaras...@apache.org
Subject svn commit: r329722 [2/2] - in /directory/apacheds/trunk/xdocs: ./ users/
Date Mon, 31 Oct 2005 04:00:43 GMT
Modified: directory/apacheds/trunk/xdocs/users/plugin.xml
URL: http://svn.apache.org/viewcvs/directory/apacheds/trunk/xdocs/users/plugin.xml?rev=329722&r1=329721&r2=329722&view=diff
==============================================================================
--- directory/apacheds/trunk/xdocs/users/plugin.xml (original)
+++ directory/apacheds/trunk/xdocs/users/plugin.xml Sun Oct 30 20:00:37 2005
@@ -1,191 +1,186 @@
 <?xml version="1.0" encoding="UTF-8"?>
+
 <document>
   <properties>
-    <author email="akarasulu@apache.org">Alex Karasulu</author>
-    <title>Maven Directory Plugin</title>
+    <author email="akarasulu">akarasulu</author>
+    <title>Plugin</title>
   </properties>
-  
   <body>
-    <section name="Maven Directory Plugin">
+    <section heading="h1" name="Maven Directory Plugin">
       <p>
-        Currently the primary function of the plugin is to generates 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>
-
-      <ul>
-        <li>
-          Compiled hard coded files load into the server really fast in theory.
-        </li>
+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>
-          Published schemas never really change so why do they need to be in a
-          human readable form.
-        </li>
+Extra code generation phase is not that hard with a plugin
+tool.</li>
         <li>
-          Eventually, schema changes made through LDAP will be preserved through
-          restarts.
-        </li>
+Schema verification can occur before deploying schemas into the
+server.</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>
-      </ul>
-
-      <subsection name="Properties">
+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>
+            <th>
+Property</th>
+            <th>
+Optional?</th>
+            <th>
+Description</th>
           </tr>
           <tr>
-            <td>maven.ldap.server.schema.target.dir</td>
-            <td>Yes</td>
             <td>
-              <p>Default value is
-                <code>target/schema</code>.</p>
-            </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>
-              <p>Default value is
-                <code>uid=admin,ou=system</code>.</p>
-            </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>
-              <p>Default value is
-                <code>src/schema</code>.</p>
-            </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>
-              <p>Default value is
-                <code>org.apache.ldap.server.schema.bootstrap</code>.</p>
-            </td>
+maven.ldap.server.schema.packageDefault</td>
+            <td>
+Yes</td>
+            <td>
+Default value is
+org.apache.ldap.server.schema.bootstrap.</td>
           </tr>
         </table>
       </subsection>
-
-      <goals>
-        <goal>
-          <name>directory:generate</name>
-          <description>
-            Generates class files for OpenLDAP schemas.
-          </description>
-        </goal>
-        <goal>
-          <name>directory:init</name>
-          <description>
-            Finds the required parameters needed for the goals of the
-            plugin.
-          </description>
-        </goal>
-        <goal>
-          <name>directory:prepare-filesystem</name>
-          <description>
-            Creates source output directories used to deposite schema
-            files that are generated.
-          </description>
-        </goal>
-        <goal>
-          <name>directory:schema</name>
-          <description>
-            Top level schema generating function that uses other goals to
-            coordinate generation.
-          </description>
-        </goal>
-      </goals>
-
-      <subsection names="Usage">
+      <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>.
+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 name="How to Integrate">
+    <section heading="h1" name="How to Integrate Plugin Into Your Own Projects">
       <p>
-        Ok so 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>
-        <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 <code>maven.ldap.server.schema.dir</code>
-          property in your project.properties file.   For each schema file
-          add the file base name to the <code>maven.ldap.server.schemas</code>
-          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 <code>
-          maven.ldap.server.schema.target.dir</code> property in your
-          project.properties file.
-        </li>
-        <li>
-          By default the plugin generates code in a server schema package:
-          <code>org.apache.ldap.server.schema.bootstrap</code>.  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, <code>
-          maven.ldap.server.schema.package.</code> with the name of the schema
-          (<b>without</b> the extension) appended to it.  So for schema file
-          foo.schema the following property key would be used: <code>
-          maven.ldap.server.schema.package.foo</code> 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 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 <b>base</b> for the schema
-          dependency list is <code>maven.ldap.server.schema.deps.</code> and
-          for a foo.schema file the full key would be
-          <code>maven.ldap.server.schema.deps.foo</code>
-        </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 <code>maven.ldap.server.schema.owner.
-          </code> so don't forget to append the schema name to it.
-        </li>
+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 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
+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 ~
@@ -225,54 +220,48 @@
 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&amp;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.
+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&amp;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>
-        <b>WARNING</b>: 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>
+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 name="Functionality for the Future">
-      <ul>
-         <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>
+    <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>    
+    </section>
   </body>
 </document>

Added: directory/apacheds/trunk/xdocs/users/userclasses.xml
URL: http://svn.apache.org/viewcvs/directory/apacheds/trunk/xdocs/users/userclasses.xml?rev=329722&view=auto
==============================================================================
--- directory/apacheds/trunk/xdocs/users/userclasses.xml (added)
+++ directory/apacheds/trunk/xdocs/users/userclasses.xml Sun Oct 30 20:00:37 2005
@@ -0,0 +1,147 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+  <properties>
+    <author email="akarasulu">akarasulu</author>
+    <title>User Classes</title>
+  </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 w/ possible reqs 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 specification 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>
+      <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>
+      <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 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 defined 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>
+.
+      </p>
+      <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>
+    </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 one time.  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>



Mime
View raw message