Obtaining policy information for a newly created object by using XML

Use the GetPolicy procedure of the Managed Active Directory namespace to obtain the permissions and other policy elements for an object.

When system objects such as organizational units, groups, users, and Web sites are created, it is usually necessary to apply appropriate security permissions to the newly created object. In addition, it is often necessary to create additional objects that belong to the newly created object, and apply security settings to these additional child objects.

The GetPolicy procedure defines:

Security permissions that must be applied to all new system objects.
Group memberships that must be granted to new group and user objects.
Child organizational units and child groups that must be created within new organizational units.

Organizational units can be nested to any depth.

Example of a request that calls the GetPolicy procedure

<request>
  <procedure>
	<execute namespace="Managed Active Directory" procedure="GetPolicy">
	<executeData>
		<policyName>reseller</policyName>
		<containerPath>LDAP://ou=Reseller,ou=Hosting,dc=contoso,dc=com</containerPath>
		<objectName>ResellerGuy</objectName>
		<objectType>user</objectType>
	</executeData>
	</execute>
  </procedure>
</request>

Input for GetPolicy

The following input is valid for this request:

Policy name
Use the <policyName> element to specify the type of organization for this policy. Possible types are:
- default
- hosting
- reseller
- customer
If you do not include this element, the request uses the default value. The default value does little except to create the requested object. When calling GetPolicy with <objectType> equal to the organization, <policyName> specifies the type of organizational unit being created. For other <objectType> values, then <policyName> refers to the type of the owner organization specified by <containerPath>.
Container path
Use the <containerPath> element when creating the hosting organizational unit to specify the Lightweight Directory Access Protocol (LDAP) path of the domain in which Hosting is to be created. In all other cases, use <containerPath> to specify the LDAP path that refers to an organizational unit created by CreateOrganization. This parameter tells GetPolicy what the parent of the newly created object should be. In the case of Web sites, services, and directories, the <containerPath> refers to an owner relationship rather than an Active Directory container relationship.
Object name
Use the <objectName> element to specify the name of the object on which to get the policy.
Object type
Use the <objectType> element to specify the type of object on which to get the policy. The object type can be user, org, group, webService, webSite, or webDir. The user, org, and group types refer to Active Directory object types. The webService type refers to the W3SVC and MSFTPSVC metabase objects, for which GetPolicy specifies security settings. The webSite type refers to a Web site or File Transfer Protocol (FTP) site metabase object. The webDir type refers to a file system directory on the hard disk of the server.
Object path (optional)
Use the <objectPath> element to specify the LDAP path as an alternative way of providing the <containerPath> and <objectName> parameters. If this parameter is specified, the <objectName> is taken from the first component of the LDAP path, and the remaining components compose the <containerPath>.

The following topics provide additional information about how GetPolicy is implemented.

How to read the GetPolicy procedure

A tag named <policies> within the <procedureData> inside of GetPolicy contains all of the essential policy information. When a call is made to GetPolicy, the system looks in <policies> for a <policy> tag whose policyName attribute matches the <policyName> that was passed in as a parameter. The system then looks within that <policy> element for a tag whose name is the same as the <objectType> passed in as a parameter.

If there is more than one such element, as is the case with the <webDir> elements in the hosting policy, all of them are returned. There will be at least one attribute ("type" in the case of <webDir>) that differs among the returned elements.

After one or more elements that match the provided <policyName> and <objectType> have been identified, GetPolicy performs two more operations before returning the data. The first operation is name expansion. The second operation is expansion of any <trusteeGroupNameGrant> and <trusteeWebGroupNameGrant> elements. The third operation is calculating and assigning a "path" attribute to each org, group, and user element.

Name expansion

Every call to GetPolicy provides an <objectName> and a <containerPath>, although these items can be optionally provided in the form of a single <objectPath> which implies both <objectName> and <containerPath>.

The <containerPath> is further converted by GetPolicy into three component pieces: the name of the parent, the distinguished name (also known as DN) of the parent (which is the LDAP path minus the "LDAP://" portion). To use the supplied pieces, everywhere in the selected policy element that a name in square brackets appears, the square brackets and the text within are replaced as follows:

[self] is replaced with the name supplied in <objectName>
[parent] is replaced with the parent name (not the full distinguished name or LDAP path)
[parentDN] is replaced with the distinguished name of the parent.
[dc] is replaced with the domain components of the parent's LDAP path.

The following excerpt shows how this works for a <user> object created within a reseller:

<policy policyName="reseller">
		...
	<user name="[self]">
		<memberOfGroup name=		"LDAP://cn=AllUsers@[parent],ou=Services,[parentDN]" />
	</user>

Using the parameters shown in the previous section, Typical Usage, the excerpt will be returned as:

<policy policyName="reseller">
		...
	<user name="Reseller Guy">
		<memberOfGroup name=		"LDAP://cn=AllUsers@Reseller,ou=Services,ou=Hosting,dc=contoso,dc=com" />
	</user>

Trustee expansion

Elements named <trusteeGroupNameGrant> and <trusteeWebGroupNameGrant> are used within access control entry (<ace>) elements as macros for longer, but repetitive entries. The following element:

<trusteeGroupNameGrant name="LDAP://cn=AllUsers@[self],ou=Services,ou=[self],[parentDN]" />

expands to:

<trustee>LDAP://cn=AllUsers@Reseller,ou=Services,ou=Reseller,ou=Hosting,dc=contoso,dc=com
  </trustee>
<trusteeType>TRUSTEE_IS_GROUP</trusteeType>
<trusteeForm>TRUSTEE_IS_SID</trusteeForm>
<mode>GRANT_ACCESS</mode>

where the extra tags are some commonly used <ace> entries.

The <trusteeWebGroupNameGrant> expands in similar fashion, except that the extra <ace> tags have a different format to suit the Web settings:

<trustee>LDAP://cn=AllUsers@Reseller,ou=Services,ou=Reseller,ou=Hosting,dc=contoso,dc=com
	</trustee>
<trusteeNameType>1</trusteeNameType>
<aceType>0</aceType>
<trusteeForm>1</trusteeForm>

Path calculation

The LDAP path of each org, group, and user element is calculated and added to the element as an attribute named "path". This is a convenience function for the benefit of the caller, but is not of much interest for reading or modifying GetPolicy.

Typical response for GetPolicy

This procedure returns as extensive response; the details will vary depending on your particular deployment.

Important

Although Active Directory is not case sensitive for elements such as the Lightweight Directory Access Protocol (LDAP) path, XML is case sensitive. To ensure that the procedure executes appropriately, specify all tags, elements, and data using uppercase and lowercase letters exactly as shown in the XML examples. For additional guidelines on how to use XML, see the Microsoft Web site (http://www.microsoft.com/).