src/site/xdoc/docs/users/acareas.xml - directory-server - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>

 <document>
   <properties>
     <author email="akarasulu">akarasulu</author>

   </properties>
   <body>
     <section heading="h1" name="Introduction">
       <p>
 This guide will show you how to create an Access Control Specific Area and
 Access Control Inner Areas for administering access controls within ApacheDS.
 Basic knowledge of the X.500 administrative model is presumed along with an
 understanding of the Basic Access Control Scheme in X.501. For quick primers
 please take a look at the following
 documentation:</p>
       <ul nesting="1">
         <li>
           <a href="./subentries.html">Subentries</a>
 and the Administrative
 Model
         </li>
         <li>
           <a href="./authorization.html">Authorization</a>
         </li>
       </ul>
     </section>
     <section heading="h1" name="Creating Access Control Specific Areas (ACSA)">
       <p>
 An access control specific area is an Autonomous Administrative Area (AAA) for
 managing access control specific aspects of a subtree within the DIT. Like all
 administrative areas, an access control specific area is rooted at a vertex
 entry called the Administrative Point (AP). The ACSA spans down until leaf
 entries are encountered or until another ACSA is encountered. Access control
 specific areas do not
 overlap.</p>
       <p>
 Under the AP, you can add subentries that contain prescriptiveACI attributes.
 Zero or more subentries can be added, each with one or more prescriptiveACI.
 These subentries apply access control information (ACI) in these prescriptiveACI
 attributes to collections of entries within the
 ACSA.</p>
       <subsection heading="h2" name="Adding an 'administrativeRole' Attribute">
         <p>
 An entry becomes an AP when it has an administrativeRole attribute added to it
 with the appropriate
 value
           <a href="./s.html">s</a>
 . For an ACSA, we need to add the 'accessControlSpecificArea' value to this
 attribute.
         </p>
         <p>
 Most of the time users will create partitions in the server and set the root
 context of the partition (its suffix) to be the AP for a ACSA. For example the
 default server.xml for ApacheDS ships with a partition with the suffix,
 'dc=example,dc=com'. We can use this suffix entry as the AP and our ACSA can
 cover all entries under and including
 'dc=example,dc=com'.</p>
         <p>
 The code below binds to the server as admin ('uid=admin,ou=system') and modifies
 the suffix entry to become an ACSA. Note that we check to make sure the
 attribute does not already exist before attempting the add
 operation.</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:389/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 );

   // Lookup the administrativeRole specifically since it is operational
   Attributes ap = ctx.getAttributes( "", new String[] { "administrativeRole" } );
   Attribute administrativeRole = ap.get( "administrativeRole" );

   // If it does not exist or has no ACSA value then add the attribute
   if ( administrativeRole == null || ! administrativeRole.contains( "accessControlSpecificArea" ) )
   {
     Attributes changes = new BasicAttributes( "administrativeRole", "accessControlSpecificArea", true );
     ctx.modifyAttributes( "", DirContext.ADD_ATTRIBUTE, changes );
   }
   ...
 </source>
         <p>
 This simple modification of adding the value 'accessControlSpecificArea' to the
 administrativeRole makes the suffix entry 'dc=example,dc=com' an AP for an
 access control specific area. Now you can add subentries to your heart's content
 which subordinate to the
 AP.</p>
       </subsection>
     </section>
     <section heading="h1" name="Creating an Access Control Inner Administrative Area">
       <p>
 Creating an inner area involves the same process. In fact the same code can be
 used by changing the value added to the administrativeRole attribute. To create
 the inner area just add 'accessControlInnerArea' for the administrativeRole
 within the AP: same steps, same code, different value for the
 administrativeRole.</p>
     </section>
     <section heading="h1" name="Access Control Subentries">
       <p>
 After creating the access control area you can create subentries that
 subordinate to this AP for managing access to it and anything below. Access
 control subentries are entries with the objectClasses: 'subentry' and
 'accessControlSubentry'. An access control subentry must contain 3 attributes
 other than the obvious objectClass attribute. These required attributes are
 listed
 below:</p>
       <table>
         <tr>
           <th>
 Attribute</th>
           <th>
 SINGLE-VALUED</th>
           <th>
 Description</th>
         </tr>
         <tr>
           <td>
 cn</td>
           <td>
 no</td>
           <td>
 The name of the subentry used as its
 RDN</td>
         </tr>
         <tr>
           <td>
 subtreeSpecification</td>
           <td>
 yes</td>
           <td>
 The specification for the collection of entries the ACI is to be applied
 to.</td>
         </tr>
         <tr>
           <td>
 prescriptiveACI</td>
           <td>
 no</td>
           <td>
 The attribute holding the
 ACIItem</td>
         </tr>
       </table>
     </section>
   </body>
 </document>
	<?xml version="1.0" encoding="UTF-8"?>

	<document>
	<properties>
	<author email="akarasulu">akarasulu</author>

	</properties>
	<body>
	<section heading="h1" name="Introduction">
	<p>
	This guide will show you how to create an Access Control Specific Area and
	Access Control Inner Areas for administering access controls within ApacheDS.
	Basic knowledge of the X.500 administrative model is presumed along with an
	understanding of the Basic Access Control Scheme in X.501. For quick primers
	please take a look at the following
	documentation:</p>
	<ul nesting="1">
	<li>
	<a href="./subentries.html">Subentries</a>
	and the Administrative
	Model
	</li>
	<li>
	<a href="./authorization.html">Authorization</a>
	</li>
	</ul>
	</section>
	<section heading="h1" name="Creating Access Control Specific Areas (ACSA)">
	<p>
	An access control specific area is an Autonomous Administrative Area (AAA) for
	managing access control specific aspects of a subtree within the DIT. Like all
	administrative areas, an access control specific area is rooted at a vertex
	entry called the Administrative Point (AP). The ACSA spans down until leaf
	entries are encountered or until another ACSA is encountered. Access control
	specific areas do not
	overlap.</p>
	<p>
	Under the AP, you can add subentries that contain prescriptiveACI attributes.
	Zero or more subentries can be added, each with one or more prescriptiveACI.
	These subentries apply access control information (ACI) in these prescriptiveACI
	attributes to collections of entries within the
	ACSA.</p>
	<subsection heading="h2" name="Adding an 'administrativeRole' Attribute">
	<p>
	An entry becomes an AP when it has an administrativeRole attribute added to it
	with the appropriate
	value
	<a href="./s.html">s</a>
	. For an ACSA, we need to add the 'accessControlSpecificArea' value to this
	attribute.
	</p>
	<p>
	Most of the time users will create partitions in the server and set the root
	context of the partition (its suffix) to be the AP for a ACSA. For example the
	default server.xml for ApacheDS ships with a partition with the suffix,
	'dc=example,dc=com'. We can use this suffix entry as the AP and our ACSA can
	cover all entries under and including
	'dc=example,dc=com'.</p>
	<p>
	The code below binds to the server as admin ('uid=admin,ou=system') and modifies
	the suffix entry to become an ACSA. Note that we check to make sure the
	attribute does not already exist before attempting the add
	operation.</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:389/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 );

	// Lookup the administrativeRole specifically since it is operational
	Attributes ap = ctx.getAttributes( "", new String[] { "administrativeRole" } );
	Attribute administrativeRole = ap.get( "administrativeRole" );

	// If it does not exist or has no ACSA value then add the attribute
	if ( administrativeRole == null \|\| ! administrativeRole.contains( "accessControlSpecificArea" ) )
	{
	Attributes changes = new BasicAttributes( "administrativeRole", "accessControlSpecificArea", true );
	ctx.modifyAttributes( "", DirContext.ADD_ATTRIBUTE, changes );
	}
	...
	</source>
	<p>
	This simple modification of adding the value 'accessControlSpecificArea' to the
	administrativeRole makes the suffix entry 'dc=example,dc=com' an AP for an
	access control specific area. Now you can add subentries to your heart's content
	which subordinate to the
	AP.</p>
	</subsection>
	</section>
	<section heading="h1" name="Creating an Access Control Inner Administrative Area">
	<p>
	Creating an inner area involves the same process. In fact the same code can be
	used by changing the value added to the administrativeRole attribute. To create
	the inner area just add 'accessControlInnerArea' for the administrativeRole
	within the AP: same steps, same code, different value for the
	administrativeRole.</p>
	</section>
	<section heading="h1" name="Access Control Subentries">
	<p>
	After creating the access control area you can create subentries that
	subordinate to this AP for managing access to it and anything below. Access
	control subentries are entries with the objectClasses: 'subentry' and
	'accessControlSubentry'. An access control subentry must contain 3 attributes
	other than the obvious objectClass attribute. These required attributes are
	listed
	below:</p>
	<table>
	<tr>
	<th>
	Attribute</th>
	<th>
	SINGLE-VALUED</th>
	<th>
	Description</th>
	</tr>
	<tr>
	<td>
	cn</td>
	<td>
	no</td>
	<td>
	The name of the subentry used as its
	RDN</td>
	</tr>
	<tr>
	<td>
	subtreeSpecification</td>
	<td>
	yes</td>
	<td>
	The specification for the collection of entries the ACI is to be applied
	to.</td>
	</tr>
	<tr>
	<td>
	prescriptiveACI</td>
	<td>
	no</td>
	<td>
	The attribute holding the
	ACIItem</td>
	</tr>
	</table>
	</section>
	</body>
	</document>