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:

Organizational units can be nested to any depth.

Example of a request that calls the GetPolicy procedure

	<execute namespace="Managed Active Directory" procedure="GetPolicy">

Input for GetPolicy

The following input is valid for this request:

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:

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]" />

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" />

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:


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:


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.